You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by nd...@apache.org on 2005/06/17 17:23:10 UTC
cvs commit: xml-xerces/java/docs faq-dom.xml dom.xml dom3.xml readme.xml
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: commits-unsubscribe@xerces.apache.org
For additional commands, e-mail: commits-help@xerces.apache.org