ContentNames consist of a sequence of byte[] components which may not be assumed to follow any string encoding, or any other particular encoding. More...
Classes | |
interface | ComponentProvider |
Allows a class to be included as an argument to a ContentName builder. More... | |
Public Member Functions | |
ContentName () | |
Will become private in future. | |
ContentName (byte[] component) | |
This Constructor is required to avoid the varargs constructor interpreting a single byte[] as a list of separate byte arguments. | |
ContentName (Object...args) | |
Varargs name builder, Strings always represent a single component, interpreted as UTF8. | |
ContentName (ContentName parent, byte[] component) | |
ContentName (ContentName parent, ContentNameProvider cnp) | |
ContentName (ContentName parent, String component) | |
ContentName (ContentName parent, ComponentProvider cprov) | |
final ContentName | getContentName () |
ContentName (byte components[][]) | |
This method is here to avoid a warning when passing a byte[][] parameter directly into the varargs constructor. | |
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 (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, should not generally be needed since ContentNames are immutable. | |
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 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) |
int | hashCode () |
boolean | contains (String str) throws URISyntaxException |
Uses the canonical URI representation. | |
boolean | contains (byte[] component) |
boolean | contains (ComponentProvider cp) |
int | containsWhere (String str) throws URISyntaxException |
Looks for a component. | |
int | containsWhere (ComponentProvider cp) |
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. | |
int | whereLast (ComponentProvider cp) |
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. | |
boolean | componentStartsWith (byte[] value) |
int | componentStartsWithWhere (byte[] value) |
ContentName | cut (int componentCount) |
Return the first componentCount components of this name as a new name. | |
ContentName | right (int position) |
Removes the first components from the 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 end) |
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) |
Iterator< byte[]> | iterator () |
This returns the components of the name. | |
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 Component.DotDot, 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() |
Protected Member Functions | |
ContentName (ArrayList< byte[]> components) | |
Protected Attributes | |
byte[][] | _components |
ContentNames consist of a sequence of byte[] components which may not be assumed to follow any string encoding, or any other particular encoding.
Warning: This class is designed to be immutable. Some methods expose the internal byte[] components. You must be careful not to change the contents of these byte[] when you receive the values back from this class.
org.ccnx.ccn.protocol.ContentName.ContentName | ( | ) |
Will become private in future.
Today used together with decode(XMLDecoder) to decode a ContentName. In the future there will be a XMLDecoder constructor used for decoding.
org.ccnx.ccn.protocol.ContentName.ContentName | ( | byte[] | component | ) |
This Constructor is required to avoid the varargs constructor interpreting a single byte[] as a list of separate byte arguments.
component | a single component. The data is cloned, so there is no restriction on its use after this call. |
org.ccnx.ccn.protocol.ContentName.ContentName | ( | Object... | args | ) |
Varargs name builder, Strings always represent a single component, interpreted as UTF8.
Varargs name builder. Convenience method to allow ContentNames to be constructed from multiple parts.
stringParser | method to call to parse String arguments | |
args | Any number of null, byte[], String, ContentNameProvider or ComponentProvider arguments |
MalformedContentNameStringException | if a String argument does not parse correctly when passed to stringParser |
org.ccnx.ccn.protocol.ContentName.ContentName | ( | ContentName | parent, | |
bytechildComponents | [][] | |||
) |
Constructor given another ContentName, appends extra components.
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.
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".
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.
count | only this number of name components are taken from 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.
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.
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, should not generally be needed since ContentNames are immutable.
Used by subclasses merely wanting to converta a ContentName into a different type of name for encoding/decoding.
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.
MalformedContentNameStringException |
final byte [] org.ccnx.ccn.protocol.ContentName.component | ( | int | i | ) |
Get the i'th component, indexed from 0.
i | index of component to fetch, first (leftmost) component = 0. |
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?
name | Component as native Java string |
static byte [] org.ccnx.ccn.protocol.ContentName.componentParseURI | ( | String | name | ) | throws Component.DotDot, 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.
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.
name | a single component of a name, URI encoded |
static String org.ccnx.ccn.protocol.ContentName.componentPrintNative | ( | byte[] | bs | ) | [static] |
static String org.ccnx.ccn.protocol.ContentName.componentPrintURI | ( | byte[] | bs | ) | [static] |
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.
bs | input byte array. |
ArrayList<byte[]> org.ccnx.ccn.protocol.ContentName.components | ( | ) |
boolean org.ccnx.ccn.protocol.ContentName.componentStartsWith | ( | byte[] | value | ) |
int org.ccnx.ccn.protocol.ContentName.componentStartsWithWhere | ( | byte[] | value | ) |
boolean org.ccnx.ccn.protocol.ContentName.contains | ( | String | str | ) | throws URISyntaxException |
Uses the canonical URI representation.
str |
int org.ccnx.ccn.protocol.ContentName.containsWhere | ( | byte[] | component | ) |
Return component index of the first matching component if it exists.
component | Component to search for. |
int org.ccnx.ccn.protocol.ContentName.containsWhere | ( | String | str | ) | throws URISyntaxException |
Looks for a component.
str | Component to search for, encoded using URI encoding. |
URISyntaxException |
ContentName org.ccnx.ccn.protocol.ContentName.copy | ( | int | nameComponentCount | ) |
int org.ccnx.ccn.protocol.ContentName.count | ( | ) |
ContentName org.ccnx.ccn.protocol.ContentName.cut | ( | String | component | ) | throws URISyntaxException |
Slice the name off right before the given component.
component | In URI encoded form. |
ContentName org.ccnx.ccn.protocol.ContentName.cut | ( | byte[] | component | ) |
Slice the name off right before the given component.
component |
ContentName org.ccnx.ccn.protocol.ContentName.cut | ( | int | componentCount | ) |
Return the first componentCount components of this name as a new name.
componentCount |
void org.ccnx.ccn.protocol.ContentName.decode | ( | XMLDecoder | decoder | ) | throws ContentDecodingException [virtual] |
Used by NetworkObject to decode the object from a network stream.
Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.
Reimplemented in org.ccnx.ccn.io.content.ConfigSlice.Filter.
void org.ccnx.ccn.protocol.ContentName.encode | ( | XMLEncoder | encoder | ) | throws ContentEncodingException [virtual] |
Used by NetworkObject to encode the object to a network stream.
Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.
Reimplemented in org.ccnx.ccn.io.content.ConfigSlice.Filter.
static ContentName org.ccnx.ccn.protocol.ContentName.fromNative | ( | ContentName | parent, | |
String[] | parts | |||
) | [static] |
static ContentName org.ccnx.ccn.protocol.ContentName.fromNative | ( | String[] | parts | ) | [static] |
static ContentName org.ccnx.ccn.protocol.ContentName.fromNative | ( | ContentName | parent, | |
String | name1, | |||
String | name2 | |||
) | [static] |
static ContentName org.ccnx.ccn.protocol.ContentName.fromNative | ( | ContentName | parent, | |
byte[] | name | |||
) | [static] |
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.
parent | used for the base of the name. | |
name | Native Java String which will be encoded as UTF-8 in the output ContentName |
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?
name |
MalformedContentNameStringException | if name does not start with "/" |
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.
parent | used for the base of the name. | |
name | sequence of URI encoded name components, appended to the base. |
MalformedContentNameStringException | Use new ContentName#ContentName(ContentName, String) or Component#parseURI(String) and new ContentName#ContentName(ContentName, byte[]) for more exact semantic match. |
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.
MalformedContentNameStringException |
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:
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:
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)
name |
MalformedContentNameStringException |
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.
Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.
Reimplemented in org.ccnx.ccn.io.content.WrappingKeyName, org.ccnx.ccn.profiles.namespace.ParameterizedName.PrefixName, org.ccnx.ccn.profiles.namespace.ParameterizedName.SuffixName, org.ccnx.ccn.profiles.security.access.AccessControlPolicyMarker.ProfileName, and org.ccnx.ccn.test.profiles.ccnd.PrefixRegistrationManagerTest.NotReallyAContentName.
static String org.ccnx.ccn.protocol.ContentName.hexPrint | ( | byte[] | bs | ) | [static] |
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.
other |
boolean org.ccnx.ccn.protocol.ContentName.isPrefixOf | ( | ContentName | name, | |
int | count | |||
) |
Tests if the first n components are a prefix of name.
name | ||
count | number of components to check |
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.
name | name being compared with. |
Iterator<byte[]> org.ccnx.ccn.protocol.ContentName.iterator | ( | ) |
This returns the components of the name.
Warning - the iterator directly returns the underlying byte arrays used in the name to hold the components. These must not be modified (they may be reused in multiple places, and are assumed not to change).
final byte [] org.ccnx.ccn.protocol.ContentName.lastComponent | ( | ) |
static ContentName org.ccnx.ccn.protocol.ContentName.parse | ( | String | str | ) | throws MalformedContentNameStringException [static] |
Parses the canonical URI representation.
str |
MalformedContentNameStringException | Use fromURI(String) |
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.
ContentName org.ccnx.ccn.protocol.ContentName.right | ( | int | position | ) |
Removes the first components from the name.
Includes only components from position on.
position | component number to include as first component in the new name. 0 includes all components, 1 includes from the second component on. |
boolean org.ccnx.ccn.protocol.ContentName.startsWith | ( | byte[] | value | ) |
Does a component of the ContentName startWith value?
value |
int org.ccnx.ccn.protocol.ContentName.startsWithWhere | ( | byte[] | value | ) |
Return component index of first component that starts with argument value.
value |
String org.ccnx.ccn.protocol.ContentName.stringComponent | ( | int | i | ) |
ContentName org.ccnx.ccn.protocol.ContentName.subname | ( | int | start, | |
int | end | |||
) |
Return a subname of this name as a new name.
Two indexes are supplied, and a new name is made, taking the components between these indexes.
start | the starting component index (0-based) | |
end | the number of the last component to include. (1-based) |
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.
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.
Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.
int org.ccnx.ccn.protocol.ContentName.whereLast | ( | byte[] | component | ) |
Return component index of the last matching component if it exists.
component | Component to search for. |
int org.ccnx.ccn.protocol.ContentName.whereLast | ( | String | str | ) | throws URISyntaxException |
Looks for a component, starting from the end.
str | Component to search for, encoded using URI encoding. |
URISyntaxException |