uk.org.blankaspect.nlf
Class ChunkList

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

public class ChunkList
extends Chunk

This class implements a chunk list: a special chunk that contains other chunks. Objects of this class act as the branch nodes in the tree structure of a Nested List File. Lists may be nested: a list may contain other lists, which gives rise to the name "Nested List File". At the top level of the list hierarchy is the root list, which contains everything in an NLF apart from the file header.

A list has the standard chunk header, with the reserved identifier $LIST, and list-header extension, which consists of a list-instance identifier -- an additional identifier that denotes the instance of a list -- and an optional namespace name. In the list-header extension, the namespace name is encoded as two size bytes followed by a UTF-8 sequence. The byte order of the size bytes is determined by the byte-order flag in the header of the Nested List File document to which the list belongs. The maximum size of a namespace name is 65535 bytes.

A namespace name, which must be a well-formed URI reference, may be set on a list in order to declare a namespace whose scope is the list itself and its descendants. A namespace name that is set on a list is referred to as the list's local namespace name to distinguish it from a list's namespace name, which is either its local namespace name, or, if it has no local namespace name, the namespace name of its parent.

A list is created by the Document.createList(Id) method. The root list of a document is created by the Document.createRootList(Id) method.

Since:
1.0
See Also:
Chunk

Nested Class Summary
 
Nested classes/interfaces inherited from class uk.org.blankaspect.nlf.Chunk
Chunk.Base64Encoder, Chunk.Encoder, Chunk.Processor, Chunk.Reader, Chunk.Writer
 
Field Summary
static Id LIST_ID
           
static int MAX_NAMESPACE_NAME_SIZE
           
static int MIN_NAMESPACE_NAME_SIZE
           
protected static int NAMESPACE_NAME_SIZE_MASK
           
static int NAMESPACE_NAME_SIZE_SIZE
           
 
Fields inherited from class uk.org.blankaspect.nlf.Chunk
document, encoder, id, MAX_SIZE, MIN_SIZE, parent, reader, size, SIZE_SIZE, writer
 
Constructor Summary
protected ChunkList(Document document, Id instanceId)
          Constructs a chunk list with the specified owner document and list-instance identifier.
protected ChunkList(Document document, Id instanceId, java.lang.String namespaceName)
          Constructs a chunk list with the specified owner document, list-instance identifier and local namespace name.
 
Method Summary
 void appendChunk(Chunk chunk)
          Adds the specified chunk to the end of this chunk list.
 Attributes createAttributes()
          Creates an attributes chunk for this list, if the list does not already have one.
 int firstIndexOf(Id id)
          Returns the index of the first occurrence of a chunk with the specified identifier in this list, or -1 if no chunk with the specified identifier is found.
 int firstIndexOf(Id id, int startIndex)
          Returns the index of the first occurrence of a chunk with the specified identifier in this list, starting from the specified index, or -1 if no chunk with the specified identifier is found.
 Attributes getAttributes()
          Returns the attributes chunk from the list, or null if the list does not have an attributes chunk.
 Chunk getChunk(int index)
          Returns the chunk at the specified index in the list.
 Id getInstanceId()
          Returns the list-instance identifier.
 java.lang.String getLocalNamespaceName()
          Returns the local namespace name of this list (ie, the namespace name that is set on the list), or null if no namespace name is set on the list.
 java.lang.String getName()
          Returns the name of this list.
 java.lang.String getNamespaceName()
          Returns the namespace name that applies to this list, which is the list's local namespace name (ie, the namespace name that is set on the list), or, if the list does not have a local namespace name, the namespace name of the list's parent.
 byte[] getNamespaceNameBytes(boolean littleEndian)
          Returns the encoded form of the list's local namespace name (two size bytes followed by a UTF-8 sequence) as an array of bytes.
 int getNamespaceNameFieldSize()
          Returns the size of the field that this list's local namespace name would occupy in a Nested List File.
 int getNamespaceNameSize()
          Returns the size of this list's local namespace name when it is encoded as a UTF-8 sequence.
 int getNumChunks()
          Returns the number of chunks in the list.
 java.lang.String getPathname()
          Returns the pathname of this list.
 boolean hasChunks()
          Tests whether this list contains chunks.
 boolean isRoot()
          Tests whether this list is the root list of the document to which it belongs.
 int lastIndexOf(Id id)
          Returns the index of the last occurrence of a chunk with the specified identifier in this list, or -1 if no chunk with the specified identifier is found.
 int lastIndexOf(Id id, int endIndex)
          Returns the index of the last occurrence of a chunk with the specified identifier in this list, ending at the specified index, or -1 if no chunk with the specified identifier is found.
 void processChunks(NlfConstants.TraversalOrder traversalOrder, Chunk.Processor processor)
          Traverses the document subtree in the specified order, starting at this list and calling the specified chunk processor on each chunk that is visited.
 Chunk removeChunk(int index)
          Removes the chunk at the specified index from the chunk list, and returns the chunk that was removed.
 void setNamespaceName(java.lang.String nsName)
          Sets the local namespace name of this list to the specified string, which may be null.
 java.lang.String toString()
          Returns a string representation of this chunk list.
 org.w3c.dom.Element toXml(org.w3c.dom.Document xmlDocument)
          Returns this list as an XML element of the specified document.
protected  org.w3c.dom.Element toXml(org.w3c.dom.Document xmlDocument, org.w3c.dom.Element element)
          Returns this list as an XML element of the specified document.
 void updateSize()
          Updates the list's size field.
 void writeHeaderExtension(java.io.DataOutput dataOutput)
          Writes the list-header extension (list-instance identifier and namespace name) to the specified data output.
 
Methods inherited from class uk.org.blankaspect.nlf.Chunk
compareTo, getDocument, getEncoder, getHeaderSize, getId, getParent, getReader, getSize, getSizeBytes, getWriter, isAttributes, isList, setEncoder, setParent, setReader, setSize, setWriter, writeHeader
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LIST_ID

public static final Id LIST_ID

NAMESPACE_NAME_SIZE_SIZE

public static final int NAMESPACE_NAME_SIZE_SIZE
See Also:
Constant Field Values

MIN_NAMESPACE_NAME_SIZE

public static final int MIN_NAMESPACE_NAME_SIZE
See Also:
Constant Field Values

MAX_NAMESPACE_NAME_SIZE

public static final int MAX_NAMESPACE_NAME_SIZE
See Also:
Constant Field Values

NAMESPACE_NAME_SIZE_MASK

protected static final int NAMESPACE_NAME_SIZE_MASK
See Also:
Constant Field Values
Constructor Detail

ChunkList

protected ChunkList(Document document,
                    Id instanceId)
Constructs a chunk list with the specified owner document and list-instance identifier. The list will not have a local namespace name.

Parameters:
document - the document to which the list will belong.
instanceId - the list-instance identifier.
Since:
1.0
See Also:
ChunkList(Document, Id, java.lang.String)

ChunkList

protected ChunkList(Document document,
                    Id instanceId,
                    java.lang.String namespaceName)
             throws java.lang.IllegalArgumentException
Constructs a chunk list with the specified owner document, list-instance identifier and local namespace name.

Parameters:
document - the document to which the list will belong.
instanceId - the list-instance identifier.
namespaceName - the namespace name, which may be null.
Throws:
java.lang.IllegalArgumentException -
  • namespaceName is not a well-formed URI reference, or
  • the length of the UTF-8 encoding of namespaceName is greater than 65535 bytes.
Since:
1.0
See Also:
ChunkList(Document, Id)
Method Detail

toString

public java.lang.String toString()
Returns a string representation of this chunk list. The string consists of the list-instance identifier and the local namespace name, if one has been set, separated with a comma and a space.

Overrides:
toString in class java.lang.Object
Returns:
a string consisting of the list-instance identifier and the local namespace name, if one has been set, separated with a comma and a space.
Since:
1.0

updateSize

public void updateSize()
Updates the list's size field. The size is set to the sum of the field size of the list-instance identifier, the field size of the namespace name and the sizes of the chunks in the list. Chunk.updateSize() is called on each of the chunks in the list before its size is added to the size of this list.

Overrides:
updateSize in class Chunk
Since:
1.0
See Also:
Chunk.getSize(), Chunk.setSize(long), Chunk.Writer.getLength()

getNamespaceName

public java.lang.String getNamespaceName()
Returns the namespace name that applies to this list, which is the list's local namespace name (ie, the namespace name that is set on the list), or, if the list does not have a local namespace name, the namespace name of the list's parent. If none of the list's ancestors has a local namespace name, null is returned.

Overrides:
getNamespaceName in class Chunk
Returns:
the namespace name that applies to this list, or null if no namespace name applies.
Since:
1.0
See Also:
getLocalNamespaceName(), setNamespaceName(java.lang.String), Chunk.getNamespaceName()

getName

public java.lang.String getName()
Returns the name of this list. A list's name is formed by prefixing its namespace name and a vertical line character (U+007C) to its list-instance identifier. If the list has no namespace name, its name is just its list-instance identifier.

Overrides:
getName in class Chunk
Returns:
the name of this list.
Since:
1.0
See Also:
Chunk.getName()

getPathname

public java.lang.String getPathname()
Returns the pathname of this list. A pathname, which might not be unique within a particular document, is formed by concatenating the list-instance identifiers of the ancestors of this list with the list-instance identifier of this list. The components of the pathname (ie, the identifiers) are separated with '.' (U+002E). The pathname has a leading '.' if its first component is not the root list.

Overrides:
getPathname in class Chunk
Returns:
the pathname of this list.
Since:
1.0

toXml

public org.w3c.dom.Element toXml(org.w3c.dom.Document xmlDocument)
                          throws org.w3c.dom.DOMException,
                                 java.io.IOException,
                                 NlfException
Returns this list as an XML element of the specified document.

Overrides:
toXml in class Chunk
Parameters:
xmlDocument - the XML document that is to be the owner of the element that is created.
Returns:
the XML element that is generated from this list.
Throws:
org.w3c.dom.DOMException - if an exception occurs in creating the XML element or one of its child elements.
java.io.IOException - if an I/O error occurs in reading chunk data.
NlfException - if
  • an exception occurs in encoding chunk data, or
  • there is not enough memory to create an XML element.
Since:
1.0

getInstanceId

public Id getInstanceId()
Returns the list-instance identifier.

Returns:
the list-instance identifier.
Since:
1.0

getLocalNamespaceName

public java.lang.String getLocalNamespaceName()
Returns the local namespace name of this list (ie, the namespace name that is set on the list), or null if no namespace name is set on the list.

Returns:
the local namespace name of this list: the namespace name that is set on this list, or null if no namespace name is set.
Since:
1.0
See Also:
getNamespaceName(), setNamespaceName(java.lang.String)

hasChunks

public boolean hasChunks()
Tests whether this list contains chunks.

Returns:
true if this list contains at least one chunk; false otherwise.
Since:
1.0

getNumChunks

public int getNumChunks()
Returns the number of chunks in the list.

Returns:
the number of chunks in the list.
Since:
1.0

getChunk

public Chunk getChunk(int index)
               throws java.lang.IndexOutOfBoundsException
Returns the chunk at the specified index in the list.

Returns:
the chunk at the specified index in the list.
Throws:
java.lang.IndexOutOfBoundsException - if (index < 0) or (index >= getNumChunks()).
Since:
1.0
See Also:
getNumChunks()

getAttributes

public Attributes getAttributes()
Returns the attributes chunk from the list, or null if the list does not have an attributes chunk.

Returns:
the attributes chunk from the list, or null if the list does not have an attributes chunk.
Since:
1.0
See Also:
createAttributes()

isRoot

public boolean isRoot()
Tests whether this list is the root list of the document to which it belongs.

Returns:
true if this list is the root list; false otherwise.
Since:
1.0

setNamespaceName

public void setNamespaceName(java.lang.String nsName)
                      throws java.lang.IllegalArgumentException
Sets the local namespace name of this list to the specified string, which may be null.

Parameters:
nsName - the string to which the local namespace name of this list is to be set. If nsName is null or an empty string, the list will not have a local namespace name.
Throws:
java.lang.IllegalArgumentException - if
  • nsName is not a well-formed URI reference, or
  • the length of the UTF-8 encoding of nsName is greater than 65535 bytes.
Since:
1.0
See Also:
getLocalNamespaceName(), getNamespaceName()

getNamespaceNameSize

public int getNamespaceNameSize()
Returns the size of this list's local namespace name when it is encoded as a UTF-8 sequence. The size does not include the initial size bytes.

Returns:
the size of this list's local namespace name when it is encoded as a UTF-8 sequence, or 0 if the list does not have a local namespace name.
Since:
1.0
See Also:
getNamespaceNameFieldSize()

getNamespaceNameFieldSize

public int getNamespaceNameFieldSize()
Returns the size of the field that this list's local namespace name would occupy in a Nested List File. The size includes the initial size bytes and the UTF-8 encoding of the namespace name.

Returns:
the size of the UTF-8 encoding of this list's local namespace name, including the initial size bytes.
Since:
1.0
See Also:
getNamespaceNameSize()

getNamespaceNameBytes

public byte[] getNamespaceNameBytes(boolean littleEndian)
Returns the encoded form of the list's local namespace name (two size bytes followed by a UTF-8 sequence) as an array of bytes.

Parameters:
littleEndian - true if the byte order of the size bytes is little-endian; false if the byte order is big-endian.
Returns:
a byte array containing the encoded form of the list's local namespace name: two size bytes followed by a UTF-8 sequence.
Since:
1.0

appendChunk

public void appendChunk(Chunk chunk)
                 throws java.lang.IllegalArgumentException,
                        NlfUncheckedException
Adds the specified chunk to the end of this chunk list. The chunk is not added to the list if it and the list belong to different documents. Also, the chunk is not added to the list if its inclusion would violate the list hierarchy, either by adding a list to itself or by adding an ancestor of the list to the list. If the chunk is already in the list, it will be removed and then added to the end of the list.

Parameters:
chunk - the chunk that is to be added to the end of the list.
Throws:
java.lang.IllegalArgumentException - if chunk is null.
NlfUncheckedException - if
  • this list and chunk belong to different documents, or
  • adding chunk to this list would violate the list hierarchy because chunk is this list or an ancestor of this list.
Since:
1.0

removeChunk

public Chunk removeChunk(int index)
                  throws java.lang.IndexOutOfBoundsException
Removes the chunk at the specified index from the chunk list, and returns the chunk that was removed. The chunk that is returned has its parent field set to null to indicate that it has no parent.

Parameters:
index - the index of the chunk that is to be removed from the list.
Throws:
java.lang.IndexOutOfBoundsException - if (index < 0) or (index >= getNumChunks()).
Since:
1.0
See Also:
appendChunk(Chunk), getNumChunks()

firstIndexOf

public int firstIndexOf(Id id)
Returns the index of the first occurrence of a chunk with the specified identifier in this list, or -1 if no chunk with the specified identifier is found.

Parameters:
id - the identifier that is to be searched for.
Returns:
the index of the first occurrence of a chunk with the identifier id in this list, or -1 if no chunk with the identifier id is found.
Since:
1.0
See Also:
firstIndexOf(Id, int), lastIndexOf(Id), lastIndexOf(Id, int)

firstIndexOf

public int firstIndexOf(Id id,
                        int startIndex)
Returns the index of the first occurrence of a chunk with the specified identifier in this list, starting from the specified index, or -1 if no chunk with the specified identifier is found.

Parameters:
id - the identifier that is to be searched for.
startIndex - the index from which the search is to start. The index may be outside the bounds of the list.
Returns:
the index of the first occurrence of a chunk with the identifier id in this list, starting from startIndex, or -1 if no chunk with the identifier id is found.
Since:
1.0
See Also:
firstIndexOf(Id), lastIndexOf(Id), lastIndexOf(Id, int)

lastIndexOf

public int lastIndexOf(Id id)
Returns the index of the last occurrence of a chunk with the specified identifier in this list, or -1 if no chunk with the specified identifier is found.

Parameters:
id - the identifier that is to be searched for.
Returns:
the index of the last occurrence of a chunk with the identifier id in this list, or -1 if no chunk with the identifier id is found.
Since:
1.0
See Also:
firstIndexOf(Id), firstIndexOf(Id, int), lastIndexOf(Id, int)

lastIndexOf

public int lastIndexOf(Id id,
                       int endIndex)
Returns the index of the last occurrence of a chunk with the specified identifier in this list, ending at the specified index, or -1 if no chunk with the specified identifier is found.

Parameters:
id - the identifier that is to be searched for.
endIndex - the index at which the search is to end. The index may be outside the bounds of the list.
Returns:
the index of the last occurrence of a chunk with the identifier id in this list, ending at endIndex, or -1 if no chunk with the identifier id is found.
Since:
1.0
See Also:
firstIndexOf(Id), firstIndexOf(Id, int), lastIndexOf(Id)

createAttributes

public Attributes createAttributes()
Creates an attributes chunk for this list, if the list does not already have one. If an attributes chunk is created, it is returned; otherwise null is returned. An attributes chunk is added at the start of the list, so that it is always the first chunk in the list.

Returns:
the attributes chunk that was created for this list, or null if the list already has an attributes chunk.
Since:
1.0

writeHeaderExtension

public void writeHeaderExtension(java.io.DataOutput dataOutput)
                          throws java.io.IOException
Writes the list-header extension (list-instance identifier and namespace name) to the specified data output.

Parameters:
dataOutput - the data output to which the list-header extension is to be written.
Throws:
java.io.IOException - if an I/O error occurs.
Since:
1.0

processChunks

public void processChunks(NlfConstants.TraversalOrder traversalOrder,
                          Chunk.Processor processor)
                   throws TerminatedException
Traverses the document subtree in the specified order, starting at this list and calling the specified chunk processor on each chunk that is visited.

Parameters:
traversalOrder - the order, breadth-first or depth-first, in which the tree is to be traversed.
processor - the processor that is to be called on each chunk that is visited.
Throws:
java.lang.IllegalArgumentException - if traversalOrder is null or processor is null.
TerminatedException - if the traversal of the tree is terminated.
Since:
1.0

toXml

protected org.w3c.dom.Element toXml(org.w3c.dom.Document xmlDocument,
                                    org.w3c.dom.Element element)
                             throws org.w3c.dom.DOMException,
                                    java.io.IOException,
                                    NlfException
Returns this list as an XML element of the specified document.

Parameters:
xmlDocument - the XML document that is to be the owner of the element that is created.
element - the XML element that is to be generated, or null if a new element should be created.
Returns:
the XML element that is generated from this list.
Throws:
org.w3c.dom.DOMException - if an exception occurs in creating the XML element or one of its child elements.
java.io.IOException - if an I/O error occurs in reading chunk data.
NlfException - if
  • an exception occurs in encoding chunk data, or
  • there is not enough memory to create an XML element.
Since:
1.0