JAXP Support for DOM

JAXP 1.2 is aligned with DOM level 2. There are a number of features in DOM level 2 to make navigation easier, but the main advance (and source of complications) is support for XML namespaces.

The DOM interface itself defines methods for constructing a tree programmatically, and methods for navigating around a tree, but it does not define any way of constructing a DOM tree by parsing a source XML document. JAXP is designed to plug this gap.

The architecture of the interface is very similar to the SAX case:

1. First call the static method DocumentBuilderFactory.newInstance () to get a DocumentBuilderFactory representing one particular vendor's DOM implementation.

2. Then use the newDocumentBuilder() method on this DocumentBuilderFactory to obtain a DocumentBuilder.

3. Finally, call one of the various parse() methods on the DocumentBuilder to obtain a DOM Document object.

javax.xml.parsers.DocumentBuilderFactory

The first thing an application must do is obtain a DocumentBuilderFactory, which it can do by calling the static method DocumentBuilderFactory.newInstance() . Different vendors of DOM implementations will each implement their own subclass of DocumentBuilderFactory , and this call determines which implementation your application will end up using. If there are several available, the one that is used is based on the following decision process:

1. Use the value of the system property javax.xml.parsers.DocumentBuilderFactory if it is available. You can typically set system properties using the -D option on the Java command line, or by calling System.setProperty() from your application.

2. Look for a properties file $JAVA_HOME/lib/jaxp.properties , and within this file, for the property named

    javax.xml.parsers. DocumentBuilderFactory. 

3. Use the services API, which is part of the JAR specification. In practice this means that the DOM implementation used will be the first one found on the classpath.

It is likely that when you install a particular DOM implementation, it will contain a file in its . jar archive that makes that particular implementation the default, so if you don't do anything to select a specific implementation, the one chosen will depend on the order of files and directories on your class path .

Again, the default parser in Sun's JDK 1.4 is the Crimson parser. If you prefer to use Xerces, set the system property to org.apache.xerces.jaxp.DocumentBuilderFactoryImpl.

Once you have got a DocumentBuilderFactory , you can use a number of methods to configure it. Finally, you can call the newDocumentBuilder() method to return a DocumentBuilder . The methods available are:

Method	Description
Object getAttribute (String) [IAE]	Gets information about the properties of the underlying implementation
boolean isCoalescing()	Determines whether the resulting DocumentBuilder will merge CDATA nodes into their adjacent text nodes
boolean isExpandEntityReferences()	Determines whether the resulting DocumentBuilder will expand entity references and merge their content into the adjacent text nodes
boolean isIgnoringComments()	Determines whether the resulting DocumentBuilder will ignore comments in the source XML
boolean isIgnoringElement ContentWhitespace()	Determines whether the resulting DocumentBuilder will ignore whitespace in element content
boolean isNamespaceAware()	Determines whether the resulting DocumentBuilder is namespace aware
boolean isValidating()	Determines whether the resulting DocumentBuilder will validate the XML source
DocumentBuilder newDocumentBuilder() [PCE]	Returns a new DocumentBuilder configured as specified by previous calls
static DocumentBuilderFactory newInstance() [FCE]	Returns a vendor-specific DocumentBuilderFactory selected according to the rules given above
setAttribute(String, Object) [IAE]	Sets vendor-specific properties on the underlying implementation
void setCoalescing (boolean)	Determines whether the resulting DocumentBuilder will merge CDATA nodes into their adjacent text nodes
void setExpandEntityReferences(boolean)	Determines whether the resulting DocumentBuilder will expand entity references and merge their content into the adjacent text nodes
Void setIgnoringComments(boolean)	Determines whether the resulting DocumentBuilder will ignore comments in the source XML
Void setIgnoringElementContent Whitespace(boolean)	Determines whether the resulting DocumentBuilder will ignore whitespace in element content
void setNamespaceAware(boolean)	Determines whether the resulting DocumentBuilder is namespace aware
void setValidating(boolean)	Determines whether the resulting DocumentBuilder will validate the XML source

javax.xml.parsers.DocumentBuilder

A DocumentBuilder is always obtained by calling the newDocumentBuilder() method of a DocumentBuilderFactory.

A DocumentBuilder performs the task of parsing a source XML document and returning the resulting instance of org.w3.dom.Document, containing the root of a tree representation of the document in memory.

The source document is specified in similar ways to the input for a SAX parser. This doesn't mean that a DocumentBuilder has to use a SAX parser to do the actual parsing: Some will work this way and others won't. It's defined this way to avoid unnecessary differences between the SAX and DOM approaches.

You might be aware that in the Microsoft DOM implementation, the Document class has a method load() that parses a source XML file and constructs a Document object. This is a Microsoft extension; there is no corresponding method in the W3C DOM definition. This DocumentBuilder class fills the gap.

The methods available are:

Method	Description
boolean isNamespaceAware()	Indicates whether the parser understands XML namespaces
boolean isValidating()	Indicates whether the parser validates the XML source
Document newDocument()	Returns a new Document object with no content. The returned Document can be populated using DOM methods such as createElement() .
Document parse(File) [IOE, SAXE, IAE]	Parses the XML in the supplied file, and returns the resulting Document object
Document parse(InputSource) [IOE, SAXE, IAE]	Parses the XML in the supplied SAX InputSource , and returns the resulting Document object
Document parse(InputStream) [IOE, SAXE, IAE]	Parses the XML in the supplied InputStream , and returns the resulting Document object. Note that the System ID of the source document will be unknown, so it will not be possible to resolve any relative URIs contained in the document
Document parse(InputStream, String) [IOE, SAXE, IAE]	Parses the XML in the supplied InputStream , and returns the resulting Document object. The second argument supplies the System ID of the source document, which will be used to resolve any relative URIs contained in the document
Document parse(String) [IOE, SAXE, IAE]	Parses the XML in the document identified by the supplied URI, and returns the resulting Document object
void setEntityResolver(EntityResolver)	Supplies a SAX EntityResolver to be used during the parsing
void setErrorHandler(Error Handler)	Supplies a SAX ErrorHandler to be used during the parsing