XMLBuilder (Media Authoring with Java API)
Date: 2016-02-05

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/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.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    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)`

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### createChild

          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.

      Parameters:
        `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.
      Returns:
        Newly created element within the given namespace.

    - #### appendElement

          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.

      Parameters:
        `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.

    - #### appendElement

          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.

      Parameters:
        `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.
      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.

    - #### toXMLNonMetadata

          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.

      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(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.

      Parameters:
        `metadataObject` - Object to serialize as XML.
      Returns:
        XML representation of the given metadata object.
      Throws:
        `NullPointerException` - The metadata object is `null`.
        `IllegalArgumentException` - The given metadata object does not have an associated class definition.

    - #### appendObject

          public static final void appendObject(Node parent,
                                                MetadataObject metadataObject)

    - #### appendValue

          public static final void appendValue(Element element,
                                               String namespace,
                                               String prefix,
                                               String symbolName,
                                               PropertyValue value)

    - #### 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 namespace,
                                              String prefix,
                                              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.
        `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.
      Returns:
        Newly created child element.

    - #### appendElement

          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.

      Parameters:
        `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.
      Returns:
        Newly created child element.

    - #### appendElement

          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.

      Parameters:
        `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.
      Returns:
        Newly created child element.

    - #### appendElement

          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.

      Parameters:
        `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.
      Returns:
        Newly created child element.

    - #### appendStream

          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.

      Parameters:
        `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.
      Returns:
        Newly created stream element.

    - #### makeDoctype

          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.

      Parameters:
        `fragment` - Document fragment 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 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.

      Parameters:
        `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.

    - #### setAttribute

          public static final void setAttribute(Element element,
                                                String namespace,
                                                String prefix,
                                                String attributeName,
                                                PropertyValue value)

    - #### 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`

    - #### validate

          public static final void validate(String schemaPath,
                                            String document)
                                     throws NullPointerException,
                                            SAXException,
                                            IOException

      Throws:
        `NullPointerException`
        `SAXException`
        `IOException`

    - #### main

          public static final void main(String[] args)
                                 throws Exception

      Throws:
        `Exception`

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.