DocumentBuilderFactory

DocumentBuilderFactory

javax.xml.parsers

---

Java 1.4

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