A DocumentBuilderFactory is a factory class for creating DocumentBuilder objects. You can obtain a DocumentBuilderFactory by instantiating an implementation-specific subclass provided by a parser vendor, but it is much more common to simply call newInstance( ) to obtain an instance of the factory that has been configured as the default for the system. Once you have obtained a factory object, you can use the various set methods to configure the properties of the DocumentBuilder objects it will create. These methods allow you to specify whether the parsers created by the factory will:

• coalesce CDATA sections with adjacent text nodes;

• expand entity references or leave them unexpanded in the document tree;

• omit XML comments from the document tree;

• omit ignorable whitespace from the document tree;

• handle XML namespaces correctly; and

• validate XML documents against a DTD or other schema.

In Java 5.0, you can use setSchema( ) to specify the javax.xml.vaidation.Schema object against which parsers should validate their documents. And you can use setXIncludeAware( ) to indicate that parsers should process XInclude markup.

In addition to the various implementation-independent set methods, you can also use setAttribute( ) pass an implementation-dependent named attribute to the underlying parser implementation. Once you have configured the factory object as desired, simply call newDocumentBuilder( ) to create a DocumentBuilder object with the all of the attributes you have specified. Note that DocumentBuilderFactory objects are not typically threadsafe.

The javax.xml.parsers package allows parser implementations to be "plugged in." This pluggability is provided by the getInstance( ) method, which follows the following steps to determine which DocumentBuilderFactory implementation to use:

• If the javax.xml.parsers.DocumentBuilderFactory system property is defined, then the class specified by that property is used.

• Otherwise, if the jre/lib/jaxp.properties file exists in the Java distribution and contains a definition for the javax.xml.parsers.DocumentBuilderFactory property, then the class specified by that property is used.

• Otherwise, if any of the JAR files on the classpath includes a file named META-INF/services/javax.xml.parsers.DocumentBuilderFactory, then the class named in that file will be used.

• Otherwise, a default implementation provided by the Java implementation will be used.

public abstract class DocumentBuilderFactory {
// Protected Constructors
     protected DocumentBuilderFactory( );  
// Public Class Methods
     public static DocumentBuilderFactory newInstance( );  
// Public Instance Methods
     public abstract Object getAttribute(String name) 
        throws IllegalArgumentException;  
5.0  public abstract boolean getFeature(String name) 
        throws ParserConfigurationException;  
5.0  public javax.xml.validation.Schema getSchema( );  
     public boolean isCoalescing( );  
     public boolean isExpandEntityReferences( );  
     public boolean isIgnoringComments( );  
     public boolean isIgnoringElementContentWhitespace( );  
     public boolean isNamespaceAware( );  
     public boolean isValidating( );  
5.0  public boolean isXIncludeAware( );  
     public abstract DocumentBuilder newDocumentBuilder( ) 
        throws ParserConfigurationException;  
     public abstract void setAttribute(String name, Object value) 
        throws IllegalArgumentException;  
     public void setCoalescing(boolean coalescing);  
     public void setExpandEntityReferences(boolean expandEntityRef);  
5.0  public abstract void setFeature(String name, boolean value) 
        throws ParserConfigurationException;  
     public void setIgnoringComments(boolean ignoreComments);  
     public void setIgnoringElementContentWhitespace(boolean whitespace);  
     public void setNamespaceAware(boolean awareness);  
5.0  public void setSchema(javax.xml.validation.Schema schema);  
     public void setValidating(boolean validating);  
5.0  public void setXIncludeAware(boolean state);  
}