SAX Package: Using SAX Object Model

The SAX package contains an example similar to the ProcessXMLGreeting example. It demonstrates the usage of the Tamino TSAXObjectModel , which represents the SAX object model. You should be familiar with the SAX object model to understand the TSAXObjectModel and this example.

Overview

Using the classes TDOMObjectModel, TJDOMObjectModel or TStreamObjectModel has advantages over using SAX for reasons of simplicity. This is because SAX requires the user to develop one or more event handlers. For example, when using the TDOMObjectModel the complete XML document is read into memory and represented as a tree. This allows you to manipulate any part of the document instantly, and does not require any programming on your part. This convenience comes, of course, at the expense of system resources and speed, as the complete XML document needs to be parsed and Java objects need to be instantiated to represent the complete DOM tree. This mechanism may result in considerable overhead, especially in those cases where your application only requires a small part of the XML document. In that case an approach based on SAX may provide a much more efficient alternative. Using SAX you must provide one or more event handlers for the parser. An event handler is a component that registers itself for callbacks from the parser when SAX events are fired.

The TDOMObjectModel, TJDOMObjectModel and TStreamObjectModel are factory classes providing a singleton instance by means of the factory method getInstance(). These object models are generic and can work with every type of XML document. In contrast, the TSAXObjectModel differs here, as it is not generic. For each type of XML document, a specific instance of the TSAXObjectModel must be created, specifying one or two sets of helper classes. Each set consists of an event handler (extention of the SAX DefaultHandler) and a class representing the XML node either as a document or an element. The event handler provides the processing logic specific to the XML node. The event handlers available with the SAX package are named elementDefaultHandler and documentDefaultHandler. The class (use saxElementClass or saxDocumentClass) must be an implementation of the TSAXDocument or TSAXElement. When deciding to use the TSAXObjectModel it is important to know whether it is to be used for processing query results or single XML documents (either programmatically instantiated or retrieved from Tamino) or both. For the processing of query results a saxElementClass and an elementDefaultHandler are required. If only single XML documents are retrieved from Tamino (via the accessor retrieve method) or if single XML documents are created (via a TXMLObject newInstance factory method), a saxDocumentClass and a documentDefaultHandler are required. The documented example demonstrates both.

The SAX package consists of following classes:

Class

Description

ProcessGreeting

The class with the main method. It actually does the same as the ProcessXMLGreeting example:

It establishes a connection, gets an Accessor (SAX accessor), inserts, retrieves, updates and deletes an XML document <Message>...</Message> in local transaction mode.

Greeting

Represents an XML document.

It implements the TSAXElement and TSAXDocument interfaces

GreetingDefaultHandler

Extends the SAX DefaultHandler.

Its purpose is to handle all events for the Message XML documents

DocumentDefaultHandler

Extends the TDocumentDefaultHandler class.

It does its work by delegating the events to a GreetingDefaultHandler.

ElementDefaultHandler

Extends the TSAXElementDefaultHandler class.

It does its work by delegating the events to a GreetingDefaultHandler.

Note:
Because the ProcessGreeting class has the same functionality as the ProcessXMLGreeting we only describe the SAX aspects in the following sections.

Note:
When interpreting an InputStream using the SAX object model, user-specific implementations of the abstract TSAXElementDefaultHandler class are used. To clear the contents that might currently be available from TSAXElementDefaultHandler's methods getFirstElement() and getElementIterator(), the interface now offers a reset() method which is called at the appropriate time before input stream interpretation starts. The default implementation of the reset() method is empty. If, for example, the user-specific implementation of TSAXElementDefaultHandler maintains a list of elements, thís list must be cleared in the reset() method.

Construct a TSAXObjectModel

// Instantiate the default handler that processes the sax events
greetingDefaultHandler = new GreetingDefaultHandler();

// Instantiate the document and element event handlers each of which
// delegates its events to the greetingDefaultHandler
docDefHandler = new DocumentDefaultHandler( greetingDefaultHandler );
elDefHandler = new ElementDefaultHandler( greetingDefaultHandler );

// Instantiate the specific TSAXObjectModel
saxObjectModel = new TSAXObjectModel("GreetingSAXObjectModel", Greeting.class, Greeting.class, docDefHandler, elDefHandler );

// Do the object model registration.
TXMLObjectModel.register( saxObjectModel );

Obtain a SAX Accessor

accessor = connection.newXMLObjectAccessor(TAccessLocation.newInstance( collection ) , saxObjectModel );
    }

Running the Example

You need to include the .jar files TaminoAPI4J.jar, JavaTaminoAPIExamples.jar, xercesImpl.jar, xmlParserAPIs.jar and log4j.jar in your CLASSPATH. These files are included in the distribution of the Tamino API (see section Component Profile). You can then run the Java interpreter: 

java com.softwareag.tamino.db.api.examples.greeting.SAX.ProcessGreeting
Going to insert <Greeting>Hello World</Greeting>
Insert succeeded, ino:collection:ino:etc, ino:doctype:Greeting, ino:id:1
Update succeeded!
Queried document:<Greeting ino:id="1">Hello World, updated :-)</Greeting>
Deleted the document!

Note:
As in other examples delivered with the Tamino XML Server, using JavaTaminoAPIExamples.jar only works if you have created a database called "mydb" on your local host. Otherwise you will have to change the source code and recompile it.