An Oracle XML parser reads an XML document and uses either a Document Object Model (DOM) application programming interface (API) or Simple API for XML (SAX) to access to its content and structure. You can parse in either validating or nonvalidating mode.

This chapter assumes that you are familiar with these technologies:

• Document Object Model (DOM): An in-memory tree representation of the structure of an XML document.

• Simple API for XML (SAX): A standard for event-based XML parsing.

• Java API for XML Processing (JAXP): A standard interface for processing XML with Java applications that supports the DOM and SAX standards.

• document type definition (DTD): A set of rules that defines the valid structure of an XML document.

• XML Schema: A World Wide Web Consortium (W3C) recommendation that defines the valid structure of data types in an XML document.

• XML Namespaces: A mechanism for differentiating element and attribute names within an XML document.

• binary XML: An XML representation that uses the compact schema-aware format, in which both scalable and nonscalable DOMs can save XML documents.

For more information, see the list of XML resources in the Related Documents.

The DOM Level 1, Level 2, and Level 3 specifications are W3C Recommendations.

See Document Object Model (DOM) Technical Reports for the W3C DOM specifications.

SAX is available in version 1.0 (deprecated) and 2.0. SAX is not a W3C specification. See SAX Project.

XML Namespaces are a W3C Recommendation. See Namespaces in XML 1.0 (Third Edition).

JCR 1.0 (also known as JSR 170) defines a standard Java API for applications to interact with content repositories. See JSR 170: Content Repository for Java technology API.

JAXP is a standard API that enables use of DOM, SAX, XML Schema, and Extensible Stylesheet Language Transformation (XSLT), independent of processor implementation.

DOM Stream access to XML nodes is done by Procedural Language/Structured Query Language (PL/SQL) and Java APIs. Nodes in an XML document can now far exceed 64 KB. Thus Joint Photographic Experts Group (JPEG), Word, PDF, rich text format (RTF), and HTML documents can be more readily stored.

XMLParser is the abstract base class for the XML parser for Java. An instantiated parser invokes the parse() method to read an XML document. XMLDOMImplementation factory methods provide another way to parse binary XML to create scalable DOM.

Figure 12-1 shows the basic parsing process, using XMLParser. The figure does not apply to XMLDOMImplementation().

Figure 12-1 XML Parser Process

Description of "Figure 12-1 XML Parser Process"

These APIs provide a Java application with access to a parsed XML document:

• DOM API

  DOM API parses XML documents and builds a tree representation of the documents in memory. To parse with DOM API, use either a DOMParser object or the XMLDOMImplementation interface factory methods to create a pluggable, scalable DOM (SDOM).

• SAX API

  SAX API processes an XML document as a stream of events, which means that a program cannot access random locations in a document. To parse with SAX API, use a SAXParser object.

• JAXP

  JAXP is a Java-specific API that supports DOM, SAX, and Extensible Stylesheet Language (XSL). To parse with JAXP, use a DocumentBuilder or SAXParser object.

Subsequent topics use the sample XML document in Example 12-1 to show the differences among DOM, SAX, and JAXP.

<?xml version="1.0"?>
  <EMPLIST>
    <EMP>
     <ENAME>MARY</ENAME>
    </EMP>
    <EMP>
     <ENAME>SCOTT</ENAME>
    </EMP>
  </EMPLIST>

DOM API builds an in-memory tree representation of the XML document. DOM API provides classes and methods to navigate and process the tree.

For example, given the document described in Example 12-1, the DOM API creates the in-memory tree shown in Figure 12-2.

The important aspects of DOM API are:

• DOM API provides a familiar tree structure of objects, making it easier to use than the SAX API.

• The tree can be manipulated. For example, elements can be reordered and renamed, and both elements and attributes can be added and deleted.

• Interactive applications can store the tree in memory, where users can access and manipulate it.

• XKD includes DOM API extensions that support XPath. (Although the DOM standard does not support XPath, most XPath implementations use DOM.)

• XDK supports SDOM. For details, see SDOM.

XDK supports pluggable, scalable DOM (SDOM). This support relieves problems of memory inefficiency, limited scalability, and lack of control over the DOM configuration. SDOM creation and configuration are mainly supported using the XMLDOMImplementation class.

Important aspects of SDOM are:

• SDOM can use plug-in external XML in its existing forms.

  Plug-in XML data can be in different forms—binary XML, XMLType, third-party DOM, and so on. SDOM need not replicate external XML in an internal representation. SDOM is created on top of plug-in XML data through the Reader and InfosetWriter abstract interfaces.

• SDOM has transient nodes.

  Nodes are created only if they are accessed and are freed if they are not used.

• SDOM can use binary XML as both input and output.

  SDOM can interact with data in two ways:

  • Through the abstract InfosetReader and InfosetWriter interfaces.

    To read and write BinXML data, users can use the BinXML implementation of InfosetReader and InfosetWriter. To read and write in other forms of XML infoset, users can use their own implementations.

  • Through an implementation of the InfosetReader and InfosetWriter adaptor for BinXMLStream.

Unlike DOM, SAX is event-based, so SAX API does not build in-memory tree representations of input documents. SAX API processes the input document element by element and can report events and significant data to callback methods in the application.

For example, given the document described in Example 12-1, the SAX API parses it as the series of linear events shown in Figure 12-2.

The important aspects of SAX API are:

• It is useful for search operations and other programs that need not manipulate an XML tree.

• It does not consume significant memory resources.

• It is faster than DOM when retrieving XML documents from a database.

Figure 12-2 Comparing DOM (Tree-Based) and SAX (Event-Based) APIs

Description of "Figure 12-2 Comparing DOM (Tree-Based) and SAX (Event-Based) APIs"

JAXP lets you plug in an implementation of the SAX or DOM parser. The SAX and DOM APIs provided by XDK are examples of vendor-specific implementations supported by JAXP. The main advantage of JAXP is that it lets you write interoperable applications.

An application that uses features available through JAXP can very easily switch the implementation.

The main disadvantage of JAXP is that it runs more slowly than vendor-specific APIs. Also, JAXP lacks several features that Oracle-specific APIs provide. Some Oracle-specific features are available through the JAXP extension mechanism, but an application that uses these extensions loses the flexibility of switching implementation.

Namespaces can help you avoid name collisions between elements or attributes in XML documents.

Example 12-2 is an XML document that uses the <address> tag for both a company address and an employee address. An XML processor cannot distinguish between a company address and an employee address.

Example 12-3 is an XML document that uses these namespaces to distinguish between company and employee <address> tags:

http://www.oracle.com/employee
http://www.oracle.com/company

Example 12-3 associates the com prefix with the first namespace and the emp prefix with the second namespace.

When parsing documents that use namespaces, it is helpful to remember these terms:

• Namespace URI is the URI assigned to xmlns. In Example 12-3, http://www.oracle.com/employee and http://www.oracle.com/company are namespace URIs.

• Namespace prefix is a namespace identifier declared with xmlns. In Example 12-3, emp and com are namespace prefixes.

• Local name is the name of an element or attribute without the namespace prefix. In Example 12-3, employee and company are local names.

• Qualified name is the local name plus the prefix. In Example 12-3, emp:employee and com:company are qualified names.

• Expanded name is the result of substituting the namespace URI for the namespace prefix. In Example 12-3, http://www.oracle.com/employee:employee and http://www.oracle.com/company:company are expanded element names.

<?xml version='1.0'?>
<addresslist>
  <company>
    <address>500 Oracle Parkway,
             Redwood Shores, CA 94065
    </address>
  </company>
  <!-- ... -->
  <employee>
    <lastname>King</lastname>
    <address>3290 W Big Beaver
             Troy, MI 48084
    </address>
  </employee>
  <!-- ... -->
</addresslist>

<?xml version='1.0'?>
<addresslist>
<!-- ... -->
  <com:company
    xmlns:com="http://www.oracle.com/company">
    <com:address>500 Oracle Parkway,
             Redwood Shores, CA 94065
    </com:address>
  </com:company>
  <!-- ... -->
  <emp:employee
    xmlns:emp="http://www.oracle.com/employee">
    <emp:lastname>King</emp:lastname>
    <emp:address>3290 W Big Beaver
             Troy, MI 48084
    </emp:address>
</emp:employee>

To parse an XML document, invoke the parse() method. Typically, you invoke initialization and termination methods in association with the parse() method.

The parser mode can be either validating or nonvalidating. In validating mode, the parser determines whether the document conforms to the specified DTD or XML schema. In nonvalidating mode, the parser checks only for well-formedness. To set the parser mode, invoke the setValidationMode() method defined in oracle.xml.parser.v2.XMLParser.

Table 12-1 shows the setValidationMode() flags that you can use in the XDK parser.

In addition to setting the validation mode with setValidationMode(), you can use the oracle.xml.parser.schema.XSDBuilder class to build an XML schema and then configure the parser to use it by invoking the XMLParser.setXMLSchema() method. In this case, the XML parser automatically sets the validation mode to SCHEMA_STRICT_VALIDATION and ignores the schemaLocation and noNamespaceSchemaLocation attributes. You can also change the validation mode to SCHEMA_LAX_VALIDATION. The XMLParser.setDoctype() method is a parallel method for DTDs, but unlike setXMLSchema() it does not alter the validation mode.

You can use the XML compressor, which is implemented in the XML parser, to compress and decompress XML documents. The compression algorithm is based on tokenizing the XML tags.

The assumption is that any XML document repeats some tags, so tokenizing these tags gives considerable compression. The degree of compression depends on the type of document: the larger the tags and the lesser the text content, the better the compression.

The Oracle XML parser generates a binary compressed output from either an in-memory DOM tree or SAX events generated from an XML document. Table 12-2 describes the two types of compression.

The compressed streams generated from DOM and SAX are compatible; that is, you can use the compressed stream generated from SAX to generate the DOM tree and the reverse. As with XML documents in general, you can store the compressed XML data output in the database as a BLOB data item.

When a program parses a large XML document and creates a DOM tree in memory, it can affect performance. You can compress an XML document into a binary stream by serializing the DOM tree. You can regenerate the DOM tree without validating the XML data in the compressed stream. You can treat the compressed stream as a serialized stream, but the data in the stream is more controlled and managed than the compression implemented by Java default serialization.

Thd basic process of using the XML Parser for Java is described.

Figure 12-3 shows how to use the XML parser in a typical XML processing application.

Figure 12-3 XML Parser for Java

Description of "Figure 12-3 XML Parser for Java"

The basic process of the application shown in Figure 12-3 is:

1. The DOM or SAX parser parses input XML documents. For example, the program can parse XML data documents, DTDs, XML schemas, and XSL stylesheets.

2. If you implement a validating parser, then the processor attempts to validate the XML data document against any supplied DTDs or XML schemas.

Demo programs for the XML parser for Java are included in $ORACLE_HOME/xdk/demo/java/parser.

class.xml
DemoUtil.java
empl.xml
family.dtd
family.xml
iden.xsl
NSExample.xml
traversal.xml

DOMCompression.java
DOMDeCompression.java
SAXCompression.java
SAXDeCompression.java
SampleSAXHandler.java
sample.xml
xml.ser

AutoDetectEncoding.java
DOM2Namespace.java
DOMNamespace.java
DOMRangeSample.java
DOMSample.java
EventSample.java
I18nSafeXMLFileWritingSample.java
NodeIteratorSample.java
ParseXMLFromString.java
TreeWalkerSample.java

JAXPExamples.java
age.xsl
general.xml
jaxpone.xml
jaxpone.xsl
jaxpthree.xsl
jaxptwo.xsl
oraContentHandler.java

SAX2Namespace.java
SAXNamespace.java
SAXSample.java
Tokenizer.java

XSLSample.java
XSLSample2.java
match.xml
match.xsl
math.xml
math.xsl
number.xml
number.xsl
position.xml
position.xsl
reverse.xml
reverse.xsl
string.xml
string.xsl
style.txt
variable.xml
variable.xsl

1. Change into the $ORACLE_HOME/xdk/demo/java/parser directory (UNIX) or %ORACLE_HOME%\xdk\demo\java\parser directory (Windows).
2. Set up your environment as described in Setting Up the XDK for Java Environment.
3. Change into each of these subdirectories and run make (UNIX) or Make.bat (Windows) at the command line. For example:

   cd comp;make;cd ..
   cd jaxp;make;cd ..
   cd sax;make;cd ..
   cd dom;make;cd ..
   cd xslt;make;cd ..
   

   The make file compiles the source code in each directory, runs the programs, and writes the output for each program to a file with an *.out extension.

4. You can view the *.out files to view the output for the programs.

The oraxml utility, which is located in $ORACLE_HOME/bin (UNIX) or %ORACLE_HOME%\bin (Windows), is a command-line interface that parses XML documents. It checks for both well-formedness and validity.

oraxml -dtd -enc family.xml

The encoding of the input file: UTF-8

The input XML file is parsed without errors using DTD validation mode.

Java classes that you can use to implement DOM-based components in your XML application are described.

The architecture of the DOM Parser is described.

Figure 12-4 Basic Architecture of the DOM Parser

Description of "Figure 12-4 Basic Architecture of the DOM Parser"

DOMSample.java shows the basic steps for parsing an input XML document and accessing it through a DOM. DOMSample.java receives an XML file as input, parses it, and prints the elements and attributes in the DOM tree.

1. Create a DOMParser object (a parser) by invoking the DOMParser() constructor.

   The code in DOMSample.java is:

   DOMParser parser = new DOMParser();
   

2. Configure the parser properties, using the methods in Table 12-5.

   This code fragment from DOMSample.java specifies the error output stream, sets the validation mode to DTD validation, and enables warning messages:

   parser.setErrorStream(System.err);
   parser.setValidationMode(DOMParser.DTD_VALIDATION);
   parser.showWarnings(true);
   

3. Parse the input XML document by invoking the parse() method, which builds a tree of Node objects in memory.

   This code fragment from DOMSample.java parses an instance of the java.net.URL class:

   parser.parse(url);
   

   The XML input can be a file, a string buffer, or a URL. As the following code fragment shows, DOMSample.java accepts a file name as a parameter and invokes the createURL helper method to construct a URL object that can be passed to the parser:

   public class DOMSample
   {
      static public void main(String[] argv)
      {
         try
         {
            if (argv.length != 1)
            {
               // Must pass in the name of the XML file.
               System.err.println("Usage: java DOMSample filename");
               System.exit(1);
            }
            ...
            // Generate a URL from the filename.
            URL url = DemoUtil.createURL(argv[0]);
            ...
   

4. Invoke getDocument() to get a handle to the root of the in-memory DOM tree, which is an XMLDocument object.

   You can use this handle to access every part of the parsed XML document. The XMLDocument class implements the interfaces in Table 12-6.

   The code fragment from DOMSample.java is:

   XMLDocument doc = parser.getDocument();
   

5. Get and manipulate DOM nodes of the retrieved document by invoking XMLDocument methods in Table 12-7.

   This code fragment from DOMSample.java uses the DOMParser.print() method to print the elements and attributes of the DOM tree:

   System.out.print("The elements are: ");
   printElements(doc);
    
   System.out.println("The attributes of each element are: ");
   printElementAttributes(doc);
   

   The following code fragment from DOMSample.java implements the printElements() method, which invokes getElementsByTagName() to get a list of all the elements in the DOM tree. Then the code loops through the list, invoking getNodeName() to print the name of each element:

   static void printElements(Document doc)
   {
      NodeList nl = doc.getElementsByTagName("*");
      Node n;
   
      for (int i=0; i<nl.getLength(); i++)
      {
         n = nl.item(i);
         System.out.print(n.getNodeName() + " ");
      }
    
      System.out.println();
   }
   

   The following code fragment from DOMSample.java implements the printElementAttributes() method, which invokes Document.getElementsByTagName() to get a list of all the elements in the DOM tree. Then the code loops through the list, invoking Element.getAttributes() to get the list of attributes for the element and invoking Node.getNodeName() to get the attribute name and Node.getNodeValue() to get the attribute value:

   static void printElementAttributes(Document doc)
   {
      NodeList nl = doc.getElementsByTagName("*");
      Element e;
      Node n;
      NamedNodeMap nnm;
    
      String attrname;
      String attrval;
      int i, len;
    
      len = nl.getLength();
   
      for (int j=0; j < len; j++)
      {
         e = (Element)nl.item(j);
         System.out.println(e.getTagName() + ":");
         nnm = e.getAttributes();
    
         if (nnm != null)
         {
            for (i=0; i<nnm.getLength(); i++)
            {
               n = nnm.item(i);
               attrname = n.getNodeName();
               attrval = n.getNodeValue();
               System.out.print(" " + attrname + " = " + attrval);
            }
         }
         System.out.println();
      }
   }
   

6. Reset the parser state by invoking the reset() method. The parser is now ready to parse a new document.

How to create and use a pluggable, scalable DOM (SDOM) is explained.

DOM2Namespace.java shows a simple use of the parser and namespace extensions to the DOM APIs. The program receives an XML document, parses it, and prints the elements and attributes in the document.

// Print document elements
printElements(doc);
 
// Print document element attributes
System.out.println("The attributes of each element are: ");
printElementAttributes(doc);

static void printElements(Document doc)
{
   NodeList nl = doc.getElementsByTagName("*");
   Element nsElement;
   String prefix;
   String localName;
   String nsName;

   System.out.println("The elements are: ");
   for (int i=0; i < nl.getLength(); i++)
   {
      nsElement = (Element)nl.item(i);
 
      prefix = nsElement.getPrefix();
      System.out.println("  ELEMENT Prefix Name :" + prefix);
 
      localName = nsElement.getLocalName();
      System.out.println("  ELEMENT Local Name    :" + localName);
 
      nsName = nsElement.getNamespaceURI();
      System.out.println("  ELEMENT Namespace     :" + nsName);
   } 
   System.out.println();
}

static void printElementAttributes(Document doc)
{
   NodeList nl = doc.getElementsByTagName("*");
   Element e;
   Attr nsAttr; 
   String attrpfx;
   String attrname;
   String attrval; 
   NamedNodeMap nnm;
   int i, len;
 
   len = nl.getLength();
 
   for (int j=0; j < len; j++)
   {
      e = (Element) nl.item(j);
      System.out.println(e.getTagName() + ":");
 
      nnm = e.getAttributes();
 
      if (nnm != null)
      {
         for (i=0; i < nnm.getLength(); i++)
         {
            nsAttr = (Attr) nnm.item(i);
 
            attrpfx = nsAttr.getPrefix();
            attrname = nsAttr.getLocalName();
            attrval = nsAttr.getNodeValue();
 
            System.out.println(" " + attrpfx + ":" + attrname + " = " 
                               + attrval);
         }
      }
      System.out.println();
   }
}

EventSample.java shows how to register events with an event listener. For example, adding a node to a specified DOM element triggers an event, which causes the listener to print information about the event.

1. Instantiate an event listener.

   When a registered change triggers an event, the event is passed to the event listener, which handles it. This code fragment from EventSample.java shows the implementation of the listener:

   eventlistener evtlist = new eventlistener();
   ...
   class eventlistener implements EventListener
   {
      public eventlistener(){}
      public void handleEvent(Event e)
      {
         String s = " Event "+e.getType()+" received " + "\n";
         s += " Event is cancelable :"+e.getCancelable()+"\n";
         s += " Event is bubbling event :"+e.getBubbles()+"\n";
         s += " The Target is " + ((Node)(e.getTarget())).getNodeName() + "\n\n";
         System.out.println(s);
      }
   }
   

2. Instantiate a new XMLDocument and then invoke getImplementation() to retrieve a DOMImplementation object.

   Invoke the hasFeature() method to determine which features this implementation supports, as this code fragment from EventSample.java does:

   XMLDocument doc1 = new XMLDocument();
   DOMImplementation impl = doc1.getImplementation();
    
   System.out.println("The impl supports Events "+
                      impl.hasFeature("Events", "2.0"));
   System.out.println("The impl supports Mutation Events "+
                      impl.hasFeature("MutationEvents", "2.0"));
   

3. Register desired events with the listener. This code fragment from EventSample.java registers three events on the document node:

   doc1.addEventListener("DOMNodeRemoved", evtlist, false);
   doc1.addEventListener("DOMNodeInserted", evtlist, false);
   doc1.addEventListener("DOMCharacterDataModified", evtlist, false);
   

   This code fragment from EventSample.java creates a node of type XMLElement and then registers three events on the node:

   XMLElement el = (XMLElement)doc1.createElement("element");
   ...
   el.addEventListener("DOMNodeRemoved", evtlist, false);
   el.addEventListener("DOMNodeRemovedFromDocument", evtlist, false);
   el.addEventListener("DOMCharacterDataModified", evtlist, false);
   ...
   

4. Perform actions that trigger events, which are then passed to the listener for handling, as this code fragment from EventSample.java does:

   att.setNodeValue("abc");
   el.appendChild(el1);
   el.appendChild(text);
   text.setNodeValue("xyz");
   doc1.removeChild(el);

According to the W3C DOM specification, a range identifies a range of content in a Document, DocumentFragment, or Attr. The range selects the content between a pair of boundary points that correspond to the start and end of the range.

1. After invoking getDocument() to create the XMLDocument, create a range object with createRange() and invoke setStart() and setEnd() to set its boundaries, as this code fragment from DOMRangeSample.java does:

   XMLDocument doc = parser.getDocument();
   ...
   Range r = (Range) doc.createRange();
   XMLNode c = (XMLNode) doc.getDocumentElement();
    
   // set the boundaries
   r.setStart(c,0);
   r.setEnd(c,1);
   

2. Invoke XMLDocument methods to get information about the range and manipulate its contents.

   This code fragment from DOMRangeSample.java selects and prints the contents of the current node:

   r.selectNodeContents(c);
   System.out.println(r.toString());
   

   This code fragment clones and prints the contents of a range:

   XMLDocumentFragment df =(XMLDocumentFragment) r.cloneContents();
   df.print(System.out);
   

   This code fragment gets and prints the start and end containers for the range:

   c = (XMLNode) r.getStartContainer();
   System.out.println(c.getText());
   c = (XMLNode) r.getEndContainer();
   System.out.println(c.getText());

XDK implements the NodeFilter and TreeWalker interfaces, which are defined by the W3C DOM Level 2 Traversal and Range specification.

1. Create a node filter object.

   The acceptNode() method in the nf class, which implements the NodeFilter interface, invokes getNodeType() to get the type of node, as this code fragment from TreeWalkerSample.java does:

   NodeFilter n2 = new nf();
   ...
   class nf implements NodeFilter
   {
     public short acceptNode(Node node)
     {
       short type = node.getNodeType();
    
       if ((type == Node.ELEMENT_NODE) || (type == Node.ATTRIBUTE_NODE))
          return FILTER_ACCEPT;
       if ((type == Node.ENTITY_REFERENCE_NODE))
          return FILTER_REJECT;
       return FILTER_SKIP;
     }
   }
   

2. Invoke the XMLDocument.createTreeWalker() method to create a tree walker.

   This code fragment from TreeWalkerSample.java uses the root node of the XMLDocument as the root node of the tree walker and includes all nodes in the tree:

   XMLDocument doc = parser.getDocument();
   ...
   TreeWalker tw = doc.createTreeWalker(doc.getDocumentElement(),NodeFilter.SHOW_ALL,n2,true);
   

3. Get the root element of the TreeWalker object, as this code fragment from TreeWalkerSample.java does:

   XMLNode nn = (XMLNode)tw.getRoot();
   

4. Traverse the tree.

   This code fragment from TreeWalkerSample.java walks the tree in document order by invoking the TreeWalker.nextNode() method:

   while (nn != null)
   {
     System.out.println(nn.getNodeName() + " " + nn.getNodeValue());
     nn = (XMLNode)tw.nextNode();
   }
   

   This code fragment from TreeWalkerSample.java walks the left depth of the tree by invoking the firstChild() method:

    while (nn != null)
    {
      System.out.println(nn.getNodeName() + " " + nn.getNodeValue());
      nn = (XMLNode)tw.firstChild();
    }
   

   You can walk the right depth of the tree by invoking the lastChild() method.

The interfaces and classes of the SAX API, which is released in a Level 1 and Level 2 version, are described.

These are the interfaces and classes:

• Interfaces implemented by the Oracle XML parser

• Interfaces that your application must implement (see Table 12-12)

• Standard SAX classes

• SAX 2.0 helper classes in the org.xml.sax.helper package (see Table 12-13)

• Demonstration classes in the nul package

Table 12-12 lists and describes the SAX 2.0 interfaces that your application must implement.

Table 12-13 lists and describes the SAX 2.0 helper classes.

Figure 12-5 shows how to create a SAX parser and use it to parse an input document.

Figure 12-5 Using the SAXParser Class

Description of "Figure 12-5 Using the SAXParser Class"

The basic steps for parsing an input XML document with SAX are:

1. Create a SAXParser object and configure its properties.

   For example, set the validation mode. For configuration methods, see Table 12-5.

2. Instantiate an event handler.

   Your application must implement the handler interfaces in Table 12-12.

3. Register your event handlers with the XML parser.

   This step enables the parser to invoke the correct methods when a given event occurs. For information about SAXParser methods for registering event handlers, see Table 12-14.

4. Parse the input document with the SAXParser.parse() method.

   All SAX interfaces are assumed to be synchronous: the parse method must not return until parsing is complete. Readers must wait for an event-handler callback to return before reporting the next event.

   When the SAXParser.parse() method is invoked, the program invokes one of several callback methods implemented in the application. The methods are defined by the ContentHandler, ErrorHandler, DTDHandler, and EntityResolver interfaces implemented in the event handler. For example, the application can invoke the startElement() method when a start element is encountered.

Table 12-14 lists and describes the SAXParser methods for registering event handlers and explains when to use them. An application can register a new or different handler in the middle of a parse; the SAX parser must begin using the newly registered handler immediately.

SAXSample.java shows the basic steps of SAX parsing. The SAXSample class extends HandlerBase. The program receives an XML file as input, parses it, and prints information about the contents of the file.

1. Store the Locator:

   Locator locator;
   

   The Locator associates a SAX event with a document location. The SAX parser provides location information to the application by passing a Locator instance to the setDocumentLocator() method in the content handler. The application can use the object to get the location of any other content handler event in the XML source document.

2. Instantiate a new event handler.:

   SAXSample sample = new SAXSample();
   

3. Instantiate the SAX parser and configure it:

   Parser parser = new SAXParser();
   ((SAXParser)parser).setValidationMode(SAXParser.DTD_VALIDATION);
   

   The preceding code sets the mode to DTD validation.

4. Register event handlers with the SAX parser:

   parser.setDocumentHandler(sample);
   parser.setEntityResolver(sample);
   parser.setDTDHandler(sample);
   parser.setErrorHandler(sample);
   

   You can use the registration methods in the SAXParser class, but you must implement the event handler interfaces yourself.

   Here is part of the DocumentHandler interface implementation:

   public void setDocumentLocator (Locator locator)
   {
     System.out.println("SetDocumentLocator:");
     this.locator = locator;
   }
   public void startDocument()
   {
     System.out.println("StartDocument");
   }
   public void endDocument() throws SAXException
   {
     System.out.println("EndDocument");
   }
   public void startElement(String name, AttributeList atts)
                                                  throws SAXException
   {
     System.out.println("StartElement:"+name);
     for (int i=0;i<atts.getLength();i++)
     {
       String aname = atts.getName(i);
       String type = atts.getType(i);
       String value = atts.getValue(i); 
       System.out.println("   "+aname+"("+type+")"+"="+value);
     }  
   }
   ...
   

   The following code implements the EntityResolver interface:

   public InputSource resolveEntity (String publicId, String systemId)
                         throws SAXException
   {
     System.out.println("ResolveEntity:"+publicId+" "+systemId);
     System.out.println("Locator:"+locator.getPublicId()+" locator.getSystemId()+
                       " "+locator.getLineNumber()+" "+locator.getColumnNumber());
     return null;
   }
   

   The following code implements the DTDHandler interface:

   public void notationDecl (String name, String publicId, String systemId)
   {
     System.out.println("NotationDecl:"+name+" "+publicId+" "+systemId);
   }
   public void unparsedEntityDecl (String name, String publicId,
                                   String systemId, String notationName)
   {
     System.out.println("UnparsedEntityDecl:"+name + " "+publicId+" "+
                         systemId+" "+notationName);
   }
   

   The following code implements the ErrorHandler interface:

   public void warning (SAXParseException e)
              throws SAXException
   {
     System.out.println("Warning:"+e.getMessage());
   }
   public void error (SAXParseException e)
              throws SAXException
   {
     throw new SAXException(e.getMessage());
   }
   public void fatalError (SAXParseException e)
             throws SAXException
   {
     System.out.println("Fatal error");
     throw new SAXException(e.getMessage());
   }
   

5. Parse the input XML document:

   parser.parse(DemoUtil.createURL(argv[0]).toString());
   

   The preceding code converts the document to a URL and then parses it.

SAX2Namespace.java implements an event handler named XMLDefaultHandler as a subclass of the org.xml.sax.helpers.DefaultHandler class.

1. Instantiate a new event handler of type DefaultHandler:

   DefaultHandler defHandler = new XMLDefaultHandler();
   

2. Create a SAX parser and set its validation mode:

   Parser parser = new SAXParser();
   ((SAXParser)parser).setValidationMode(SAXParser.DTD_VALIDATION);
   

   The preceding code sets the mode to DTD validation.

3. Register event handlers with the SAX parser:

   parser.setContentHandler(defHandler);
   parser.setEntityResolver(defHandler);
   parser.setDTDHandler(defHandler);
   parser.setErrorHandler(defHandler);
   

   The preceding code registers handlers for the input document, the DTD, entities, and errors.

   The following code shows the XMLDefaultHandler implementation. The startElement() and endElement() methods print the qualified name, local name, and namespace URI for each element (for an explanation of these terms, see Table 12-7).

   class XMLDefaultHandler extends DefaultHandler
   {
      public void XMLDefaultHandler(){}
      public void startElement(String uri, String localName,
                               String qName, Attributes atts)
      throws SAXException
      {
         System.out.println("ELEMENT Qualified Name:" + qName);
         System.out.println("ELEMENT Local Name    :" + localName);
         System.out.println("ELEMENT Namespace     :" + uri);
    
         for (int i=0; i<atts.getLength(); i++)
         {
            qName = atts.getQName(i);
            localName = atts.getLocalName(i);
            uri = atts.getURI(i);
    
            System.out.println(" ATTRIBUTE Qualified Name   :" + qName);
            System.out.println(" ATTRIBUTE Local Name       :" + localName);
            System.out.println(" ATTRIBUTE Namespace        :" + uri);
    
            // You can get the type and value of the attributes either
            // by index or by the Qualified Name.
    
            String type = atts.getType(qName);
            String value = atts.getValue(qName);
    
            System.out.println(" ATTRIBUTE Type             :" + type);
            System.out.println(" ATTRIBUTE Value            :" + value);
    
            System.out.println();
    
         }
      }
      public void endElement(String uri, String localName,
                             String qName) throws SAXException
      {
         System.out.println("ELEMENT Qualified Name:" + qName);
         System.out.println("ELEMENT Local Name    :" + localName);
         System.out.println("ELEMENT Namespace     :" + uri);
      }
   }
   

4. Parse the input XML document:

   parser.parse(DemoUtil.createURL(argv[0]).toString());
   

   The preceding code converts the document to a URL and then parses it.

You can create a simple SAX parser as a instance of the XMLTokenizer class and use the parser to tokenize the input XML.

1. Create a URL from the input XML stream:

   URL url = DemoUtil.createURL(arg);
   

2. Create an XMLTokenizer parser:

   parser  = new XMLTokenizer ((XMLToken)new Tokenizer());
   

3. Register an output error stream:

   parser.setErrorStream  (System.out);
   

4. Register tokens with the parser:

   parser.setToken (STagName, true);
   parser.setToken (EmptyElemTag, true);
   parser.setToken (STag, true);
   parser.setToken (ETag, true);
   parser.setToken (ETagName, true);
   ...
   

5. Tokenize the XML document:

   parser.tokenize (url);
   

   The token() callback method determines the action to take upon encountering a particular token. The following code is part of the implementation of this method:

   public void token (int token, String value)
   {
      switch (token)
      {
      case XMLToken.STag:
         System.out.println ("STag: " + value);
         break;
      case XMLToken.ETag:
         System.out.println ("ETag: " + value);
         break;
      case XMLToken.EmptyElemTag:
         System.out.println ("EmptyElemTag: " + value);
         break;
      case XMLToken.AttValue:
         System.out.println ("AttValue: " + value);
         break;
      ...
      default:
         break;
      }
   }

JAXP consists of abstract classes that provide a thin layer for parser pluggability. Oracle implemented JAXP based on the Sun reference implementation.

Table 12-16 lists and describes the packages that comprise JAXP.

You can rely on the factory design pattern to create new SAX parser engines with JAXP.

Figure 12-6 shows the basic process.

Figure 12-6 SAX Parsing with JAXP

Description of "Figure 12-6 SAX Parsing with JAXP"

The basic steps for parsing with SAX through JAXP are:

1. Create a new SAX parser factory with the SAXParserFactory class.
2. Configure the factory.
3. Create a new SAX parser (SAXParser) object from the factory.
4. Set the event handlers for the SAX parser.
5. Parse the input XML documents.

You can rely on the factory design pattern to create new DOM document builder engines with JAXP.

Figure 12-7 shows the basic process.

Figure 12-7 DOM Parsing with JAXP

Description of "Figure 12-7 DOM Parsing with JAXP"

The basic steps for parsing with DOM through JAXP are:

1. Create a new DOM parser factory with the DocumentBuilderFactory class.
2. Configure the factory.
3. Create a new DOM builder (DocumentBuilder) object from the factory.
4. Set the error handler and entity resolver for the DOM builder.
5. Parse the input XML documents.

The basic steps for transforming XML through JAXP are described.

1. Create a new transformer factory with the TransformerFactory class.
2. Configure the factory.
3. Create a new transformer from the factory and specify an XSLT stylesheet.
4. Configure the transformer.
5. Transform the document.

The JAXPExamples.java program shows the basic steps of parsing with JAXP.

public class JAXPExamples
{
        public static void main(String argv[])
        throws TransformerException, TransformerConfigurationException,
               IOException, SAXException, ParserConfigurationException,                 
               FileNotFoundException
        {
        try {
         URL xmlURL = createURL("jaxpone.xml");
         String xmlID = xmlURL.toString();
         URL xslURL = createURL("jaxpone.xsl");
         String xslID = xslURL.toString();
         //
         System.out.println("--- basic ---");
         basic(xmlID, xslID);
         System.out.println();
         ...
      } catch(Exception err) {
        err.printStackTrace();
      }
   }
   //
   public static void basic(String xmlID, String xslID)
      throws TransformerException, TransformerConfigurationException
   {
      TransformerFactory tfactory = TransformerFactory.newInstance();
      Transformer transformer = tfactory.newTransformer(new StreamSource(xslID));
      StreamSource source = new StreamSource(xmlID);
      transformer.transform(source, new StreamResult(System.out));
   }
...
}

1. Create a new instance of a TransformerFactory and cast it to a SAXTransformerFactory:

   TransformerFactory tfactory = TransformerFactory.newInstance();
   SAXTransformerFactory stfactory = (SAXTransformerFactory)tfactory;
   

2. Create an XML reader by creating a StreamSource object from a stylesheet and passing it to the factory method newXMLFilter():

   URL xslURL = createURL("jaxpone.xsl");
   String xslID = xslURL.toString();
   ...
   StreamSource streamSource = new StreamSource(xslID);
   XMLReader reader = stfactory.newXMLFilter(streamSource);
   

   newXMLFilter() returns an XMLFilter object that uses the specified Source as the transformation instructions.

3. Create a content handler and register it with the XML reader:

   ContentHandler contentHandler = new oraContentHandler();
   reader.setContentHandler(contentHandler);
   

   The preceding code creates an instance of the class oraContentHandler by compiling the oraContentHandler.java program in the demo directory.

   The following code shows part of the implementation of the oraContentHandler class:

   public class oraContentHandler implements ContentHandler
   {
      private static final String TRADE_MARK = "Oracle 9i ";
    
      public void setDocumentLocator(Locator locator)
      {
         System.out.println(TRADE_MARK + "- setDocumentLocator");
      }
    
      public void startDocument()
         throws SAXException
      {
         System.out.println(TRADE_MARK + "- startDocument");
      }
    
      public void endDocument()
         throws SAXException
      {
         System.out.println(TRADE_MARK + "- endDocument");
      }
      ...
   

4. Parse the input XML document by passing the InputSource to the XMLReader.parse() method:

   InputSource is = new InputSource(xmlID);
   reader.parse(is);

You can use JAXP to perform basic transformations.

1. Create a new instance of a TransformerFactory:

   TransformerFactory tfactory = TransformerFactory.newInstance();
   

2. Create a new XSL transformer from the factory and specify the stylesheet to use for the transformation:

   URL xslURL = createURL("jaxpone.xsl");
   String xslID = xslURL.toString();
   ...
   Transformer transformer = tfactory.newTransformer(new StreamSource(xslID));
   

   In the preceding code, the stylesheet is jaxpone.xsl.

3. Set the stream source to the input XML document:

   URL xmlURL = createURL("jaxpone.xml");
   String xmlID = xmlURL.toString();
   ...
   StreamSource source = new StreamSource(xmlID);
   

   In the preceding code, the stream source is jaxpone.xml.

4. Transform the document from a StreamSource to a StreamResult:

   transformer.transform(source, new StreamResult(System.out));

DOMCompression.java shows the basic steps of DOM compression. The most important DOM compression method is XMLDocument.writeExternal(), which saves the state of the object by creating a binary compressed stream with information about the object.

1. Create a DOM parser, parse an input XML document, and get the DOM representation:

   public class DOMCompression
   {
      static OutputStream out = System.out;
      public static void main(String[] args)
      {
         XMLDocument doc = new XMLDocument();
         DOMParser parser = new DOMParser();
         try
         {
           parser.setValidationMode(XMLParser.SCHEMA_VALIDATION);
           parser.setPreserveWhitespace(false);
           parser.retainCDATASection(true);
           parser.parse(createURL(args[0]));
           doc = parser.getDocument();
           ...
   

   For a description of this technique, see Performing Basic DOM Parsing.

2. Create a FileOutputStream and wrap it in an ObjectOutputStream for serialization:

   OutputStream os = new FileOutputStream("xml.ser");
   ObjectOutputStream oos = new ObjectOutputStream(os);
   

3. Serialize the object to the file by invoking XMLDocument.writeExternal():

   doc.writeExternal(oos);
   

   This method saves the state of the object by creating a binary compressed stream with information about this object.

DOMDeCompression.java shows the basic steps of DOM decompression. The most important DOM decompression method is XMLDocument.readExternal(), which reads the information that the writeExternal() method wrote (the compressed stream) and restores the object.

1. Create a file input stream for the compressed file and wrap it in an ObjectInputStream:

   InputStream is;
   ObjectInputStream ois;
   ...
   is = new FileInputStream("xml.ser");
   ois = new ObjectInputStream(is);
   

   The preceding code creates a FileInputStream from the compressed file created in Compressing a DOM Object.

2. Create a new XML document object to contain the decompressed data:

   XMLDocument serializedDoc = null;
   serializedDoc = new XMLDocument();
   

3. Read the compressed file by invoking XMLDocument.readExternal():

   serializedDoc.readExternal(ois);
   serializedDoc.print(System.out);
   

   The preceding code data and prints it to System.out.

SAXCompression.java shows the basic steps of parsing a file with SAX and writing the compressed stream to a file. The important class is CXMLHandlerBase, which is a SAX Handler that compresses XML data based on SAX events.

1. Create a FileOutputStream and wrap it in an ObjectOutputStream:

   String compFile = "xml.ser";
   FileOutputStream outStream = new FileOutputStream(compFile);
   ObjectOutputStream out = new ObjectOutputStream(outStream);
   

2. Create the SAX event handler:

   CXMLHandlerBase cxml = new CXMLHandlerBase(out);
   
   

   The CXMLHandlerBase class implements the ContentHandler, DTDHandler, EntityResolver, and ErrorHandler interfaces.

3. Create the SAX parser:

   SAXParser parser = new SAXParser();
   

4. Configure the SAX parser:

   parser.setContentHandler(cxml);
   parser.setEntityResolver(cxml);
   parser.setValidationMode(XMLConstants.NONVALIDATING);
   

   The preceding code sets the content handler, entity resolver, and validation mode.

   Note:

   Although oracle.xml.comp.CXMLHandlerBase implements both DocumentHandler and ContentHandler interfaces, Oracle recommends using the SAX 2.0 ContentHandler interface.

5. Parse the XML:

   parser.parse(url);
   

   The SAXCompression.java program writes the serialized data to the ObjectOutputStream.

SAXDeCompression.java shows the basic steps of reading the serialized data from the file that SAXCompression.java wrote. The important class is CXMLParser, which is an XML parser that regenerates SAX events from a compressed stream.

1. Create a SAX event handler:

   SampleSAXHandler xmlHandler = new SampleSAXHandler();
   

2. Create the SAX parser by instantiating the CXMLParser class:

   CXMLParser parser = new CXMLParser();
   

   The CXMLParser class implements the regeneration of XML documents from a compressed stream by generating SAX events from them.

3. Set the event handler for the SAX parser:

   parser.setContentHandler(xmlHandler);
   

4. Parse the compressed stream and generate the SAX events:

   parser.parse(args[0]);
   

   The preceding code receives a file name from the command line and parses the XML.

You can use the selectNodes() method in the XMLNode class to extract content from a DOM tree or subtree based on the select patterns allowed by XSL.

% java selectNodesTest family.xml
Sarah
Bob
Joanne
Jim

% java selectNodesTest family.xml //member/@memberid
m1
m2
m3
m4

//
// selectNodesTest.java
//
import java.io.*;
import oracle.xml.parser.v2.*;
import org.w3c.dom.Node;
import org.w3c.dom.Element;
import org.w3c.dom.Document;
import org.w3c.dom.NodeList;
 
public class selectNodesTest
{
  public static void main(String[] args)
    throws Exception
  {
    // supply an xpath expression
    String pattern = "/family/member/text()";
    // accept a filename on the command line
    // run the program with $ORACLE_HOME/xdk/demo/java/parser/common/family.xml
    String file    = args[0];
 
    if (args.length == 2)
      pattern = args[1];
 
    DOMParser dp = new DOMParser();
 
    dp.parse(DemoUtil.createURL(file));  // include createURL from DemoUtil
    XMLDocument xd = dp.getDocument();
    XMLElement element = (XMLElement) xd.getDocumentElement();
    NodeList nl = element.selectNodes(pattern, element);
    for (int i = 0; i < nl.getLength(); i++)
    {
      System.out.println(nl.item(i).getNodeValue());
    } // end for
  } // end main
} // end selectNodesTest

How to merge XML documents using XMLElement.appendChild() is described.

String firstname = "Gianfranco";
String lastname = "Pietraforte";

XMLDocument xmldoc1 = new XMLDocument();
XMLElement e1 = xmldoc1.createElement("person");
XMLDocument xmldoc2 = new XMLDocument();
XMLElement e2 = xmldoc2.createElement("firstname");
e1.appendChild(e2);

XMLDocument doc1 = new XMLDocument();
XMLElement element1 = doc1.createElement("person");
XMLDocument doc2 = new XMLDocument();
XMLElement element2 = doc2.createElement("firstname");
// element2 = doc1.importNode(element2);
// element2 = doc1.adoptNode(element2);
element1.appendChild(element2);

You can use load and parse a DTD.

Topics for handling character sets with the parser are introduced.