org.ccnx.ccn.protocol.ContentName Class Reference

ContentNames consist of a sequence of byte[] components which may not be assumed to follow any string encoding, or any other particular encoding. More...

Inheritance diagram for org.ccnx.ccn.protocol.ContentName:

org.ccnx.ccn.impl.encoding.GenericXMLEncodable org.ccnx.ccn.impl.encoding.XMLEncodable org.ccnx.ccn.impl.encoding.XMLEncodable org.ccnx.ccn.io.content.ConfigSlice.Filter org.ccnx.ccn.io.content.WrappingKeyName

List of all members.

Public Member Functions

 ContentName (byte components[][])
 ContentName (ContentName parent, byte[] name)
 Constructor given another ContentName, appends an extra component.
 ContentName (ContentName parent, byte[][] childComponents)
 Constructor given another ContentName, appends extra components.
 ContentName (ContentName parent, ArrayList< byte[]> childComponents)
 Now that components() returns an ArrayList<byte []>, make a constructor that takes that as input.
 ContentName (ContentName parent, int start, ArrayList< byte[]> childComponents)
 parent is base name, then add components from childComponets starting at index "start".
 ContentName (ContentName parent, byte[] name1, byte[] name2)
 ContentName (int count, byte components[][])
 Constructor for extending or contracting names.
 ContentName (int count, ArrayList< byte[]>components)
 Constructor for extending or contracting names.
 ContentName (int start, int count, ArrayList< byte[]>components)
 Subname constructor for extending or contracting names, extracts particular subcomponents from an existing set.
 ContentName (ContentName otherName)
 Copy constructor, also used by subclasses merely wanting a different name in encoding/decoding.
ContentName clone ()
ContentName parent ()
 Returns a new name with the last component removed.
String toString ()
 Default toString() implementation simply prints the text encoding of the object.
String toURIString ()
 Print as string with scheme in front.
ArrayList< byte[]> components ()
int count ()
ContentName append (ContentName other)
 Append a segmented name to this name.
ContentName append (String postfix) throws MalformedContentNameStringException
 Append a name to this one, where the child name might have more than one path component -- e.g.
final byte[] component (int i)
 Get the i'th component, indexed from 0.
final byte[] lastComponent ()
String stringComponent (int i)
void decode (XMLDecoder decoder) throws ContentDecodingException
 Used by NetworkObject to decode the object from a network stream.
boolean isPrefixOf (ContentName name)
 Test if this name is a prefix of another name - i.e.
boolean isPrefixOf (ContentName name, int count)
 Tests if the first n components are a prefix of name.
boolean isPrefixOf (ContentObject other)
 Compare our name to the name of the ContentObject.
boolean isPrefixOf (ContentObject other, int count)
boolean equals (Object obj)
 hashCode and equals not auto-generated, ArrayList does not do the right thing.
int hashCode ()
boolean contains (String str) throws URISyntaxException
 Uses the canonical URI representation.
boolean contains (byte[] component)
int containsWhere (String str) throws URISyntaxException
 Looks for a component.
int whereLast (String str) throws URISyntaxException
 Looks for a component, starting from the end.
int containsWhere (byte[] component)
 Return component index of the first matching component if it exists.
int whereLast (byte[] component)
 Return component index of the last matching component if it exists.
boolean startsWith (byte[] value)
 Does a component of the ContentName startWith value?
int startsWithWhere (byte[] value)
 Return component index of first component that starts with argument value.
ContentName cut (int componentCount)
 Return the first componentNumber components of this name as a new name.
ContentName cut (byte[] component)
 Slice the name off right before the given component.
ContentName cut (String component) throws URISyntaxException
 Slice the name off right before the given component.
ContentName subname (int start, int componentCount)
 Return a subname of this name as a new name.
ContentName postfix (ContentName prefix)
 Return the remainder of this name after the prefix, if the prefix is a prefix of this name.
void encode (XMLEncoder encoder) throws ContentEncodingException
 Used by NetworkObject to encode the object to a network stream.
boolean validate ()
 Make sure all of the necessary fields are filled in prior to attempting to encode.
long getElementLabel ()
 Allow the encoder/decoder to retrieve the top-level element name programmatically.
ContentName copy (int nameComponentCount)
int compareTo (ContentName o)

Static Public Member Functions

static ContentName fromURI (String name) throws MalformedContentNameStringException
 Return the ContentName represented by the given URI.
static ContentName fromURI (String parts[]) throws MalformedContentNameStringException
 Given an array of strings, apply URI decoding and create a ContentName.
static ContentName fromURI (ContentName parent, String name) throws MalformedContentNameStringException
 Return the ContentName created by appending one component to the supplied parent.
static ContentName fromNative (String name) throws MalformedContentNameStringException
 Return the ContentName created from a native Java String.
static ContentName fromNative (ContentName parent, String name)
 Return the ContentName created by appending one component to the supplied parent.
static ContentName fromNative (ContentName parent, byte[] name)
static ContentName fromNative (ContentName parent, String name1, String name2)
static ContentName fromNative (String[] parts)
static ContentName fromNative (ContentName parent, String[] parts)
static String componentPrintURI (byte[] bs, int offset, int length)
 Print bytes in the URI Generic Syntax of RFC 3986 including byte sequences that are not legal character encodings in any character set and byte sequences that have special meaning for URI resolution per RFC 3986.
static String componentPrintURI (byte[] bs)
static String componentPrintNative (byte[] bs)
static String hexPrint (byte[] bs)
static byte[] componentParseURI (String name) throws DotDotComponent, URISyntaxException
 Parse the URI Generic Syntax of RFC 3986.
static byte[] componentParseNative (String name)
 Parse native string component: just UTF-8 encode For full names in native strings only "/" is special but for an individual component we will even allow that.
static ContentName parse (String str) throws MalformedContentNameStringException
 Parses the canonical URI representation.

Static Public Attributes

static final String SCHEME = "ccnx:"
 Official CCN URI scheme.
static final String ORIGINAL_SCHEME = "ccn:"
 This scheme has been deprecated, but we still want to accept it.
static final String SEPARATOR = "/"
static final ContentName ROOT = new ContentName(0, (ArrayList<byte []>)null)

Protected Attributes

ArrayList< byte[]> _components

Classes

class  DotDotComponent


Detailed Description

ContentNames consist of a sequence of byte[] components which may not be assumed to follow any string encoding, or any other particular encoding.

The constructors therefore provide for creation only from byte[]s. To create a ContentName from Strings, a client must call one of the static methods that implements a conversion.


Constructor & Destructor Documentation

org.ccnx.ccn.protocol.ContentName.ContentName ( ContentName  parent,
byte[]  name 
)

Constructor given another ContentName, appends an extra component.

Parameters:
parent used for the base of the name, if null, no prefix added.
name component to be appended; if null, just copy parent

org.ccnx.ccn.protocol.ContentName.ContentName ( ContentName  parent,
bytechildComponents  [][] 
)

Constructor given another ContentName, appends extra components.

Parameters:
parent used for the base of the name.
childComponents components to be appended.

org.ccnx.ccn.protocol.ContentName.ContentName ( ContentName  parent,
ArrayList< byte[]>  childComponents 
)

Now that components() returns an ArrayList<byte []>, make a constructor that takes that as input.

Parameters:
parent used for the base of the name.
childComponents the additional name components to add at the end of parent

org.ccnx.ccn.protocol.ContentName.ContentName ( ContentName  parent,
int  start,
ArrayList< byte[]>  childComponents 
)

parent is base name, then add components from childComponets starting at index "start".

Parameters:
parent used for the base of the name.
start index in childComponents to begin adding from
childComponents the additional name components to add at the end of parent

org.ccnx.ccn.protocol.ContentName.ContentName ( int  count,
byte  components[][] 
)

Constructor for extending or contracting names.

Parameters:
count only this number of name components are taken from components. If count exceeds the number of components passed all components will be included and additional space will be preallocated in the representation for subsequent addition of components.
components 

org.ccnx.ccn.protocol.ContentName.ContentName ( int  count,
ArrayList< byte[]>  components 
)

Constructor for extending or contracting names.

Performs a faster shallow copy of the components, as we don't tend to alter name components once created.

Parameters:
count Only this number of name components are copied into the new name.
components These are the name components to be copied. Can be null, empty, or longer or shorter than count.

org.ccnx.ccn.protocol.ContentName.ContentName ( int  start,
int  count,
ArrayList< byte[]>  components 
)

Subname constructor for extending or contracting names, extracts particular subcomponents from an existing set.

Performs a faster shallow copy of the components, as we don't tend to alter name components once created.

Parameters:
start This is index (0-based) of the first component to copy.
count Only this number of name components are copied into the new name. If count-start is greater than the last component in the components array, only copies count-start.
components These are the name components to be copied. Can be null, empty, or longer or shorter than count.

org.ccnx.ccn.protocol.ContentName.ContentName ( ContentName  otherName  ) 

Copy constructor, also used by subclasses merely wanting a different name in encoding/decoding.

Parameters:
otherName 


Member Function Documentation

static ContentName org.ccnx.ccn.protocol.ContentName.fromURI ( String  name  )  throws MalformedContentNameStringException [static]

Return the ContentName represented by the given URI.

A CCN ContentName consists of a sequence of binary components of any length (including 0), which allows such things as encrypted name components. It is often convenient to work with string representations of names in various forms.

The canonical String representation of a CCN ContentName is a URI encoding of the name according to RFC 3986 with the addition of special treatment for name components of 0 length or containing only one or more of the byte value 0x2E, which is the US-ASCII encoding of '.'. The major features of the URI encoding are the use of a limited set of characters and the use of percent-encoding to encode all other byte values. The combination of percent-encoding and special treatment for certain name components allows the canonical CCN string representation to encode all possible CCN names.

The legal characters in the URI are limited to the unreserved characters "a" through "z", "A" through "Z", "0" through "9", and "-", "_", ".", and "~" plus the reserved delimiters "!", "$" "&", "'", "(", ")", "*", "+", ",", ";", "=". The reserved delimiter "/" is a special case interpreted as component separator and so may not be used within a component unescaped. Any query (starting '?') or fragment (starting '#') is ignored which means that these reserved delimiters must be percent-encoded if they are to be part of the name.

The URI must begin with either the "/" delimiter or the scheme specification "ccnx:" plus delimiter to make URI absolute.

The decoding from a URI String to a ContentName translates each legal character to its US-ASCII byte encoding, except for the "." which is subject to special handling described below. Any other byte value in a component (including those corresponding to "/" and ":") must be percent-encoded in the URI. Any character sequence starting with "?" or "#" is discarded (to the end of the component).

The resolution rules for relative references are applied in this decoding:

  • "//" in the URI is interpreted as "/"
  • "/./" and "/." in the URI are interpreted as "/" and ""
  • "/../" and "/.." in the URI are interpreted as removing the preceding component

Any component of 0 length, or containing only one or more of the byte value 0x2E ("."), is represented in the URI by one "." per byte plus the suffix "..." which provides unambiguous representation of all possible name components in conjunction with the use of the resolution rules given above. Thus the decoding from URI String to ContentName makes conversions such as:

  • "/.../" in the URI is converted to a 0-length name component
  • "/..../" in the URI is converted to the name component {0x2E}
  • "/...../" in the URI is converted to the name component {0x2E, 0x2E}
  • "/....../" in the URI is converted to the name component {0x2E, 0x2E, 0x2E}

Note that this URI encoding is very similar to but not the same as the application/x-www-form-urlencoded MIME format that is used by the Java java.net.URLDecoder.

TODO: Inconsistent with C lib in that it does not strip authority part TODO: Inconsistent with C lib in that it does not fully strip query and fragment parts (within component only)

Parameters:
name 
Returns:
Exceptions:
MalformedContentNameStringException 

static ContentName org.ccnx.ccn.protocol.ContentName.fromURI ( String  parts[]  )  throws MalformedContentNameStringException [static]

Given an array of strings, apply URI decoding and create a ContentName.

See also:
fromURI(String)
Exceptions:
MalformedContentNameStringException 

static ContentName org.ccnx.ccn.protocol.ContentName.fromURI ( ContentName  parent,
String  name 
) throws MalformedContentNameStringException [static]

Return the ContentName created by appending one component to the supplied parent.

The new component is converted from URI string encoding.

See also:
fromURI(String)
Parameters:
parent used for the base of the name.
name sequence of URI encoded name components, appended to the base.
Exceptions:
MalformedContentNameStringException 

static ContentName org.ccnx.ccn.protocol.ContentName.fromNative ( String  name  )  throws MalformedContentNameStringException [static]

Return the ContentName created from a native Java String.

In native strings only "/" is special, interpreted as component delimiter, while all other characters will be encoded as UTF-8 in the output ContentName Native String representations do not incorporate a URI scheme, and so must begin with the component delimiter "/". TODO use Java string escaping rules?

Parameters:
name 
Exceptions:
MalformedContentNameStringException if name does not start with "/"

static ContentName org.ccnx.ccn.protocol.ContentName.fromNative ( ContentName  parent,
String  name 
) [static]

Return the ContentName created by appending one component to the supplied parent.

This method intentionally throws no declared exceptions so you can be confident in encoding any native Java String.

Parameters:
parent used for the base of the name.
name Native Java String which will be encoded as UTF-8 in the output ContentName

String org.ccnx.ccn.protocol.ContentName.toString (  ) 

Default toString() implementation simply prints the text encoding of the object.

This demonstrates how to force use of the text encoding.

Reimplemented from org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

String org.ccnx.ccn.protocol.ContentName.toURIString (  ) 

Print as string with scheme in front.

toString already prints in URI format with leading /, just add scheme.

static String org.ccnx.ccn.protocol.ContentName.componentPrintURI ( byte[]  bs,
int  offset,
int  length 
) [static]

Print bytes in the URI Generic Syntax of RFC 3986 including byte sequences that are not legal character encodings in any character set and byte sequences that have special meaning for URI resolution per RFC 3986.

This is designed to match the C library URI encoding.

This method must be invertible by parseComponent() so for any input sequence of bytes it must be the case that parseComponent(printComponent(input)) == input.

All bytes that are unreserved characters per RFC 3986 are left unescaped. Other bytes are percent encoded.

Empty path components and path components "." and ".." have special meaning for relative URI resolution per RFC 3986. To guarantee these component variations are preserved and recovered exactly when the URI is parsed by parseComponent() we use a convention that components that are empty or consist entirely of '.' characters will have "..." appended. This is intended to be consistent with the CCN C library handling of URI representation of names.

Parameters:
bs input byte array.
Returns:

static byte [] org.ccnx.ccn.protocol.ContentName.componentParseURI ( String  name  )  throws DotDotComponent, URISyntaxException [static]

Parse the URI Generic Syntax of RFC 3986.

Including handling percent encoding of sequences that are not legal character encodings in any character set. This method is the inverse of printComponent() and for any input sequence of bytes it must be the case that parseComponent(printComponent(input)) == input. Note that the inverse is NOT true printComponent(parseComponent(input)) != input in general.

See also:
fromURI(String)
Note in particular that this method interprets sequences of more than two dots ('.') as representing an empty component or dot component value as encoded by componentPrint. That is, the component value will be the value obtained by removing three dots.
Parameters:
name a single component of a name, URI encoded
Returns:
a name component

static byte [] org.ccnx.ccn.protocol.ContentName.componentParseNative ( String  name  )  [static]

Parse native string component: just UTF-8 encode For full names in native strings only "/" is special but for an individual component we will even allow that.

This method intentionally throws no declared exceptions so you can be confident in encoding any native Java String TODO make this use Java string escaping rules?

Parameters:
name Component as native Java string

int org.ccnx.ccn.protocol.ContentName.count (  ) 

Returns:
The number of components in the name.

ContentName org.ccnx.ccn.protocol.ContentName.append ( String  postfix  )  throws MalformedContentNameStringException

Append a name to this one, where the child name might have more than one path component -- e.g.

foo/bar/bash. Will add leading / to postfix for parsing, if one not present.

Exceptions:
MalformedContentNameStringException 

final byte [] org.ccnx.ccn.protocol.ContentName.component ( int  i  ) 

Get the i'th component, indexed from 0.

Parameters:
i 
Returns:
null if i is out of range.

String org.ccnx.ccn.protocol.ContentName.stringComponent ( int  i  ) 

Returns:
The i'th component, converted using URI encoding.

void org.ccnx.ccn.protocol.ContentName.decode ( XMLDecoder  decoder  )  throws ContentDecodingException [virtual]

Used by NetworkObject to decode the object from a network stream.

See also:
org.ccnx.ccn.impl.encoding.XMLEncodable

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

Reimplemented in org.ccnx.ccn.io.content.ConfigSlice.Filter.

boolean org.ccnx.ccn.protocol.ContentName.isPrefixOf ( ContentName  name  ) 

Test if this name is a prefix of another name - i.e.

do all components in this name exist in the name being compared with. Note there do not need to be any more components in the name being compared with.

Parameters:
name name being compared with.

boolean org.ccnx.ccn.protocol.ContentName.isPrefixOf ( ContentName  name,
int  count 
)

Tests if the first n components are a prefix of name.

Parameters:
name 
count number of components to check

boolean org.ccnx.ccn.protocol.ContentName.isPrefixOf ( ContentObject  other  ) 

Compare our name to the name of the ContentObject.

If our name is 1 component longer than the ContentObject and no prefix count is set, our name might contain a digest. In that case, try matching the content to the last component as a digest.

Parameters:
other 
Returns:

static ContentName org.ccnx.ccn.protocol.ContentName.parse ( String  str  )  throws MalformedContentNameStringException [static]

Parses the canonical URI representation.

Parameters:
str 
Returns:
Exceptions:
MalformedContentNameStringException 

boolean org.ccnx.ccn.protocol.ContentName.contains ( String  str  )  throws URISyntaxException

Uses the canonical URI representation.

Parameters:
str 
Returns:

int org.ccnx.ccn.protocol.ContentName.containsWhere ( String  str  )  throws URISyntaxException

Looks for a component.

Parameters:
str Component to search for, encoded using URI encoding.
Returns:
The index of the first component that matched. Starts at 0.
Exceptions:
URISyntaxException 

int org.ccnx.ccn.protocol.ContentName.whereLast ( String  str  )  throws URISyntaxException

Looks for a component, starting from the end.

Parameters:
str Component to search for, encoded using URI encoding.
Returns:
The index of the first component that matched. Starts at 0.
Exceptions:
URISyntaxException 

int org.ccnx.ccn.protocol.ContentName.containsWhere ( byte[]  component  ) 

Return component index of the first matching component if it exists.

Parameters:
component Component to search for.
Returns:
-1 on failure, component index otherwise (starts at 0).

int org.ccnx.ccn.protocol.ContentName.whereLast ( byte[]  component  ) 

Return component index of the last matching component if it exists.

Parameters:
component Component to search for.
Returns:
-1 on failure, component index otherwise (starts at 0).

boolean org.ccnx.ccn.protocol.ContentName.startsWith ( byte[]  value  ) 

Does a component of the ContentName startWith value?

Parameters:
value 
Returns:

int org.ccnx.ccn.protocol.ContentName.startsWithWhere ( byte[]  value  ) 

Return component index of first component that starts with argument value.

Parameters:
value 
Returns:

ContentName org.ccnx.ccn.protocol.ContentName.cut ( int  componentCount  ) 

Return the first componentNumber components of this name as a new name.

Parameters:
componentNumber 
Returns:

ContentName org.ccnx.ccn.protocol.ContentName.cut ( byte[]  component  ) 

Slice the name off right before the given component.

Parameters:
component 

ContentName org.ccnx.ccn.protocol.ContentName.cut ( String  component  )  throws URISyntaxException

Slice the name off right before the given component.

Parameters:
component In URI encoded form.

ContentName org.ccnx.ccn.protocol.ContentName.subname ( int  start,
int  componentCount 
)

Return a subname of this name as a new name.

Parameters:
start the starting component index (0-based)
componentCount the number of components to include beginning with start.
Returns:
the new name.

ContentName org.ccnx.ccn.protocol.ContentName.postfix ( ContentName  prefix  ) 

Return the remainder of this name after the prefix, if the prefix is a prefix of this name.

Otherwise return null. If the prefix is identical to this name, return the root (empty) name.

void org.ccnx.ccn.protocol.ContentName.encode ( XMLEncoder  encoder  )  throws ContentEncodingException [virtual]

Used by NetworkObject to encode the object to a network stream.

See also:
org.ccnx.ccn.impl.encoding.XMLEncodable

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

Reimplemented in org.ccnx.ccn.io.content.ConfigSlice.Filter.

boolean org.ccnx.ccn.protocol.ContentName.validate (  )  [virtual]

Make sure all of the necessary fields are filled in prior to attempting to encode.

All implementations of encode(XMLEncoder) should call this for their classes prior to encoding.

Returns:
true if object is valid and can be encoded, false if there is a problem; for example mandatory fields are uninitialized

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

long org.ccnx.ccn.protocol.ContentName.getElementLabel (  )  [virtual]

Allow the encoder/decoder to retrieve the top-level element name programmatically.

This allows subclasses to rename elements without changing their encoder/decoders.

Returns:
the element label to use, as a key in a loaded encoding dictionary

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

Reimplemented in org.ccnx.ccn.io.content.WrappingKeyName.


The documentation for this class was generated from the following file:

Generated on Thu Feb 16 00:45:06 2012 for Content-Centric Networking in Java by  doxygen 1.5.6