uk.org.blankaspect.nlf
Class Attributes

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

public class Attributes
extends Chunk

This class implements an attributes chunk. An attributes chunk is a special chunk in a Nested List File. A chunk list may contain one attributes chunk, which has the reserved identifier $ATTR and consists of a list of name-value pairs, analogous to the attributes of an element in an XML document. The names of the attributes in an attributes list must be unique. In a Nested List File, the name and value of an attribute are each 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 chunk belongs. The maximum size of a name or value is 65535 bytes.

To allow the conversion of a Nested List File to XML, an attribute name must be 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.

When an attributes chunk is constructed, its chunk writer is set to a default writer, which is suitable for use by Document.write(java.io.File). The default writer may be replaced, using Chunk.setWriter(Chunk.Writer), if it is unsuitable for a particular purpose. The rewrite flag, which is accessed with isRewrite() and setRewrite(boolean), is used by the default writer to indicate to the document writer whether the attributes chunk should be rewritten on the second pass (for example, if an attribute value can be set only after subsequent chunks have been written).

Since:
1.0
See Also:
Chunk, ChunkList

Nested Class Summary
static class Attributes.Attr
          This class implements an attribute name-value pair.
 
Nested classes/interfaces inherited from class uk.org.blankaspect.nlf.Chunk
Chunk.Base64Encoder, Chunk.Encoder, Chunk.Processor, Chunk.Reader
 
Field Summary
static Id ATTRIBUTES_ID
           
static int MAX_NAME_SIZE
           
static int MAX_VALUE_SIZE
           
static int MIN_NAME_SIZE
           
static int MIN_VALUE_SIZE
           
protected static int NAME_SIZE_MASK
           
static int NAME_SIZE_SIZE
           
protected static int VALUE_SIZE_MASK
           
static int VALUE_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 Attributes(Document document)
          Constructs an attributes chunk.
 
Method Summary
 boolean equals(java.lang.Object obj)
          Compares this attributes chunk with a specified object.
 Attributes.Attr getAttribute(int index)
          Returns the attribute at the specified index in the attributes list.
 int getNumAttributes()
          Returns the number of attributes in this chunk's attributes list.
 boolean hasAttributes()
          Returns true if this chunk contains at least one attribute.
 int hashCode()
          Returns the hash code for this object.
 int indexOf(java.lang.String name)
          Returns the index of the attribute with the specified name in this chunk's attributes list, or -1 if the list does not contain an attribute with the specified name.
 boolean isRewrite()
          Returns true if the attributes will be rewritten on the second pass of the document writer.
static boolean isValidName(java.lang.String str)
          Tests whether the specified string is a valid attribute name.
 Attributes.Attr removeAttribute(int index)
          Removes the attribute at the specified index from this chunk's attributes list, and returns the attribute that was removed.
 void setAttribute(Attributes.Attr attribute)
          Sets the specified attribute in this chunk's attributes list.
 void setRewrite(boolean rewrite)
          Sets the flag that indicates whether the attributes will be rewritten on the second pass of the document writer.
 java.lang.String toString()
          Returns a string representation of the attributes chunk.
protected  void toXml(org.w3c.dom.Element element)
          Sets the attributes in this chunk's attributes list as attributes of the specified XML element.
 
Methods inherited from class uk.org.blankaspect.nlf.Chunk
compareTo, getDocument, getEncoder, getHeaderSize, getId, getName, getNamespaceName, getParent, getPathname, getReader, getSize, getSizeBytes, getWriter, isAttributes, isList, setEncoder, setParent, setReader, setSize, setWriter, toXml, updateSize, writeHeader
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ATTRIBUTES_ID

public static final Id ATTRIBUTES_ID

NAME_SIZE_SIZE

public static final int NAME_SIZE_SIZE
See Also:
Constant Field Values

MIN_NAME_SIZE

public static final int MIN_NAME_SIZE
See Also:
Constant Field Values

MAX_NAME_SIZE

public static final int MAX_NAME_SIZE
See Also:
Constant Field Values

NAME_SIZE_MASK

protected static final int NAME_SIZE_MASK
See Also:
Constant Field Values

VALUE_SIZE_SIZE

public static final int VALUE_SIZE_SIZE
See Also:
Constant Field Values

MIN_VALUE_SIZE

public static final int MIN_VALUE_SIZE
See Also:
Constant Field Values

MAX_VALUE_SIZE

public static final int MAX_VALUE_SIZE
See Also:
Constant Field Values

VALUE_SIZE_MASK

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

Attributes

protected Attributes(Document document)
Constructs an attributes chunk. An attributes chunk can be constructed only by the list to which it belongs. A list can contain no more than one attributes chunk.

The chunk writer for this chunk is set to a default chunk writer when an Attributes object is constructed. The default writer may be replaced by the base-class method Chunk.setWriter(Chunk.Writer).

Parameters:
document - the document to which this chunk is to belong.
Since:
1.0
Method Detail

isValidName

public static boolean isValidName(java.lang.String str)
Tests whether the specified string is a valid attribute name. An attribute name 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 if the specified string is a valid attribute name; false otherwise.
Since:
1.0

equals

public boolean equals(java.lang.Object obj)
Compares this attributes chunk with a specified object. The result is true if and only if obj is an Attributes object that contains the same attributes as this object, though not necessarily in the same order.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the object with which the comparison is to be made.
Returns:
true if obj is an Attributes object that contains the same attributes as this object, though not necessarily in the same order; 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 a string representation of the attributes chunk. Each attribute in the attributes list is in the form name="value", and attributes are separated with a comma and a space.

Overrides:
toString in class java.lang.Object
Returns:
the attributes chunk as a string, with each attribute in the form name="value", and attributes separated with a comma and a space.
Since:
1.0
See Also:
Attributes.Attr.toString()

isRewrite

public boolean isRewrite()
Returns true if the attributes will be rewritten on the second pass of the document writer.

Returns:
true if the attributes will be rewritten on the second pass of the document writer; false otherwise.
Since:
1.0
See Also:
setRewrite(boolean)

hasAttributes

public boolean hasAttributes()
Returns true if this chunk contains at least one attribute.

Returns:
true if this chunk contains at least one attribute; false otherwise.
Since:
1.0
See Also:
getNumAttributes()

getNumAttributes

public int getNumAttributes()
Returns the number of attributes in this chunk's attributes list.

Returns:
the number of attributes in this chunk's attributes list.
Since:
1.0
See Also:
hasAttributes()

getAttribute

public Attributes.Attr getAttribute(int index)
                             throws java.lang.IndexOutOfBoundsException
Returns the attribute at the specified index in the attributes list.

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

setRewrite

public void setRewrite(boolean rewrite)
Sets the flag that indicates whether the attributes will be rewritten on the second pass of the document writer. The flag, which is used by an Attributes object's default writer, can be tested by a replacement writer with isRewrite().

Parameters:
rewrite - true if the attributes should be rewritten on the second pass of the document writer; false otherwise.
Since:
1.0
See Also:
isRewrite()

indexOf

public int indexOf(java.lang.String name)
            throws java.lang.IllegalArgumentException
Returns the index of the attribute with the specified name in this chunk's attributes list, or -1 if the list does not contain an attribute with the specified name. As the attributes in the list must have unique names, any occurrence in the list of an attribute with a given name will be the only occurrence.

Parameters:
name - the name of the attribute whose index is to be determined.
Returns:
the index of the attribute with the specified name the attributes list, or -1 if the list does not contain an attribute with the specified name.
Throws:
java.lang.IllegalArgumentException - if name is null.
Since:
1.0

setAttribute

public void setAttribute(Attributes.Attr attribute)
                  throws java.lang.IllegalArgumentException
Sets the specified attribute in this chunk's attributes list. If there is already an attribute with the same name in the list, it is replaced with the specified attribute; otherwise, the new attribute is added to the end of the list.

Parameters:
attribute - the attribute that is to be set in or added to the list of attributes.
Throws:
java.lang.IllegalArgumentException - if attribute is null.
Since:
1.0
See Also:
removeAttribute(int)

removeAttribute

public Attributes.Attr removeAttribute(int index)
                                throws java.lang.IndexOutOfBoundsException
Removes the attribute at the specified index from this chunk's attributes list, and returns the attribute that was removed.

Parameters:
index - the index of the attribute that is to be removed from the list of attributes.
Returns:
the attribute that was removed from the list.
Throws:
java.lang.IndexOutOfBoundsException - if (index < 0) or (index >= getNumAttributes()).
Since:
1.0
See Also:
setAttribute(Attr), getNumAttributes(), indexOf(java.lang.String)

toXml

protected void toXml(org.w3c.dom.Element element)
              throws org.w3c.dom.DOMException
Sets the attributes in this chunk's attributes list as attributes of the specified XML element.

Parameters:
element - the XML element on which the attributes are to be set.
Throws:
org.w3c.dom.DOMException - if an attribute name is not valid for the XML version of the document to which element belongs.
Since:
1.0