uk.org.blankaspect.nlf
Class Chunk

java.lang.Object
  extended by uk.org.blankaspect.nlf.Chunk
All Implemented Interfaces:
java.lang.Comparable<Chunk>
Direct Known Subclasses:
Attributes, ChunkList

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

This class implements a chunk of a Nested List File. The chunk, which is the primary structural unit of a Nested List File, consists of a header and binary data. The header consists of an identifier and a size field. The identifier field is of variable size, up to 256 bytes; the size of the size field is 8 bytes. The chunk size does not include the size of the header.

A chunk is created with the Document.createChunk(Id) method, and is added to a list with the ChunkList.appendChunk(Chunk) method. A chunk can be added only to a list that belongs to the same document as the chunk.

There are two special chunks: the list and the attributes chunk, which have the reserved identifiers "$LIST" and "$ATTR" respectively.

Since:
1.0
See Also:
ChunkList

Nested Class Summary
static class Chunk.Base64Encoder
          This singleton class implements a Base64 encoder for chunk data.
static interface Chunk.Encoder
          This interface specifies the methods that must be implemented by a class that encodes chunk data as character data for use as a text node of an XML file.
static interface Chunk.Processor
          This interface specifies the method that must be implemented by a class that processes the chunks that are visited in the traversal of a document tree or subtree.
static interface Chunk.Reader
          This interface specifies the methods that must be implemented by a class that reads chunk data from a data input.
static interface Chunk.Writer
          This interface specifies the methods that must be implemented by a class that writes chunk data to a data output.
 
Field Summary
protected  Document document
           
protected  Chunk.Encoder encoder
           
protected  Id id
           
static long MAX_SIZE
           
static long MIN_SIZE
           
protected  ChunkList parent
           
protected  Chunk.Reader reader
           
protected  long size
           
static int SIZE_SIZE
           
protected  Chunk.Writer writer
           
 
Constructor Summary
protected Chunk(Document document, Id id)
          Constructs a chunk with the specified owner document and identifier.
 
Method Summary
 int compareTo(Chunk chunk)
          Compares this chunk with the specified Chunk object.
 Document getDocument()
          Returns the Nested List File document to which this chunk belongs.
 Chunk.Encoder getEncoder()
          Returns the chunk encoder for this chunk.
 int getHeaderSize()
          Returns the size of the chunk header (identifier and size).
 Id getId()
          Returns the identifier of this chunk.
 java.lang.String getName()
          Returns the name of this chunk.
 java.lang.String getNamespaceName()
          Returns the namespace name that applies to this chunk.
 ChunkList getParent()
          Returns the chunk list that contains this chunk, or null if this chunk has no parent.
 java.lang.String getPathname()
          Returns the pathname of this chunk.
 Chunk.Reader getReader()
          Returns the chunk reader for this chunk.
 long getSize()
          Returns the size of this chunk in bytes.
 byte[] getSizeBytes(boolean littleEndian)
          Returns the size of the chunk as an array of bytes, with the specified byte order.
 Chunk.Writer getWriter()
          Returns the chunk writer for this chunk.
 boolean isAttributes()
          Tests whether this chunk is an attributes chunk or a subclass of an attributes chunk.
 boolean isList()
          Tests whether this chunk is a chunk list or a subclass of a chunk list.
 void setEncoder(Chunk.Encoder encoder)
          Sets the chunk encoder for this chunk to the specified encoder.
protected  void setParent(ChunkList list)
          Sets this chunk's parent to the specified list.
 void setReader(Chunk.Reader reader)
          Sets the chunk reader for this chunk to the specified reader.
 void setSize(long size)
          Sets the size of this chunk to the specified value.
 void setWriter(Chunk.Writer writer)
          Sets the chunk writer for this chunk to the specified writer.
 org.w3c.dom.Element toXml(org.w3c.dom.Document xmlDocument)
          Returns this chunk as an XML element of the specified document.
 void updateSize()
          Updates the chunk's size field from the chunk writer, if one has been set.
 void writeHeader(java.io.DataOutput dataOutput)
          Writes the chunk header (identifier and size) to the specified data output.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SIZE_SIZE

public static final int SIZE_SIZE
See Also:
Constant Field Values

MIN_SIZE

public static final long MIN_SIZE
See Also:
Constant Field Values

MAX_SIZE

public static final long MAX_SIZE
See Also:
Constant Field Values

document

protected Document document

parent

protected ChunkList parent

id

protected Id id

size

protected long size

reader

protected Chunk.Reader reader

writer

protected Chunk.Writer writer

encoder

protected Chunk.Encoder encoder
Constructor Detail

Chunk

protected Chunk(Document document,
                Id id)
Constructs a chunk with the specified owner document and identifier. A Base64 encoder is set as the default encoder.

Parameters:
document - the document to which the chunk will belong.
id - the chunk identifier.
Since:
1.0
Method Detail

compareTo

public int compareTo(Chunk chunk)
Compares this chunk with the specified Chunk object. The comparison is performed by comparing the identifiers 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

Because of the restrictions on identifiers, special chunks (ie, chunks with reserved identifiers) will always precede general chunks (ie, chunks with non-reserved identifiers).

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

getDocument

public Document getDocument()
Returns the Nested List File document to which this chunk belongs.

Returns:
the document to which this chunk belongs.
Since:
1.0

getParent

public ChunkList getParent()
Returns the chunk list that contains this chunk, or null if this chunk has no parent.

Returns:
the chunk list that contains this chunk, or null if this chunk has no parent.
Since:
1.0
See Also:
setParent(ChunkList)

getId

public Id getId()
Returns the identifier of this chunk.

Returns:
the identifier of this chunk.
Since:
1.0

getSize

public long getSize()
Returns the size of this chunk in bytes. A value of -1 indicates that the size is invalid and that the size of the chunk should be obtained by another means (eg, from getWriter().getLength()).

Returns:
the size of this chunk.
Since:
1.0
See Also:
setSize(long), updateSize(), Chunk.Writer.getLength()

getReader

public Chunk.Reader getReader()
Returns the chunk reader for this chunk. The reader is used to read the chunk data from a data input, usually a Nested List File document.

Returns:
the chunk reader that will read the data of this chunk.
Since:
1.0
See Also:
setReader(Reader), Chunk.Reader

getWriter

public Chunk.Writer getWriter()
Returns the chunk writer for this chunk. The writer is used to write the chunk data to a data output, usually a Nested List File document.

Returns:
the chunk writer that will write the data of this chunk.
Since:
1.0
See Also:
setWriter(Writer), Chunk.Writer

getEncoder

public Chunk.Encoder getEncoder()
Returns the chunk encoder for this chunk. The encoder is used by toXml(org.w3c.dom.Document) to encode the chunk data for use as a text node of an XML file.

Returns:
the chunk encoder that will encode the data of this chunk.
Since:
1.0
See Also:
setEncoder(Encoder), Chunk.Encoder

setSize

public void setSize(long size)
Sets the size of this chunk to the specified value.

Parameters:
size - the value to which the size of this chunk is to be set.
Since:
1.0
See Also:
getSize(), updateSize()

setReader

public void setReader(Chunk.Reader reader)
Sets the chunk reader for this chunk to the specified reader. The reader is used to read the chunk data from a data input, usually a Nested List File document.

Parameters:
reader - the Reader that is to be this chunk's reader.
Since:
1.0
See Also:
getReader()

setWriter

public void setWriter(Chunk.Writer writer)
Sets the chunk writer for this chunk to the specified writer. The writer is used to write the chunk data to a data output, usually a Nested List File document.

Parameters:
writer - the Writer that is to be this chunk's writer.
Since:
1.0
See Also:
getWriter()

setEncoder

public void setEncoder(Chunk.Encoder encoder)
Sets the chunk encoder for this chunk to the specified encoder. The encoder is used by toXml(org.w3c.dom.Document) to encode the chunk data for use as a text node of an XML file.

Parameters:
encoder - the Encoder that is to be this chunk's encoder.
Since:
1.0
See Also:
getEncoder()

isAttributes

public boolean isAttributes()
Tests whether this chunk is an attributes chunk or a subclass of an attributes chunk.

Returns:
true if this chunk is an attributes chunk or a subclass of an attributes chunk; false otherwise.
Since:
1.0

isList

public boolean isList()
Tests whether this chunk is a chunk list or a subclass of a chunk list.

Returns:
true if this chunk is a chunk list or a subclass of a chunk list; false otherwise.
Since:
1.0

updateSize

public void updateSize()
Updates the chunk's size field from the chunk writer, if one has been set. The chunk size is set to the value returned by the chunk writer's getLength() method.

Since:
1.0
See Also:
getSize(), setSize(long), Chunk.Writer.getLength()

getNamespaceName

public java.lang.String getNamespaceName()
Returns the namespace name that applies to this chunk. A chunk's namespace name is the first non-null local namespace name that is encountered in an ancestor when ascending the document tree. If none of the chunk's ancestors has a local namespace name, null is returned.

Returns:
the namespace name that applies to this chunk, or null if no namespace name applies.
Since:
1.0
See Also:
ChunkList.getNamespaceName()

getName

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

Returns:
the name of this chunk.
Since:
1.0
See Also:
ChunkList.getName()

getPathname

public java.lang.String getPathname()
Returns the pathname of this chunk. A pathname, which might not be unique within a particular document, is formed by concatenating the list-instance identifiers of the ancestors of this chunk with the identifier of this chunk. 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.

Returns:
the pathname of this chunk.
Since:
1.0

getHeaderSize

public int getHeaderSize()
Returns the size of the chunk header (identifier and size).

Returns:
the size of the chunk header (identifier and size).
Since:
1.0

getSizeBytes

public byte[] getSizeBytes(boolean littleEndian)
Returns the size of the chunk as an array of bytes, with the specified byte order.

Parameters:
littleEndian - true if the byte order is little-endian; false if the byte order is big-endian.
Returns:
the size of the chunk as an array of bytes.
Since:
1.0

writeHeader

public void writeHeader(java.io.DataOutput dataOutput)
                 throws java.io.IOException
Writes the chunk header (identifier and size) to the specified data output.

Parameters:
dataOutput - the data output to which the chunk header is to be written.
Throws:
java.io.IOException - if an I/O error occurs.
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 chunk as an XML element of the specified document. The chunk data are obtained from the chunk's reader, and encoded as text with the chunk's encoder. The default encoder is the single instance of Base64Encoder.

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 chunk.
Throws:
org.w3c.dom.DOMException - if an exception occurs in creating the XML element.
java.io.IOException - if an I/O error occurs in reading the chunk data.
NlfException - if
  • an exception occurs in encoding the chunk data, or
  • there is not enough memory to create an XML element.
Since:
1.0

setParent

protected void setParent(ChunkList list)
Sets this chunk's parent to the specified list.

Parameters:
list - the list that is to be this chunk's parent.
Since:
1.0