Kinesis SoftwareKineticFusion

[Show Table of Contents]

10 RVML Reference

[Hide Table of Contents]



10.6.4 Introduction to RVML Tag Libraries

As explained earlier, when processing a new startElement event the KineticFusion ContentHandler will try to acquire an ElementHandler from the current ElementHandler by calling startSubElement(). If the current ElementHandler does not recognise the new element namespace and element name it will return null.

The ContentHandler does not immediately abort at this stage. Instead it consults a Tag Library configuration file to see if the specified namespace is supported by external Tag Libraries. If the namespace is defined, it will instead ask the factory class for the namespace to provide a handler to continue processing. If a handler is provided by the factory, processing of the document continues with the new handler.

10.6.4.1 Tag Library Configuration

The location of the Tag Library configuration file is specified by the kinesis.xml.tagLibraryConfigFile configuration option. The configuration file is an XML document with the following DTD:

<!ELEMENT TagLibraries (TagLibrary*) >
<!ELEMENT TagLibrary EMPTY >
<!ATTLIST TagLibrary 
    namespace CDATA #REQUIRED
    factoryClass CDATA #REQUIRED
    classLocation CDATA #REQUIRED
> 

The TagLibrary element defines the handler for a single namespace. The attributes of the TagLibrary element are as follows:

  • namespace: the namespace used with the element inside the RVML document
  • factoryClass: the class that provides ElementHandlers to process specified elements in the namespace. The specified class must implement the com.kinesis.xml.libraries.TagHandlerFactoryType interface
  • classLocation: the directory or Jar file containing the factory class.

10.6.4.2 Tag Library Factory Class

The Tag library factory class defined in the Tag Libraries configuration must implement the com.kinesis.xml.libraries.TagHandlerFactoryType interface and must have a default constructor. The interface contains a single method:

/**
 * Factory class for creating new Tag Handlers
 */
public interface TagHandlerFactoryType {
 
    
    /**
     * Return a new SAX handler for the specified element in the given context.
     * The factory can add any returned handler to the parent handler to add
     * persistent handling for this element in the specified context.
     * 
     * @param context
     *          The current context. This provides the contextual information
     *          on the movie including the current hierarchy of Sax element
     *          handlers
     * @param namespaceURI
     *          THe namespace URI of the element
     * @param localName
     *          The local name of the element
     * @return The handler for the element or null if there is no valid handler
     */
    public KFSaxElementHandlerType getSaxHandler(RVMLSaxContextType context,
                                                String namespaceURI, 
                                                String localName);
}

The factory object is responsible for processing a request for a handler in the defined namespace, constructing a handler object if it is determined that the specified element is supported, and returning the handler.

10.6.4.3 Persisting an RVML SAX Handler

Handlers are not automatically reused in KineticFusion. Should the same namespace/element pair be encountered multiple times when processing a document the namespace factory will be invoked each time to provide an appropriate handler. To prevent this from occurring, the ElementHandler interface (KFSaxElementHandlerType) provides two methods for registering handlers with their parent handlers so that they no longer need to be continually provided by the factory:

addGeneralSubElementHandler(String namespace, String elementName, KFSaxElementHandlerType handler)

This registers a single handler as a child handler for the namespace/element pair under the handler.

addGeneralSubElementHandler(String namespace, KFSaxElementHandlerType handler)

This registers a handler as being a generic handler that handles all elements located in the specified namespace.

Both of these methods are optional - they return true if the handler supports persistence, but all ElementHandlers that inherit from RVMLElementHandlerAdapter support these operations.

To register a handler with the parent handler, the current hierarchy of handlers can be retrieved from the Context object.