Support for the input and output of {@linkplain tv.amwa.maj.industry.MetadataObject 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 {@link tv.amwa.maj.io.xml.XMLBuilder#toXML(tv.amwa.maj.industry.MetadataObject) toXML()} methods of the {@linkplain tv.amwa.maj.io.xml.XMLBuilder 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 {@link tv.amwa.maj.io.xml.XMLSerializable XMLSerializable} or {@link tv.amwa.maj.industry.MetadataObject 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 {@link tv.amwa.maj.io.xml.XMLBuilder#createFromXML(InputSource) createFromXML()} or {@link tv.amwa.maj.io.xml.XMLBuilder#createFromXMLString(String) createFromXMLString()} methods of the {@linkplain tv.amwa.maj.io.xml.XMLBuilder 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 {@linkplain tv.amwa.maj.io.xml.AAFElement AAF element class}. To read a preface from an XML file, register all the required data types and then use the {@link tv.amwa.maj.io.xml.XMLFactory#readPreface(String) readPreface()} static method of the {@link tv.amwa.maj.io.xml.XMLFactory XML factory}.

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

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

Catch {@linkplain java.io.IOException 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 {@linkplain tv.amwa.maj.io.xml.AAFElement AAF element class}. To write a complete Reg XML file, use the {@link tv.amwa.maj.io.xml.XMLFactory#writePreface(tv.amwa.maj.model.Preface, String) writePreface()} static method of the {@link tv.amwa.maj.io.xml.XMLFactory XML factory}.

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

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

The {@linkplain tv.amwa.maj.model.Preface preface} will be automatically updated with a correct {@linkplain tv.amwa.maj.model.Dictionary dictionary} and any extensions classes will be added to the output. Note that an application is expected to have added an appropriate {@linkplain tv.amwa.maj.model.Identification identification} to the preface to identify the current version of the file before calling this method.

## Generating Meta Dictionaries

Use the {@linkplain tv.amwa.maj.io.xml.MetaDictionaryGenerator meta dictionary generator} to create an XML-format meta dictionary for the baseline AAF model or an extension data model.

## Generating XSDs

Use the {@linkplain tv.amwa.maj.io.xml.XSDGenerator XML schema generator} to create an XML schema that can be used to validate baseline and/or extension data models.

@see tv.amwa.maj.industry.MediaEngine#toString(tv.amwa.maj.industry.MetadataObject)