net.named_data.jndn

Class Name

java.lang.Object

net.named_data.jndn.Name

All Implemented Interfaces:

Comparable, ChangeCountable

public class Name
extends Object
implements ChangeCountable, Comparable

A Name holds an array of Name.Component and represents an NDN name.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Name.Component A Name.Component holds a read-only name component value.

Constructor Summary

Constructors

Constructor and Description
Name() Create a new Name with no components.
Name(ArrayList components) Create a new Name, copying the components.
Name(Name.Component[] components) Create a new Name, copying the components.
Name(Name name) Create a new Name with the components in the given name.
Name(String uri) Parse the uri according to the NDN URI Scheme and create the name with the components.

Method Summary

Methods

Modifier and Type	Method and Description
Name	append(Blob value) Append a new GENERIC component, using the existing Blob value.
Name	append(byte[] value) Append a new GENERIC component, copying from value.
Name	append(Name.Component component) Append the component to this name.
Name	append(Name name)
Name	append(String value) Convert the value to UTF8 bytes and append a Name.Component.
Name	appendImplicitSha256Digest(Blob digest) Append a component of type ImplicitSha256DigestComponent, so that isImplicitSha256Digest() is true.
Name	appendImplicitSha256Digest(byte[] digest) Append a component of type ImplicitSha256DigestComponent, so that isImplicitSha256Digest() is true.
Name	appendSegment(long segment) Append a component with the encoded segment number according to NDN naming conventions for "Segment number" (marker 0x00).
Name	appendSegmentOffset(long segmentOffset) Append a component with the encoded segment byte offset according to NDN naming conventions for segment "Byte offset" (marker 0xFB).
Name	appendSequenceNumber(long sequenceNumber) Append a component with the encoded sequence number according to NDN naming conventions for "Sequencing" (marker 0xFE).
Name	appendTimestamp(long timestamp) Append a component with the encoded timestamp according to NDN naming conventions for "Timestamp" (marker 0xFC).
Name	appendVersion(long version) Append a component with the encoded version number according to NDN naming conventions for "Versioning" (marker 0xFD).
void	clear() Clear all the components.
int	compare(int iStartComponent, int nComponents, Name other) Compare a subset of this name to all of the other name, equivalent to this.getSubName(iStartComponent, nComponents).compare(other).
int	compare(int iStartComponent, int nComponents, Name other, int iOtherStartComponent) Compare a subset of this name to a subset of the other name, equivalent to this.getSubName(iStartComponent, nComponents).compare (other.getSubName(iOtherStartComponent)), getting all components of other from iOtherStartComponent to the end of the name.
int	compare(int iStartComponent, int nComponents, Name other, int iOtherStartComponent, int nOtherComponents) Compare a subset of this name to a subset of the other name, equivalent to this.getSubName(iStartComponent, nComponents).compare (other.getSubName(iOtherStartComponent, nOtherComponents)).
int	compare(Name other) Compare this to the other Name using NDN canonical ordering.
int	compareTo(Object o)
int	CompareTo(Object o)
boolean	equals(Name name) Check if this name has the same component count and components as the given name.
boolean	equals(Object other)
static Blob	fromEscapedString(String escapedString) Make a Blob value by decoding the escapedString according to the NDN URI Scheme.
static Blob	fromEscapedString(String escapedString, int beginOffset, int endOffset) Make a Blob value by decoding the escapedString between beginOffset and endOffset according to the NDN URI Scheme.
static Blob	fromHex(String hexString, int beginOffset, int endOffset) Make a Blob value by decoding the hexString between beginOffset and endOffset.
Name.Component	get(int i) Get the component at the given index.
long	getChangeCount() Get the change count, which is incremented each time this object is changed.
Name	getPrefix(int nComponents) Return a new Name with the first nComponents components of this Name.
Name	getSubName(int iStartComponent) Get a new name, constructed as a subset of components starting at iStartComponent until the end of the name.
Name	getSubName(int iStartComponent, int nComponents) Get a new name, constructed as a subset of components.
Name	getSuccessor() Get the successor of this name which is defined as follows.
int	hashCode()
boolean	isPrefixOf(Name name) Check if the N components of this name are the same as the first N components of the given name.
boolean	match(Name name) Check if the N components of this name are the same as the first N components of the given name.
void	set(String uri)
int	size() Get the number of components.
static String	toEscapedString(ByteBuffer value) Convert the value by escaping characters according to the NDN URI Scheme.
static void	toEscapedString(ByteBuffer value, StringBuffer result) Write the value to result, escaping characters according to the NDN URI Scheme.
String	toString()
String	toUri() Encode this name as a URI according to the NDN URI Scheme.
String	toUri(boolean includeScheme) Encode this name as a URI according to the NDN URI Scheme.
void	wireDecode(Blob input) Decode the input using the default wire format WireFormat.getDefaultWireFormat() and update this Name.
void	wireDecode(Blob input, WireFormat wireFormat) Decode the input using a particular wire format and update this Name.
void	wireDecode(ByteBuffer input) Decode the input using the default wire format WireFormat.getDefaultWireFormat() and update this Name.
void	wireDecode(ByteBuffer input, WireFormat wireFormat) Decode the input using a particular wire format and update this Name.
Blob	wireEncode() Encode this Name for the default wire format WireFormat.getDefaultWireFormat().
Blob	wireEncode(WireFormat wireFormat) Encode this Name for a particular wire format.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Name

public Name()

Create a new Name with no components.

Name

public Name(Name name)

Create a new Name with the components in the given name.

Parameters:

name - The name with components to copy from.

Name

public Name(ArrayList components)

Create a new Name, copying the components.

Parameters:

components - The components to copy.

Name

public Name(Name.Component[] components)

Create a new Name, copying the components.

Parameters:

components - The components to copy.

Name

public Name(String uri)

Parse the uri according to the NDN URI Scheme and create the name with the components.

Parameters:

uri - The URI string.

Method Detail

size

public final int size()

Get the number of components.

Returns:

The number of components.

get

public final Name.Component get(int i)

Get the component at the given index.

Parameters:

i - The index of the component, starting from 0. However, if i is negative, return the component at size() - (-i).

Returns:

The name component at the index.

set

public final void set(String uri)

clear

public final void clear()

Clear all the components.

append

public final Name append(byte[] value)

Append a new GENERIC component, copying from value. (To append an ImplicitSha256Digest component, use appendImplicitSha256Digest.)

Parameters:

value - The component value.

Returns:

This name so that you can chain calls to append.

append

public final Name append(Blob value)

Append a new GENERIC component, using the existing Blob value. (To append an ImplicitSha256Digest component, use appendImplicitSha256Digest.)

Parameters:

value - The component value.

Returns:

This name so that you can chain calls to append.

append

public final Name append(Name.Component component)

Append the component to this name.

Parameters:

component - The component to append.

Returns:

This name so that you can chain calls to append.

append

public final Name append(Name name)

append

public final Name append(String value)

Convert the value to UTF8 bytes and append a Name.Component. Note, this does not escape %XX values. If you need to escape, use Name.fromEscapedString. Also, if the string has "/", this does not split into separate components. If you need that then use append(new Name(value)).

Parameters:

value - The string to convert to UTF8.

Returns:

This name so that you can chain calls to append.

getSubName

public final Name getSubName(int iStartComponent,
              int nComponents)

Get a new name, constructed as a subset of components.

Parameters:

iStartComponent - The index if the first component to get. If iStartComponent is -N then return return components starting from name.size() - N.

nComponents - The number of components starting at iStartComponent. If greater than the size of this name, get until the end of the name.

Returns:

A new name.

getSubName

public final Name getSubName(int iStartComponent)

Get a new name, constructed as a subset of components starting at iStartComponent until the end of the name.

Parameters:

iStartComponent - The index if the first component to get. If iStartComponent is -N then return return components starting from name.size() - N.

Returns:

A new name.

getPrefix

public final Name getPrefix(int nComponents)

Return a new Name with the first nComponents components of this Name.

Parameters:

nComponents - The number of prefix components. If nComponents is -N then return the prefix up to name.size() - N. For example getPrefix(-1) returns the name without the final component.

Returns:

A new Name.

toUri

public final String toUri(boolean includeScheme)

Encode this name as a URI according to the NDN URI Scheme.

Parameters:

includeScheme - If true, include the "ndn:" scheme in the URI, e.g. "ndn:/example/name". If false, just return the path, e.g. "/example/name", which is normally the case where toUri() is used for display.

Returns:

The URI string.

toUri

public final String toUri()

Encode this name as a URI according to the NDN URI Scheme. Just return the path, e.g. "/example/name" which is the default case where toUri() is used for display.

Returns:

The URI string.

toString

public String toString()

Overrides:

toString in class Object

appendSegment

public final Name appendSegment(long segment)

Append a component with the encoded segment number according to NDN naming conventions for "Segment number" (marker 0x00). http://named-data.net/doc/tech-memos/naming-conventions.pdf

Parameters:

segment - The segment number.

Returns:

This name so that you can chain calls to append.

appendSegmentOffset

public final Name appendSegmentOffset(long segmentOffset)

Append a component with the encoded segment byte offset according to NDN naming conventions for segment "Byte offset" (marker 0xFB). http://named-data.net/doc/tech-memos/naming-conventions.pdf

Parameters:

segmentOffset - The segment byte offset.

Returns:

This name so that you can chain calls to append.

appendVersion

public final Name appendVersion(long version)

Append a component with the encoded version number according to NDN naming conventions for "Versioning" (marker 0xFD). http://named-data.net/doc/tech-memos/naming-conventions.pdf Note that this encodes the exact value of version without converting from a time representation.

Parameters:

version - The version number.

Returns:

This name so that you can chain calls to append.

appendTimestamp

public final Name appendTimestamp(long timestamp)

Append a component with the encoded timestamp according to NDN naming conventions for "Timestamp" (marker 0xFC). http://named-data.net/doc/tech-memos/naming-conventions.pdf

Parameters:

timestamp - The number of microseconds since the UNIX epoch (Thursday, 1 January 1970) not counting leap seconds.

Returns:

This name so that you can chain calls to append.

appendSequenceNumber

public final Name appendSequenceNumber(long sequenceNumber)

Append a component with the encoded sequence number according to NDN naming conventions for "Sequencing" (marker 0xFE). http://named-data.net/doc/tech-memos/naming-conventions.pdf

Parameters:

sequenceNumber - The sequence number.

Returns:

This name so that you can chain calls to append.

appendImplicitSha256Digest

public final Name appendImplicitSha256Digest(Blob digest)
                                      throws EncodingException

Append a component of type ImplicitSha256DigestComponent, so that isImplicitSha256Digest() is true.

Parameters:

digest - The SHA-256 digest value.

Returns:

This name so that you can chain calls to append.

Throws:

EncodingException - If the digest length is not 32 bytes.

appendImplicitSha256Digest

public final Name appendImplicitSha256Digest(byte[] digest)
                                      throws EncodingException

Append a component of type ImplicitSha256DigestComponent, so that isImplicitSha256Digest() is true.

Parameters:

digest - The SHA-256 digest value.

Returns:

This name so that you can chain calls to append.

Throws:

EncodingException - If the digest length is not 32 bytes.

equals

public boolean equals(Name name)

Check if this name has the same component count and components as the given name.

Parameters:

name - The Name to check.

Returns:

true if the names are equal, otherwise false.

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getSuccessor

public final Name getSuccessor()

Get the successor of this name which is defined as follows. N represents the set of NDN Names, and X,Y ∈ N. Operator < is defined by the NDN canonical order on N. Y is the successor of X, if (a) X < Y, and (b) ∄ Z ∈ N s.t. X < Z < Y. In plain words, the successor of a name is the same name, but with its last component advanced to a next possible value. Examples: - The successor of / is /%00 - The successor of /%00%01/%01%02 is /%00%01/%01%03 - The successor of /%00%01/%01%FF is /%00%01/%02%00 - The successor of /%00%01/%FF%FF is /%00%01/%00%00%00

Returns:

A new name which is the successor of this.

match

public final boolean match(Name name)

Check if the N components of this name are the same as the first N components of the given name.

Parameters:

name - The Name to check.

Returns:

true if this matches the given name, otherwise false. This always returns true if this name is empty.

isPrefixOf

public final boolean isPrefixOf(Name name)

Check if the N components of this name are the same as the first N components of the given name.

Parameters:

name - The Name to check.

Returns:

true if this matches the given name, otherwise false. This always returns true if this name is empty.

wireEncode

public final Blob wireEncode(WireFormat wireFormat)

Encode this Name for a particular wire format.

Parameters:

wireFormat - A WireFormat object used to encode this Name.

Returns:

The encoded buffer.

wireEncode

public final Blob wireEncode()

Encode this Name for the default wire format WireFormat.getDefaultWireFormat().

Returns:

The encoded buffer.

wireDecode

public final void wireDecode(ByteBuffer input,
              WireFormat wireFormat)
                      throws EncodingException

Decode the input using a particular wire format and update this Name.

Parameters:

input - The input buffer to decode. This reads from position() to limit(), but does not change the position.

wireFormat - A WireFormat object used to decode the input.

Throws:

EncodingException - For invalid encoding.

wireDecode

public final void wireDecode(ByteBuffer input)
                      throws EncodingException

Decode the input using the default wire format WireFormat.getDefaultWireFormat() and update this Name.

Parameters:

input - The input buffer to decode. This reads from position() to limit(), but does not change the position.

Throws:

EncodingException - For invalid encoding.

wireDecode

public final void wireDecode(Blob input,
              WireFormat wireFormat)
                      throws EncodingException

Decode the input using a particular wire format and update this Name.

Parameters:

input - The input blob to decode.

wireFormat - A WireFormat object used to decode the input.

Throws:

EncodingException - For invalid encoding.

wireDecode

public final void wireDecode(Blob input)
                      throws EncodingException

Decode the input using the default wire format WireFormat.getDefaultWireFormat() and update this Name.

Parameters:

input - The input blob to decode.

Throws:

EncodingException - For invalid encoding.

compare

public final int compare(Name other)

Compare this to the other Name using NDN canonical ordering. If the first components of each name are not equal, this returns -1 if the first comes before the second using the NDN canonical ordering for name components, or 1 if it comes after. If they are equal, this compares the second components of each name, etc. If both names are the same up to the size of the shorter name, this returns -1 if the first name is shorter than the second or 1 if it is longer. For example, sorted gives: /a/b/d /a/b/cc /c /c/a /bb . This is intuitive because all names with the prefix /a are next to each other. But it may be also be counter-intuitive because /c comes before /bb according to NDN canonical ordering since it is shorter.

Parameters:

other - The other Name to compare with.

Returns:

0 If they compare equal, -1 if this Name comes before other in the canonical ordering, or 1 if this Name comes after other in the canonical ordering. See http://named-data.net/doc/0.2/technical/CanonicalOrder.html

compare

public final int compare(int iStartComponent,
          int nComponents,
          Name other,
          int iOtherStartComponent,
          int nOtherComponents)

Compare a subset of this name to a subset of the other name, equivalent to this.getSubName(iStartComponent, nComponents).compare (other.getSubName(iOtherStartComponent, nOtherComponents)).

Parameters:

iStartComponent - The index if the first component of this name to compare. If iStartComponent is -N then compare components starting from name.size() - N.

nComponents - The number of components starting at iStartComponent. If greater than the size of this name, compare until the end of the name.

other - The other Name to compare with.

iOtherStartComponent - The index if the first component of the other name to compare. If iOtherStartComponent is -N then compare components starting from other.size() - N.

nOtherComponents - The number of components starting at iOtherStartComponent. If greater than the size of the other name, compare until the end of the name.

Returns:

0 If the sub names compare equal, -1 if this sub name comes before the other sub name in the canonical ordering, or 1 if after.

compare

public final int compare(int iStartComponent,
          int nComponents,
          Name other,
          int iOtherStartComponent)

Compare a subset of this name to a subset of the other name, equivalent to this.getSubName(iStartComponent, nComponents).compare (other.getSubName(iOtherStartComponent)), getting all components of other from iOtherStartComponent to the end of the name.

Parameters:

iStartComponent - The index if the first component of this name to compare. If iStartComponent is -N then compare components starting from name.size() - N.

nComponents - The number of components starting at iStartComponent. If greater than the size of this name, compare until the end of the name.

other - The other Name to compare with.

iOtherStartComponent - The index if the first component of the other name to compare. If iOtherStartComponent is -N then compare components starting from other.size() - N.

Returns:

0 If the sub names compare equal, -1 if this sub name comes before the other sub name in the canonical ordering, or 1 if after.

compare

public final int compare(int iStartComponent,
          int nComponents,
          Name other)

Compare a subset of this name to all of the other name, equivalent to this.getSubName(iStartComponent, nComponents).compare(other).

Parameters:

iStartComponent - The index if the first component of this name to compare. If iStartComponent is -N then compare components starting from name.size() - N.

nComponents - The number of components starting at iStartComponent. If greater than the size of this name, compare until the end of the name.

other - The other Name to compare with.

Returns:

0 If the sub names compare equal, -1 if this sub name comes before the other name in the canonical ordering, or 1 if after.

compareTo

public final int compareTo(Object o)

Specified by:

compareTo in interface Comparable

CompareTo

public final int CompareTo(Object o)

getChangeCount

public final long getChangeCount()

Get the change count, which is incremented each time this object is changed.

Specified by:

getChangeCount in interface ChangeCountable

Returns:

The change count.

fromEscapedString

public static Blob fromEscapedString(String escapedString,
                     int beginOffset,
                     int endOffset)

Make a Blob value by decoding the escapedString between beginOffset and endOffset according to the NDN URI Scheme. If the escaped string is "", "." or ".." then return a Blob with a null pointer, which means the component should be skipped in a URI name. This does not check for a type code prefix such as "sha256digest=".

Parameters:

escapedString - The escaped string

beginOffset - The offset in escapedString of the beginning of the portion to decode.

endOffset - The offset in escapedString of the end of the portion to decode.

Returns:

The Blob value. If the escapedString is not a valid escaped component, then the Blob has a null pointer.

fromEscapedString

public static Blob fromEscapedString(String escapedString)

Make a Blob value by decoding the escapedString according to the NDN URI Scheme. If the escaped string is "", "." or ".." then return a Blob with a null pointer, which means the component should be skipped in a URI name. This does not check for a type code prefix such as "sha256digest=".

Parameters:

escapedString - The escaped string.

Returns:

The Blob value. If the escapedString is not a valid escaped component, then the Blob has a null pointer.

toEscapedString

public static void toEscapedString(ByteBuffer value,
                   StringBuffer result)

Write the value to result, escaping characters according to the NDN URI Scheme. This also adds "..." to a value with zero or more ".". This does not add a type code prefix such as "sha256digest=".

Parameters:

value - The ByteBuffer with the value. This reads from position() to limit().

result - The StringBuffer to write to.

toEscapedString

public static String toEscapedString(ByteBuffer value)

Convert the value by escaping characters according to the NDN URI Scheme. This also adds "..." to a value with zero or more ".". This does not add a type code prefix such as "sha256digest=".

Parameters:

value - The ByteBuffer with the value. This reads from position() to limit().

Returns:

The escaped string.

fromHex

public static Blob fromHex(String hexString,
           int beginOffset,
           int endOffset)

Make a Blob value by decoding the hexString between beginOffset and endOffset.

Parameters:

hexString - The hex string.

beginOffset - The offset in hexString of the beginning of the portion to decode.

endOffset - The offset in hexString of the end of the portion to decode.

Returns:

The Blob value. If the hexString is not a valid hex string, then the Blob has a null pointer.