tv.amwa.maj.io.xml (Media Authoring with Java API)
Date: 2016-02-05

# Package tv.amwa.maj.io.xml

Support for the input and output of metadata objects as XML fragments and documents.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  XMLSerializable | Specifies a class that can add comments and extra element to its current value to nodes of an XML DOM tree.

- Class Summary
  Class | Description
  --- | ---
  AAFElement | Representation of the root element of an AAF XML document "`<AAF>`".
  LocalHandler | Content handler class that is implemented by all content handlers that can deserialize an XML element and create an object.
  MasterContentHandler | The master content handler is the root of all SAX content handlers used to deserialize XML documents and fragments into object instances of this AAF implementation.
  MetadataObjectHandler | Parse an XML element and its children into metadata objects, which are classes annotated with their XML serialization information.
  MetaDictionaryGenerator | Generate a Reg-XML compliant meta dictionary for either the baseline AAF model or an extension data model.
  RefImplIntegrationTest |
  XMLBuilder | A class of static utility methods to assist with the process of serializing and deserializing AAF classes to/from XML representations.
  XMLFactory | Provides a means to read and write XML files from the local filing system.
  XMLStream |
  XSDGenerator | Generate an XML schema for validating a Reg-XML document.

## Package tv.amwa.maj.io.xml Description

Support for the input and output of metadata objects as XML fragments and documents. The XML format is specified according to SMPTE 2001-1 and SMPTE 2001-2 registered data XML.

MAJ uses a SAX-based parser for reading XML and creates DOM trees to write out XML. As such, in this implementation of the MAJ API, parsing XML is less resource intensive than writing out to XML.

## Serializing an object to XML fragments

To convert a single object and any of its contained strong referenced objects to XML, use method `toXML()` methods of the XML builder.

    import tv.amwa.maj.io.xml.XMLBuilder;
    import tv.amwa.maj.iface.MaterialPackage;
    ...

    MaterialPackage material = ...;
    String packageAsXML = XMLBuilder.toXML(material);

Any objects that implement `XMLSerializable` or `MetadataObject` can be serialized to XML fragments.

All MAJ interchangeable classes and meta-classes can be serialized to the same XML format with their `toString()` method.

## Creating objects from an XML fragment

To read the XML representation of an object in XML and create an instance in memory, use either the `createFromXML()` or `createFromXMLString()` methods of the XML builder.

    import tv.amwa.maj.io.xml.XMLBuilder;
    import tv.amwa.maj.iface.MaterialPackage;
    ...

    MaterialPackage material =
            (MaterialPackage) XMLBulder.createFromXMLString(packageAsXML);

## Reading complete Reg XML files

Complete XML files have a root `<AAF>` root element, represented by the AAF element class. To read a preface from an XML file, register all the required data types and then use the `readPreface()` static method of the `XML factory`.

    import tv.amwa.maj.io.xml.XMLFactory;
    import tv.amwa.maj.model.Preface;
    ....

    Preface preface = XMLFactory.readPreface("input_file.xml");

Catch IO exceptions to find out about any problems parsing the XML.

Note that the automatic processing of extension metadata that is not registered with MAJ is not supported in the current version of the MAJ API.

## Writing complete Reg XML files

Complete XML files have a root `<AAF>` root element, represented by the AAF element class. To write a complete Reg XML file, use the `writePreface()` static method of the `XML factory`.

    import tv.amwa.maj.io.xml.XMLFactory;
    ....

    XMLFactory.writePreface(preface, "output_file.xml");

The preface will be automatically updated with a correct dictionary and any extensions classes will be added to the output. Note that an application is expected to have added an appropriate identification to the preface to identify the current version of the file before calling this method.

## Generating Meta Dictionaries

Use the meta dictionary generator to create an XML-format meta dictionary for the baseline AAF model or an extension data model.

## Generating XSDs

Use the XML schema generator to create an XML schema that can be used to validate baseline and/or extension data models.

See Also:
  `MediaEngine.toString(tv.amwa.maj.industry.MetadataObject)`

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