|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectuk.org.blankaspect.nlf.Chunk
uk.org.blankaspect.nlf.ChunkList
public class ChunkList
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.
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 |
---|
public static final Id LIST_ID
public static final int NAMESPACE_NAME_SIZE_SIZE
public static final int MIN_NAMESPACE_NAME_SIZE
public static final int MAX_NAMESPACE_NAME_SIZE
protected static final int NAMESPACE_NAME_SIZE_MASK
Constructor Detail |
---|
protected ChunkList(Document document, Id instanceId)
document
- the document to which the list will belong.instanceId
- the list-instance identifier.ChunkList(Document, Id, java.lang.String)
protected ChunkList(Document document, Id instanceId, java.lang.String namespaceName) throws java.lang.IllegalArgumentException
document
- the document to which the list will belong.instanceId
- the list-instance identifier.namespaceName
- the namespace name, which may be null
.
java.lang.IllegalArgumentException
- namespaceName
is not a well-formed URI reference, ornamespaceName
is greater than 65535
bytes.ChunkList(Document, Id)
Method Detail |
---|
public java.lang.String toString()
toString
in class java.lang.Object
public void updateSize()
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.
updateSize
in class Chunk
Chunk.getSize()
,
Chunk.setSize(long)
,
Chunk.Writer.getLength()
public java.lang.String getNamespaceName()
null
is returned.
getNamespaceName
in class Chunk
null
if no namespace name applies.getLocalNamespaceName()
,
setNamespaceName(java.lang.String)
,
Chunk.getNamespaceName()
public java.lang.String getName()
getName
in class Chunk
Chunk.getName()
public java.lang.String getPathname()
getPathname
in class Chunk
public org.w3c.dom.Element toXml(org.w3c.dom.Document xmlDocument) throws org.w3c.dom.DOMException, java.io.IOException, NlfException
toXml
in class Chunk
xmlDocument
- the XML document that is to be the owner of the element that is created.
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
public Id getInstanceId()
public java.lang.String getLocalNamespaceName()
null
if no namespace name is set on the list.
null
if no namespace name is set.getNamespaceName()
,
setNamespaceName(java.lang.String)
public boolean hasChunks()
true
if this list contains at least one chunk; false
otherwise.public int getNumChunks()
public Chunk getChunk(int index) throws java.lang.IndexOutOfBoundsException
java.lang.IndexOutOfBoundsException
- if (index < 0)
or (index >=
getNumChunks()
)
.getNumChunks()
public Attributes getAttributes()
null
if the list does not have an attributes
chunk.
null
if the list does not have an attributes
chunk.createAttributes()
public boolean isRoot()
true
if this list is the root list; false
otherwise.public void setNamespaceName(java.lang.String nsName) throws java.lang.IllegalArgumentException
null
.
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.
java.lang.IllegalArgumentException
- if
nsName
is not a well-formed URI reference, ornsName
is greater than 65535 bytes.getLocalNamespaceName()
,
getNamespaceName()
public int getNamespaceNameSize()
0
if the list does not have a local namespace name.getNamespaceNameFieldSize()
public int getNamespaceNameFieldSize()
getNamespaceNameSize()
public byte[] getNamespaceNameBytes(boolean littleEndian)
littleEndian
- true
if the byte order of the size bytes is little-endian; false
if the byte order is big-endian.
public void appendChunk(Chunk chunk) throws java.lang.IllegalArgumentException, NlfUncheckedException
chunk
- the chunk that is to be added to the end of the list.
java.lang.IllegalArgumentException
- if chunk
is null
.
NlfUncheckedException
- if
chunk
belong to different documents, orchunk
to this list would violate the list hierarchy because
chunk
is this list or an ancestor of this list.public Chunk removeChunk(int index) throws java.lang.IndexOutOfBoundsException
parent
field set to null
to indicate that it has
no parent.
index
- the index of the chunk that is to be removed from the list.
java.lang.IndexOutOfBoundsException
- if (index < 0)
or (index >=
getNumChunks()
)
.appendChunk(Chunk)
,
getNumChunks()
public int firstIndexOf(Id id)
-1
if no chunk with the specified identifier is found.
id
- the identifier that is to be searched for.
id
in this list, or
-1
if no chunk with the identifier id
is found.firstIndexOf(Id, int)
,
lastIndexOf(Id)
,
lastIndexOf(Id, int)
public int firstIndexOf(Id id, int startIndex)
-1
if no chunk with the specified identifier is found.
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.
id
in this list,
starting from startIndex
, or -1
if no chunk with the identifier id
is
found.firstIndexOf(Id)
,
lastIndexOf(Id)
,
lastIndexOf(Id, int)
public int lastIndexOf(Id id)
-1
if no chunk with the specified identifier is found.
id
- the identifier that is to be searched for.
id
in this list, or
-1
if no chunk with the identifier id
is found.firstIndexOf(Id)
,
firstIndexOf(Id, int)
,
lastIndexOf(Id, int)
public int lastIndexOf(Id id, int endIndex)
-1
if no chunk with the specified identifier is found.
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.
id
in this list,
ending at endIndex
, or -1
if no chunk with the identifier id
is
found.firstIndexOf(Id)
,
firstIndexOf(Id, int)
,
lastIndexOf(Id)
public Attributes createAttributes()
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.
null
if the list already has
an attributes chunk.public void writeHeaderExtension(java.io.DataOutput dataOutput) throws java.io.IOException
dataOutput
- the data output to which the list-header extension is to be written.
java.io.IOException
- if an I/O error occurs.public void processChunks(NlfConstants.TraversalOrder traversalOrder, Chunk.Processor processor) throws TerminatedException
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.
java.lang.IllegalArgumentException
- if traversalOrder
is null
or processor
is null
.
TerminatedException
- if the traversal of the tree is terminated.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
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.
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
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |