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

tv.amwa.maj.io.xml

## Class MasterContentHandler

- java.lang.Object
- - tv.amwa.maj.io.xml.MasterContentHandler

- All Implemented Interfaces:
    ContentHandler, AAFSpecifiedClasses
  Direct Known Subclasses:
    LocalHandler, MetadataObjectHandler

      public class MasterContentHandler
      extends Object
      implements ContentHandler, AAFSpecifiedClasses

  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. The SAX parser included with the core Java APIs provides an efficient, event-driven approach to parsing XML documents. This class and its subclasses provide content handlers that respond to the parser's generated events and create object instances. This content handler is designed so that every object that can be deserialized from a known XML element name can do so by first registering an appropriate handler.

  To make use of the parsing capabilities of a master content handler, call `XMLBuilder.createFromXML(InputSource)`. This will create a master content handler, parse the input source and return any resulting object.

  All classes that provide content handlers are capable of creating instances from XML fragments must register themselves with the static handler registry of this class using `registerHandler(Class)`. The handler must extend `LocalHandler`, which is in turn a direct subclass of this class. To intiialize all the XML handlers required to parse AAF XML files, call `registerCoreHandlers()`.

  One approach that can be taken to providing an element specific handler is to implement a static inner class within the object to be created from the given element. For example:

       public class VersionNumber {

         ...

         public final static class XMLHandler
              extends tv.amwa.maj.io.xml.LocalHandler
              implements org.xml.sax.ContentHandler.ContentHandler {

            ...
          }
          ...
        }

  More information on how to do this is provided in the documentation for the `LocalHandler` class.

- - ### Field Summary

    - ### Fields inherited from interface tv.amwa.maj.industry.AAFSpecifiedClasses

      `abstractInterchangeable, abstractMeta, existingMeta, interchangeable, meta`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `characters(char[] ch, int start, int length)`
    `void` | `endDocument()` Called at the end of the document represented by the input source of this master content handler.
    `void` | `endElement(String uri, String localName, String name)` Called if an end element event is sent by the SAX parser to a master content handler.
    `void` | `endPrefixMapping(String prefix)`
    `Map<String,String>` | `getAttributesForThis()` Returns the attributes of the element associated with this content handler.
    `String` | `getAttributeValueThisElement(String attributeName)` Retrieve the value of an attribute of the element associated with this local handler.
    `String` | `getElementName()` Returns the element name of the element associated with this content handler.
    `String` | `getFullElementName()`
    `String` | `getNamespace()`
    `void` | `ignorableWhitespace(char[] ch, int start, int length)`
    `void` | `processingInstruction(String target, String data)`
    `void` | `registerCoreHandlers()` Registers handlers for the core elements of AAF XML.
    `boolean` | `registerHandler(Class<? extends LocalHandler> handler)` Registers an XML handling class for a given element name.
    `void` | `registerHandlersForClass(Class<?> containsHandler)`
    `void` | `setDocumentLocator(Locator locator)`
    `void` | `skippedEntity(String name)`
    `void` | `startDocument()`
    `void` | `startElement(String uri, String localName, String name, Attributes atts)` Called by the SAX parser when the root element of the input source of this master content handler has been read.
    `void` | `startPrefixMapping(String prefix, String uri)`

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

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

- - ### Method Detail

    - #### characters

          public void characters(char[] ch,
                                 int start,
                                 int length)
                          throws SAXException

      Specified by:
        `characters` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.characters(char[], int, int)`

    - #### endDocument

          public void endDocument()
                           throws SAXException

      Called at the end of the document represented by the input source of this master content handler. The result of the master content handler parse is the result of its only subelement.

      Specified by:
        `endDocument` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.endDocument()`

    - #### endElement

          public void endElement(String uri,
                                 String localName,
                                 String name)
                          throws SAXException

      Called if an end element event is sent by the SAX parser to a master content handler. This should not happen and so an exception will be thrown.

      Specified by:
        `endElement` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)`

    - #### endPrefixMapping

          public final void endPrefixMapping(String prefix)
                                      throws SAXException

      Specified by:
        `endPrefixMapping` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.endPrefixMapping(java.lang.String)`

    - #### ignorableWhitespace

          public final void ignorableWhitespace(char[] ch,
                                                int start,
                                                int length)
                                         throws SAXException

      Specified by:
        `ignorableWhitespace` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.ignorableWhitespace(char[], int, int)`

    - #### processingInstruction

          public final void processingInstruction(String target,
                                                  String data)
                                           throws SAXException

      Specified by:
        `processingInstruction` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.processingInstruction(java.lang.String, java.lang.String)`

    - #### setDocumentLocator

          public final void setDocumentLocator(Locator locator)

      Specified by:
        `setDocumentLocator` in interface `ContentHandler`
      See Also:
        `ContentHandler.setDocumentLocator(org.xml.sax.Locator)`

    - #### skippedEntity

          public final void skippedEntity(String name)
                                   throws SAXException

      Specified by:
        `skippedEntity` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.skippedEntity(java.lang.String)`

    - #### startDocument

          public final void startDocument()
                                   throws SAXException

      Specified by:
        `startDocument` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.startDocument()`

    - #### startElement

          public void startElement(String uri,
                                   String localName,
                                   String name,
                                   Attributes atts)
                            throws SAXException

      Called by the SAX parser when the root element of the input source of this master content handler has been read. A sub element content handler is created from the register of handlers and parsing of the document continues using this newly created handler.

      Specified by:
        `startElement` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`

    - #### startPrefixMapping

          public final void startPrefixMapping(String prefix,
                                               String uri)
                                        throws SAXException

      Specified by:
        `startPrefixMapping` in interface `ContentHandler`
      Throws:
        `SAXException`
      See Also:
        `ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)`

    - #### registerHandler

          public final boolean registerHandler(Class<? extends LocalHandler> handler)
                                        throws NullPointerException,
                                               IllegalArgumentException

      Registers an XML handling class for a given element name. The handler must be class that extends `LocalHandler`. If a handler is already registered for the given element name, it is not replaced. This is to ensure that if `registerCoreHandlers()` has been called, core handlers are not overridden. If the given handler is successfully registered, `true` is returned, otherwise `false`.

      Parameters:
        `handler` - Content handler for the given element name.
      Returns:
        Has the given content handler been registered successfully?
      Throws:
        `NullPointerException` - The handler argument is `null`.
        `IllegalArgumentException` - The given handler does not contain an accessible "`elementName`" static string value.

    - #### registerHandlersForClass

          public final void registerHandlersForClass(Class<?> containsHandler)

    - #### registerCoreHandlers

          public final void registerCoreHandlers()

      Registers handlers for the core elements of AAF XML. To extend the range of elements parsed by this master content handler, call `registerHandler(Class)`.

    - #### getAttributesForThis

          public final Map<String,String> getAttributesForThis()

      Returns the attributes of the element associated with this content handler.

      Returns:
        Attributes of the element associated with this content handler.

    - #### getAttributeValueThisElement

          public final String getAttributeValueThisElement(String attributeName)
                                                    throws NullPointerException

      Retrieve the value of an attribute of the element associated with this local handler. The value of the attribute may not be available for one of two reasons:

      - No attributes are defined for the element associated with this local handler.
      - An attribute of the given name was not defined for the element.
      Parameters:
        `attributeName` - Name of an attribute of the element associated with this local handler.
      Returns:
        Value of the attribute with the given name, or `null` is the value of the attribute is not available.
      Throws:
        `NullPointerException` - The attribute name argument is `null`.

    - #### getElementName

          public final String getElementName()

      Returns the element name of the element associated with this content handler. This will be the same as the "`elementName`" static value of the content handler.

      Returns:
        Element name of the element associated with this content handler.

    - #### getNamespace

          public final String getNamespace()

    - #### getFullElementName

          public final String getFullElementName()

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