You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by el...@apache.org on 2003/01/22 00:17:01 UTC
cvs commit: xml-xerces/java/docs faq-dom.xml dom3.xml dom.xml
elena 2003/01/21 15:17:01
Modified: java/docs faq-dom.xml dom3.xml dom.xml
Log:
Update the DOM documentation for the new release
Revision Changes Path
1.5 +40 -43 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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- faq-dom.xml 21 Nov 2002 17:32:56 -0000 1.4
+++ faq-dom.xml 21 Jan 2003 23:17:01 -0000 1.5
@@ -190,21 +190,22 @@
<jump href="#domparser">Create</jump> the DOMBuilder.
</li>
<li>
- Set <em>validate</em> feature using <code>setNormalizationFeature</code>
- method.
+ Retrieve <code>DOMConfiguration</code> from the <code>Document</code>,
+ and set <em>validate</em> feature to true.
</li>
<li>
- Make sure your document has <em>xsi:schemaLocation</em>
- or
- <em>xsi:noSchemaLocation</em> attributes at the document root that
- specify the location of schema(s) against which validation should occur.
+ Provide XML Schemas (agains which validation should occur)
+ by either setting <em>xsi:schemaLocation</em>/
+ <em>xsi:noSchemaLocation</em> attributes on the <code>documentElement</code>, or
+ by setting <code>schema-location</code> parameter on the
+ <code>DOMConfiguration</code>.
</li>
<li>
- The
- <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html#Document3-documentURI">documentURI</jump>
- must be set. Locations of the schema documents will be resolved relative to the
- <code>documentURI</code>
- .
+ Relative URIs for the schema documents will be resolved relative to the
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html#Document3-documentURI">documentURI</jump>
+ (which should be set).
+ Otherwise, you can implement your own <code>DOMEntityResolver</code> and set it
+ via <code>entity-resolver</code> on the <code>DOMConfiguration</code>.
</li>
</ul>
<p>
@@ -222,14 +223,17 @@
identify attribute nodes by their namespaceURI and localName. Because of this fundamental difference, mixing both
sets of methods can lead to unpredictable results.</em></p>
- <source>import org.w3c.dom.Document;
+ <source>
+import org.w3c.dom.Document;
+import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.ls.DOMBuilder;
.....
-Document document = builder.parseURI("data/personal.xml");
-document.setErrorHandler(new MyErrorHandler());
-document.setNormalizationFeature("validate", true);
+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();</source>
<p>
@@ -338,34 +342,27 @@
<link idref='features' anchor="validation.schema">schema feature</link> are turned on before you parse a document.
</p>
- <p>Xerces does not <em>yet</em> provide a way to set an ID attribute after the document was loaded.
- </p>
- <!--
- <p>According to the XML Schema specification, an instance document might have
-more than one <jump href="http://www.w3.org/TR/xmlschema-1/#key-vr">validation root</jump> and
-it specifies that the
-<jump href="http://www.w3.org/TR/xmlschema-1/#cvc-id">ID/IDREFS</jump> must be
-unique within the context of a particular validation root, meaning that a
-document may contain multiple identical ids. In this case, the output
-of getElementById() is unspecified. On the other hand, if the document root is
-a validation root of the document, getElementById() should work as expected.
-
-During loading there is no way (currently) so specify validation roots
-in Xerces, thus Xerces always treats the document root as validation
-root.
-However, in the future it is possible to give XPath expression
-specifying at what elements validation should start. For example:
-
-<documentRoot>
-<validationRoot_1>Some Data</validationRoot_1>
-<validationRoot_2>Some Data</validationRoot_2>
-<documentRoot>
-
-In this case, ID/IDREF must be unique in the scope of validationRoot_1
-or in scope of validationRoot_2, however ID/IDREF table might not be
-unique for documentRoot.
--->
-
</a>
</faq>
+
+
+ <faq title="Setting ID attribute">
+ <q>How do I specify an ID attribute in the DOM?</q>
+ <a> <p>You can use the DOM level 3 setIdAttribute, setIdAttributeNS, and setIdAttributeNode methods
+ to specify ID attribute in the DOM. See <jump href="#dom3">DOM Level 3</jump>.
+ </p>
+ </a>
+ </faq>
+
+ <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/2002/WD-DOM-Level-3-Core-20021022/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
+ <code>validate-if-schema</code> feature must be turned on).
+ If you need to access the full PSVI in the DOM please refer to <jump href="faq-xs.html#faq-5">Using XML Schemas</jump>.
+ </p>
+ </a>
+ </faq>
</faqs>
1.7 +250 -106 xml-xerces/java/docs/dom3.xml
Index: dom3.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dom3.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- dom3.xml 27 Aug 2002 03:01:57 -0000 1.6
+++ dom3.xml 21 Jan 2003 23:17:01 -0000 1.7
@@ -1,110 +1,254 @@
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
<s1 title="Document Object Model Level 3 Implementation">
-<s2 title="Disclaimer">
-<p>
+ <s2 title="Disclaimer">
+ <p>
-The &ParserNameLong; &ParserVersion; contains a partial implementation of
-the W3C Document Object Model Level 3.
-</p>
- <p>The <jump href="http://www.w3.org/DOM/DOMTR#DOML3">DOM Level 3</jump>
- specification is at the stage of <strong>Working Draft</strong>, which represents
- work in progress and thus may be updated, replaced, or obsoleted by
- other documents at any time.
-
-
-This implementation is experimental: it should not be considered as complete or correct.
-</p>
-</s2>
-<s2 title="Introduction">
-<p>
- The &ParserNameLong; &ParserVersion; contains an implementation of a subset of the
- W3C DOM Level 3 as specified in
- <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html">Core</jump>,
- <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725/">
- Load and Save</jump>, and
- <jump href="http://www.w3.org/TR/2001/WD-DOM-Level-3-ASLS-20011025/abstract-schemas.html">Abstract Schemas</jump> [<strong>deprecated</strong>].
-
- </p>
-<p>
- The DOM Level 3 methods for which implementation is not provide will throw <code>DOMException NOT_SUPPORTED_ERR</code> exception.
-</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>Most of the DOM Level 3 functionality is implemented, including:</p>
-
-<ul>
- <li><strong>DOMBuilder</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725/load-save.html#LS-DOMBuilderFilter">filter</jump> -- if an application provides
-a filter, the parser will call this filter at the completion of the construction of each
-<code>Element</code> node.
- </li>
-<li><strong>DOMWriter</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725/load-save.html#LS-DOMWriterFilter">filter</jump> -- if an application provides
-a filter, the serializer will call this filter before serializing each <code>Node</code>.
- </li>
- <li><strong>Document</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html#Document3-normalizeDocument">normalizeDocument</jump> -- this method normalizes Text nodes, makes the document "namespace wellformed" by adding missing namespace declaration attributes and adding or changing namespace prefixes, updates the replacement tree of EntityReference nodes, normalizes attribute values, etc. The actual result depends on the features being set and governing what operations actually take place. The methods <code>setNormalizationFeature, getNormalizationFeature, canSetNormalizationFeature</code> are also supported.
- </li>
-
-<li><strong>Node</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html#Node3-compareTreePosition">compareTreePosition</jump> -- compares a node with this node with regard to their position in the tree and according to the document order.
-</li>
-<li><strong>Node</strong>
-<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html#Node3-lookupNamespaceURI">lookupNamespaceURI</jump>,
-<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html#Node3-lookupNamespacePrefix">lookupNamespacePrefix</jump>,
-<jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020409/core.html#Node3-isDefaultNamespace">isDefaultNamespace</jump> -- performs different namespace URI/prefix lookups.
-</li>
-<li><em>DOMError</em>, <em>DOMErrorHandler</em>, <em>DOMLocator</em>, <em>UserDataHandler</em> -- users can register error and user data handlers.
-</li>
-
-</ul>
-
-<p>
-The <code>normalization features</code> supported are:</p>
-<ul>
-<li><strong>canonical-form</strong> [<em>false</em>]</li>
-<li><strong>cdata-sections</strong> [<em>true/false</em>]</li>
-<li><strong>comments</strong> [<em>true/false</em>]</li>
-<li><strong>entities</strong> [<em>true/false</em>]</li>
-<li><strong>infoset</strong> [<em>false</em>]</li>
-<li><strong>namespace-declarations</strong> [<em>true</em>]</li>
-<li><strong>normalize-characters</strong> [<em>false</em>]</li>
-<li><strong>split-cdata-sections</strong> [<em>true/false</em>]</li>
-<li><strong>validate-if-schema</strong> [<em>false</em>]</li>
-<li><strong>whitespace-in-element-content</strong> [<em>true</em>]</li>
-<li><strong>datatype-normalization</strong> [<em>true/false</em>] -- the XML Schema normalized values will not be exposed via the DOM even if the value of this feature is set to true (to be implemented). </li>
-<li><strong>discard-default-content</strong> [<em>true/false</em>] -- the removal of default content depends on <code>isSpecified</code> flag. </li>
-<li><strong>validate</strong> [<em>true/false</em>] -- revalidation is supported only against XML Schemas. For more information, please refer to <link idref='faq-dom'>How to revalidate DOM in memory?</link>.</li>
-</ul>
-</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>
-<ul>
- <li><strong>DOMBuilder</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/load-save.html#ID-LS-DOMBuilder-parseWithContext">parserWithContext</jump>
-</li>
-<li><strong>DOMImplementationLS</strong> <jump href="">MODE_ASYNCHRONOUS</jump> -- not supported.
-</li>
- <li><strong>DOMImplementationLS</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/load-save.html#createDOMBuilder">createDOMBuilder</jump> -- if
-<code>schemaType</code> has value of <em>"http://www.w3.org/2001/XMLSchema"</em> the parser created will attempt to validate against DTD if one is found. If DTD is not found the parser will validate against XML Schemas.
- </li>
-</ul>
-
-</s2> <s2 title='Implementation of DOM Level 3 Abstract Schemas'>
-<p> The implementation of Abstract Schemas is <strong>deprecated</strong>.
-The funtionality will be removed in the future releases of Xerces.</p>
-
-<ul>
- <li>
- <code>DOMImplementationAS</code>
- </li>
- <li>
- <code>DOMASBuilder</code> supports parsing of XML Schemas and setting the <code>ASModel</code> on the parser.
- </li>
-</ul>
-<note>
-<code>DOMASBuilder</code> does not support parsing of DTDs.
-The parser provides only partial implementation for <code>ASModel</code>.
-For more information on how to parse schemas and set those on the parser instance, see <code>dom.ASBuilder</code> sample.
-</note>
-</s2></s1>
+ The &ParserNameLong; &ParserVersion; contains a partial
+ implementation of the W3C Document Object Model Level 3.
+ </p>
+ <p>
+ The
+ <jump href="http://www.w3.org/DOM/DOMTR#DOML3">DOM Level 3</jump>
+ specification is at the stage of
+ <strong>Working Draft</strong>
+ , which represents work in progress and thus may be
+ updated, replaced, or obsoleted by other documents at any
+ time.
+
+
+ This implementation is experimental: it should not be
+ considered as complete or correct.
+ </p>
+ </s2>
+ <s2 title="Introduction">
+ <p>
+ The &ParserNameLong; &ParserVersion; contains an implementation of a subset of the W3C DOM Level 3 as specified in
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20021022/">Core</jump>,
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725/">Load and Save</jump>
+ , and
+ <jump href="http://www.w3.org/TR/2001/WD-DOM-Level-3-ASLS-20011025/abstract-schemas.html">Abstract Schemas</jump>
+ [<strong>deprecated</strong>].
+
+ </p>
+ <p>
+ The DOM Level 3 methods for which implementation is not provide throw
+ <code>DOMException NOT_SUPPORTED_ERR</code>
+ exception.
+ </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>All of the DOM Level 3 Core functionality is implemented, including:</p>
+
+ <ul>
+ <li>
+ <strong>DOMImplementationRegistry</strong>
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20021022/core.html#Bootstrap">Bootstrapping</jump>
+ -- lets an application find an implementation, based on the specific features it requires.
+ </li>
+
+ <li>
+ <strong>Document</strong>
+ <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20021022/core.html#DOMConfiguration">configuration</jump>
+ -- using configuration users can set different parameters for the Document.
+ </li>
+ <li>
+ <strong>Element</strong> setIdAttribute, setIdAttributeNS, setIdAttributeNode
+ -- allows to set an <code>ID</code> attribute for the current element.
+ </li>
+ <li>
+ <strong>TypeInfo</strong>
+ -- exposes type information in the DOM tree.
+ </li>
+ <li>
+ <strong>Node</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20021022/core.html#Node3-compareDocumentPosition">compareDocumentPosition</jump>
+ -- compares a node with this node with regard to their position in the tree and according to the document order.
+
+ </li>
+ <li>
+ <em>DOMError</em>, <em>DOMErrorHandler</em>, <em>DOMLocator</em>, <em>UserDataHandler</em>
+ -- users can register error and user data handlers.
+ </li>
+ </ul>
+
+ <p>
+ The
+ <code>parameters</code>
+ supported are:
+ </p>
+ <ul>
+ <li>
+ <strong>error-handler</strong>
+ [
+ <em>DOMErrorHandler</em>
+ ]
+ </li>
+ <li>
+ <strong>entity-resolver</strong>
+ [
+ <em>DOMEntityResolver</em>
+ ]
+ </li>
+ <li>
+ <strong>schema-type</strong>
+ [
+ <em>String</em>
+ ]
+ </li>
+ <li>
+ <strong>schema-location</strong>
+ [
+ <em>String</em>
+ ]
+ </li>
+ <li>
+ <strong>canonical-form</strong>
+ [
+ <em>false</em>
+ ]
+ </li>
+ <li>
+ <strong>cdata-sections</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>comments</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>entities</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>infoset</strong>
+ [
+ <em>false</em>
+ ]
+ </li>
+ <li>
+ <strong>namespace-declarations</strong>
+ [
+ <em>true</em>
+ ]
+ </li>
+ <li>
+ <strong>normalize-characters</strong>
+ [
+ <em>false</em>
+ ]
+ </li>
+ <li>
+ <strong>split-cdata-sections</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>validate-if-schema</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>whitespace-in-element-content</strong>
+ [
+ <em>true</em>
+ ]
+ </li>
+ <li>
+ <strong>datatype-normalization</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>discard-default-content</strong>
+ [
+ <em>true/false</em>
+ ] -- the removal of default content depends on
+ <code>isSpecified</code>
+ flag.
+ </li>
+ <li>
+ <strong>validate</strong>
+ [
+ <em>true/false</em>
+ ] -- revalidation is supported only against XML Schemas. For more information, please refer to
+ <link idref='faq-dom'>How to revalidate DOM in memory?</link>
+ .
+ </li>
+ <li>
+ <strong>validate-if-schema</strong>
+ [
+ <em>true/false</em>
+ ]
+ </li>
+ <li>
+ <strong>psvi</strong>
+ [
+ <em>true/false</em>
+ ] -- setting the value of this parameter to true will include
+ PSVI information in the DOM tree.
+ To access the information, cast dom.Element to org.apache.xerces.xni.psvi.ElementPSVI and dom.Attr to org.apache.xerces.xni.psvi.AttributePSVI.
+ </li>
+
+ </ul>
+ </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>
+ <ul>
+
+ <li>
+ <strong>DOMBuilder</strong> <jump href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/load-save.html#ID-LS-DOMBuilder-parseWithContext">parserWithContext</jump>
+ -- not supported.
+ </li>
+ <li><strong>DOMImplementationLS</strong> <jump href="">MODE_ASYNCHRONOUS</jump>
+ -- not supported.
+ </li>
+ </ul>
+
+ </s2>
+ <s2 title='Implementation of DOM Level 3 Abstract Schemas'>
+ <p>
+ The implementation of Abstract Schemas is
+ <strong>deprecated</strong>
+ . The funtionality will be removed in the future releases of Xerces.
+ </p>
+
+ <ul>
+ <li>
+ <code>DOMImplementationAS</code>
+ </li>
+ <li>
+ <code>DOMASBuilder</code>
+ supports parsing of XML Schemas and setting the
+ <code>ASModel</code>
+ on the parser.
+ </li>
+ </ul>
+ <note>
+ <code>DOMASBuilder</code>
+ does not support parsing of DTDs. The parser provides only partial implementation for
+ <code>ASModel</code>
+ . For more information on how to parse schemas and set those on the parser instance, see
+ <code>dom.ASBuilder</code>
+ sample.
+ </note>
+ </s2>
+</s1>
\ No newline at end of file
1.2 +1 -1 xml-xerces/java/docs/dom.xml
Index: dom.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dom.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dom.xml 27 Aug 2002 03:01:57 -0000 1.1
+++ dom.xml 21 Jan 2003 23:17:01 -0000 1.2
@@ -18,7 +18,7 @@
<p>This section provides the following topics:</p>
<ul>
-<li><jump href='http://www.w3.org/DOM/faq'>About DOM</jump></li>
+<li><jump href='http://www.w3.org/DOM/faq.html'>About DOM</jump></li>
<li><link idref='faq-dom'>How do I?</link> -- the most frequently asked questions
about DOM that include some sample code.</li>
<li><link idref='samples-dom'>DOM Samples</link> -- documents various DOM samples
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org