<s1 title="JAXP Parsing">

<p>The standard Java interface for XML parsing, JAXP, provides two methods for
parsing XML: DOM and SAX.  The DOM (document object model) parses the input
into an XML tree using the org.w3c.xml.Node API.  SAX doesn't create any
result object tree, instead calling methods in a ContentHandler.</p>

<p>In general, DOM parsing is easier to understand, but SAX parsing can
be more efficient because many applications can avoid creating an
intermediate XML tree.</p>

<s2 title="DOM parsing">

<p>For strict XML parsing to the DOM, the best technique is to use the
standard JAXP API.  That way, you can configure your application to
use whichever XML parser is most convenient for you.</p>

<p>JAXP parsing uses the following steps:</p>

<ol>
<li>Create a DocumentBuilderFactory instance.
<li>Set any parser flags or properties.
<li>Create DocumentBuilder to create the parser.
<li>Parse the document
</ol>

<example title="Reading and Writing using the DOM">
import java.io.*;
import javax.xml.parsers.*;
import org.w3c.dom.*;
import com.caucho.xml.*;

...

// Create a new parser using the JAXP API (javax.xml.parser)
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder parser = factory.newDocumentBuilder();

// Parse the file into a DOM Document (org.w3c.dom)
Document doc = parser.parse("test.xml");

// Create a new XML printer (com.caucho.xml)
FileOutputStream os = new FileOutputStream("out.xml");
XmlPrinter printer = new XmlPrinter(os);

// Print the document
printer.print(doc);
os.close();
</example>

<p>Printing DOM objects is easily done by using Resin's XmlPrinter API.</p>

</s2>

<s2 title="Configuration">

<p>JAXP is a standard interface which supports pluggable XML
parser implementations.  JAXP selects the parser based on
system properties.  You can set the properties to select
a different parser than the default one.</p>

<p>If you use libraries which include JAXP classes, those libraries
might default to another, probably slower, XML parser.  You may
need to configure the system properties to ensure that you'll use
Resin's fast parser.</p>

<deftable title="JAXP Properties for Resin">
<tr><th>system property<th>Resin value
<tr><td>javax.xml.parsers.DocumentBuilderFactory
    <td>com.caucho.xml.parsers.XmlDocumentBuilderFactory
<tr><td>javax.xml.parsers.SAXParserFactory
    <td>com.caucho.xml.parsers.XmlSAXParserFactory
<tr><td>javax.xml.transform.TransformerFactory
    <td>com.caucho.xsl.Xsl
</deftable>

<deftable title="JAXP Properties for Xalan/Xerces">
<tr><th>system property<th>Xerces value
<tr><td>javax.xml.parsers.DocumentBuilderFactory
    <td>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
<tr><td>javax.xml.parsers.SAXParserFactory
    <td>org.apache.xerces.jaxp.SAXParserFactoryImpl
<tr><td>javax.xml.transform.TransformerFactory
    <td>org.apache.xalan.processor.TransformerFactoryImpl
</deftable>

<p>The resin.conf and web.xml will let you configure system properties on
a per-application basis.  The configuration looks like:</p>

<example>
&lt;web-app>
  &lt;system-property javax.xml.parsers.DocumentBuilderFactory=
                      "com.caucho.xml.parsers.XmlDocumentBuilderFactory"/>

  ...
&lt;/web-app>
</example>

</s2>
</s1>
