Chapter 2: Parsing

2.4 Programming Interfaces for Document Structure

DOM, SAX, ElementHandler

In DOM, an XML document is represented as a tree whose nodes are elements, texts, and so on. An XML processor generates the tree and hands it to an application program (in Figure 2.1, "DOM" shows this). DOM provides a set of API to access and manipulate these nodes in the DOM tree. Since DOM-based XML processor creates the entire structure of an XML document in memory, it is suitable for applications that operates on the document as a whole. In particular, the following situations are best suited for the use of DOM.

1. When structurally modifying an XML document. For example,
• Sorting elements in a particular order
• Moving some elements from one place of the tree to another
• Etc.
2. When sharing the document in memory with other applications.

1. When dealing with a large document that does not fit in the memory.
2. When doing tasks on elements that are irrelevant to the surrounding document structure, e.g.,
• Counting the total number of elements in a document
• Extracting contents of a specific element
• Etc.

XML for Java supports both DOM and SAX, as well as its proprietary ElementHandler API. This third API is event-driven as SAX but it also creates DOM tree. Therefore, it is suitable for an event-oriented task but at the same time the application program needs to manipulate the internal structure of an element.

In the following subsections, we take a simple task of extracting information from an XML document with a set of attribute and value pairs, and explain how these three API can be used for this task.

2.4.1 DOM: Object Model for XML Document

XML is a language for describing a tree structured data. In XML, an element is represented by a start tag and a matching end tag (or an empty-element tag). An element may contain one or more elements between the beginning and ending tags. Therefore, an entire document renders itself as a nested tree. For example, our department example department.xml can be depicted as in Figure 2.2. Footnote: For simplicity, text elements solely consisting of white spaces are not shown in the figure. Chapter 3 elaborates on the structure containing white space texts. Each pair of tags (i.e., beginning and ending tags) corresponds to an Element node (square box in the figure), and each chunk of text surrounded by two tags corresponds to a Text node (string in the figure). These nodes are defined as objects in DOM.

Figure 2.2: Structure of an XML Document (department.xml)

The term "document object model" has been used for referring to models that are designed for defining the structure of an HTML document, allowing scripting languages such as JavaScript to access the elements of the structure. You may have experiences of writing JavaScript programs that manipulate the value of an input field within a Form element. For example, "document.forms(1).username.value" refers to the value of the input field with the name "username" in the first form element in an HTML document. However, because the current HTML object models are dependent on browsers, in general multiple pages should be prepared for different browsers. One of the goals of the W3C DOM Working Group is to define a common, interoperable document object model for HTML.

The W3C DOM Working Group is also defining a document object model for XML. Since XML and HTML object models have so much in common, those definitions that overlap between HTML and XML object models are called Core Document Object Model. Most of the XML-related definitions are in the core, but there are few XML-specific objects (called Extended XML Interfaces) specified in the Core document.

Primarily DOM defines a platform- and language-neutral interface for application programs in terms of standard set of objects. To help interoperability DOM defines APIs for OMG IDL, Java, and ECMAScript (called language bindings). The current DOM specification is called Level-1 DOM. It is expected that DOM will evolve by incorporating additional features.

From an object-oriented programming viewpoint, DOM API is a set of interfaces that should be implemented by a particular DOM implementation. XML for Java is one example of such DOM implementation. The following table shows interfaces and classes defined in DOM (Core) Level 1.

The table also shows the implementation classes provided by XML for Java. For example, the interface Document is implemented by the class TXDocument in XML for Java.

Figure 2.3 shows the class hierarchy of the DOM Level 1 Core interfaces. Note that Node is the primary data structure that constructs a tree structure. DOM tree constituents such as Element, Text, and Attr are all defined as a derived interface from Node.

Figure 2.3: Class/Interface Hierarchy of DOM Level 1 Specification (W3C Recommendation)

Now let us look at DOM in action. One of the frequently required actions for XML documents is to extract a text content from elements. The program (MakeEltTblDOM.java) we use to illustrate the use of DOM is to extract key-value pairs from an XML document such as keyval.xml shown below.

<?xml version="1.0"?>
<keyval>
  <key>URL</key>
  <value>http://www.ibm.com/xml</value>
  <key>Owner</key>
  <value>IBM</value>
</keyval>

To get the strings such as "URL" and "http://www.ibm.com/xml", we should first find the specified element in a DOM tree, and extract the content text from it. The complete listing of MakeEltTblDOM.java is shown in Listing 2.3.

import com.ibm.xml.parser.Parser;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.Hashtable;
import org.w3c.dom.CDATASection;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.EntityReference;
import org.w3c.dom.Node;
import org.w3c.dom.Text;

/**
 * MakeEltTblDOM.java
 **/
public class MakeEltTblDOM {

    static public void main(String[] argv) {
        if (argv.length != 1) {
            System.err.println("Missing filename.");
            System.exit(1);
        }
        try {
            // Open specified file

            InputStream is = new FileInputStream(argv[0]);

            // Start parsing
            Parser parser = new Parser(argv[0]);   // @XML4J
            Document doc = parser.readStream(is);  // @XML4J

            // Check if there is errors
            if (parser.getNumberOfErrors() > 0) { // @XML4J
                System.exit(1);
            }
            // Document is well-formed

            // Create hashtable for string key-value pairs
            Hashtable hash = new Hashtable();

            String key = null, value = null;
            
            // Traverse all the children of the root element
            for (Node kvchild = doc.getDocumentElement().getFirstChild();
                kvchild != null;
                kvchild = kvchild.getNextSibling()) {
                // When child is an element
                if (kvchild instanceof Element) {
                    // If tag name is "key", store its content in vkey
                    if (kvchild.getNodeName().equals("key")) {
                        key = makeChildrenText(kvchild);

                    // If tag name is "value"
                    } else if (kvchild.getNodeName().equals("value")) {
                        // Extract the text content from the child
                        value = makeChildrenText(kvchild);
                        // Check key is specified and
                        // store the key-value pair int the hashtable
                        if (key != null) {
                            hash.put(key, value);
                            key = null;
                        }
                    }
                }
            }
            // Display the hashtable
            System.out.println(hash);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

private static String makeChildrenText (Node node){
    // Create a StringBuffer to store the result.
    // StringBuffer is more efficient than String
    StringBuffer buffer = new StringBuffer();
    return makeChildrenText1 (node, buffer);
}

private static String makeChildrenText1 (Node node, StringBuffer buffer){
        // Visit all the child nodes
        for (Node ch = node.getFirstChild();
             ch != null;
             ch = ch.getNextSibling()) {
            // Recursively call if the child may have children
            if (ch instanceof Element || ch instanceof EntityReference) {
                buffer.append(makeChildrenText(ch));
            // If the child is a text, append it to the result buffer
            } else if (ch instanceof Text) {
                buffer.append(ch.getNodeValue());
            }
        }

        return buffer.toString();
    }
}

As usual, our program first reads an XML document from a file and creates a DOM tree in the variable doc. We learned how to read an XML documents in previous examples. After reading the documents, our program scans all the child elements of the root element to locate key elements and value elements.

    // Traverse all the children of the root element
    for (Node kvchild = doc.getDocumentElement().getFirstChild();
           kvchild != null;
           kvchild = kvchild.getNextSibling()) {
    ...
    }

The private method makeChildrenText() (which simply calls makeChildrenText1()) in the bottom half of the program is to extract all the texts in the descendant nodes and return the concatenation of them. It is necessary because <key> elements and / or <value> elements may have subelements recursively. You can see how the program recursively descend into subtrees. The point here is the test on whether an element may have child nodes (either it is an Element or an EntityReference). If it is, then the process goes recursively into the child nodes.

         ...
        // Visit all the child nodes
        for (Node ch = node.getFirstChild();
             ch != null;
             ch = ch.getNextSibling()) {
            // Recursively call if the child may have children
            if (ch instanceof Element || ch instanceof EntityReference) {
                buffer.append(makeChildrenText(ch));
            // If the child is a text, append it to the result buffer
            } else if (ch instanceof Text) {
                buffer.append(ch.getNodeValue());
            }
        }

The output of running this program is like this.

R:\samples\chap2>java MakeEltTblDOM keyval.xml
{URL=http://www.ibm.com/xml, Owner=IBM}

In this section, we introduced DOM, the object model for XML documents, and showed a simple program that uses the DOM API. DOM is one of the most fundamental API for dealing with XML documents by computer programs. Chapters 3 and later will make a heavy use of DOM. Chapter 4 has more on programming techniques using DOM. In addition, we provided the complete Java binding of DOM in Appendix D. The next subsection will cover the other fundamental API, SAX.

2.4.2 SAX: Event-Driven API of XML Processor

In Section 2.4.1, we surveyed the method of using DOM API to access the structure of an XML document, where the entire process is divided into two phases; parsing an XML document and then accessing the DOM tree. We introduce two alternative ways to access the document structure -- using event-driven APIs. An application that wishes to receive information on document structure, such as the element type name of each element, attribute names appearing in an element, and attribute values of each attribute can register handlers to the XML processor. The processor notifies the handlers events such as start of a new tag, data characters, and so on. Unlike the case of using DOM API, the entire process is one-pass. That is, any application-specific operations are performed during parsing.

In this subsection and the next subsection, we explain two different event-driven APIs. One is Simple API for XML (SAX), which is supported by several other XML processors. The other is ElementHandler which is specific to XML for Java. We first show how SAX can be used for simple rewriting of XML documents.

Simple API for XML, or SAX, is a event-driven API for XML processors. SAX is designed as a lightweight API that does not involve generation of internal structures.

Applications are required to register event handlers to a parser object that implements the org.sax.Parser interface. SAX has three handler interfaces; DocumentHandler, DTDHandler, and ErrorHandler (SAX also provides the default implementation class HandlerBase for the default behavior of all of these interfaces.).

DocumentHandler is most important and most frequently used because it is called whenever an element is found.

A normal steps required to use DocumentHandler is as follows.

            import org.xml.sax.Parser;
            ...
            Class c = Class.forName("com.ibm.xml.parser.SAXDriver");
            Parser parser = (Parser)c.newInstance();
            parser.setDocumentHandler(new MyHandler());

First, the code must import the Parser interface. The next line

            Class c = Class.forName("com.ibm.xml.SAXDriver");

creates an instance of a SAX driver. com.ibm.cml.SAXDriver is a SAX driver provided by XML for Java. Using this driver, you can create a parser object as follows.

            Parser parser = (Parser)c.newInstance();

This is a standard technique in Java to dynamically specify class to be instantiated at run time. Note that Parser is an interface defined in the SAX package. With the following line, an instance of class MyHandler is registered as a DocumentHandler.

            parser.setDocumentHandler(new MyHandler());

MyHandler can be programmed by implementing the DocumentHandler interface, or by subclassing the adapter class HandlerBase, which has each empty method for all the events.

Table 2.2 shows the methods defined in the DocumentHandler interface.

Table 2.2: Methods of DocumentHandler

Method	Description
startDocument()	Receive notification of the beginning of the document
endDocument()	Receive notification of the end of the document
startElement(String name, AttributeList atts)	Receive notification of the beginning of an element.
endElement(String name)	Receive notification of the end of an element.
characters(char ch[], int start, int length)	Receive notification of character data.
ignorableWhitespace(char ch[], int start, int length)	Receive notification of ignorable whitespace in element content.
processingInstruction(String target, String data)	Receive notification of a processing instruction.
setDocumentLocator(Locator locator)	Receive an object for locating the origin of SAX document events. The Locator object gives information on the location of the event such as line number and column position.

SAX defines several event types and associated methods. It might be helpful to understand how these methods are called during the parsing process, so our first SAX application, NotifyStr.java (Listing 2.4), is to report all the SAX events to the standard output. Listing 2.4 shows the complete listing.

Listing 2.4: NotifyStr.java: Trace methods of DocumentHandler

import org.xml.sax.AttributeList; import org.xml.sax.HandlerBase; import org.xml.sax.Parser; import org.xml.sax.Locator; import org.xml.sax.SAXException; /** * NotifyStr.java */ public class NotifyStr extends HandlerBase { static public void main(String[] argv) { try { Class c = Class.forName(argv[0]); Parser parser = (Parser )c.newInstance(); NotifyStr notifyStr = new NotifyStr(); parser.setDocumentHandler(notifyStr); parser.parse(argv[1]); } catch (Exception e) { e.printStackTrace(); } } public NotifyStr() { } public void startDocument() throws SAXException { System.out.println("startDocument is called:"); } public void endDocument() throws SAXException { System.out.println("endDocument is called:"); } public void startElement(String name, AttributeList amap) throws SAXException { System.out.println("startElement is called: element name=" + name); for (int i = 0; i < amap.getLength(); i++) { String attname = amap.getName(i); String type = amap.getType(i); String value = amap.getValue(i); System.out.println(" attribute name="+attname+" type="+type+" value="+value); } } public void endElement(String name) throws SAXException { System.out.println("endElement is called: " + name); } public void characters(char[] ch, int start, int length) throws SAXException { System.out.println("characters is called: " + new String(ch, start, length)); } }

This program takes a SAX driver class as the first command line argument and the file name of an XML document as the second argument. To run the program using XML for Java as the SAX driver, you have to supply "com.ibm.xml.parser.SAXDriver" as the first argument.

R:\samples\chap2>java NotifyStr com.ibm.xml.parser.SAXDriver deparment.xml startDocument is called: startElement is called: element name=department startElement is called: element name=employee attribute name=id type=CDATA value=J.D startElement is called: element name=name characters is called: John Doe endElement is called: name startElement is called: element name=email characters is called: John.Doe@foo.ibm.com endElement is called: email endElement is called: employee startElement is called: element name=employee attribute name=id type=CDATA value=B.S startElement is called: element name=name characters is called: Bob Smith endElement is called: name startElement is called: element name=email characters is called: Bob.Smith@foo.com endElement is called: email endElement is called: employee startElement is called: element name=employee attribute name=id type=CDATA value=A.M startElement is called: element name=name characters is called: Alice Miller endElement is called: name startElement is called: element name=email characters is called: Alice.Miller@jp.ibm.com endElement is called: email endElement is called: employee endElement is called: department endDocument is called:

With this output, you should be able to understand when these methods are called.

To highlight the differences in programming with DOM and ElementHandler, we show the SAX version of our key-value program in Listing 2.5.

Listing 2.5: MakeEltTblSAX.java: Extract Key-Value pairs and stores them into a hashtable (SAX-based implementation)

import java.io.File; import java.io.FileInputStream; import java.io.InputStream; import java.net.URL; import java.util.Hashtable; import org.xml.sax.AttributeList; import org.xml.sax.HandlerBase; import org.xml.sax.Parser; import org.xml.sax.SAXException; /** * MakeEltTblSAX.java */ public class MakeEltTblSAX extends HandlerBase { static public void main(String[] argv) { if (argv.length != 2) { System.err.println("Usage: java MakeEltTblSAX <SAX-class-name> <xml-filename>"); System.exit(1); } try { // get class object for SAX Driver Class c = Class.forName(argv[0]); // create instance of the class Parser parser = (Parser)c.newInstance(); // create document handler, MakeEltTblSAX makehash = new MakeEltTblSAX(); // and register it parser.setDocumentHandler(makehash); parser.parse(argv[1]); System.out.println(makehash.m_hash); } catch (Exception e) { e.printStackTrace(); } } Hashtable m_hash; public MakeEltTblSAX() { m_hash = new Hashtable(); m_state = STATE_OTHER; m_textbuf = new StringBuffer(); } int m_state; static final int STATE_KEY = 0, STATE_VALUE = 1, STATE_OTHER = 2; StringBuffer m_textbuf; String m_key; public void startElement(String name, AttributeList amap) throws SAXException { if (name.equals("key")) { // store status m_state = STATE_KEY; m_textbuf.setLength(0); } else if (name.equals("value")) { // store status m_state = STATE_VALUE; m_textbuf.setLength(0); } } public void endElement(String name) throws SAXException { if (name.equals("key")) { m_key = m_textbuf.toString(); this.m_state = STATE_OTHER; } else if (name.equals("value")) { m_hash.put(m_key, m_textbuf.toString()); this.m_state = STATE_OTHER; } } public void characters(char[] ch, int start, int length) throws SAXException { if (STATE_KEY == m_state || STATE_VALUE == m_state) { m_textbuf.append(ch, start, length); } } public void endDocument() throws SAXException { m_textbuf = null; m_key = null; } }

Again, this program produces exactly the same result as follows:

R:\samples\chap2>java MakeEltTblSAX com.ibm.xml.parser.SAXDriver keyval.xml {URL=http://www.ibm.com/xml, Owner=IBM}

Note that in this sample program, the SAX driver's name is specified in the command line. There is no XML processor-dependent code in this program. MakeEltTblSAX.java should run with any SAX-compatible XML processor.

As you can see in the above examples, for any element in the tree, three methods, startElement(), characters() (possibly multiple times), and endElement() are called in this sequence. However, as these are independently called each other, the application program is responsible for keeping track of with which element an event is associated. In MakeEltTblSAX.java, the variable m_state holds the state of the process if the current tag is "key" or "value. It is set in the startElement() method as shown below.

public void startElement(String name, AttributeList amap) throws SAXException {
        if (name.equals("key")) {
            m_state = STATE_KEY;
            m_textbuf.setLength(0);
        } else if (name.equals("value")) {
            m_state = STATE_VALUE;
            m_textbuf.setLength(0);
        }
    }

The variable m_state is reset in the endElement() method.

When a text is found (that is, the characters() method is called), it checks if it appears in a context of either "key" or "value," and if so, concatenate the string to the buffer.

    public void characters(char[] ch, int start, int length) throws SAXException {
        if (STATE_KEY == m_state || STATE_VALUE == m_state) {
            m_textbuf.append(ch, start, length);
        }
    }

When the endElement() is called, the assembled text strings are stored in the hash table.

    public void endElement(String name) throws SAXException {
        if (name.equals("key")) {
            m_key = m_textbuf.toString();
            this.m_state = STATE_OTHER;
        } else if (name.equals("value")) {
            m_hash.put(m_key, m_textbuf.toString());
            this.m_state = STATE_OTHER;
        }
    }

2.4.3 Element Handler: Yet another Event-Driven API

IBM's XML for Java allows you to register an element handler to a particular element name before starting reading an XML document. An element handler is called whenever the parser encounters the specified element. We will show how element handler can change the structure of an input document using this API. Like SAX, applications can receive events about elements. The difference between them is that ElementHandler creates a DOM tree, while SAX does not. On the other hand, an ElementHander can be attached to elements only -- you cannot catch events of other types.

ElementHandler is particularly useful when modifying some element while preserving the overall structure. We use SimpleFilter.java (Listing 2.6) to illustrate the use of ElementHandler for this purpose. This program translates the email tags into the url tags. For example,
<email>John.Doe@foo.com</email>
will be converted into
<url href="mailto:John.Doe@foo.com"/>.

An element handler is a class that implements the com.ibm.xml.parser.ElementHandler interface. Therefore, first you need to import it in your program.

import com.ibm.xml.parser.ElementHandler;

Since ElementHandler is an interface, you have to define a class that implements this interface. ElementHandler has only one method, handleElement() to be implemented by its implementation class.

Note: If you are familiar with C or C++ and not very familiar with the Java 1.1's event model, you may consider an element handler as a sort of a call back function. These are of course separate concepts but at least you can get a glimpse of the idea.

Listing 2.6: SimpleFilter.java -- Modify structure of an XML document

/** * SimpleFilter.java **/ // Note: This class is XML4J specific import org.w3c.dom.Document; import com.ibm.xml.parser.Parser; import com.ibm.xml.parser.TXDocument; import com.ibm.xml.parser.TXElement; import com.ibm.xml.parser.ElementHandler; import java.io.FileInputStream; import java.io.PrintWriter; public class SimpleFilter implements ElementHandler { // This method is XML4J-specific. public TXElement handleElement(TXElement el) { // ElementHandler String addr = el.getText(); TXElement e = new TXElement("url"); e.setAttribute("href", "mailto:"+addr); return e; } public static void main(String[] argv) { if (argv.length != 1) { System.err.println("Missing filename."); System.exit(1); } try { FileInputStream is = new FileInputStream(argv[0]); Parser parser = new Parser(argv[0]); // @XML4J // Register ElementHandler parser.addElementHandler(new SimpleFilter(), "email"); // Start parsing @XML4J Document doc = parser.readStream(is); // Error? if (parser.getNumberOfErrors() > 0) { // @XML4J System.exit(1); // If the document has any error, // the program is terminated. } // Generate modified XML document ((TXDocument)doc).printWithFormat(new PrintWriter(System.out)); // @XML4J } catch (Exception e) { e.printStackTrace(); } } }

Here, the class named SimpleFilter implements an element handler. In the method main(), we create a new instance of this element handler and register it as the handler of the element "email" in the following line.

     parser.addElementHandler(new SimpleFilter(), "email");

During the parsing, when an "email" element is created after seeing an end tag (</email>), the handleElement() method of the element handler is called. The implementation of this method is shown below.

public TXElement handleElement(TXElement el) { // ElementHandler
     String addr = el.getText();
     TXElement e = new TXElement("url");
     e.setAttribute("href", "mailto:"+addr);
     return e;
}

The newly generated "email" element is passed through the argument el. The program obtains the text string in this element (such as "John.Doe@foo.com") by calling getText() (this is functionally equivalent to the makeChildrenText() method in Section 2.4.1) and set it to the variable addr. Then, another element named "url" is created and the address is set to its "href" attribute. Finally this new "url" element is returned as the return value of this method. This will replace the original "email" element in the resulting DOM tree. This way, <email>John.Doe@foo.com</email> is effectively replaced by <url href="mailto:John.Doe@foo.com"/>.

Let us execute the program and see what is the result.

R:\samples\chap2>java SimpleFilter department.xml <?xml version="1.0"?> <!DOCTYPE department SYSTEM "department.dtd" > <department> <employee id="J.D"> <name>John Doe</name> <url href="mailto:John.Doe@foo.ibm.com"/> </employee> <employee id="B.S"> <name>Bob Smith</name> <url href="mailto:Bob.Smith@foo.com"/> </employee> <employee id="A.M"> <name>Alice Miller</name> <url href="http://www.trl.jp.ibm.com/~amiller/"/> </employee> </department>

As you see, the <email> tags of John Doe and Bob Smith have been replaced by the <url> tags.

Note: In XML for Java, validity constraints are checked after ElementHandler is called. In other words, the constraints are applied to the modified structure. Therefore, the url element must be declared in the DTD.

You can attach as many element handlers as you like to any element names. By default, the handleElement() method is called after the parser sees the end tag of an element. For example, if you have an element handler attached to "employee", it is called when the parser sees a </employee> tag.

<department>
  <employee id="J.D">
    <name>John Doe</name>
    <email>John.Doe@foo.com</email>
    <title>Manager<title/>
  </employee>
<department>

For the input above, all the complete element structures for "name," "email," and "title" are available to the element handler of "employee". On the other hand, the element for "department" is not yet complete so it is not available to you. An exception to this is the attributes of the parent tag -- XML for Java provides methods for accessing them. Refer to Appendix D for interface specifications for the details.

Java 1.1 introduced a powerful concept called inner class into Java language syntax. It allows you to embed a class definition within an expression as an anonymous class. Inner classes are particularly useful for element handlers because you do not need to give a separate name for each element handler.

In the above example, we have defined SimpleFilter as an implementation of ElementHandler and register it as an element handler of "email" as shown below.

parser.addElementHandler(new SimpleFilter(), "email");

With inner class, we can embed a class definition in place of new SimpleFilter() as follows:

           parser.addElementHandler(new ElementHandler() {
                public TXElement handleElement(TXElement el) {
                    String addr = el.getText();
                    TXElement e = new TXElement("url");
                    e.setAttribute("href", "mailto:"+addr);
:                   return e;
                }
                , "email");
           }

The entire rewritten program is shown in Listing 2.7.

Listing 2.7: SimpleFilter2 -- Modify structure of an XML document (inner class version)

/** * SimpleFilter2.java **/ // Note: This class is XML4J specific import org.w3c.dom.Document; import com.ibm.xml.parser.Parser; import com.ibm.xml.parser.TXDocument; import com.ibm.xml.parser.TXElement; import com.ibm.xml.parser.ElementHandler; import java.io.FileInputStream; import java.io.PrintWriter; public class SimpleFilter2 { public static void main(String[] argv) { if (argv.length != 1) { System.err.println("Missing filename."); System.exit(1); } try { FileInputStream is = new FileInputStream(argv[0]); Parser parser = new Parser(argv[0]); // @XML4J // ================================================ // @XML4J parser.addElementHandler(new ElementHandler() { public TXElement handleElement(TXElement el) { String addr = el.getText(); TXElement e = new TXElement("url"); e.setAttribute("href", "mailto:"+addr); return e; }} , "email"); // Start parsing Document doc = parser.readStream(is); // @XML4J // Error? if (parser.getNumberOfErrors() > 0) { // @XML4J System.exit(1); // If the document has any error, // the program is terminated. } // Generate modified XML document ((TXDocument)doc).printWithFormat(new PrintWriter(System.out)); // @XML4J } catch (Exception e) { e.printStackTrace(); } } }

Using element handlers, you can write simple filter programs, such as searching particular tags, substituting and inserting elements, and so on.

The next example is functionally equivalent to MakeEltTblDOM.java(Listing 2.3) that we discussed in Section 2.4.1. Comparing these two programs, you will see the difference between the two approaches.

Listing 2.8: MakeEltTblEltHandler.java: Extract key-value pairs and store them into HashTable (ElementHandler-based implementation)

import java.io.FileInputStream; import java.io.InputStream; import java.util.Hashtable; import com.ibm.xml.parser.ElementHandler; import com.ibm.xml.parser.Parser; import com.ibm.xml.parser.TXElement; /** * MakeEltTblEltHandler.java **/ // This class is XML4J specific. public class MakeEltTblEltHandler implements ElementHandler { Hashtable hash = new Hashtable(); String key = null; // ElementHandler public TXElement handleElement(TXElement el) { String name = el.getNodeName(); // Extract value of tag "key" if (name.equals("key")) { this.key = el.getText(); // Extract value of tag "value" and store the pair into HashTable } else if (name.equals("value") && this.key != null) { this.hash.put(this.key, el.getText()); this.key = null; } return el; } static public void main(String[] argv) { if (argv.length != 1) { System.err.println("Missing filename."); System.exit(1); } try { InputStream is = new FileInputStream(argv[0]); Parser parser = new Parser(argv[0]); // Create and register ElementHandler MakeEltTblEltHandler handler = new MakeEltTblEltHandler(); parser.addElementHandler(handler, "key"); parser.addElementHandler(handler, "value"); // Start parsing parser.readStream(is); // Error check if (parser.getNumberOfErrors() > 0) { System.exit(1); } // Display HashTable System.out.println(handler.hash); } catch (Exception e) { e.printStackTrace(); } } }

Running this program produces exactly the same result as MakeEltTblDOM.java.

R:\samples\chap2>java MakeEltTblEltHandler keyval.xml {URL=http://www.ibm.com/xml, Owner=IBM}

The core of this program is the handleElement() method. This method is registered for two tag names; "value" and "key." Tag name is obtained by calling getNodeName() method. Also the content of the tag is obtained with getText(). These methods are specific to XML for Java.

Comparison of Three APIs

We have examined the three APIs provided by XML for Java. The following table summarizes the comparison of the three approaches. You should select appropriate one depending on your application.

	DOM	SAX	ElementHandler
Create a tree structure?	Yes	No	Yes
Event-driven?	No	Yes	Yes
Types of event available	NA	Document, Element, Text, PI	Element only
Efficient for large documents?	No	Yes	Yes

---

2.5 Summary

In this chapter we have explained the basics of programming using XML for Java as an XML processor. We showed how to read and generate XML documents. Two types of APIs, DOM and event-driven APIs, are discussed.

With an event-driven API, simple tasks can be implemented easily as a one-pass process, and can be more efficient than the DOM-based process, because with DOM an entire DOM tree is always created before doing any application-specific tasks. On the other hand, it is hard to randomly access different parts of the tree with a one-pass process. The readers should consider the pros and cons of these methods and select an appropriate method.

The next chapter deals with generation in more detail.

---

---

Hiroshi Maruyama <maruyama@jp.ibm.com>