uk.org.blankaspect.nlf
Class Id

java.lang.Object
  extended by uk.org.blankaspect.nlf.Id
All Implemented Interfaces:
java.lang.Comparable<Id>

public class Id
extends java.lang.Object
implements java.lang.Comparable<Id>

This class implements an identifier that is used to identify the chunks in a Nested List File. An identifier is a string that is encoded as a size byte followed by a UTF-8 sequence. The size of the UTF-8 sequence must be between 1 and 255 bytes.

Identifiers that start with the '$' character (U+0024) are reserved.

To allow the conversion of a Nested List File to XML, a non-reserved identifer must be a valid unprefixed name (ie, a name that doesn't contain a ':') under XML 1.1. Note that XML 1.1 names are less restrictive than those of XML 1.0, so that a name that is valid under XML 1.1 might not be valid under XML 1.0.

Since:
1.0

Field Summary
static int MAX_SIZE
           
static int MIN_SIZE
           
static java.lang.String RESERVED_PREFIX
           
static char RESERVED_PREFIX_CHAR
           
protected static int SIZE_MASK
           
static int SIZE_SIZE
           
 
Constructor Summary
Id(byte[] bytes)
          Constructs an identifier from an array of bytes.
Id(byte[] bytes, int offset)
          Constructs an identifier from an array of bytes, starting at the specified offset.
Id(java.lang.String str)
          Constructs an identifier from a string.
 
Method Summary
 int compareTo(Id id)
          Compares this identifier with the specified Id object.
 boolean equals(java.lang.Object obj)
          Compares this identifier with the specified object.
 byte[] getBytes()
          Returns the encoded form of the identifier (a size byte followed by a UTF-8 sequence) as an array of bytes.
 int getFieldSize()
          Returns the size of the field that the identifier would occupy in a Nested List File.
 int getSize()
          Returns the size of the identifier when it is encoded as a UTF-8 sequence.
static int getSize(byte[] bytes, int offset)
          Returns the size of an identifier that is encoded in an array of bytes at a specified offset.
 java.lang.String getValue()
          Returns the value of the identifier.
 int hashCode()
          Returns the hash code for this object.
 boolean isReserved()
          Tests whether an identifier is reserved (ie, whether it starts with the reserved prefix).
static boolean isValidId(java.lang.String str)
          Tests whether the specified string is a valid identifier.
 java.lang.String toName(java.lang.String prefix)
          Converts this identifier to a name, using the specified prefix.
 java.lang.String toString()
          Returns the identifier as a string.
 void write(java.io.DataOutput dataOutput)
          Writes the encoded form of the identifier (a size byte followed by a UTF-8 sequence) to the specified data output (an instance of java.io.DataOuput).
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

SIZE_SIZE

public static final int SIZE_SIZE
See Also:
Constant Field Values

MIN_SIZE

public static final int MIN_SIZE
See Also:
Constant Field Values

MAX_SIZE

public static final int MAX_SIZE
See Also:
Constant Field Values

SIZE_MASK

protected static final int SIZE_MASK
See Also:
Constant Field Values

RESERVED_PREFIX_CHAR

public static final char RESERVED_PREFIX_CHAR
See Also:
Constant Field Values

RESERVED_PREFIX

public static final java.lang.String RESERVED_PREFIX
Constructor Detail

Id

public Id(byte[] bytes)
   throws java.lang.IllegalArgumentException
Constructs an identifier from an array of bytes. The bytes are expected to be in the form in which an identifier appears in a Nested List File: the first byte is the length of the UTF-8 sequence that follows. The UTF-8 sequence is an encoding of the value of the identifier.

Parameters:
bytes - the array of bytes from which the identifier is constructed. The first byte of the array is the size of the UTF-8 sequence that follows.
Throws:
java.lang.IllegalArgumentException - if
  • the first byte of bytes is zero, or
  • the bytes starting at bytes[1] are not a valid UTF-8 sequence, or
  • the UTF-8 sequence, when decoded, is not a valid identifier.
Since:
1.0

Id

public Id(byte[] bytes,
          int offset)
   throws java.lang.IllegalArgumentException
Constructs an identifier from an array of bytes, starting at the specified offset. The bytes are expected to be in the form in which an identifier appears in a Nested List File: the byte at offset is the length of the UTF-8 sequence that follows. The UTF-8 sequence is an encoding of the value of the identifier.

Parameters:
bytes - the array of bytes from which the identifier is constructed. The byte of the array at offset is the size of the UTF-8 sequence that follows.
offset - the offset to bytes at which the identifier begins.
Throws:
java.lang.IllegalArgumentException - if
  • the byte of bytes at offset is zero, or
  • the bytes starting at bytes[offset+1] are not a valid UTF-8 sequence, or
  • the UTF-8 sequence, when decoded, is not a valid identifier.
Since:
1.0

Id

public Id(java.lang.String str)
   throws java.lang.IllegalArgumentException
Constructs an identifier from a string.

Parameters:
str - the string from which the identifier is constructed.
Throws:
java.lang.IllegalArgumentException - if
  • the string is empty, or
  • the UTF-8 encoding of the string is longer than 255 bytes, or
  • the string contains an invalid character.
Since:
1.0
Method Detail

getSize

public static int getSize(byte[] bytes,
                          int offset)
Returns the size of an identifier that is encoded in an array of bytes at a specified offset.

Parameters:
bytes - the array of bytes that contains the encoded identifier.
offset - the offset to bytes at which the identifier begins.
Returns:
the size of the encoded identifier (ie, the value of the byte of bytes at offset).
Since:
1.0

isValidId

public static boolean isValidId(java.lang.String str)
Tests whether the specified string is a valid identifier. A non-reserved identifier is valid if it is a valid unprefixed name (ie, a name that doesn't contain a ':') under XML 1.1.

Parameters:
str - the string that is to be tested.
Returns:
true the specified string is a valid identifier; false otherwise.
Since:
1.0

compareTo

public int compareTo(Id id)
Compares this identifier with the specified Id object. The comparison is performed by comparing the values of the two objects using java.lang.String.compareTo(java.lang.String), which compares strings lexicographically by the Unicode value of each character in the strings.

The result is

A result of zero implies that the equals(Object) method would return true.

Because of the restrictions on the characters in an identifier, reserved identifiers will always precede non-reserved identifiers.

Specified by:
compareTo in interface java.lang.Comparable<Id>
Parameters:
id - the Id object with which the comparison is to be made.
Returns:
  • 0 (zero) if the value of this identifier is equal to the value of id;
  • a value less than 0 if the value of this identifier is lexicographically less than the value of id;
  • a value greater than 0 if the value of this identifier is lexicographically greater than the value of id.
Since:
1.0

equals

public boolean equals(java.lang.Object obj)
Compares this identifier with the specified object. The result is true if and only if obj is an Id object that has the same value as this identifier.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the object with which the comparison is to be made.
Returns:
true if the objects have the same value; false otherwise.
Since:
1.0

hashCode

public int hashCode()
Returns the hash code for this object.

Overrides:
hashCode in class java.lang.Object
Returns:
the hash code for this object.
Since:
1.1
See Also:
equals(Object)

toString

public java.lang.String toString()
Returns the identifier as a string. The string is just the value of the identifier (ie, the value returned by getValue() ).

Overrides:
toString in class java.lang.Object
Returns:
the identifier as a string.
Since:
1.0
See Also:
getValue()

getValue

public java.lang.String getValue()
Returns the value of the identifier.

Returns:
the value of the identifier.
Since:
1.0

getSize

public int getSize()
Returns the size of the identifier when it is encoded as a UTF-8 sequence. The size does not include the initial size byte.

Returns:
the size of the UTF-8 encoding of identifier.
Since:
1.0
See Also:
getFieldSize()

getFieldSize

public int getFieldSize()
Returns the size of the field that the identifier would occupy in a Nested List File. The size includes the initial size byte and the UTF-8 encoding of the identifier.

Returns:
the size of the UTF-8 encoding of the identifier, including the initial size byte.
Since:
1.0
See Also:
getSize()

isReserved

public boolean isReserved()
Tests whether an identifier is reserved (ie, whether it starts with the reserved prefix).

Returns:
true if the identifier is reserved; false otherwise.
Since:
1.0

toName

public java.lang.String toName(java.lang.String prefix)
Converts this identifier to a name, using the specified prefix. The name is formed from the prefix and the value of the identifier: if the prefix is null, this method returns the string that is returned by getValue(); otherwise, it returns the concatenation of the prefix, a vertical line character (U+007C) and the string that is returned by getValue().

Parameters:
prefix - the prefix that is to be used to form the name.
Returns:
a string formed from the specified prefix and the value of this identifier.
Since:
1.0

getBytes

public byte[] getBytes()
Returns the encoded form of the identifier (a size byte followed by a UTF-8 sequence) as an array of bytes.

Returns:
a byte array containing the encoded form of the identifier: a size byte followed by a UTF-8 sequence.
Since:
1.0

write

public void write(java.io.DataOutput dataOutput)
           throws java.io.IOException
Writes the encoded form of the identifier (a size byte followed by a UTF-8 sequence) to the specified data output (an instance of java.io.DataOuput).

Parameters:
dataOutput - the data output to which the encoded form of the identifier (a size byte followed by a UTF-8 sequence) is to be written.
Throws:
java.io.IOException - if an I/O error occurs.
Since:
1.0
See Also:
getBytes()