4 XML Parsing for Java

Prerequisites

Oracle XML parsing reads an XML document and uses DOM or SAX APIs to provide programmatic access to its content and structure. You can use parsing in validating or nonvalidating mode.

This chapter assumes that you are familiar with the following technologies:

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

• Simple API for XML (SAX). SAX is a standard for event-based XML parsing.

• Java API for XML Processing (JAXP). JAXP is a standard interface for processing XML with Java applications. It supports the DOM and SAX standards.

• Document Type Definition (DTD). An XML DTD defines the legal structure of an XML document.

• XML Schema. Like a DTD, an XML schema defines the legal structure of an XML document.

• XML Namespaces. Namespaces are a mechanism for differentiating element and attribute names.

• Binary XML. Both scalable and nonscalable DOMs can save XML documents in this format.

If you require a general introduction to the preceding technologies, consult the XML resources listed in "Related Documents" of the preface.

Standards and Specifications

The DOM Level 1, Level 2, and Level 3 specifications are W3C Recommendations. You can find links to the specifications for all three levels at the following URL:

http://www.w3.org/DOM/DOMTR

SAX is available in version 1.0, which is deprecated, and 2.0. It is not a W3C specification. You can find the documentation for SAX at the following URL:

http://www.saxproject.org/

XML Namespaces are a W3C Recommendation. You can find the specification at the following URL:

http://www.w3.org/TR/REC-xml-names

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

JAXP version 1.2 includes an XSLT framework plus some updates to the parsing API to support DOM Level 2 and SAX version 2.0 and an improved scheme to locate pluggable implementations. JAXP provides support for XML schema and an XSLT compiler. You can access the JAXP specification, which is produced by Sun Microsystems, at the following URL:

http://java.sun.com/xml/downloads/jaxp.html

Large Node Handling

DOM Stream access to XML nodes is done by PL/SQL and Java APIs. Nodes in an XML document can now exceed 64 KBytes by a large amount. Thus JPEG, Word, PDF, RTF, and HTML documents can be more readily stored.

XML Parsing in Java

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 method to parse Binary XML to create scalable DOM.

Figure 4-1 illustrates the basic parsing process, using XMLParser. The diagram does not apply to XMLDOMImplementation().

Figure 4-1 The XML Parser Process

Description of "Figure 4-1 The XML Parser Process"

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

• DOM API, which parses XML documents and builds a tree representation of the documents in memory. Use either a DOMParser object to parse with DOM or the XMLDOMImplementation interface factory methods to create a pluggable, scalable DOM.

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

• JAXP, which is a Java-specific API that supports DOM, SAX, and XSL. Use a DocumentBuilder or SAXParser object to parse with JAXP.

The sample XML document in Example 4-1 helps illustrate the differences among DOM, SAX, and JAXP.

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

DOM in XML Parsing

DOM builds an in-memory tree representation of the XML document. For example, the DOM API receives the document described in Example 4-1 and creates an in-memory tree as shown in Figure 4-2. DOM provides classes and methods to navigate and process the tree.

In general, the DOM API provides the following advantages:

• DOM API is easier to use than SAX because it provides a familiar tree structure of objects.

• Structural manipulations of the XML tree, such as re-ordering elements, adding to and deleting elements and attributes, and renaming elements, can be performed.

• Interactive applications can store the object model in memory, enabling users to access and manipulate it.

• DOM as a standard does not support XPath. However, most XPath implementations use DOM. The Oracle XDK includes DOM API extensions to support XPath.

• A pluggable, scalable DOM can be created that considerably improves scalability and efficiency.

Scalable DOM

With Oracle 11g Release 1 (11.1), XDK provides scalable, pluggable support for DOM. This relieves problems of memory inefficiency, limited scalability, and lack of control over the DOM configuration.

For the scalable DOM, the configuration and creation are mainly supported using the XMLDOMImplementation class.

These are important aspects of scalable DOM:

• Plug-in Data allows external XML representation to be directly used by Scalable DOM without replicating XML in internal representation.

  Scalable DOM is created on top of plug-in XML data through the Reader and InfosetWriter abstract interfaces. XML data can be in different forms, such as Binary XML, XMLType, and third-party DOM, and so on.

• Transient nodes. DOM nodes are created lazily and may be freed if not in use.

• Binary XML

  The scalable DOM can use binary XML as both input and output format. Scalable DOM can interact with the data in two ways:

  • Through the abstract InfosetReader and InfosetWriter interfaces. Users can (1) use the BinXML implementation of InfosetReader and InfosetWriter to read and write BinXML data, and (2) use other implementations supplied by the user to read and write in other forms of XML infoset.

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

  See Also:

  Chapter 5, "Using Binary XML for Java"

Scalable DOM support consists of the following:

• Pluggable DOM Support

• Lazy Materialization

• Configurable DOM Settings

SAX in the XML Parser

Unlike DOM, SAX is event-based, so it does not build in-memory tree representations of input documents. SAX processes the input document element by element and can report events and significant data to callback methods in the application. The XML document in Example 4-1 is parsed as a series of linear events as shown in Figure 4-2.

In general, the SAX API provides the following advantages:

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

• It does not consume significant memory resources.

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

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

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

JAXP in the XML Parser

The JAXP API enables you to plug in an implementation of the SAX or DOM parser. The SAX and DOM APIs provided in the Oracle XDK are examples of vendor-specific implementations supported by JAXP.

In general, the advantage of JAXP is that you can use it to write interoperable applications. If an application uses features available through JAXP, then it can very easily switch the implementation.

The main disadvantage of JAXP is that it runs more slowly than vendor-specific APIs. In addition, several features are available through Oracle-specific APIs that are not available through JAXP APIs. Only some of the Oracle-specific features are available through the extension mechanism provided in JAXP. If an application uses these extensions, however, then the flexibility of switching implementation is lost.

Namespace Support in the XML Parser

The XML parser for Java can parse unqualified element types and attribute names as well as those in namespaces. Namespaces are a mechanism to resolve or avoid name collisions between element types or attributes in XML documents by providing "universal" names. Consider the XML document shown in Example 4-2.

<?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>

Without the use of namespaces, an application processing the XML document in Example 4-2 does not know whether the <address> tag refers to a company or employee address. As shown in Example 4-3, you can use namespaces to distinguish the <address> tags. The example declares the following XML namespaces:

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

Example 4-3 associates the com prefix with the first namespace and the emp prefix with the second namespace. Thus, an application can distinguish <com:address> from <emp:address>.

<?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>

It is helpful to remember the following terms when parsing documents that use namespaces:

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

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

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

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

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

Validation in the XML Parser

Applications invoke the parse() method to parse XML documents. Typically, applications invoke initialization and termination methods in association with the parse() method. You can use the setValidationMode() method defined in oracle.xml.parser.v2.XMLParser to set the parser mode to validating or nonvalidating.

By parsing an XML document according to the rules specified in a DTD or an XML schema, a validating XML parser determines whether the document conforms to the specified DTD or XML schema. If the XML document does conform, then the document is valid, which means that the structure of the document conforms to the DTD or schema rules. A nonvalidating parser checks for well-formedness only.

Table 4-1 shows the flags that you can use in setValidationMode() to set the validation mode in the Oracle 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.

Compression in the XML Parser

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 a number of tags and 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 an in-memory DOM tree or SAX events generated from an XML document. Table 4-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 vice versa. As with XML documents in general, you can store the compressed XML data output in the database as a BLOB.

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's default serialization.

Using the XML Parser for Java: Basic Process

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

Figure 4-3 XML Parser for Java

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

The basic process of the application shown in Figure 4-3 is as follows:

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.

Running the XML Parser Demo Programs

Demo programs for the XML parser for Java are included in $ORACLE_HOME/xdk/demo/java/parser. The demo programs are distributed among the subdirectories described in Table 4-3.

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

Documentation for how to compile and run the sample programs is located in the README. The basic steps are as follows:

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 Java XDK Environment".

3. Change into each of the following 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.

Using the XML Parser Command-Line Utility

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.

To use oraxml ensure that the following is true:

• Your CLASSPATH is set up as described in "Setting Up the Java XDK Environment". In particular, make sure you CLASSPATH environment variable points to the xmlparserv2.jar file.

• Your PATH environment variable can find the Java interpreter that comes with the version of the JDK that you are using.

Table 4-4 lists the oraxml command-line options.

For example, change into the $ORACLE_HOME/xdk/demo/java/parser/common directory. You can validate the document family.xml against family.dtd by executing the following on the command line:

oraxml -dtd -enc family.xml

The output should appear as follows:

The encoding of the input file: UTF-8The input XML file is parsed without errors using DTD validation mode.

Using the DOM API

To implement DOM-based components in your XML application, you can use the following XDK classes:

• oracle.xml.parser.v2.DOMParser. This class implements an XML 1.0 parser according to the W3C recommendation. Because DOMParser extends XMLParser, all methods of XMLParser are available to DOMParser.

  See Also:

  "DOM Parser Architecture"

• oracle.xml.parser.v2.XMLDOMImplementation. This class contains factory methods used to created scalable, pluggable DOM.

  For purposes of this discussion, DOMs created with the XMLDOMImplementation class are referred to as scalable or pluggable DOM.

  See Also:

  "Creating Scalable DOM"

You can also make use of the DOMNamespace and DOM2Namespace classes, which are sample programs included in $ORACLE_HOME/xdk/demo/java/parser/dom.

DOM Parser Architecture

Figure 4-4 is an architectural diagram of the DOM Parser.

Figure 4-4 Basic Architecture of the DOM Parser

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

Useful Methods and Interfaces

The following tables provide useful methods and interfaces to use in creating an application such as the one just created in "Performing Basic DOM Parsing".

Table 4-5 lists useful configuration methods.

Table 4-6 lists the interfaces that the XMLDocument class implements.

Table 4-7 lists some useful methods for obtaining nodes.

Creating Scalable DOM

This section discusses how to create and use a scalable DOM.

This section contains the following topics:

• Using Pluggable DOM

• Using Lazy Materialization

• Using Configurable DOM Settings

• Scalable DOM Applications

public Document createDocument(InfosetReader reader) throws DOMException

InfosetReader reader;
While (reader.hasNext())
{
   reader.next();
   if (reader.getEventType() == START_ELEMENT)
   {
        QName name = reader.getQName();
        TypedAttributeList attrList = reader.getAttributeList();
     }
} 

If (reader.hasSeekSupport())
   reader.seek(offset);

XMLDocument doc;
InfosetWriter writer;
doc.save(writer, false);
writer.close();
 

DOMParser parser = new DOMParser();
parser.setAttribute(PARTIAL_DOM, Boolean.TRUE); //enable scalable DOM
parser.setAttribute(PAGE_MANAGER, new FilePageManager("pageFile"));
...
// DOMParser other configuration
parser.parse(fileURL);
XMLDocument doc = parser.getDocument();

public void setAttribute(String name, Object value) throws IllegalArgumentException

XMLDOMImplementation domimpl = new XMLDOMImplementation();
domimpl.setAttribute(XMLDocument.SCALABLE_DOM, Boolean.TRUE);
domimpl.setAttribute(XMLDocument.ACCESS_MODE,XMLDocument.UPDATEABLE);
XMLDocument scalableDoc = (XMLDocument) domimpl.createDocument(reader);

BinXMLProcessor proc = BinXMLProcessorFactory.createProcessor();
BinXMLStream bstr = proc.createBinXMLStream();
BinXMLEncoder enc = bstr.getEncoder();
enc.setProperty(BinXMLEncoder.ENC_SCHEMA_AWARE, false);
 
SAXParser parser = new SAXParser();
parser.setContentHandler(enc.getContentHandler());
parser.setErrorHandler(enc.getErrorHandler());
parser.parse(BinXMLUtil.createURL(xmlfile));
 
BinXMLDecoder dec = bstr.getDecoder();
InfosetReader reader = dec.getReader();
XMLDOMImplementation domimpl = new XMLDOMImplementation();
domimpl.setAttribute(XMLDocument.SCALABLE_DOM, Boolean.TRUE);
XMLDocument currentDoc = (XMLDocument) domimpl.createDocument(reader);

Performing DOM Operations with Namespaces

The DOM2Namespace.java program illustrates 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.

The initial four steps of the "Performing Basic DOM Parsing", from parser creation to the getDocument() call, are basically the same as for DOM2Namespace.java. The principal difference is in printing the DOM tree, which is step 5. The DOM2Namespace.java program does the following instead:

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

The printElements() method implemented by DOM2Namespace.java calls getElementsByTagName() to obtain a list of all the elements in the DOM tree. It then loops through each item in the list and casts each Element to an nsElement. For each nsElement it calls nsElement.getPrefix() to get the namespace prefix, nsElement.getLocalName() to get the local name, and nsElement.getNamespaceURI() to get the namespace URI:

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();
}

The printElementAttributes() method calls Document.getElementsByTagName() to obtain a NodeList of the elements in the DOM tree. It then loops through each element and calls Element.getAttributes() to obtain the list of attributes for the element as special list called a NamedNodeMap. For each item in the attribute list it calls nsAttr.getPrefix() to get the namespace prefix, nsAttr.getLocalName() to get the local name, and nsAttr.getValue() to obtain the value:

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();
   }
}

Performing DOM Operations with Events

The EventSample.java program shows how to register various events with an event listener. For example, if a node is added to a specified DOM element, an event is triggered, which causes the listener to print information about the event.

The program follows these steps:

1. Instantiate an event listener. When a registered change triggers an event, this event is passed to the event listener, which handles it. The following 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 call getImplementation() to retrieve a DOMImplementation object. You can call the hasFeature() method to determine which features are supported by this implementation. The following code fragment from EventSample.java illustrates this technique:

   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. The following 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);
   

   The following code fragment from EventSample.java creates a node of type XMLElement and then registers three events on this 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. The following code fragment from EventSample.java illustrates this technique:

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

Performing DOM Operations with Ranges

According to the W3C DOM specification, a range identifies a range of content in a Document, DocumentFragment, or Attr. It selects the content between a pair of boundary-points that correspond to the start and the end of the range. Table 4-8 describes useful range methods accessible through XMLDocument.

The DOMRangeSample.java program illustrates some of the things that you can do with ranges.

The initial four steps of the "Performing Basic DOM Parsing", from parser creation to the getDocument() call, are the same as for DOMRangeSample.java. The DOMRangeSample.java program then proceeds by following these steps:

1. After calling getDocument() to create the XMLDocument, create a range object with createRange() and call setStart() and setEnd() to set its boundaries. The following code fragment from DOMRangeSample.java illustrates this technique:

   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. Call XMLDocument methods to obtain information about the range and manipulate its contents. Table 4-8 describes useful methods. The following code fragment from DOMRangeSample.java selects the contents of the current node and prints it:

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

   The following code fragment clones a range contents and prints it:

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

   The following code fragment obtains 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());
   

Only some of the features of the demo program are described in this section. For more detail, refer to the demo program itself.

Performing DOM Operations with TreeWalker

The W3C DOM Level 2 Traversal and Range specification defines the NodeFilter and TreeWalker interfaces. The XDK includes implementations of these interfaces.

A node filter is an object that can filter out certain types of Node objects. For example, it can filter out entity reference nodes but accept element and attribute nodes. You create a node filter by implementing the NodeFilter interface and then passing a Node object to the acceptNode() method. Typically, the acceptNode() method implementation calls getNodeType() to obtain the type of the node and compares it to static variables such as ELEMENT_TYPE, ATTRIBUTE_TYPE, and so forth, and then returns one of the static fields in Table 4-9 based on what it finds.

You can use TreeWalker objects to traverse a document tree or subtree using the view of the document defined by their whatToShow flags and filters (if any). You can use the XMLDocument.createTreeWalker() method to create a TreeWalker object by specifying the following:

• A root node for the tree

• A flag that governs the type of nodes it should include in the logical view

• A filter for filtering nodes

• A flag that determines whether entity references and their descendents should be included

Table 4-10 describes useful methods in the org.w3c.dom.traversal.TreeWalker interface.

The TreeWalkerSample.java program illustrates some of the things that you can do with node filters and tree traversals.

The initial four steps of the "Performing Basic DOM Parsing", from parser creation to the getDocument() call, are the same as for TreeWalkerSample.java. The TreeWalkerSample.java program then proceeds by following these steps:

1. Create a node filter object. The acceptNode() method in the nf class, which implements the NodeFilter interface, invokes getNodeType() to obtain the type of node. The following code fragment from TreeWalkerSample.java illustrates this technique:

   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. The following 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. Obtain the root element of the TreeWalker object. The following code fragment illustrates this technique:

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

4. Traverse the tree. The following code fragment illustrates how to walk the tree in document order by calling the TreeWalker.nextNode() method:

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

   The following code fragment illustrates how to walk the tree the left depth of the tree by calling the firstChild() method (you can traverse the right depth of the tree by calling the lastChild() method):

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

Only some of the features of the demo program are described in this section. For more detail, refer to the demo program itself.

Using the SAX API

The SAX API, which is released in a Level 1 and Level 2 versions, is a set of interfaces and classes. We can divide the API into the following categories:

• Interfaces implemented by the Oracle XML parser.

• Interfaces that you must implement in your application. The SAX 2.0 interfaces are listed in Table 4-11.

  Table 4-11 SAX2 Handler Interfaces

  Interface	Description
  ContentHandler	Receives notifications from the XML parser. The major event-handling methods are startDocument(), endDocument(), startElement(), and endElement() when it recognizes an XML tag. This interface also defines the methods characters() and processingInstruction(), which are invoked when the parser encounters the text in an XML element or an inline processing instruction.
  DeclHandler	Receives notifications about DTD declarations in the XML document.
  DTDHandler	Processes notations and unparsed (binary) entities.
  EntityResolver	Needed to perform redirection of URIs in documents. The resolveEntity() method is invoked when the parser must identify data identified by a URI.
  ErrorHandler	Handles parser errors. The program invokes the methods error(), fatalError(), and warning() in response to various parsing errors.
  LexicalHandler	Receives notifications about lexical information such as comments and CDATA section boundaries.

  
  

• Standard SAX classes.

• Additional Java classes in org.xml.sax.helper. The SAX 2.0 helper classes are as follows:

  • AttributeImpl, which makes a persistent copy of an AttributeList

  • DefaultHandler, which is a base class with default implementations of the SAX2 handler interfaces listed in Table 4-11

  • LocatorImpl, which makes a persistent snapshot of a Locator's values at specified point in the parse

  • NamespaceSupport, which adds support for XML namespaces

  • XMLFilterImpl, which is a base class used by applications that need to modify the stream of events

  • XMLReaderFactory, which supports loading SAX parsers dynamically

• Demonstration classes in the nul package.

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

Figure 4-5 Using the SAXParser Class

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

The basic stages for parsing an input XML document with SAX are as follows:

1. Create a SAXParser object and configure its properties (see Table 4-5 for useful property methods). For example, set the validation mode of the parser.

2. Instantiate an event handler. The program should provide implementations of the handler interfaces in Table 4-11.

3. Register the event handlers with the parser. You must register your event handlers with the parser so that it knows which methods to invoke when a given event occurs. Table 4-12 lists registration methods available in SAXParser.

   Table 4-12 SAXParser Methods for Registering Event Handlers

   Method	Use this method to . . .
   setContentHandler()	Register a content event handler with an application. The org.xml.sax.DefaultHandler class implements the org.xml.sax.ContentHandler interface. Applications can register a new or different handler in the middle of a parse; the SAX parser must begin using the new handler immediately.
   setDTDHandler()	Register a DTD event handler. If the application does not register a DTD handler, all DTD events reported by the SAX parser are silently ignored. Applications may register a new or different handler in the middle of a parse; the SAX parser must begin using the new handler immediately.
   setErrorHandler()	Register an error event handler with an application. If the application does not register an error handler, all error events reported by the SAX parser are silently ignored; however, normal processing may not continue. It is highly recommended that all SAX applications implement an error handler to avoid unexpected bugs. Applications may register a new or different handler in the middle of a parse; the SAX parser must begin using the new handler immediately.
   setEntityResolver()	Register an entity resolver with an application. If the application does not register an entity resolver, the XMLReader performs its own default resolution. Applications may register a new or different resolver in the middle of a parse; the SAX parser must begin using the new resolver immediately.

   
   

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.

5. When the SAXParser.parse() method is called, 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 call the startElement() method when a start element is encountered.

Performing Basic SAX Parsing

The SAXSample.java program illustrates 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.

The program follows these steps:

1. Store the 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 obtain the location of any other content handler event in the XML source document. The following code fragment from SAXSample.java illustrates this technique:

   Locator locator;
   

2. Instantiate a new event handler. The following code fragment from SAXSample.java illustrates this technique:

   SAXSample sample = new SAXSample();
   

3. Instantiate the SAX parser and configure it. The following code fragment from SAXSample.java sets the mode to DTD validation:

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

4. Register event handlers with the SAX parser. You can use the registration methods in the SAXParser class, but you must implement the handler interfaces yourself. The following code fragment registers the handlers:

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

   The following code shows some 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 shows the EntityResolver interface implementation:

   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 shows the DTDHandler interface implementation:

   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 shows the ErrorHandler interface implementation:

   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. The following code fragment converts the document to a URL and then parses it:

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

Performing Basic SAX Parsing with Namespaces

This section discusses the SAX2Namespace.java sample program, which implements an event handler named XMLDefaultHandler as a subclass of the org.xml.sax.helpers.DefaultHandler class. The easiest way to implement the ContentHandler interface is to extend the org.xml.sax.helpers.DefaultHandler class. The DefaultHandler class provides some default behavior for handling events, although typically the behavior is to do nothing.

The SAX2Namespace.java program overrides methods for only the events that it cares about. Specifically, the XMLDefaultHandler class implements only two methods: startElement() and endElement(). The startElement event is triggered whenever SAXParser encounters a new element within the XML document. When this event is triggered, the startElement() method prints the namespace information for the element.

The SAX2Namespace.java sample program follows these steps:

1. Instantiate a new event handler of type DefaultHandler. The following code fragment illustrates this technique:

   DefaultHandler defHandler = new XMLDefaultHandler();
   

2. Create a SAX parser and set its validation mode. The following code fragment from SAXSample.java sets the mode to DTD validation:

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

3. Register event handlers with the SAX parser. The following code fragment registers handlers for the input document, the DTD, entities, and errors:

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

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

   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. The following code fragment converts the document to a URL and then parses it:

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

Performing SAX Parsing with XMLTokenizer

You can create a simple SAX parser as a instance of the XMLTokenizer class and use the parser to tokenize the input XML. Table 4-13 lists useful methods in the class.

SAX parsers with Tokenizer features must implement the XMLToken interface. The callback method for XMLToken is token(), which receives an XML token and its corresponding value and performs an action. For example, you can implement token() so that it prints the token name followed by the value of the token.

The Tokenizer.java program accepts an XML document as input, parses it, and prints a list of the XML tokens. The program implements a doParse() method that does the following:

1. Create a URL from the input XML stream:

   URL url = DemoUtil.createURL(arg);
   

2. Create an XMLTokenizer parser as follows:

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

3. Register an output error stream as follows:

   parser.setErrorStream  (System.out);
   

4. Register tokens with the parser. The following code fragment from Tokenizer.java shows just some of the registered tokens:

   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 as follows:

   parser.tokenize (url);
   

   The token() callback method determines the action to take when an particular token is encountered. The following code fragment from Tokenizer.java shows some 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;
      }
   }
   

Using the JAXP API

The JAXP APIs, which are listed in Table 4-14, have an API structure consisting of abstract classes that provide a thin layer for parser pluggability. Oracle implemented JAXP based on the Sun Microsystems reference implementation.

Using the SAX API Through JAXP

You can rely on the factory design pattern to create new SAX parser engines with JAXP. Figure 4-6 illustrates the basic process.

Figure 4-6 SAX Parsing with JAXP

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

The basic steps for parsing with SAX through JAXP are as follows:

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.

Using the DOM API Through JAXP

You can rely on the factory design pattern to create new DOM document builder engines with JAXP. Figure 4-7 illustrates the basic process.

Figure 4-7 DOM Parsing with JAXP

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

The basic steps for parsing with DOM through JAXP are as follows:

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.

Parsing with JAXP

The JAXPExamples.java program illustrates the basic steps of parsing with JAXP. The program implements the following methods and uses them to parse and perform additional processing on XML files in the /jaxp directory:

• basic()

• identity()

• namespaceURI()

• templatesHandler()

• contentHandler2contentHandler()

• contentHandler2DOM()

• reader()

• xmlFilter()

• xmlFilterChain()

The program creates URLs for the jaxpone.xml and jaxpone.xsl sample XML files and then calls the preceding methods in sequence. The basic design of the demo is as follows (to save space only the basic() method is shown):

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));
   }
...
}

The reader() method in JAXPExamples.java program shows a simple technique for parsing an XML document with SAX. It follows these steps:

1. Create a new instance of a TransformerFactory and then cast it to a SAXTransformerFactory. The application can use the SAX factory to configure and obtain SAX parser instances. For example:

   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(). This method returns an XMLFilter object that uses the specified Source as the transformation instructions. For example:

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

3. Create content handler and register it with the XML reader. The following example creates an instance of the class oraContentHandler, which is created by compiling the oraContentHandler.java program in the demo directory:

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

   The following code fragment shows some 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. For example:

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

Performing Basic Transformations with JAXP

You can use JAXP to transform any class of the interface Source into a class of the interface Result. Table 4-15 shows some sample transformations.

These transformations accept the following types of input:

• XML documents

• stylesheets

• The ContentHandler class defined in oraContentHandler.java

For example, you can use the identity() method to perform a transformation in which the output XML document is the same as the input XML document. You can use the xmlFilterChain() method to apply three stylesheets in a chain.

The basic() method shows how to perform a basic XSLT transformation. The method follows these steps:

1. Create a new instance of a TransformerFactory. For example:

   TransformerFactory tfactory = TransformerFactory.newInstance();
   

2. Create a new XSL transformer from the factory and specify the stylesheet to use for the transformation. The following example specifies the jaxpone.xsl stylesheet:

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

3. Set the stream source to the input XML document. The following fragment from the basic() method sets the stream source to jaxpone.xml:

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

4. Transform the document from a StreamSource to a StreamResult. The following example transforms a StreamSource into a StreamResult:

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

Compressing and Decompressing XML from DOM

The DOMCompression.java and DOMDeCompression.java programs illustrate the basic steps of DOM compression and decompression. The most important DOM compression methods are the following:

• XMLDocument.writeExternal() saves the state of the object by creating a binary compressed stream with information about the object.

• XMLDocument.readExternal() reads the information written in the compressed stream by the writeExternal() method and restores the object.

Compressing and Decompressing XML from SAX

The SAXCompression.java program illustrates the basic steps of parsing a file with SAX, writing the compressed stream to a file, and then reading the serialized data from the file. The important classes are as follows:

• CXMLHandlerBase is a SAX Handler that compresses XML data based on SAX events. To use the SAX compression, implement this interface and register with the SAX parser by calling Parser.setDocumentHandler().

• CXMLParser is an XML parser that regenerates SAX events from a compressed stream.

Extracting Node Values from a DOM Tree

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. You can use the optional second parameter of selectNodes() to resolve namespace prefixes, that is, to return the expanded namespace URL when given a prefix. The XMLElement class implements NSResolver, so a reference to an XMLElement object can be sent as the second parameter. XMLElement resolves the prefixes based on the input document. You can use the NSResolver interface if you need to override the namespace definitions.

The sample code in Example 4-4 illustrates how to use selectNodes().

//
// 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

To test the program, create a file with the code in Example 4-4 and then compile it in the $ORACLE_HOME/xdk/demo/java/parser/common directory. Pass the filename family.xml to the program as a parameter to traverse the <family> tree. The output should be as follows:

% java selectNodesTest family.xml
Sarah
Bob
Joanne
Jim

Now run the following to determine the values of the memberid attributes of all <member> elements in the document:

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

Merging Documents with appendChild()

Suppose that you want to write a program so that a user can fill in a client-side Java form and obtain an XML document. Suppose that your Java program contains the following variables of type String:

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

You can use either of the following techniques to insert this information into an XML document:

• Create an XML document in a string and then parse it. For example:

  String xml = "<person><first>"+firstname+"</first>"+
       "<last>"+lastname+"</last></person>";
  DOMParser d = new DOMParser();
  d.parse(new StringReader(xml));
  Document xmldoc = d.getDocument();
  

• Use DOM APIs to construct an XML document, creating elements and then appending them to one another. For example:

  Document xmldoc = new XMLDocument();
  Element e1 = xmldoc.createElement("person");
  xmldoc.appendChild(e1);
  Element e2 = xmldoc.createElement("firstname");
  e1.appendChild(e2);
  Text t = xmldoc.createText("Larry");
  e2.appendChild(t);
  

Note that you can only use the second technique on a single DOM tree. For example, suppose that you write the code snippet in Example 4-5.

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

The preceding code raises a DOM exception of WRONG_DOCUMENT_ERR when calling XMLElement.appendChild() because the owner document of e1 is xmldoc1 whereas the owner of e2 is xmldoc2. The appendChild() method only works within a single tree, but the code in Example 4-5 uses two different trees.

You can use the XMLDocument.importNode() method, introduced in DOM 2, and the XMLDocument.adoptNode() method, introduced in DOM 3, to copy and paste a DOM document fragment or a DOM node across different XML documents. The commented lines in Example 4-6 show how to perform this task.

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);

Parsing DTDs

This section discusses techniques for parsing DTDs. It contains the sections:

• Loading External DTDs

• Caching DTDs with setDoctype

DOMParser parser = new DOMParser();
DTD dtd = parser.getDoctype();
parser.setDoctype(dtd);

/**
 * DESCRIPTION
 * This program illustrates DTD caching.
 */

import java.net.URL;
import java.io.*;
import org.xml.sax.InputSource;
import oracle.xml.parser.v2.*;
 
public class DTDSample
{
   static public void main(String[] args)
   {
      try
      {
         if (args.length != 3)
         {
            System.err.println("Usage: java DTDSample dtd rootelement xmldoc");
            System.exit(1);
         }
 
         // Create a DOM parser
         DOMParser parser = new DOMParser();
 
         // Configure the parser
         parser.setErrorStream(System.out);
         parser.showWarnings(true);
 
        // Create a FileReader for the DTD file specified on the command
        // line and wrap it in an InputSource
        FileReader r = new FileReader(args[0]);
        InputSource inSource = new InputSource(r);
 
        // Create a URL from the command-line argument and use it to set the 
        // system identifier
        inSource.setSystemId(DemoUtil.createURL(args[0]).toString());
 
        // Parse the external DTD from the input source. The second argument is 
        // the name of the root element.
        parser.parseDTD(inSource, args[1]);
        DTD dtd = parser.getDoctype();
 
        // Create a FileReader object from the XML document specified on the
        // command line
        r = new FileReader(args[2]);
 
        // Wrap the FileReader in an InputSource, create a URL from the filename,
        // and set the system identifier
        inSource = new InputSource(r);
        inSource.setSystemId(DemoUtil.createURL(args[2]).toString());

        // ********************
        parser.setDoctype(dtd);
        // ********************

        parser.setValidationMode(DOMParser.DTD_VALIDATION);
       // parser.setAttribute(DOMParser.USE_DTD_ONLY_FOR_VALIDATION,Boolean.TRUE);
        parser.parse(inSource);
 
        // Obtain the DOM tree and print
        XMLDocument doc = parser.getDocument();
        doc.print(new PrintWriter(System.out));
 
      }
      catch (Exception e)
      {
         System.out.println(e.toString());
      }
   }
}

parser.setAttribute(DOMParser.USE_DTD_ONLY_FOR_VALIDATION,Boolean.TRUE);

Handling Character Sets with the XML Parser

This section contains the following topics:

• Detecting the Encoding of an XML File on the Operating System

• Detecting the Encoding of XML Stored in an NCLOB Column

• Writing an XML File in a Nondefault Encoding

• Working with XML in Strings

• Parsing XML Documents with Accented Characters

• Handling Special Characters in Tag Names

/* Java encoding string for ISO8859-1*/
OutputStreamWriter out = new OutputStreamWriter(System.out, "8859_1");
OutputStreamWriter.write(...);

// create parser
DOMParser parser=new DOMParser();
// create XML document in a string
String xmlDoc =
       "<?xml version='1.0'?>"+
       "<hello>"+
       "  <world/>"+
       "</hello>";
// convert string to bytes to stream
byte aByteArr [] = xmlDoc.getBytes();
ByteArrayInputStream bais = new ByteArrayInputStream(aByteArr,0,aByteArr.length);
//  parse and obtain DOM tree
DOMParser.parse(bais);
XMLDocument doc = parser.getDocument();

StringWriter sw = new StringWriter();
PrintWriter  pw = new PrintWriter(sw);
doc.print(pw);
String YourDocInString = sw.toString();

DOMParser parser=new DOMParser(); 
parser.setPreserveWhitespace(true); 
parser.setErrorStream(System.err); 
parser.setValidationMode(false); 
parser.showWarnings(true);
parser.parse (new FileInputStream(new File("file_with_accents.xml")));

<?xml version="1.0" encoding="UTF-8"?>