Media Authoring
with Java API

tv.amwa.maj.io.xml
Class MasterContentHandler

java.lang.Object
  extended by tv.amwa.maj.io.xml.MasterContentHandler
All Implemented Interfaces:
ContentHandler, SpecifiedClasses
Direct Known Subclasses:
LocalHandler

public class MasterContentHandler
extends Object
implements ContentHandler, SpecifiedClasses

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.

Author:
Richard Cartwright

Field Summary
 
Fields inherited from interface tv.amwa.maj.industry.SpecifiedClasses
abstractInterchangeable, abstractMeta, interchangeable, meta
 
Method Summary
 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)
           
 void ignorableWhitespace(char[] ch, int start, int length)
           
 void processingInstruction(String target, String data)
           
static void registerCoreHandlers()
          Registers handlers for the core elements of AAF XML.
static boolean registerHandler(Class<? extends LocalHandler> handler)
          Registers an XML handling class for a given element name.
static 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 static 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 static final void registerHandlersForClass(Class<?> containsHandler)

registerCoreHandlers

public static 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).


Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.