These two methods determine whether CDATA sections are merged with text nodes or not. If the coalescing feature is true, then the result tree will not contain any CDATA section nodes, even if the parsed XML document does contain CDATA sections.

The default is false, but in most situations you should set this to true, especially if you’re just reading the document and are not going to write it back out again. CDATA sections should not be treated differently than any other text. Whether or not certain text is written in a CDATA section should be purely a matter of syntax sugar for human convenience, not anything that has any effect on the data model.

The following two methods determine whether the parsers produced by this factory expand entity references.

The default is true. If a parser is validating, then this it will expand entity references, even if this feature is set to false. That is, the validation feature overrides the expand entity references feature.

The five predefined references— &, <, >, ", and ' —will always be expanded regardless of the value of this property.

The following two methods determine whether the parsers produced by this factory will generate comment nodes for comments seen in the input document. The default, false, means that comment nodes will be produced. (Watch out for the double negative here. False means include comments, and true means don’t include comments. This confused me initially, and I was getting my poison pen all ready to write about the brain damage of throwing away comments although the spec required them to be included, when I realized that the method was in fact behaving like it should.)

The following two methods determine whether the parsers produced by this factory will generate text nodes for so-called “ignorable white space”; that is, white space that occurs between tags where the DTD specifies that parsed character data cannot appear.

The default is false; that is, include text nodes for ignorable white space. Setting this to true might well be useful in record-like documents. However, for this property to make a difference, the documents must have a DTD and should be valid or very nearly so. Otherwise the parser can’t tell which white space is ignorable and which isn’t.

The following two methods determine whether the parsers produced by this factory are “namespace aware.” A namespace aware parser will set the prefix and namespace URI properties of element and attribute nodes that are in a namespace. A non-namespace aware parser won’t.

The default is false, which is truly brain-damaged. You should always set this to true. For example,

DocumentBuilderFactory factory
 = DocumentBuilderFactory.newInstance();
factory.setNamespaceAware(true);

These methods determine whether or not the parsers produced by this factory validate the document against its DTD.

The default is false, do not validate. If you want to validate your documents, set this property to true. You’ll also need to register a SAX ErrorHandler with the DocumentBuilder using its setErrorHandler() method to receive notice of validity errors. Example 9.6 demonstrates with a program that uses JAXP to validate a document named on the command line.

import javax.xml.parsers.*; // JAXP
import org.xml.sax.*;
import java.io.IOException;


public class JAXPValidator {

  public static void main(String[] args) {
     
    if (args.length <= 0) {
      System.out.println("Usage: java JAXPValidator URL");
      return;
    }
    String document = args[0];
    
    try {
      DocumentBuilderFactory factory 
       = DocumentBuilderFactory.newInstance();
      // Always turn on namespace awareness
      factory.setNamespaceAware(true);
      // Turn on validation
      factory.setValidating(true);

      DocumentBuilder parser = factory.newDocumentBuilder();
      
      // SAXValidator was developed in Chapter 7
      ErrorHandler handler = new SAXValidator();
      parser.setErrorHandler(handler);
      
      parser.parse(document); 
      if (handler.isValid()) {
        System.out.println(document + " is valid.");
      }
      else {
        // If the document isn't well-formed, an exception has
        // already been thrown and this has been skipped.
        System.out.println(document + " is well-formed.");
      }
      
    }
    catch (SAXException e) {
      System.out.println(document + " is not well-formed.");
    }
    catch (IOException e) { 
      System.out.println(
       "Due to an IOException, the parser could not check " 
       + document
      ); 
    }
    catch (FactoryConfigurationError e) { 
      System.out.println("Could not locate a factory class"); 
    }
    catch (ParserConfigurationException e) { 
      System.out.println("Could not locate a JAXP parser"); 
    }
   
  }

}

Many JAXP aware parsers support various custom features. For example, Xerces, has an http://apache.org/xml/features/dom/create-entity-ref-nodes feature that lets you choose whether or not to include entity reference nodes in the DOM tree. This is not the same as deciding whether or not to expand entity references. That determines whether the entity nodes that are placed in the tree have children representing their replacement text or not.

JAXP allows you to set and get these custom features as objects of the appropriate type using these two methods:

For example, suppose you’re using Xerces and you don’t want to include entity reference nodes. They're included by default so you need to set http://apache.org/xml/features/dom/create-entity-ref-nodes to false. You would use setAttribute() on the DocumentBuilderFactory like this:

DocumentBuilderFactory factory  
 = DocumentBuilderFactory.newInstance();
 factory.setAttribute(
  "http://apache.org/xml/features/dom/create-entity-ref-nodes", 
  new Boolean(false)
 );

The naming conventions for both attribute names and values depends on the underlying parser. Xerces uses URL strings like SAX feature names. Other parsers may do something different. JAXP 1.2 will add a couple of standard attributes related to schema validation.