1
1
<?xml version='1.0' encoding='UTF-8'?>
3
* Copyright 2002-2006 The Apache Software Foundation.
5
* Licensed under the Apache License, Version 2.0 (the "License");
6
* you may not use this file except in compliance with the License.
7
* You may obtain a copy of the License at
9
* http://www.apache.org/licenses/LICENSE-2.0
11
* Unless required by applicable law or agreed to in writing, software
12
* distributed under the License is distributed on an "AS IS" BASIS,
13
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
* See the License for the specific language governing permissions and
15
* limitations under the License.
2
17
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
3
18
<faqs title='Programming with DOM'>
66
81
DOMImplementationRegistry.newInstance();
68
83
DOMImplementationLS impl =
69
(DOMImplementationLS)registry.getDOMImplementation("LS-Load");
84
(DOMImplementationLS)registry.getDOMImplementation("LS");
71
86
LSParser builder = impl.createLSParser(
72
87
DOMImplementationLS.MODE_SYNCHRONOUS, null);
74
89
Document document = builder.parseURI("data/personal.xml");</source>
75
<note>You can use DOM Level 3 Load/Save interfaces with the default Xerces distribution.
76
To access the DOM Level 3 Core functionality you need to extract the code from
77
CVS and build Xerces with the <strong>jars-dom3</strong> target.</note>
90
<note>You can now use DOM Level 3 Load/Save and Core interfaces with the default Xerces distribution.
82
95
<faq title="Serializing a DOM document">
83
96
<q>How do I serialize DOM to an output stream?</q>
84
97
<a><anchor name="dom-xml-serialization"/>
86
You can serialize a DOM tree by using Xerces <code>org.apache.xml.XMLSerializer</code>:
98
<p>You can serialize a DOM tree by using the DOM Level 3 Load and Save.
99
<code>LSSerializer</code> performs automatic namespace fixup to make your document namespace
102
<source>import org.w3c.dom.DOMImplementationRegistry;
103
import org.w3c.dom.Document;
104
import org.w3c.dom.ls.DOMImplementationLS;
105
import org.w3c.dom.ls.LSSerializer;
109
System.setProperty(DOMImplementationRegistry.PROPERTY,
110
"org.apache.xerces.dom.DOMImplementationSourceImpl");
111
DOMImplementationRegistry registry = DOMImplementationRegistry.newInstance();
113
DOMImplementationLS impl =
114
(DOMImplementationLS)registry.getDOMImplementation("LS");
118
LSSerializer writer = impl.createLSSerializer();
119
String str = writer.writeToString(document);</source>
122
You can also serialize a DOM tree by using the JAXP Transformer API.
126
You can also serialize a DOM tree by using the Xerces <code>org.apache.xml.XMLSerializer</code> serialization code directly. This is a non-standard way of serializing a DOM and should be avoided:
88
128
<source>import org.apache.xml.serialize.OutputFormat;
89
129
import org.apache.xml.serialize.XMLSerializer;
100
140
new FileWriter("output.xml"), format);
101
141
serializer.asDOMSerializer();
102
142
serializer.serialize(document);</source>
103
<p>You can also serialize a DOM tree by using the DOM Level 3 Load and Save.
104
<code>DOMWriter</code> performs automatic namespace fixup to make your document namespace
107
<source>import org.w3c.dom.DOMImplementationRegistry;
108
import org.w3c.dom.Document;
109
import org.w3c.dom.ls.DOMImplementationLS;
110
import org.w3c.dom.ls.LSWriter;
114
System.setProperty(DOMImplementationRegistry.PROPERTY,
115
"org.apache.xerces.dom.DOMImplementationSourceImpl");
116
DOMImplementationRegistry registry = DOMImplementationRegistry.newInstance();
118
DOMImplementationLS impl =
119
(DOMImplementationLS)registry.getDOMImplementation("LS-Load");
123
LSWriter writer = impl.createLSSerializer();
124
String str = writer.writeToString(document);</source>
157
175
<code>org.w3c.dom.Document</code> interface:</p>
159
177
<li><code>org.apache.xerces.dom.CoreDocumentImpl</code> --
160
supports DOM Level 2 Core Recommendation.</li>
178
supports DOM Level 3 Core Recommendation.</li>
161
179
<li><code>org.apache.xerces.dom.DocumentImpl</code> --
162
supports DOM Level 2 Core, Mutation Events, Traversal and Ranges.</li>
180
supports DOM Level 3 Core, Mutation Events, Traversal and Ranges.</li>
163
181
<li><code>org.apache.xerces.dom.PSVIDocumentImpl</code> --
164
182
provides access to the post schema validation infoset via DOM.</li>
171
189
<faq title="Accessing the DOM Level 3 API">
172
190
<q>How do I access the DOM Level 3 functionality?</q>
173
191
<a> <anchor name="dom3"/>
175
The DOM Level 3 functionality is not exposed in the regular
177
To get access to the DOM Level 3, you need either to extract source code from CVS or
178
to download both Xerces source and tools distributions and
179
build Xerces with the target <strong>jars-dom3</strong>. The build will generate
180
the <code>dom3-xml-apis.jar</code> that includes the DOM Level 3 API and
181
<code>dom3-xercesImpl.jar</code> that includes partial implementation of the API.
182
The samples (i.e. <code>samples.dom.DOM3</code>) can be found in
183
<code>xercesSamples.jar</code>.
185
<p>For more information, refer to the <link idref='dom3'>DOM Level 3
186
Implementation</link> page.
188
<note>Always remove build directory (either manually or by
189
executing build <code>clean</code> target)
190
before building specialized Xerces jars.
193
The DOM Level 3 functionality is now exposed by default since Xerces-J 2.7.0.
196
The experimental interfaces which were once present in the <code>org.apache.xerces.dom3</code>
197
package no longer exist. This package existed primarily so that the DOM Level 2
198
and DOM Level 3 implementations in Xerces-J 2.6.2 and prior could co-exist. Code which
199
depended on the <code>org.apache.xerces.dom3</code> package must be modified to use the
200
official DOM Level 3 API located in the <code>org.w3c.dom.*</code> packages.
202
<p>For more information, refer to the <link idref='dom3'>DOM Level 3
203
Implementation</link> page.
196
209
<q>How do I access run under Sun JDK 1.4 and higher?</q>
197
210
<a> <anchor name="dom3-run"/>
198
211
<p>Use the <jump href="http://java.sun.com/j2se/1.4/docs/guide/standards/">
199
Endorsed Standards Override Mechanism</jump> to specify dom3-xml-apis.jar.
200
More complete description is available <jump href="http://xml.apache.org/xalan-j/faq.html#faq-N100CB">here</jump>.
212
Endorsed Standards Override Mechanism</jump> to specify xercesImpl.jar and xml-apis.jar.
213
More complete description is available <jump href="http://xml.apache.org/xalan-j/faq.html#faq-N100CC">here</jump>.
208
221
<a> <anchor name="xsdom"/>
209
222
<p>By default Xerces does not store the PSVI information in the DOM tree. </p>
211
The following source shows you how to parse an XML document (using JAXP) and how to retrieve PSVI (using the <jump href="http://www.w3.org/Submission/2004/SUBM-xmlschema-api-20040122/">XML Schema API</jump>):
224
The following source shows you how to parse an XML document (using JAXP) and how to retrieve PSVI (using the <jump href="http://www.w3.org/Submission/xmlschema-api/">XML Schema API</jump>):
213
226
//<code>dbf</code> is JAXP DocumentBuilderFactory
242
255
(DOMImplementation) registry.getDOMImplementation("psvi");
245
The PSVI information will not be added or modified as you modify the tree in memory. Instead, if you want to get updated PSVI information, you need to validate your DOM in memory using the <jump href="http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/core.html#Document3-normalizeDocument">normalizeDocument</jump> method as described in the <jump href="#xsrevalidate">next question</jump>.
258
The PSVI information will not be added or modified as you modify the tree in memory. Instead, if you want to get updated PSVI information, you need to validate your DOM in memory using the <jump href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-normalizeDocument">normalizeDocument</jump> method as described in the <jump href="#xsrevalidate">next question</jump>.
247
260
<p>You can find more information about how to use the XML Schema API <jump href="faq-xs.html">here</jump>.</p>
256
269
DOM revalidation is supported via W3C DOM Level 3 Core
257
270
<em>Document.normalizeDocument()</em>.
259
<note>This release only supports revalidation against XML Schemas. Revalidation against DTDs or any other schema type is not implemented.</note>
272
<note>This release only supports revalidation against XML Schemas and DTDs. Revalidation against other schema types is not implemented.</note>
261
274
<p>To revalidate the document you need:</p>
264
<jump href="#dom3">Build</jump> DOM Level 3 Xerces jars.
267
277
<jump href="#domparser">Create</jump> the DOMParser.
281
291
Relative URIs for the schema documents will be resolved relative to the
282
<jump href="http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/core.html#Document3-documentURI">documentURI</jump>
292
<jump href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-documentURI">documentURI</jump>
283
293
(which should be set).
284
Otherwise, you can implement your own <code>DOMResourceResolver</code> and set it
294
Otherwise, you can implement your own <code>LSResourceResolver</code> and set it
285
295
via <code>resource-resolver</code> on the <code>DOMConfiguration</code>.
289
299
<strong>Note:</strong> if a document contains any DOM Level 1 nodes (the nodes created using createElement,
290
300
createAttribute, etc.) a fatal error will occur as described in the
291
<jump href='http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/namespaces-algorithms.html'>Namespace Normalization</jump>
301
<jump href='http://www.w3.org/TR/DOM-Level-3-Core/namespaces-algorithms.html'>Namespace Normalization</jump>
294
<jump href='http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/core.html#Namespaces-Considerations'>DOM specification</jump>
304
<jump href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#Namespaces-Considerations'>DOM specification</jump>
295
305
discourages using DOM Level 1 nodes in the namespace aware application:
297
307
<p><em>DOM Level 1 methods are namespace ignorant. Therefore, while it is safe to use these methods when not
310
320
Document document = builder.parseURI("data/personal-schema.xml");
311
DOMConfiguration config = document.getConfig();
321
DOMConfiguration config = document.getDomConfig();
312
322
config.setParameter("error-handler",new MyErrorHandler());
323
config.setParameter("schema-type", "http://www.w3.org/2001/XMLSchema");
313
324
config.setParameter("validate", Boolean.TRUE);
314
325
document.normalizeDocument();</source>
355
366
DocumentBuilder builder = /* builder instance */;
356
367
builder.setErrorHandler(handler);</source>
357
368
<p>If you are using <jump href="http://www.w3.org/DOM/DOMTR#DOML3">DOM Level 3</jump>
358
you can register an error handler with the <code>DOMBuilder</code> by supplying
369
you can register an error handler with the <code>LSParser</code> by supplying
359
370
a class which implements the <code>org.w3c.dom.DOMErrorHandler</code>
360
371
interface. <strong>Note:</strong> all exceptions during parsing or saving XML data
361
372
are reported via DOMErrorHandler.</p>
369
380
<p>The Xerces <code>http://apache.org/xml/features/dom/create-entity-ref-nodes</code>
371
(or corresponding DOM Level 3 DOMBuilder <code>entities</code> feature)
382
(or corresponding DOM Level 3 LSParser <code>entities</code> feature)
372
383
controls how entities appear in the DOM tree. When one of those features
373
384
is set to true (the default), an occurrence of an entity reference
374
385
in the XML document will be represented by a subtree with an
432
443
<faq title="Accessing type information">
433
444
<q>How do I access type information in the DOM?</q>
434
<a> <p><jump href="#dom3">DOM Level 3</jump> defines a <jump href="http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/core.html#TypeInfo">TypeInfo</jump>
445
<a> <p><jump href="#dom3">DOM Level 3</jump> defines a <jump href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#TypeInfo">TypeInfo</jump>
435
446
interface that exposes type information for
436
447
element and attribute nodes. The type information depends on the document schema and is only available
437
448
if Xerces was able to find the corresponding grammar (DOM Level 3 <code>validate</code> or
added
removed
docs/faq-dom.xml
