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