5.4 Generating RVML SAX Events

There are two ways to create an SWF movie using the Server component. The first is to use an RVML XML document as input. However, it is also possible to emulate an RVML document without actually having the external representation. This section will outline how to achieve this and present an example of converting from an RVML DOM representation to SWF without having to convert the DOM to XML.

5.4.1 Using the Server SAX Handler

KineticFusion using SAX( Simple API for XML) technology internally to process XML documents. SAX is an event-oriented interface that processes XML documents by sending document events to a Content Handler as they are encountered in the input. For more information on SAX and how KineticFusion handles these event see the Extending RVML section.

The SAX handling capabilities are implemented by the com.kinesis.server.ServerSaxHandlerType interface. The Server component provides access to the KineticFusion Content handler by creating an new instance from the KineticFusionServerFactory:

The ServerSaxHandlerType interface implements all the methods of the four main SAX interfaces ( EntityResolver, DTDHandler, ContentHandler, ErrorHandler) and provides the following methods:

/**
 * Represents  an initialized SAX Handler that can be used to process RVML SAX events 
 * without requiring an input stream. The handler can be used as input into any SAX event
 * parser, and will output to the specified SWFOutputType after the endDocument() event. 
 * Instances must be initialized using the initializeMovie() method before being any event processing
 * begins. A single instance can be reused for processing multiple documents. 
  */
public interface ServerSaxHandlerType extends EntityResolver, DTDHandler, ContentHandler, ErrorHandler{

    /**
     * Initialize the parameters of the input movie. The inputSpec defines the names and global
     * data available during processing. Once the endDocument() event is received, the movie will be output
     * using the outputSpec
     * @param inputSpec Specification of the input used to create this movie providing additional metadata where
     * necessary to write the output 
     * @param outputSpec Full output specification of the output stream and associated parameters
     * @throws NullPointerException If any of the arguments are null
     */
    void initializeMovie(RVMLInputSpecificationType inputSpec, SWFOutputType outputSpec);

    /**
     * Return the processing state of the last processing operation. If any ActionScript messages 
     * were generated these are included in the results along with the overall success flag. 
     * @return The last set of processing results.
     */
    ResultType getResult();

    /**
     * Reset the handler to its initial state
     */
    void reset();
}

Once an instance of a ServerSAXHandlerType is created it should be initialized with the parameters of the input RVML document and the output SWF movie. This is accomplished using the initializeMovie() method. If the handler is used before this method is called then a SAXException is thrown immediately.

The input specification is implemented using an RVMLInputSpecificationType instead of an RVMLInputType since there is no need to access the RVML input reader. The RVMLInputSpecificationType provides the following methods:

public String getDocumentIdentifier()

Return a string used to identify the document in output log messages

public Map getGlobalData()

Defines a map of data that is added to the Global Data Source for the document

public File getDocumentRoot()

Defines the root location for the input document for resolving any document-relative locations

The SAX handler will process all the input SAX events as if they were coming from a normal SAX parser. When the endDocument() event is received the resulting Movie is output to the specified SWFOutputType instance.

The result of processing including any ActionScript messages can be obtained from the getResult() method.

The reset() method should be called in the case of SAXExceptions during parsing to ensure that the state of the handler is reset and that interim messages are discarded.

The most common reason for using a ServerSaxHandlerType is where the RVML document already exists in memory as a DOM. There is an example class in the examples folder called SaxEventDOMWalker.java that illustrates how to walk a DOM and output SAX events. It can be integrated with the ServerSaxHandlerType using:

File input = new File( "Input.rvml" );
File output = new File( "Output.swf" );

 ServerSaxHandlerType saxHandler = KineticFusionServerFactory.getInstance().newServerSaxHandler();
 saxHandler.initializeMovie( new RVMLFileInput( input ), new SWFFileOutput( output ) );
 
 SaxEventDOMWalker walker = new SaxEventDOMWalker( saxHandler );
 try
 {
     walker.walkDOM( d ); // Where d is the Document object corresponding to the input file
 } catch (SAXException e)
 {
     System.out.println( "Got Exception, class = " + e.getClass() + ", message = " + e.getMessage() );
     e.printStackTrace();
 }
 saxHandler.reset();

Copyright 2003-2005 Kinesis Software. All rights reserved.