| Questions |
| Concurrent access Specifying non-Xerces DOM implementation Accessing the DOM Level 3 API Creating a DOM Parser Serializing a DOM document. Revalidation of DOM document in Memory Handling Errors in DOM Controlling Entity Representation Associating user data with a Node Making getElementById() work Setting ID attribute Accessing type information
| Answers |
| Is Xerces DOM implementation thread-safe? |
| No. DOM does not require implementations to be thread safe. If you need to access the DOM from multiple threads, you are required to add the appropriate locks to your application code.
| How do I supply my own implementation of the DOM? |
| Use http://apache.org/xml/properties/dom/document-class-name property to register your own implementation of the `org.w3c.dom.Document` interface. Xerces provides the following implementations of the `org.w3c.dom.Document` interface: `org.apache.xerces.dom.CoreDocumentImpl` -- supports DOM Level 2 Core Recommendation. `org.apache.xerces.dom.DocumentImpl` -- supports DOM Level 2 Core, Mutation Events, Traversal and Ranges. `org.apache.xerces.dom.PSVIDocumentImpl` -- provides access to the post schema validation infoset via DOM.
| How do I access the DOM Level 3 functionality? |
| The DOM Level 3 functionality is not exposed in the regular Xerces distribution. To get access to the DOM Level 3, extract source code from CVS and build Xerces with the target jars-dom3. The build will generate the `dom3-xmlParserAPIs.jar` that includes the DOM Level 3 API and `dom3-xercesImpl.jar` that includes partial implementation of the API. The samples (i.e. `samples.dom.DOM3`) can be found in `xercesSamples.jar`. For more information, refer to the DOM Level 3 Implementation page.
| Always remove build directory (either manually or by executing build `clean` target) before building specialized Xerces jars.
| How do I create a DOM parser? |
| You can create a DOM parser by using the Java APIs for XML Processing (JAXP) or using the DOM Level 3 Load and Save. The following source code shows how to create the parser with JAXP:
    import java.io.IOException;
    import javax.xml.parsers.DocumentBuilder;
    import javax.xml.parsers.DocumentBuilderFactory;
    import javax.xml.parsers.FactoryConfigurationError;
    import javax.xml.parsers.ParserConfigurationException;
    import org.w3c.dom.Document;
    import org.xml.sax.SAXException;

    ...

    String xmlFile = "file:///xerces-2_3_0/data/personal.xml";
    try {
        DocumentBuilderFactory factory =
        DocumentBuilderFactory.newInstance();
        DocumentBuilder builder = factory.newDocumentBuilder();
        Document document = builder.parse(xmlFile);
    }
    catch (FactoryConfigurationError e) {
        // unable to get a document builder factory
    }
    catch (ParserConfigurationException e) {
        // parser was unable to be configured
    catch (SAXException e) {
        // parsing error
    }
    catch (IOException e) {
        // i/o error
    }
The following source code shows how to create the parser using DOM Level 3:
    import  org.w3c.dom.DOMImplementationRegistry;
    import  org.w3c.dom.Document;
    import  org.w3c.dom.ls.DOMImplementationLS;
    import  org.w3c.dom.ls.DOMBuilder;

    ...

    System.setProperty(DOMImplementationRegistry.PROPERTY,
        "org.apache.xerces.dom.DOMImplementationSourceImpl");
    DOMImplementationRegistry registry =
        DOMImplementationRegistry.newInstance();

    DOMImplementationLS impl =
        (DOMImplementationLS)registry.getDOMImplementation("LS-Load");

    DOMBuilder builder = impl.createDOMBuilder(
        DOMImplementationLS.MODE_SYNCHRONOUS, null);

    Document document = builder.parseURI("data/personal.xml");
| You can use DOM Level 3 Load/Save interfaces with the default Xerces distribution. To access the DOM Level 3 Core functionality you need to extract the code from CVS and build Xerces with the jars-dom3 target.
| How do I serialize DOM to an output stream? |
| You can serialize a DOM tree by using Xerces `org.apache.xml.XMLSerializer`:
    import org.apache.xml.serialize.OutputFormat;
    import org.apache.xml.serialize.XMLSerializer;
    import org.apache.xml.serialize.LineSeparator;

    ...

    OutputFormat format = new OutputFormat((Document)core);
    format.setLineSeparator(LineSeparator.Windows);
    format.setIndenting(true);
    format.setLineWidth(0);
    format.setPreserveSpace(true);
    XMLSerializer serializer = new XMLSerializer (
        new FileWriter("output.xml"), format);
    serializer.asDOMSerializer();
    serializer.serialize(document);
You can also serialize a DOM tree by using the DOM Level 3 Load and Save. `DOMWriter` performs automatic namespace fixup to make your document namespace well-formed.
    import  org.w3c.dom.DOMImplementationRegistry;
    import  org.w3c.dom.Document;
    import  org.w3c.dom.ls.DOMImplementationLS;
    import  org.w3c.dom.ls.DOMWriter;

    ...

    System.setProperty(DOMImplementationRegistry.PROPERTY,
        "org.apache.xerces.dom.DOMImplementationSourceImpl");
    DOMImplementationRegistry registry = DOMImplementationRegistry.newInstance();

    DOMImplementationLS impl =
        (DOMImplementationLS)registry.getDOMImplementation("LS-Load");

    ...

    DOMWriter builder = impl.createDOMWriter();
    writer.writeNode(System.out, document);
| How can I make sure that my DOM document in memory conforms to a schema? |
| DOM revalidation is supported via W3C DOM Level 3 Core Document.normalizeDocument(). .
| This release only supports revalidation against XML Schemas. Revalidation against DTDs or any other schema type is not implemented.
To revalidate the document you need: Build DOM Level 3 Xerces jars. Create the DOMBuilder. Retrieve `DOMConfiguration` from the `Document`, and set validate feature to true. Provide XML Schemas (agains which validation should occur) by either setting xsi:schemaLocation/ xsi:noSchemaLocation attributes on the `documentElement`, or by setting `schema-location` parameter on the `DOMConfiguration`. Relative URIs for the schema documents will be resolved relative to the documentURI (which should be set). Otherwise, you can implement your own `DOMEntityResolver` and set it via `entity-resolver` on the `DOMConfiguration`. Note: if a document contains any DOM Level 1 nodes (the nodes created using createElement, createAttribute, etc.) the fatal error will occur as described in the Namespace Normalization algorithm. In general, the DOM specification discourages using DOM Level 1 nodes in the namespace aware application: DOM Level 1 methods are namespace ignorant. Therefore, while it is safe to use these methods when not dealing with namespaces, using them and the new ones at the same time should be avoided. DOM Level 1 methods solely identify attribute nodes by their nodeName. On the contrary, the DOM Level 2 methods related to namespaces, identify attribute nodes by their namespaceURI and localName. Because of this fundamental difference, mixing both sets of methods can lead to unpredictable results.
    import org.w3c.dom.Document;
    import org.w3c.dom.DOMConfiguration;
    import org.w3c.dom.ls.DOMBuilder;

    .....

    Document document = builder.parseURI("data/personal-schema.xml");
    DOMConfiguration config = document.getConfig();
    config.setParameter("error-handler",new MyErrorHandler());
    config.setParameter("validate", Boolean.TRUE);
    document.normalizeDocument();
For more information, please refer to the DOM Level 3 Implementation page.
| How do handle errors? |
| You should register an error handler with the parser by supplying a class which implements the `org.xml.sax.ErrorHandler` interface. This is true regardless of whether your parser is a DOM based or SAX based parser. You can register an error handler on a `DocumentBuilder` created using JAXP like this:
    import javax.xml.parsers.DocumentBuilder;
    import org.xml.sax.ErrorHandler;
    import org.xml.sax.SAXException;
    import org.xml.sax.SAXParseException;

    ErrorHandler handler = new ErrorHandler() {
        public void warning(SAXParseException e) throws SAXException {
            System.err.println("[warning] "+e.getMessage());
        }
        public void error(SAXParseException e) throws SAXException {
            System.err.println("[error] "+e.getMessage());
        }
        public void fatalError(SAXParseException e) throws SAXException {
            System.err.println("[fatal error] "+e.getMessage());
            throw e;
        }
    };

    DocumentBuilder builder = /* builder instance */;
    builder.setErrorHandler(handler);
If you are using DOM Level 3 you can register an error handler with the `DOMBuilder` by supplying a class which implements the `org.w3c.dom.DOMErrorHandler` interface. Note: all exceptions during parsing or saving XML data are reported via DOMErrorHandler.
| How can I control the way that entities are represented in the DOM? |
| The Xerces `http://apache.org/xml/features/dom/create-entity-ref-nodes` feature (or corresponding DOM Level 3 DOMBuilder `entities` feature) controls how entities appear in the DOM tree. When one of those features is set to true (the default), an occurance of an entity reference in the XML document will be represented by a subtree with an EntityReference node at the root whose children represent the entity expansion. If the feature is false, an entity reference in the XML document is represented by only the nodes that represent the entity expansion. In either case, the entity expansion will be a DOM tree representing the structure of the entity expansion, not a text node containing the entity expansion as text.
| How do I associate my own data with a node in the DOM tree? |
| The class `org.apache.xerces.dom.NodeImpl` provides the `setUserData(Object o)` and the `Object getUserData()` methods that you can use to attach any object to a node in the DOM tree. Beware that you should try and remove references to your data on nodes you no longer use (by calling `setUserData(null)`, or these nodes will not be garbage collected until the entire document is garbage collected. If you are using Xerces with the DOM Level 3 support you can use `org.w3c.dom.Node.setUserData()` and register your own `UserDataHandler`.
| Why does not getElementById() work for documents validated against XML Schemas? |
| Make sure the validation feature and the schema feature are turned on before you parse a document.
| How do I specify an ID attribute in the DOM? |
| You can use the DOM level 3 setIdAttribute, setIdAttributeNS, and setIdAttributeNode methods to specify ID attribute in the DOM. See DOM Level 3.
| How do I access type information in the DOM? |
| DOM Level 3 defines a TypeInfo interface that exposes type information for element and attribute nodes. The type information depends on the document schema and is only available if Xerces was able to find the corresponding grammar (DOM Level 3 `validate` or `validate-if-schema` feature must be turned on). If you need to access the full PSVI in the DOM please refer to Using XML Schemas.

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.