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 component, using the existing Blob value.
Name	append(byte[] value) Append a new 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	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(Name other) Compare this to the other Name using NDN canonical ordering.
int	compareTo(Object o)
boolean	equals(Object object) Check if this name has the same component count and components as the given name.
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.
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.
int	hashCode()
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	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, toString, 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 component, copying from value.

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 component, using the existing Blob value.

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.

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.

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.

equals

public boolean equals(Object object)

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

Overrides:

equals in class Object

Parameters:

object - The Name to check.

Returns:

true if the object is a Name and the names are equal, otherwise false.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

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.

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 comes before other in the canonical ordering, or 1 if *this comes after other in the canonical ordering. See http://named-data.net/doc/0.2/technical/CanonicalOrder.html

compareTo

public final int compareTo(Object o)

Specified by:

compareTo in interface Comparable

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.

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.

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 ".".

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 ".".

Parameters:

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

Returns:

The escaped string.