public final class XMLBuilder extends Object
A class of static utility methods to assist with the process of serializing and
deserializing AAF classes to/from XML representations.
This representation is the core human-readable form used by this Java implementation of the
AAF object model. To serialize a metadata object or
XML serializable object to an XML
document or fragment, call toXML(MetadataObject) or toXMLNonMetadata(XMLSerializable). To create an
object instance from an XML input source, call createFromXML(InputSource).
The append and set static methods of this class allow DOM tree XML representations
to be constructed. This is useful when a client class needs to override or add to default serialization behaviour by
implementing the XMLSerializable.appendXMLChildren(Node).
The documents attached to the fragments created by createDocumentFragment() may
have stream data attached to them if the appendStream(Node, String, String, String, String, Stream)
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.
| Modifier and Type | Method and Description |
|---|---|
static Comment |
appendComment(Node parent,
String commentText)
Append a comment to the given parent node.
|
static Element |
appendElement(Node parent,
String namespace,
String prefix,
String elementName,
boolean value)
Append an element with a boolean value to the given parent node.
|
static Element |
appendElement(Node parent,
String namespace,
String prefix,
String elementName,
byte value)
Append an element with a byte value to the given parent node.
|
static Element |
appendElement(Node parent,
String namespace,
String prefix,
String elementName,
byte[] value)
Append an element with a byte array 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 namespace,
String prefix,
String elementName,
int value)
Append an element with an integer value to the given parent node.
|
static Element |
appendElement(Node parent,
String namespace,
String prefix,
String elementName,
long value)
Append an element with a long value to the given parent node.
|
static Element |
appendElement(Node parent,
String namespace,
String prefix,
String elementName,
String value)
Append an element with a string value to the given parent node.
|
static void |
appendObject(Node parent,
MetadataObject metadataObject) |
static Element |
appendStream(Node parent,
String namespace,
String prefix,
String elementName,
String attributeName,
Stream entityData)
Append a stream of data to this document, creating an element that references the
data stream.
|
static void |
appendValue(Element element,
String namespace,
String prefix,
String symbolName,
PropertyValue value) |
static Element |
createChild(Node parent,
String namespace,
String prefix,
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 void |
main(String[] args) |
static String |
makeDoctype(DocumentFragment fragment,
String fileName)
Creates a "
DOCTYPE" element for the given document fragment. |
static Map<String,InputStream> |
parseDocTypeToStreams(File aafxFile) |
static void |
setAttribute(Element element,
String namespace,
String prefix,
String attributeName,
PropertyValue value) |
static void |
setAttribute(Element element,
String namespace,
String prefix,
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(MetadataObject metadataObject)
Create a string representation of a metadata
object.
|
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 |
toXMLNonMetadata(XMLSerializable item)
Creates and returns an XML fragment by serializing to XML the given object that implements
XMLSerializable and is not a core metadata object. |
static String |
transformNodeToString(Node node)
Transform a DOM node into its textual XML representation.
|
static void |
validate(String schemaPath,
String document) |
static void |
writeStreams(Document document,
File associatedAafxFile) |
public static final Element createChild(Node parent, String namespace, String prefix, String elementName)
Create a new element as a child of the given element and according to the AAF name space.
parent - Element to create a child element for.namespace - Namespace if which the element is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.elementName - Unqualified name of the new element.public static final Element appendElement(Node parent, String namespace, String prefix, String elementName, long value)
Append an element with a long value to the given parent node.
parent - Parent to append a new child element to.namespace - Namespace in which the element is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.elementName - Name of the element to append.value - Value for the new element.public static final Element appendElement(Node parent, String namespace, String prefix, String elementName, String value)
Append an element with a string value to the given parent node.
parent - Parent to append a new child element to.namespace - Namespace in which the element is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.elementName - Name of the element to append.value - Value for the new element.public static final DocumentFragment createDocumentFragment()
Create a document fragment that can be used to build a serialized version of an object with.
public static final String transformNodeToString(Node node)
Transform a DOM node into its textual XML representation.
node - Node to transform to an XML string.public static final String toXMLNonMetadata(XMLSerializable item)
Creates and returns an XML fragment by serializing to XML the given object that implements
XMLSerializable and is not a core metadata object. This method returns null
if an exception occurs in the serialization process.
item - Item to serialize as an XML fragment.public static final String toXML(MetadataObject metadataObject) throws NullPointerException, IllegalArgumentException
Create a string representation of a metadata
object. The object is expected to be an instance of a class annotated with the
AAFClass and AAFProperty
annotations. Metadata in these annotations is used to create the XML tags and serialize
values of annotation-specified types to character data representations.
Note that the returned XML representation of the given metadata object will only include values for optional properties when they are present.
metadataObject - Object to serialize as XML.NullPointerException - The metadata object is null.IllegalArgumentException - The given metadata object does not have an associated
class definition.public static final void appendObject(Node parent, MetadataObject metadataObject)
public static final void appendValue(Element element, String namespace, String prefix, String symbolName, PropertyValue value)
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.
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.DOCTYPE header referencing
any stream entities of the item.public static Comment appendComment(Node parent, String commentText)
Append a comment to the given parent node.
parent - Parent to append a new child element to.commentText - Text to include with the comment.public static Element appendElement(Node parent, String namespace, String prefix, String elementName, int value)
Append an element with an integer value to the given parent node.
parent - Parent to append a new child element to.namespace - Namespace in which the element is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.elementName - Name of the element to append.value - Value for the new element.public static Element appendElement(Node parent, String namespace, String prefix, String elementName, byte value)
Append an element with a byte value to the given parent node.
parent - Parent to append a new child element to.namespace - Namespace in which the element is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.elementName - Name of the element to append.value - Value for the new element.public static Element appendElement(Node parent, String namespace, String prefix, String elementName, boolean value)
Append an element with a boolean value to the given parent node.
parent - Parent to append a new child element to.namespace - Namespace in which the element is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.elementName - Name of the element to append.value - Value for the new element.public static Element appendElement(Node parent, String namespace, String prefix, String elementName, byte[] value)
Append an element with a byte array value to the given parent node, encoding the binary data as a sequence of pairs of hexidecimal character values.
parent - Parent to append a new child to.namespace - Namespace in which the element is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.elementName - Name of the element to append.value - Value for the new element.public static Element appendStream(Node parent, String namespace, String prefix, String elementName, String attributeName, Stream 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(DocumentFragment, 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.
parent - Element to append a stream reference element to.namespace - Namespace in which the element is defined.prefix - Short prefix name for the namespace, or null is no prefix is required.elementName - Name of the stream reference element.attributeName - Name of the attribute referencing the stream.entityData - Data to be written to the stream.public static final String makeDoctype(DocumentFragment fragment, String fileName)
Creates a "DOCTYPE" element for the given document fragment. It is assumed that
the document fragement contains data stream that have been added using the
appendStream(Node, String, String, String, String, Stream) method.
fragment - Document fragment to create a DOCTYPE element for.fileName - File name to use in entity references.public static final void writeStreams(Document document, File associatedAafxFile) throws IOException
IOExceptionpublic static final void setAttribute(Element element, String namespace, String prefix, 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.
element - Element to set the attribute of.namespace - Namespace in which the attribute is defined.prefix - Short prefix name for the namespace, or null if no prefix is required.attributeName - Name of the attribute of the element to set.attributeValue - Value to set the attribute to.public static final void setAttribute(Element element, String namespace, String prefix, String attributeName, PropertyValue value)
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.
xmlSource - XML fragment to deserialize into a corresponding object instance.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.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.
xmlSource - XML fragment to deserialize into a corresponding object instance.streams - Map from stream name to an input stream providing the required stream data.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.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.
xmlSource - String representation of an XML fragment.NullPointerException - The XML source argument is null.SAXException - An exception occurred when trying to parse the given XML fragment.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.
xmlSource - String representation of an XML fragment.NullPointerException - The XML source argument is null.SAXException - An exception occurred when trying to parse the given XML fragment.public static Map<String,InputStream> parseDocTypeToStreams(File aafxFile) throws IOException
IOExceptionpublic static final void validate(String schemaPath, String document) throws NullPointerException, SAXException, IOException
(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.