nddelima 2005/06/17 08:23:10
Modified: java/docs faq-dom.xml dom.xml dom3.xml readme.xml
Log:
Documentation updates for DOM Level 3.
Revision Changes Path
1.17 +47 -61 xml-xerces/java/docs/faq-dom.xml
Index: faq-dom.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/faq-dom.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- faq-dom.xml 1 Jun 2004 17:20:42 -0000 1.16
+++ faq-dom.xml 17 Jun 2005 15:23:10 -0000 1.17
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding='UTF-8'?>
<!--
- * Copyright 2002-2004 The Apache Software Foundation.
+ * Copyright 2002-2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -87,42 +87,22 @@
DOMImplementationLS.MODE_SYNCHRONOUS, null);
Document document = builder.parseURI("data/personal.xml");</source>
- <note>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 <strong>jars-dom3</strong> target.</note>
-
+ <note>You can now use DOM Level 3 Load/Save and Core interfaces with
the default Xerces distribution.
+ </note>
</a>
</faq>
<faq title="Serializing a DOM document">
<q>How do I serialize DOM to an output stream?</q>
<a><anchor name="dom-xml-serialization"/>
- <p>
- You can serialize a DOM tree by using Xerces
<code>org.apache.xml.XMLSerializer</code>:
- </p>
- <source>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);</source>
- <p>You can also serialize a DOM tree by using the DOM Level 3 Load and
Save.
- <code>DOMWriter</code> performs automatic namespace fixup to make your
document namespace
+ <p>You can serialize a DOM tree by using the DOM Level 3 Load and
Save.
+ <code>LSSerializer</code> performs automatic namespace fixup to make
your document namespace
well-formed.
</p>
<source>import org.w3c.dom.DOMImplementationRegistry;
import org.w3c.dom.Document;
import org.w3c.dom.ls.DOMImplementationLS;
-import org.w3c.dom.ls.LSWriter;
+import org.w3c.dom.ls.LSSerializer;
...
@@ -135,8 +115,31 @@
...
-LSWriter writer = impl.createLSSerializer();
+LSSerializer writer = impl.createLSSerializer();
String str = writer.writeToString(document);</source>
+
+ <p>
+ You can also serialize a DOM tree by using the <a
href='http://xml.apache.org/xerces2-j/faq-general.html#faq-5'>JAXP Transformer
API.</a>
+ </p>
+
+ <p>
+ 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:
+ </p>
+ <source>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);</source>
</a>
</faq>
@@ -172,9 +175,9 @@
<code>org.w3c.dom.Document</code> interface:</p>
<ul>
<li><code>org.apache.xerces.dom.CoreDocumentImpl</code> --
- supports DOM Level 2 Core Recommendation.</li>
+ supports DOM Level 3 Core Recommendation.</li>
<li><code>org.apache.xerces.dom.DocumentImpl</code> --
- supports DOM Level 2 Core, Mutation Events, Traversal and Ranges.</li>
+ supports DOM Level 3 Core, Mutation Events, Traversal and Ranges.</li>
<li><code>org.apache.xerces.dom.PSVIDocumentImpl</code> --
provides access to the post schema validation infoset via DOM.</li>
</ul>
@@ -186,24 +189,10 @@
<faq title="Accessing the DOM Level 3 API">
<q>How do I access the DOM Level 3 functionality?</q>
<a> <anchor name="dom3"/>
- <p>
- The DOM Level 3 functionality is not exposed in the regular
- Xerces distribution.
- To get access to the DOM Level 3, you need either to extract source
code from CVS or
- to download both Xerces source and tools distributions and
- build Xerces with the target <strong>jars-dom3</strong>. The build will
generate
- the <code>dom3-xml-apis.jar</code> that includes the DOM Level 3 API
and
- <code>dom3-xercesImpl.jar</code> that includes partial implementation
of the API.
- The samples (i.e. <code>samples.dom.DOM3</code>) can be found in
- <code>xercesSamples.jar</code>.
- </p>
- <p>For more information, refer to the <link idref='dom3'>DOM Level 3
- Implementation</link> page.
- </p>
- <note>Always remove build directory (either manually or by
- executing build <code>clean</code> target)
- before building specialized Xerces jars.
- </note>
+ <p>The DOM Level 3 functionality is now exposed by default since
Xerces-2J 2.7.0</p>
+ <p>For more information, refer to the <link idref='dom3'>DOM Level 3
+ Implementation</link> page.
+ </p>
</a>
</faq>
@@ -211,7 +200,7 @@
<q>How do I access run under Sun JDK 1.4 and higher?</q>
<a> <anchor name="dom3-run"/>
<p>Use the <jump
href="http://java.sun.com/j2se/1.4/docs/guide/standards/";>
- Endorsed Standards Override Mechanism</jump> to specify
dom3-xml-apis.jar.
+ Endorsed Standards Override Mechanism</jump> to specify xercesImpl.jar
and xml-apis.jar.
More complete description is available <jump
href="http://xml.apache.org/xalan-j/faq.html#faq-N100CB";>here</jump>.
</p>
</a>
@@ -223,7 +212,7 @@
<a> <anchor name="xsdom"/>
<p>By default Xerces does not store the PSVI information in the DOM tree.
</p>
<p>
-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>):
+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>):
<source>
//<code>dbf</code> is JAXP DocumentBuilderFactory
@@ -257,7 +246,7 @@
(DOMImplementation) registry.getDOMImplementation("psvi");
</source>
-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>.
+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>.
<p>You can find more information about how to use the XML Schema API <jump
href="faq-xs.html">here</jump>.</p>
</a>
@@ -276,9 +265,6 @@
<p>To revalidate the document you need:</p>
<ul>
<li>
- <jump href="#dom3">Build</jump> DOM Level 3
Xerces jars.
- </li>
- <li>
<jump href="#domparser">Create</jump> the
DOMParser.
</li>
<li>
@@ -294,19 +280,19 @@
</li>
<li>
Relative URIs for the schema documents will be
resolved relative to the
- <jump
href="http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/core.html#Document3-documentURI";>documentURI</jump>
+ <jump
href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#Document3-documentURI";>documentURI</jump>
(which should be set).
- Otherwise, you can implement your own
<code>DOMResourceResolver</code> and set it
+ Otherwise, you can implement your own
<code>LSResourceResolver</code> and set it
via <code>resource-resolver</code> on the
<code>DOMConfiguration</code>.
</li>
</ul>
<p>
<strong>Note:</strong> if a document contains any DOM
Level 1 nodes (the nodes created using createElement,
createAttribute, etc.) a fatal error will occur as
described in the
- <jump
href='http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/namespaces-algorithms.html'>Namespace
Normalization</jump>
+ <jump
href='http://www.w3.org/TR/DOM-Level-3-Core/namespaces-algorithms.html'>Namespace
Normalization</jump>
algorithm.
In general, the
- <jump
href='http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107/core.html#Namespaces-Considerations'>DOM
specification</jump>
+ <jump
href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#Namespaces-Considerations'>DOM
specification</jump>
discourages using DOM Level 1 nodes in the namespace
aware application:
</p>
<p><em>DOM Level 1 methods are namespace ignorant. Therefore,
while it is safe to use these methods when not
@@ -323,7 +309,7 @@
.....
Document document = builder.parseURI("data/personal-schema.xml");
-DOMConfiguration config = document.getConfig();
+DOMConfiguration config = document.getDomConfig();
config.setParameter("error-handler",new MyErrorHandler());
config.setParameter("validate", Boolean.TRUE);
document.normalizeDocument();</source>
@@ -370,7 +356,7 @@
DocumentBuilder builder = /* builder instance */;
builder.setErrorHandler(handler);</source>
<p>If you are using <jump href="http://www.w3.org/DOM/DOMTR#DOML3";>DOM
Level 3</jump>
- you can register an error handler with the <code>DOMBuilder</code> by
supplying
+ you can register an error handler with the <code>LSParser</code> by
supplying
a class which implements the <code>org.w3c.dom.DOMErrorHandler</code>
interface. <strong>Note:</strong> all exceptions during parsing or
saving XML data
are reported via DOMErrorHandler.</p>
@@ -383,7 +369,7 @@
<a>
<p>The Xerces
<code>http://apache.org/xml/features/dom/create-entity-ref-nodes</code>
feature
- (or corresponding DOM Level 3 DOMBuilder <code>entities</code> feature)
+ (or corresponding DOM Level 3 LSParser <code>entities</code> feature)
controls how entities appear in the DOM tree. When one of those
features
is set to true (the default), an occurrence of an entity reference
in the XML document will be represented by a subtree with an
@@ -446,7 +432,7 @@
<faq title="Accessing type information">
<q>How do I access type information in the DOM?</q>
- <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>
+ <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>
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
<code>validate</code> or
1.7 +3 -4 xml-xerces/java/docs/dom.xml
Index: dom.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dom.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- dom.xml 25 Feb 2004 16:22:44 -0000 1.6
+++ dom.xml 17 Jun 2005 15:23:10 -0000 1.7
@@ -1,6 +1,6 @@
<?xml version="1.0" standalone="no"?>
<!--
- * Copyright 2002-2004 The Apache Software Foundation.
+ * Copyright 2002-2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -21,12 +21,11 @@
<ul>
<li><jump href='http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/'>DOM
Level 1 Core and HTML</jump></li>
<li><jump
href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/'>DOM Level 2
Core</jump></li>
+<li><jump href='http://www.w3.org/TR/DOM-Level-3-Core/'>DOM Level 3
Core</jump></li>
<li><jump
href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/'>DOM
Level 2 Traversal and Range</jump></li>
<li><jump
href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/'>DOM Level 2
Events: Mutation Events</jump></li>
+<li><jump href='http://www.w3.org/TR/DOM-Level-3-LS/'>DOM Level 3 Load and
Save</jump></li>
</ul>
-<p>
-Xerces2 also provides an <strong>experimental</strong> implementation of
<link idref="dom3">DOM Level 3 'Core' and 'Load and Save' Proposed
Recommendations</link>.
-</p>
</s2>
<s2 title="DOM Programmer's Guide">
1.20 +60 -17 xml-xerces/java/docs/dom3.xml
Index: dom3.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dom3.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- dom3.xml 5 Oct 2004 03:47:31 -0000 1.19
+++ dom3.xml 17 Jun 2005 15:23:10 -0000 1.20
@@ -1,6 +1,6 @@
<?xml version="1.0" standalone="no"?>
<!--
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
-->
<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
<s1 title="Document Object Model Level 3 Implementation">
+ <!--
<s2 title="Disclaimer">
<p>
@@ -34,26 +35,20 @@
considered as complete or correct.
</p>
</s2>
+ -->
<s2 title="Introduction">
<p>
The &ParserNameLong; &ParserVersion; contains an
implementation of
- the Document Object Model Level 3 <jump
href="http://www.w3.org/TR/2004/PR-DOM-Level-3-Core-20040205/";>Core</jump>
- and Document Object Model Level 3 <jump
href="http://www.w3.org/TR/2004/PR-DOM-Level-3-LS-20040205/";>Load and
Save</jump> Proposed Recommendations.
+ the Document Object Model Level 3 <jump
href="http://www.w3.org/TR/DOM-Level-3-Core/";>Core</jump>
+ and Document Object Model Level 3 <jump
href="http://www.w3.org/TR/DOM-Level-3-LS/";>Load and Save</jump>
Recommendations.
To learn how to program with the DOM Level 3 see <jump
href="samples-dom.html#DOM3">dom.DOM3</jump> sample.
</p>
-
- <note>
- To find out how to access
- <em>DOM Level 3 functionality</em>, please refer to the
- <link idref='faq-dom'>FAQ</link>
- .
- </note>
</s2>
<s2 title='Implementation of DOM Level 3 Core'>
<p>
- The <code>parameters</code> supported are:
+ DOM Level 3 Core DOMConfiguration
<code>parameters</code> supported are:
</p>
<ul>
<li>
@@ -65,7 +60,7 @@
<li>
<strong>resource-resolver</strong>
[
- <em>DOMResourceResolver</em>
+ <em>LSResourceResolver</em>
]
</li>
<li>
@@ -119,7 +114,7 @@
<li>
<strong>namespace-declarations</strong>
[
- <em>true</em>
+ <em>true/false</em>
]
</li>
<li>
@@ -190,15 +185,63 @@
</s2>
<s2 title='Implementation of DOM Level 3 Load and Save'>
- <p>Most of the functionality is implemented. Here is the list
of limitations:</p>
+ <p>
+ Additional DOM Level 3 Load and Save DOMConfiguration
<code>parameters</code> supported:
+ </p>
+ <ul>
+ <li>
+ <strong>charset-overrides-xml-encoding</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>disallow-doctype</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+
<strong>ignore-unknown-character-denormalizations</strong>
+ [
+ <em>true</em>
+ ]
+ </li>
+ <li>
+ <strong>supported-media-types-only</strong>
+ [
+ <em>false</em>
+ ]
+ </li>
+ <li>
+ <strong>discard-default-content</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>format-pretty-print</strong>
+ [
+ <em>false</em>
+ ]
+ </li>
+ <li>
+ <strong>xml-declaration</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ </ul>
+ <p></p>
+ <p>Here is the list of DOM Level 3 Load and Save
limitations:</p>
<ul>
<li>
- <strong>LSParser</strong> <jump
href="http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/load-save.html#LS-LSParser-parseWithContext";>
- parseWithContext</jump>
+ <strong>LSParser</strong> <jump
href="http://www.w3.org/TR/DOM-Level-3-LS/load-save.html#LS-LSParser-parseWithContext";>
+ parserWithContext</jump>
-- not supported.
</li>
- <li><strong>DOMImplementationLS</strong> <jump
href="http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107/load-save.html#LS-DOMIMplementationLS-MODE_ASYNCH";>
+ <li><strong>DOMImplementationLS</strong> <jump
href="http://www.w3.org/TR/DOM-Level-3-LS/load-save.html#LS-DOMImplementationLS-MODE_ASYNCH";>
MODE_ASYNCHRONOUS</jump>
-- not supported.
</li>
1.52 +21 -20 xml-xerces/java/docs/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/readme.xml,v
retrieving revision 1.51
retrieving revision 1.52
diff -u -r1.51 -r1.52
--- readme.xml 9 Mar 2004 23:21:06 -0000 1.51
+++ readme.xml 17 Jun 2005 15:23:10 -0000 1.52
@@ -39,11 +39,11 @@
XML Schema</link> page.
</p>
<p>
- Xerces2 also provides an <link idref='dom3'>experimental
implementation</link> of the
+ Xerces2 also provides an <link idref='dom3'>complete
implementation</link> of the
<jump href="http://www.w3.org/DOM/DOMTR#dom3";>Document
- Object Model Level 3 Core and Load/Save</jump> Proposed
Recommendations and provides a
- <link idref='faq-xinclude'>partial implementation</link> of the <jump
href="http://www.w3.org/TR/2003/WD-xinclude-20031110/";>XML Inclusions
- (XInclude)</jump> W3C Working Draft in Last Call. It also provides
<link idref='faq-xcatalogs'>support</link>
+ Object Model Level 3 Core and Load/Save</jump> W3C Recommendations and
provides a
+ <link idref='faq-xinclude'>complete implementation</link> of the <jump
href="http://www.w3.org/TR/2004/REC-xinclude-20041220/";>XML Inclusions
+ (XInclude)</jump> W3C Recommendation. It also provides <link
idref='faq-xcatalogs'>support</link>
for <jump
href="http://www.oasis-open.org/committees/entity/spec.html";>OASIS XML
Catalogs</jump>.
</p>
@@ -88,7 +88,14 @@
Namespaces in XML 1.1</jump> Recommendation
</li>
<li>
+ <jump href='http://www.w3.org/TR/2004/REC-xinclude-20041220/'>
+ XML Inclusions (XInclude) Version 1.0</jump> Recommendation
+ </li>
+ <li>
<jump href='http://www.w3.org/DOM/'>Document Object Model</jump>
+ (DOM) Level 3
+ <jump
href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/'>Core</jump>,
+ <jump
href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/'>Load and
Save</jump>,
(DOM) Level 2
<jump href='http://www.w3.org/TR/DOM-Level-2-Core/'>Core</jump>,
<jump href='http://www.w3.org/TR/DOM-Level-2-Events'>Events</jump>,
@@ -97,22 +104,18 @@
and Range</jump> Recommendations
</li>
<li>
- <jump href='http://sax.sourceforge.net/'>Simple API for XML</jump>
- (SAX) 2.0.1
- <jump
href='http://prdownloads.sourceforge.net/sax/sax2r2.jar'>Core</jump>,
- and
- <jump
href='http://prdownloads.sourceforge.net/sax/sax2-ext-1.0.zip'>Extensions</jump>
+ <jump href='http://sax.sourceforge.net/'>Simple API for XML</jump>
(SAX) 2.0.2 Core and Extensions
</li>
<li>
<jump href='http://java.sun.com/xml/xml_jaxp.html'>Java APIs for
- XML Processing</jump> (JAXP) 1.2
+ XML Processing</jump> (JAXP) 1.3
</li>
<li>
<jump href='http://www.w3.org/XML/Schema'>XML Schema</jump> 1.0
- <jump href='http://www.w3.org/TR/xmlschema-1/'>Structures</jump>
+ <jump
href='http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/'>Structures</jump>
and
- <jump href='http://www.w3.org/TR/xmlschema-2/'>Datatypes</jump>
- Recommendations
+ <jump
href='http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/'>Datatypes</jump>
+ Second Edition Recommendations
</li>
</ul>
@@ -129,16 +132,14 @@
<s2 title='Changes from Previous Release'>
<p>
- The &ParserNameLong; &ParserVersion; contains several bug fixes:
+ The &ParserNameLong; &ParserVersion; contains a complete
implementation of the parsing portion of JAXP 1.3 including new support for:
</p>
<ul>
- <li>This release fixes a documentation bug in the <jump
href="http://www.w3.org/Submission/2004/SUBM-xmlschema-api-20040309/";>XML
Schema API</jump>.
- In particular in the <code>XSModel</code> interface the order of
the parameters in <code>getTypeDefinition, getNotationDeclaration,
- getModelGroupDefinition, getElementDeclaration,
getAttributeDeclaration, getAttributeGroup</code> methods have been changed
- from <code>(String namespace, String name) to (String name,
String namespace)</code>.
- </li>
- <li>This release requires JDK 1.2 or later to run and also requires
JDK 1.2 or later to build the source code</li>
+ <li>SAX 2.0.2</li>
+ <li>DOM Level 3 Core and Load & Save</li>
+ <li>XInclude 1.0</li>
+ <li>The datatype and validation APIs in javax.xml.datatype and
javax.xml.validation</li>
</ul>
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
