tv.amwa.maj.io.xml
Class XMLBuilder

java.lang.Object
  tv.amwa.maj.io.xml.XMLBuilder

public final class XMLBuilder
extends Object

A class of static utility methods to assist with the process of serializing and deserializing AAF classes to their defined XML fragment representation. This representation is the core human-readable form used by this Java implementation of the AAF object model. To serialize an XML serializable object to an XML fragment, call toXML(XMLSerializable). To create an object instance from an XML input source, call createFromXML(InputSource).

The other methods of this class allow an element of a given name and value to be appended to a given node of a given document. The document is passed in to this method to avoid the overheads of repeatedly calling Node.getOwnerDocument() or creating XMLBuilder instances.

The documents attached to the fragments created by createDocumentFragment() may have stream data attached to them if the appendStream(Node, String, String, byte[]) method is called on one of the document's descendants. In this case, the number of streams currently attached to the node is stored as an Integer value with key "entityCount" and each stream is stored with the key "stream_i" where i is the zero-based index of the stream.

Author:

Richard Cartwright

Field Summary

static String	AAF_NAMESPACE_PREFIX
static String	AAF_XML_NAMESPACE

Method Summary

static Comment	appendComment(Node parent, String commentText) Append a comment to the given parent node.
static Element	appendElement(Node parent, String elementName, boolean value) Append an element with a boolean value to the given parent node.
static Element	appendElement(Node parent, String elementName, byte value) Append an element with a byte value to the given parent node.
static Element	appendElement(Node parent, String elementName, byte[] value) Append an element with a byte arrau value to the given parent node, encoding the binary data as a sequence of pairs of hexidecimal character values.
static Element	appendElement(Node parent, String elementName, int value) Append an element with an integer value to the given parent node.
static Element	appendElement(Node parent, String elementName, long value) Append an element with a long value to the given parent node.
static Element	appendElement(Node parent, String elementName, String value) Append an element with a string value to the given parent node.
static Element	appendStream(Node parent, String elementName, String attributeName, byte[] entityData) Append a stream of data to this document, creating an element that references the data stream.
static Element	createChild(Node parent, String elementName) Create a new element as a child of the given element and according to the AAF name space.
static DocumentFragment	createDocumentFragment() Create a document fragment that can be used to build a serialized version of an object with.
static Object	createFromXML(InputSource xmlSource) Creates a new instance of the object represented in serialized form by the given XML fragment.
static Object	createFromXML(InputSource xmlSource, Map<String,InputStream> streams) Creates a new instance of the object represented in serialized form by the given XML fragment with reference to the given collection of data streams.
static Object	createFromXMLString(String xmlSource) Wrapper around the createFromXML(InputSource) method that creates an input source from a new StringReader of the given string.
static Object	createFromXMLString(String xmlSource, byte[][] streams) Wrapper around the createFromXML(InputSource) method that creates an input source from a new StringReader of the given string, with byte arrays the source for data stream inputs.
static byte[]	hexStringToBytes(String hexCharacters) Convert a string of hex digits to a Java byte array, assuming that each pair of hex digits is the value of a byte in the array.
static String	makeDoctype(Document document, String fileName) Creates a "DOCTYPE" element for the given document.
static Map<String,InputStream>	parseDocTypeToStreams(File aafxFile)
static void	setAttribute(Element element, String attributeName, String attributeValue) Sets the attribute of the given element of the given name to the given value, assuming that the attribute is within the AAF namespace.
static String	toXML(XMLSerializable item) Creates and returns an XML fragment by serializing to XML the given object that implements XMLSerializable.
static String	toXML(XMLSerializable item, File xmlFile) Creates and returns an XML fragment by serializing to XML the given object that implements XMLSerializable and generating a DOCTYPE element with referenced stream entities if required.
static String	transformNodeToString(Node node) Transform a DOM node into its textual XML representation.
static void	writeStreams(Document document, File associatedAafxFile)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

AAF_XML_NAMESPACE

public static final String AAF_XML_NAMESPACE

See Also:

Constant Field Values

AAF_NAMESPACE_PREFIX

public static final String AAF_NAMESPACE_PREFIX

See Also:

Constant Field Values

Method Detail

hexStringToBytes

public static final byte[] hexStringToBytes(String hexCharacters)
                                     throws NullPointerException,
                                            IndexOutOfBoundsException

Convert a string of hex digits to a Java byte array, assuming that each pair of hex digits is the value of a byte in the array. The byte array will be halg the length of the given string.

For example, 010A10 is converted into { (byte) 1, (byte) 10, (byte) 16 }.

Parameters:

hexCharacters - Hexadecimal characters to convert to a byte array.

Returns:

Byte array created from the given hexadecimal digits.

Throws:

NullPointerException - The given string of hex digits is null.

IndexOutOfBoundsException - The given string of hexadecimal digits is not a multiple of 2.

See Also:

bytesToHexChars(byte[])

createChild

public static final Element createChild(Node parent,
                                        String elementName)

Create a new element as a child of the given element and according to the AAF name space.

Parameters:

parent - Element to create a child element for.

elementName - Unqualified name of the new element.

Returns:

Newly created element within the AAF namespace.

appendElement

public static final Element appendElement(Node parent,
                                          String elementName,
                                          long value)

Append an element with a long value to the given parent node.

Parameters:

parent - Parent to append a new child element to.

elementName - Name of the element to append.

value - Value for the new element.

appendElement

public static final Element appendElement(Node parent,
                                          String elementName,
                                          String value)

Append an element with a string value to the given parent node.

Parameters:

parent - Parent to append a new child element to.

elementName - Name of the element to append.

value - Value for the new element.

Returns:

Newly created child element.

createDocumentFragment

public static final DocumentFragment createDocumentFragment()

Create a document fragment that can be used to build a serialized version of an object with.

Returns:

XML document fragment.

transformNodeToString

public static final String transformNodeToString(Node node)

Transform a DOM node into its textual XML representation.

Parameters:

node - Node to transform to an XML string.

Returns:

String representation of the XML tree represented by the given DOM node.

toXML

public static final String toXML(XMLSerializable item)

Creates and returns an XML fragment by serializing to XML the given object that implements XMLSerializable. This method returns null if an exception occurs in the serialization process.

Parameters:

item - Item to serialize as an XML fragment.

Returns:

String representation of the given item as an XML fragment.

toXML

public static final String toXML(XMLSerializable item,
                                 File xmlFile)

Creates and returns an XML fragment by serializing to XML the given object that implements XMLSerializable and generating a DOCTYPE element with referenced stream entities if required.

Parameters:

item - Item to serialize to an XML fragment.

xmlFile - File to be used to store the XML data indicating the appropriate relative reference to stream files.

Returns:

The given item serialized to XML with a DOCTYPE header referencing any stream entities of the item.

appendComment

public static Comment appendComment(Node parent,
                                    String commentText)

Append a comment to the given parent node.

Parameters:

parent - Parent to append a new child element to.

commentText - Text to include with the comment.

Returns:

Newly created child comment.

appendElement

public static Element appendElement(Node parent,
                                    String elementName,
                                    int value)

Append an element with an integer value to the given parent node.

Parameters:

parent - Parent to append a new child element to.

elementName - Name of the element to append.

value - Value for the new element.

Returns:

Newly created child element.

appendElement

public static Element appendElement(Node parent,
                                    String elementName,
                                    byte value)

Append an element with a byte value to the given parent node.

Parameters:

parent - Parent to append a new child element to.

elementName - Name of the element to append.

value - Value for the new element.

Returns:

Newly created child element.

appendElement

public static Element appendElement(Node parent,
                                    String elementName,
                                    boolean value)

Append an element with a boolean value to the given parent node.

Parameters:

parent - Parent to append a new child element to.

elementName - Name of the element to append.

value - Value for the new element.

Returns:

Newly created child element.

appendElement

public static Element appendElement(Node parent,
                                    String elementName,
                                    byte[] value)

Append an element with a byte arrau value to the given parent node, encoding the binary data as a sequence of pairs of hexidecimal character values.

Parameters:

parent - Parent to append a new child to.

elementName - Name of the element to append.

value - Value for the new element.

Returns:

Newly created child element.

appendStream

public static Element appendStream(Node parent,
                                   String elementName,
                                   String attributeName,
                                   byte[] entityData)

Append a stream of data to this document, creating an element that references the data stream. The stream will become an external reference to a URI that indicates where the stream of data is stored. Calling makeDoctype(Document, String) will create a document type element containing a reference to the stream.

This method does not write any data to disk or to a socket. It attaches the stream data to the document that owns the parent element in the form of user data. This can be accessed when the document is being serialized to XML.

Parameters:

parent - Element to append a stream reference element to.

elementName - Name of the stream reference element.

attributeName - Name of the attribute referencing the stream.

entityData - Data to be written to the stream.

Returns:

Newly created stream element.

makeDoctype

public static final String makeDoctype(Document document,
                                       String fileName)

Creates a "DOCTYPE" element for the given document. It is assumed that the document contains data stream that have been added using the appendStream(Node, String, String, byte[]) method.

Parameters:

document - Document to create a DOCTYPE element for.

fileName - File name to use in entity references.

Returns:

XML DOCTYPE element constructed from the stream appended to the given document.

writeStreams

public static final void writeStreams(Document document,
                                      File associatedAafxFile)
                               throws IOException

Throws:

IOException

setAttribute

public static final void setAttribute(Element element,
                                      String attributeName,
                                      String attributeValue)

Sets the attribute of the given element of the given name to the given value, assuming that the attribute is within the AAF namespace. The attribute name will be prefixed with aaf:. If the attribute does not yet exist for the given element, it will be created. If the attribute does exist, its value will be replaced.

Parameters:

element - Element to set the attribute of.

attributeName - Name of the attribute of the element to set.

attributeValue - Value to set the attribute to.

createFromXML

public static Object createFromXML(InputSource xmlSource)
                            throws NullPointerException,
                                   SAXException,
                                   IOException

Creates a new instance of the object represented in serialized form by the given XML fragment. The fragment must be represented as an InputSource. All the elements of the XML fragment must have had XML handlers registered with the MasterContentHandler.registerHandler(Class) method previously to calling this method.

Parameters:

xmlSource - XML fragment to deserialize into a corresponding object instance.

Returns:

Object instance that is a deserialized version of the given XML fragment.

Throws:

NullPointerException - The XML source argument is null.

SAXException - An exception occurred when trying to parse the given XML fragment.

IOException - An input/output exception occurred when reading the given XML input source.

createFromXML

public static Object createFromXML(InputSource xmlSource,
                                   Map<String,InputStream> streams)
                            throws NullPointerException,
                                   SAXException,
                                   IOException

Creates a new instance of the object represented in serialized form by the given XML fragment with reference to the given collection of data streams. The fragment must be represented as an InputSource. All the elements of the XML fragment must have had XML handlers registered with the MasterContentHandler.registerHandler(Class) method previously to calling this method.

Parameters:

xmlSource - XML fragment to deserialize into a corresponding object instance.

streams - Map from stream name to an input stream providing the required stream data.

Returns:

Object instance that is a deserialized version of the given XML fragment.

Throws:

NullPointerException - The XML source argument is null.

SAXException - An exception occurred when trying to parse the given XML fragment.

IOException - An input/output exception occurred when reading the given XML input source.

createFromXMLString

public static Object createFromXMLString(String xmlSource)
                                  throws NullPointerException,
                                         SAXException

Wrapper around the createFromXML(InputSource) method that creates an input source from a new StringReader of the given string.

Parameters:

xmlSource - String representation of an XML fragment.

Returns:

Object instance that is a deserialized version of the given XML fragment.

Throws:

NullPointerException - The XML source argument is null.

SAXException - An exception occurred when trying to parse the given XML fragment.

createFromXMLString

public static Object createFromXMLString(String xmlSource,
                                         byte[][] streams)
                                  throws NullPointerException,
                                         SAXException

Wrapper around the createFromXML(InputSource) method that creates an input source from a new StringReader of the given string, with byte arrays the source for data stream inputs.

Parameters:

xmlSource - String representation of an XML fragment.

Returns:

Object instance that is a deserialized version of the given XML fragment.

Throws:

NullPointerException - The XML source argument is null.

SAXException - An exception occurred when trying to parse the given XML fragment.

parseDocTypeToStreams

public static Map<String,InputStream> parseDocTypeToStreams(File aafxFile)
                                                     throws IOException

Throws:

IOException