Creating and Modifying XML Documents - Beginning Java - page 1277

com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderImpl@4a5c78
How It Works
The static newInstance() method in the DocumentBuilderFactory class returns a reference to a fact-
ory object. You call the newDocumentBuilder() method for the factory object to obtain a reference to
a DocumentBuilder object that encapsulates a DOM parser. This is the default parser. If you want the
parser to validate the XML or provide other capabilities, you can set the parser features before you create
the DocumentBuilder object by calling methods for the DocumentBuilderFactory object.
You can see that you get a version of the Xerces parser as a DOM parser. Many DOM parsers are built
on top of SAX parsers, and this is the case with the Xerces parser.
SETTING DOM PARSER FEATURES
The idea of a feature for a DOM parser is the same as with SAX — a parser option that can be either on or
off. The following methods are provided by the DocumentBuilderFactory object for setting DOM parser
features:
• void setNamespaceAware(boolean aware) : Calling this method with a true argument sets the
parser to be namespace-aware. The default setting is false .
• void setValidating(boolean validating) : Calling this method with a true argument sets
the parser to validate the XML in a document as it is parsed. The default setting is false .
• void setIgnoringElementContentWhitespace(boolean ignore) : Calling this method with a
true argument sets the parser to remove ignorable whitespace so the Document object produced
by the parser does not contain ignorable whitespace. The default setting is false .
• void setIgnoringComments(boolean ignore) : Calling this method with a true argument sets
the parser to remove comments as the document is parsed. The default setting is false .
• void setExpandEntityReferences(boolean expand) : Calling this method with a true argu-
ment sets the parser to expand entity references into the referenced text. The default setting is
true .
• void setCoalescing(boolean coalesce) : Calling this method with a true argument sets the
parser to convert CDATA sections to text and append it to any adjacent text. The default setting is
false .
By default the parser that is produced is neither namespace-aware nor validating. You should at least set
these two features before creating the parser. This is quite simple:
DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
builderFactory.setNamespaceAware(true);
builderFactory.setValidating(true);
If you add the bolded statements to the example, the newDocumentBuilder() method for the factory object
should now return a validating and namespace-aware parser. With a validating parser, you should define an
ErrorHandler object that deals with parsing errors. You identify the ErrorHandler object to the parser by
calling the setErrorHandler() method for the DocumentBuilder object: