elena 2002/08/26 20:01:58
Modified: java/docs docs-book.xml dom3.xml faq-general.xml
faq-write.xml features.xml properties.xml
readme.xml releases.xml xml-schema.xml
Added: java/docs dom.xml faq-dom.xml faq-xs.xml
Log:
Updates docs to include description of DOM and XML Schema implementations in Xerces
Revision Changes Path
1.17 +16 -6 xml-xerces/java/docs/docs-book.xml
Index: docs-book.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/docs-book.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- docs-book.xml 20 Jun 2002 17:49:43 -0000 1.16
+++ docs-book.xml 27 Aug 2002 03:01:57 -0000 1.17
@@ -25,8 +25,6 @@
<!--
<external label='API JavaDoc' href='apiDocs/index.html'/>
-->
- <document label='XNI Manual' title='Xerces Native Interface'
- id='xni' source='xni.xml'/>
<hidden title='XNI Design Details'
id='xni-design' source='xni-design.xml'/>
<hidden title='XNI Core Interfaces'
@@ -44,6 +42,10 @@
id='faq-build' source='faq-build.xml'/>
<faq title='Writing Applications FAQs'
id='faq-write' source='faq-write.xml'/>
+ <faq title='Programming with DOM'
+ id='faq-dom' source='faq-dom.xml'/>
+ <faq title='Using XML Schemas'
+ id='faq-xs' source='faq-xs.xml'/>
<faq title='Performance FAQs'
id='faq-performance' source='faq-performance.xml'/>
<faq title='FAQs for Developers and Prospective Contributors'
id='faq-contributing' source='faq-contributing.xml'/>
@@ -54,12 +56,20 @@
<settings title='Parser Properties' label='Properties'
id='properties' source='properties.xml'/>
<separator/>
- <releases label='Release Info' title='Release Information'
- id='releases' source='releases.xml'/>
+
+ <document label='XNI Manual' title='Xerces Native Interface'
+ id='xni' source='xni.xml'/>
+ <document label='XML Schema' title='XML Schema' id='xml-schema'
source='xml-schema.xml'/>
+ <document label ='DOM' title='The Document Object Model' id='dom'
source='dom.xml'/>
+ <hidden title='DOM Level 3 Implementation' id='dom3' source='dom3.xml'/>
<document label='Limitations' title='Parser Limitations'
id='limitations' source='limitations.xml'/>
- <hidden title='XML Schema' id='xml-schema' source='xml-schema.xml'/>
- <hidden title='DOM Level 3 Implementation' id='dom3' source='dom3.xml'/>
+ <separator/>
+
+ <releases label='Release Info' title='Release Information'
+ id='releases' source='releases.xml'/>
+
+
<external label='Report a Bug'
href='http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Xerces2-J'/>
</book>
1.6 +12 -10 xml-xerces/java/docs/dom3.xml
Index: dom3.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dom3.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- dom3.xml 19 Jun 2002 01:09:08 -0000 1.5
+++ dom3.xml 27 Aug 2002 03:01:57 -0000 1.6
@@ -20,8 +20,8 @@
<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/2001/WD-DOM-Level-3-Core-20010913/";>Core</jump>,
- <jump
href='http://www.w3.org/TR/2001/WD-DOM-Level-3-ASLS-20011025/load-save.html'>
+ <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>].
@@ -30,13 +30,20 @@
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-write'>FAQ</link>.</note>
+<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>
@@ -67,7 +74,7 @@
<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-write'>How to revalidate DOM in memory?</link>.</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>
@@ -75,14 +82,9 @@
<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>
- -- no implementation is provided.</li>
- <li><strong>DOMBuilder</strong> <jump
href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/load-save.html#ID-LS-DOMBuilder-filter";>filter</jump>
-- no implementation is provided
</li>
-
- <li><strong>DOMWriter</strong> <jump
href="http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409/load-save.html#LS-Interfaces-DOMWriterFilter";>filter</jump>
--
-no implementation is provided.
+<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>
1.26 +10 -6 xml-xerces/java/docs/faq-general.xml
Index: faq-general.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/faq-general.xml,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- faq-general.xml 19 Jun 2002 20:55:28 -0000 1.25
+++ faq-general.xml 27 Aug 2002 03:01:57 -0000 1.26
@@ -10,12 +10,12 @@
or a feature,
please post a message to the xerces-j-user list for clarification.
</li>
- <li> To help to eliminate duplicate bug reports,
- before reporting a bug, you should
- first query the bugzilla database to see whether the bug
- has already been reported (and perhaps fixed).
- Then, checkout code from CVS, and
- build Xerces-J locally to verify that a bug still exists. </li>
+ <li> To help to eliminate duplicate or invalid bug reports,
+ before reporting a bug, you should check if the bug is
+ reproducable in the latest code in CVS by downloading the latest
+ <jump href='http://gump.covalent.net/jars/latest/xml-xerces2/'>Xerces
jars</jump>.
+ If a bug is reproducable, please, query the Bugzilla database to see
whether the bug
+ has already been reported. </li>
</ul>
<p>For more information visit the following links:</p>
<ul>
@@ -24,6 +24,10 @@
<li><jump href="http://www.mozilla.org/bugs/";>
http://www.mozilla.org/bugs/</jump></li>
</ul>
+ <p>We strongly encourage you write patches for problems you find and submit
+ them to [EMAIL PROTECTED]
+ In the interest of fixing bugs, adding enhancements, and addressing
outstanding
+ design issues, we need your active participation in the ongoing
development of Xerces2.</p>
<anchor name="bugzilla"/>
</a>
</faq>
1.20 +3 -175 xml-xerces/java/docs/faq-write.xml
Index: faq-write.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/faq-write.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- faq-write.xml 8 Jul 2002 13:40:36 -0000 1.19
+++ faq-write.xml 27 Aug 2002 03:01:57 -0000 1.20
@@ -1,91 +1,6 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
<faqs title='Writing Application FAQs'>
- <faq title="How do I access the DOM Level 3 functionality?">
- <q>How do I access the DOM Level 3 functionality?</q>
- <a> <p>
- The DOM Level 3 Core 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 <strong>jars-dom3</strong>. The build will
generate
- the <code>xmlParserAPIs.jar</code> that includes DOM Level 3 interfaces in
- <code>org.w3c.dom</code> and <code>org.w3c.dom.ls</code> packages,
- <code>xercesImpl.jar</code> that includes partial DOM Level 3 implementation
- and <code>xercesSamples.jar</code> that includes sample code
- (see <code>samples.dom.DOM3</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>
- </a>
- </faq>
- <faq title='Creating a DOM Parser'>
- <q>How do I create a DOM parser?</q>
- <a>
- <p>
- You can create a DOM parser by using the Java APIs for
- XML Processing (JAXP) or using the DOM Level 3 Load and Save.
- </p>
- <p>
- The following source code shows how to create the parser with JAXP:
- </p>
- <source>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:///&parserdir;/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
-}</source>
-
- <p>
- The following source code shows how to create the parser with DOM Level 3:
- </p>
- <source>
-import org.w3c.dom.*;
-import org.w3c.dom.ls.*;
-
- ...
-try {
-
System.setProperty(DOMImplementationRegistry.PROPERTY,"org.apache.xerces.dom.DOMImplementationSourceImpl");
-
- DOMImplementationLS impl =
(DOMImplementationLS)DOMImplementationRegistry.getDOMImplementation("LS-Load");
-
- DOMBuilder builder = impl.createDOMBuilder(DOMImplementationLS.MODE_SYNCHRONOUS,
null);
-
- Document document = builder.parseURI("data/personal.xml");
-
-} catch ( Exception ex ) {
-}
-
-
-</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>
-
- </a>
- </faq>
<faq title="Creating a SAX Parser">
<q>How do I create a SAX parser?</q>
<a>
@@ -135,48 +50,6 @@
</faq>
-->
-<faq title="Revalidation of DOM document in Memory">
-<q>How can I make sure that my DOM document in memory conforms to a schema?</q>
-<a>
- <p>
- DOM revalidation is supported via W3C DOM Level 3 Core
- <code>Document.normalizeDocument()</code>.
-</p>
- <note>This release only supports revalidation against XML Schemas.
- Revalidation against DTDs or any other schema type is not
implemented.</note>
-
- <p>To revalidate the document you need:</p>
-<ul>
- <li>Build DOM Level 3 Xerces jars
- (see <em>How do I access the DOM Level 3 functionality</em>).</li>
- <li>Create the DOMBuilder (see <em>Creating DOM parser</em>)
- or use DOM methods to create a tree in memory.</li>
- <li>Set <em>validate</em> feature using <code>setNormalizationFeature</code>
- method.</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.</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>.</li>
-</ul>
- <source>
-import org.w3c.dom.Document;
-import org.w3c.dom.ls.DOMBuilder;
-
- .....
-Document document = builder.parseURI("data/personal.xml");
-document.setErrorHandler(new MyErrorHandler());
-document.setNormalizationFeature("validate", true);
-document.normalizeDocument();
-
-
-</source>
-
- <p>For more information, please refer to the <link idref='dom3'>DOM Level 3
Implementation</link> page.</p>
-</a>
-</faq>
-
<faq title='Handling Errors'>
<q>How do handle errors?</q>
@@ -216,7 +89,7 @@
<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
a class which implements the <code>org.w3c.dom.DOMErrorHandler</code>
- interface. </p>
+ interface. For more information, refer to <link idref="faq-dom">FAQ</link></p>
<p>
You can also register an error handler on a SAXParser using JAXP
like this:
@@ -243,31 +116,6 @@
parser.getXMLReader().setErrorHandler(handler);</source>
</a>
</faq>
- <faq title='Controlling Entity Representation'>
- <q>
- How can I control the way that entities are represented in the DOM?
- </q>
- <a>
- <p>
- The DOM Level 3 feature <code>entities</code> (or corresponding Xerces
<code>http://apache.org/xml/features/dom/create-entity-ref-nodes</code> feature)
- control 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.
- </p>
- <p>
- If the feature is false, an entity reference in the XML document
- is represented by only the nodes that represent the entity
- expansion.
- </p>
- <p>
- 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.
- </p>
- </a>
- </faq>
<faq title='What does "non-validating" mean?'>
<q>
Why does "non-validating" not mean "well-formedness
@@ -336,28 +184,8 @@
</tr>
</table>
</a>
- </faq>
- <faq title='Associating Data with a Node'>
- <q>How do I associate my own data with a node in the DOM tree?</q>
- <a>
- <p>
- The class <code>org.apache.xerces.dom.NodeImpl</code> provides a
- <code>void setUserData(Object o)</code> and an <code>Object
- getUserData()</code> method that you can use to attach any object
- to a node in the DOM tree.
- </p>
- <p>
- Beware that you should try and remove references to your data on
- nodes you no longer use (by calling <code>setUserData(null)</code>,
- or these nodes will not be garbage collected until the entire
- document is garbage collected.
- </p>
- <p>If you are using Xerces with the DOM Level 3 support
- you can use <code>org.w3c.dom.Node.setUserData()</code> and register your
own
- <code>UserDataHandler</code>. </p>
- </a>
- </faq>
- <faq title='Parsing Several Documents'>
+ </faq>
+<faq title='Parsing Several Documents'>
<q>
How do I more efficiently parse several documents sharing a
common DTD?
1.29 +6 -2 xml-xerces/java/docs/features.xml
Index: features.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/features.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- features.xml 26 Jul 2002 14:16:10 -0000 1.28
+++ features.xml 27 Aug 2002 03:01:57 -0000 1.29
@@ -272,7 +272,10 @@
<false>
Fully expand the DOM nodes.
</false>
- <default value='true'/>
+ <default value='true**'/>
+ <note>In the <code>DOMBuilder</code> implementation the default value of
+ this feature is <strong>false</strong>.
+ </note>
<note>
<!--
This feature only applies when the <link idref="properties"
@@ -284,7 +287,8 @@
are expanded as the tree is traversed. This allows the parser to return a
document faster than if the tree is fully expanded during parsing and
improves memory usage when the whole tree is not traversed.
- </note>
+ </note>
+
</feature>
<feature name='http://apache.org/xml/features/dom/create-entity-ref-nodes'
id='dom.create-entity-ref-nodes'>
1.11 +2 -1 xml-xerces/java/docs/properties.xml
Index: properties.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/properties.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- properties.xml 26 Aug 2002 18:00:43 -0000 1.10
+++ properties.xml 27 Aug 2002 03:01:57 -0000 1.11
@@ -141,7 +141,8 @@
<property name='http://apache.org/xml/properties/dom/document-class-name'
id='dom.document-class-name'>
<desc>
- The fully qualified class name of the DOM implementation. The
+ The fully qualified name of the class implementing
+ the <code>org.w3c.dom.Document</code> interface. The
implementation used must have a zero argument constructor.
</desc>
<type>java.lang.String</type>
1.30 +8 -6 xml-xerces/java/docs/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/readme.xml,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- readme.xml 19 Jun 2002 21:29:08 -0000 1.29
+++ readme.xml 27 Aug 2002 03:01:57 -0000 1.30
@@ -35,10 +35,11 @@
</p>
<p>
- Please use
- <jump
href='http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Xerces2-J'>BugZilla</jump>
- to report any bugs that you find.
+ Before reporting a bug in
+<jump
href='http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Xerces2-J'>BugZilla</jump>,
+please read the <link idref='faq-general'>Bugzilla</link> FAQ.
</p>
+
<p>You can find the latest Xerces 2 jars
<jump href='http://gump.covalent.net/jars/latest/xml-xerces2/'>here</jump>.
</p>
@@ -105,9 +106,10 @@
</p>
<ul>
- <li>Added XMLResourceIdentifier to
xni.XMLDTDHandler.startExternalSubset()</li>
- <li>Added implementation to XML Schema Component / PSVI interfaces.</li>
- <li>Added DOM Level 3 revalidation support against XML Schemas.</li>
+ <li>Added xni.XMLDocumentHandler.setDocumentSource/getDocumentSource and
+ XMLDocumentSource.getDocumentHandler methods. </li>
+ <li>Expose PSVI via DOM and SAX.</li>
+ <li>Added DOM Level 3 DOMBuilderFilter and DOMBuilderWriter
implementation.</li>
</ul>
<p>
1.132 +27 -1 xml-xerces/java/docs/releases.xml
Index: releases.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/releases.xml,v
retrieving revision 1.131
retrieving revision 1.132
diff -u -r1.131 -r1.132
--- releases.xml 26 Aug 2002 18:33:28 -0000 1.131
+++ releases.xml 27 Aug 2002 03:01:57 -0000 1.132
@@ -15,6 +15,12 @@
<submitter name='Sandy Gao'/>
</add>
<add>
+ <note>Provide access to PSVI via SAX using
+ org.apache.xerces.impl.xs.psvi.PSVIProvider interface.
+ </note>
+ <submitter name='Elena Litani'/>
+ </add>
+ <add>
<note>Provided a way to convert preparsed schema grammars to XSModels.
</note>
<submitter name='Sandy Gao'/>
@@ -62,6 +68,26 @@
</note>
<submitter name="Kent Tamura, Neil Graham"/>
</fix>
+ <add>
+ <note>Provide implementation for DOM Level 3 DOMBuilderFilter and
DOMWriterFilter.
+ </note>
+ <submitter name='Elena Litani'/>
+ </add>
+ <update>
+ <note>Reorganize the code again to allow to build Xerces with DOM Level 3
support and
+ modifying the build.xml to replace import statements in the source
code.
+ </note>
+ <submitter name='Elena Litani'/>
+ </update>
+
+ <update>
+ <note>
+ Added xni.XMLDocumentHandler.setDocumentSource/getDocumentSource and
+ XMLDocumentSource.getDocumentHandler methods to allow to modify Xerces
+ pipeline dynamically.
+ </note>
+ <submitter name='Elena Litani'/>
+ </update>
<fix>
<note>General bug fixes.
</note>
1.2 +11 -79 xml-xerces/java/docs/xml-schema.xml
Index: xml-schema.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/xml-schema.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xml-schema.xml 19 Jun 2002 21:29:08 -0000 1.1
+++ xml-schema.xml 27 Aug 2002 03:01:57 -0000 1.2
@@ -17,6 +17,17 @@
Please read this document before using this package.
</p>
</s2>
+
+<s2 title="XML Schema Programmer's Guide">
+<p>This section provides the following topics:</p>
+
+<ul>
+<li><jump href='#schema-limitations'>Limitations and known bugs</jump></li>
+<li><link idref='faq-xs'>How do I?</link> -- the most frequently asked questions
+ about DOM that include some sample code.</li>
+</ul>
+</s2>
+<anchor name='schema-limitations'/>
<s2 title="Limitations">
<ul>
<li> Length, minLength, and maxLength facets are limited to the value
@@ -65,84 +76,5 @@
Schema document instance namespace, as specified by the
Recommendation. See the sample provided in the
Usage section.</p>
- </s2>
- <s2 title="Usage">
- <p>In this release, schema validation has been integrated with the
- regular SAXParser and DOMParser classes. No special classes are
- required to parse documents that use a schema.</p>
- <p>Each document that uses XML Schema grammars must specify the
location of the
- grammars it uses by using an xsi:schemaLocation attribute if they
use
- namespaces, and an xsi:noNamespaceSchemaLocation attribute
- otherwise. These are usually placed on the root / top-level element
- in the document, though they may occur on any element; for more
details see XML
- Schema Part 1 section 4.3.2.
- Here is an example with no target namespace: </p>
-<source><document
- xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
- xsi:noNamespaceSchemaLocation='document.xsd'>
-...
-</document></source>
- <p>Here is an example with a target namespace. Note that it is an
- error to specify a different namespace than the target namespace
- defined in the Schema.</p>
-<source><document
- xmlns='http://my.com'
- xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
- xsi:schemaLocation='http://my.com document.xsd'>
-...
-</document></source>
- <p>Review the sample file, 'data/personal.xsd' for an example of an
XML
- Schema grammar.</p>
- </s2>
-
- <s2 title="PSVI and Schema Component API">
- <p>Xerces provides experimental PSVI support. The PSVI augmentations can
- be accessed via interfaces in the <code>org.apache.xerces.xni.psvi</code>
- package.</p>
- <p>From within an <code>XMLDocumentHandler</code>, one can retrieve PSVI
- information when certain methods are called. For example,</p>
- <source>import org.apache.xerces.xni.psvi.*;
-
- ...
-
-public void startElement(QName element, XMLAttributes attributes,
- Augmentations augs) {
- ElementPSVI elemPSVI = (ElementPSVI)augs.getItem("ELEMENT_PSVI");
- // get PSVI items of this element out of elemPSVI
- short attemp = elemPSVI.getValidationAttempted();
- short validity = elemPSVI.getValidity();
- ...
-}</source>
- <p>Certain PSVI item is only available on certain
<code>XMLDocumentHandler</code>
- methods. For more information, please refer to the API documentation
- of the PSVI interfaces.</p>
- <p/>
- <p>The above code shows how to retrieve PSVI information after
- elements/attributes are assessed. The other kind of information PSVI
- offers is the property
- <jump
href="http://www.w3.org/TR/xmlschema-1/#e-schema_information";>[schema
information]</jump>.
- This property exposes all schema components in the schema that's used for
- assessment. These components and the schema itself are represented by
- interfaces in the <code>org.apache.xerces.impl.xs.psvi</code> package.</p>
- <p>[schema information] property is only available on the
- <code>endElement</code> method for the validation root. When this method
- is called, information about various components can be retrieved by</p>
- <source>import org.apache.xerces.xni.psvi.*;
-import org.apache.xerces.impl.xs.psvi.*;
-
- ...
-
-public void endElement(QName element, Augmentations augs) {
- ElementPSVI elemPSVI = (ElementPSVI)augs.getItem("ELEMENT_PSVI");
- XSModel xsModel = elemPSVI.getSchemaInformation();
- // get a list of [namespace schema information information item]s,
- // one for each namespace.
- ObjectList nsItems = xsModel.getNamespaceItems();
- // get an element declaration of the specified name and namespace
- XSElementDeclaration elemDecl = xsModel.getElementDeclaration
- (name, namespace);
- ...
-
-}</source>
</s2>
</s1>
1.1 xml-xerces/java/docs/dom.xml
Index: dom.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
<s1 title="Document Object Model">
<s2 title="Introduction">
<p> The Xerces2 provides an implementation of the following W3C Document Object
Model (DOM) Recommendations:</p>
<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/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>
</ul>
<p>
Xerces2 also provides an <strong>experimental</strong> implementation of <link
idref="dom3">DOM Level 3 'Core' and 'Load and Save' Working Drafts</link>.
</p>
</s2>
<s2 title="DOM Programmer's Guide">
<p>This section provides the following topics:</p>
<ul>
<li><jump href='http://www.w3.org/DOM/faq'>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
included with Xerces</li>
</ul>
</s2>
</s1>
1.1 xml-xerces/java/docs/faq-dom.xml
Index: faq-dom.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
<faqs title='Programming with DOM'>
<faq title="Concurrent access">
<q>Is Xerces DOM implementation thread-safe?</q>
<a> <p>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.
</p>
</a>
</faq>
<faq title="Specifying non-Xerces DOM implementation">
<q>How do I supply my own implementation of the DOM?</q>
<a>
<p>
Use
<jump href="">http://apache.org/xml/properties/dom/document-class-name</jump>
property
to register your own implementation of the
<code>org.w3c.dom.Document</code> interface.</p>
<p>
Xerces provides the following implementations of the
<code>org.w3c.dom.Document</code> interface:</p>
<ul>
<li><code>org.apache.xerces.dom.CoreDocumentImpl</code> --
supports DOM Level 2 Core Recommendation.</li>
<li><code>org.apache.xerces.dom.DocumentImpl</code> --
supports DOM Level 2 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>
</a>
</faq>
<faq title="Accessing the DOM Level 3 API">
<q>How do I access the DOM Level 3 functionality?</q>
<a> <p>
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 <strong>jars-dom3</strong>. The build will
generate
the <code>dom3-xmlParserAPIs.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>
</a>
</faq>
<faq title='Creating a DOM Parser'>
<q>How do I create a DOM parser?</q>
<a>
<p>
You can create a DOM parser by using the Java APIs for
XML Processing (JAXP) or using the DOM Level 3 Load and Save.
</p>
<p>
The following source code shows how to create the parser with JAXP:
</p>
<source>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:///&parserdir;/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
}</source>
<p>
The following source code shows how to create the parser using <jump
href="http://www.w3.org/DOM/DOMTR#DOML3";>DOM Level 3</jump>:
</p>
<source>
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");
</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>
</a>
</faq>
<faq title="Serializing a DOM document.">
<q>How do I serialize DOM to an output stream?</q>
<a> <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
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.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);
</source>
</a>
</faq>
<faq title="Revalidation of DOM document in Memory">
<q>How can I make sure that my DOM document in memory conforms to a schema?</q>
<a>
<p>
DOM revalidation is supported via W3C DOM Level 3 Core
<code>Document.normalizeDocument()</code>.
</p>
<note>This release only supports revalidation against XML Schemas.
Revalidation against DTDs or any other schema type is not implemented.</note>
<p>To revalidate the document you need:</p>
<ul>
<li>Build DOM Level 3 Xerces jars
(see <em>How do I access the DOM Level 3 functionality</em>).</li>
<li>Create the DOMBuilder (see <em>Creating DOM parser</em>)
or use DOM methods to create a tree in memory.</li>
<li>Set <em>validate</em> feature using <code>setNormalizationFeature</code>
method.</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.</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>.</li>
</ul>
<source>
import org.w3c.dom.Document;
import org.w3c.dom.ls.DOMBuilder;
.....
Document document = builder.parseURI("data/personal.xml");
document.setErrorHandler(new MyErrorHandler());
document.setNormalizationFeature("validate", true);
document.normalizeDocument();
</source>
<p>For more information, please refer to the <link idref='dom3'>DOM Level 3
Implementation</link> page.</p>
</a>
</faq>
<faq title='Handling Errors in DOM'>
<q>How do handle errors?</q>
<a>
<p>
You should register an error handler with the parser by supplying
a class which implements the <code>org.xml.sax.ErrorHandler</code>
interface. This is true regardless of whether your parser is a
DOM based or SAX based parser.
</p>
<p>
You can register an error handler on a <code>DocumentBuilder</code>
created using JAXP like this:
</p>
<source>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);
</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
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>
</a>
</faq>
<faq title='Controlling Entity Representation'>
<q>
How can I control the way that entities are represented in the DOM?
</q>
<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)
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.
</p>
<p>
If the feature is false, an entity reference in the XML document
is represented by only the nodes that represent the entity
expansion.
</p>
<p>
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.
</p>
</a>
</faq>
<faq title='Associating user data with a Node'>
<q>How do I associate my own data with a node in the DOM tree?</q>
<a>
<p>
The class <code>org.apache.xerces.dom.NodeImpl</code> provides the
<code>setUserData(Object o)</code> and the <code>Object
getUserData()</code> methods that you can use to attach any object
to a node in the DOM tree.
</p>
<p>
Beware that you should try and remove references to your data on
nodes you no longer use (by calling <code>setUserData(null)</code>,
or these nodes will not be garbage collected until the entire
document is garbage collected.
</p>
<p>If you are using Xerces with the DOM Level 3 support
you can use <code>org.w3c.dom.Node.setUserData()</code> and register your own
<code>UserDataHandler</code>. </p>
</a>
</faq>
</faqs>
1.1 xml-xerces/java/docs/faq-xs.xml
Index: faq-xs.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
<faqs title='Using XML Schemas'>
<faq title="Usage">
<q>How do I validate against XML schema?</q>
<a>
<p>In this release, schema validation has been integrated with the
regular SAXParser and DOMParser classes. No special classes are
required to parse documents that use a schema.</p>
<p>Each document that uses XML Schema grammars must specify the location of the
grammars it uses by using an xsi:schemaLocation attribute if they use
namespaces, and an xsi:noNamespaceSchemaLocation attribute
otherwise. These are usually placed on the root / top-level element
in the document, though they may occur on any element; for more details see XML
Schema Part 1 section 4.3.2.
Here is an example with no target namespace: </p>
<source><document
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:noNamespaceSchemaLocation='document.xsd'>
...
</document></source>
<p>Here is an example with a target namespace. Note that it is an
error to specify a different namespace than the target namespace
defined in the Schema.</p>
<source><document
xmlns='http://my.com'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://my.com document.xsd'>
...
</document></source>
<p>Review the sample file, 'data/personal.xsd' for an example of an XML
Schema grammar.</p>
</a>
</faq>
<faq title="Using Entities and CDATA Sections">
<q>How does XML Schema processor treats entities and CDATA secptions?</q>
<a>
<p>According to the XML Infoset the infoset items contributing to the
<jump href='http://www.w3.org/TR/xml-infoset/#infoitem.character'>[character
information item]</jump> are: characters in the document, whether literally,
as
a character reference, or within a CDATA section, or within Entity
Reference. The XML Schema specification
"requires as a precondition for assessment
an information set as defined in [XML-Infoset]"
<jump href='http://www.w3.org/TR/xmlschema-1/#infoset'>(Appendix D)</jump> and
thus Xerces might attempt to normalize data in an entity
reference or CDATA section. To preserve character data within entity
references and
CDATA sections,
turn off http://apache.org/xml/features/validation/schema/normalized-value
feature.
</p>
</a>
</faq>
<faq title="XML Schema API">
<q>Does Xerces provide access to the post schema validation infoset (PSVI)?</q>
<a>
<p>
Xerces defines a set of objects and interfaces for accessing and querying the
post
schema validation infoset (PSVI) defined in
<jump href='http://www.w3.org/TR/xmlschema-1/#PSVI_contributions'>
Contributions to the post-schema-validation infoset (Appendix C.2)</jump>.
The interfaces defined in the <code>org.apache.xerces.impl.xs.psvi</code>
allow
developers to access the XML Schema components, which follow as a consequence
of validation and/or assessment.
The interfaces defined in the <code>>org.apache.xerces.xni.psvi</code> defines
a
set of interfaces for accessing the PSVI from a document instance.
</p>
<note>The set of above interfaces is <strong>experimental</strong>
and may change in the future.
</note>
</a>
</faq>
<faq title="Accessing PSVI via XNI">
<q>How do I access PSVI via XNI?</q>
<a> <p>From within an <code>XMLDocumentHandler</code>, one can retrieve PSVI
information while in the scope of the document handler start/end element
calls:</p>
<source>import org.apache.xerces.xni.psvi.*;
...
public void startElement(QName element, XMLAttributes attributes,
Augmentations augs) {
ElementPSVI elemPSVI = (ElementPSVI)augs.getItem("ELEMENT_PSVI");
// get PSVI items of this element out of elemPSVI
short attemp = elemPSVI.getValidationAttempted();
short validity = elemPSVI.getValidity();
...
}</source>
<note>For more information, please refer to the API documentation
of the PSVI interfaces.</note>
<p>The above code shows how to retrieve PSVI information after
elements/attributes are assessed. The other kind of information PSVI
offers is the property
<jump href="http://www.w3.org/TR/xmlschema-1/#e-schema_information";>[schema
information]</jump>.
This property exposes all schema components in the schema that's used for
assessment. These components and the schema itself are represented by
interfaces in the <code>org.apache.xerces.impl.xs.psvi</code> package.</p>
<p>[schema information] property is only available on the
<code>endElement</code> method for the validation root. When this method
is called, information about various components can be retrieved by</p>
<source>import org.apache.xerces.xni.psvi.*;
import org.apache.xerces.impl.xs.psvi.*;
...
public void endElement(QName element, Augmentations augs) {
ElementPSVI elemPSVI = (ElementPSVI)augs.getItem("ELEMENT_PSVI");
XSModel xsModel = elemPSVI.getSchemaInformation();
// get a list of [namespace schema information information item]s,
// one for each namespace.
ObjectList nsItems = xsModel.getNamespaceItems();
// get an element declaration of the specified name and namespace
XSElementDeclaration elemDecl = xsModel.getElementDeclaration
(name, namespace);
...
}</source>
</a>
</faq>
<faq title="Accessing PSVI via DOM">
<q>How do I access PSVI via DOM?</q>
<a> <p>Use
<jump href="">http://apache.org/xml/properties/dom/document-class-name</jump>
property
to set <code>org.apache.xerces.dom.PSVIDocumentImpl</code> document
interfaces implementation. In the resulting DOM tree, you may cast
<code>org.w3c.dom.Element</code> to the
<code>org.apache.xerces.xni.psvi.ElementPSVI</code> and
<code>org.w3c.dom.Attr</code> to the
<code>org.apache.xerces.xni.psvi.AttributePSVI</code>.
</p>
<source>import org.apache.xerces.xni.psvi.*;
import org.apache.xerces.impl.xs.psvi.XSModel;
import org.apache.xerces.impl.xs.psvi.XSNamedMap;
...
Document document = parser.getDocument();
Element root = document.getDocumentElement();
// retrieve PSVI for the root element
ElementPSVI rootPSVI = (ElementPSVI)root;
// retrieve the schema used in validation of this document
XSModel schema = rootPSVI.getSchemaInformation();
XSNamedMap elementDeclarations =
schema.getComponents(XSConstants.ELEMENT_DECLARATION);
// get schema normalized value
String normalizedValue = rootPSVI.getSchemaNormalizedValue();
</source>
</a>
</faq>
<faq title="Accessing PSVI via SAX">
<q>How do I access PSVI via SAX?</q>
<a> <p>Xerces SAX parser also implements
<code>org.apache.xerces.impl.xs.psvi.PSVIProvider</code> interface.
Within the scope of the methods handling the start and end of an element, i.e.
org.xml.sax.ContentHandler.startElement (..),
an application can use the PSVIProvider to retrieve the PSVI related to that
element and its attributes.
</p>
<source>import org.apache.xerces.impl.xs.psvi.PSVIProvider;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
...
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser parser = factory.newSAXParser();
PSVIProvider psviProvider = (PSVIProvider)parser;
</source>
</a>
</faq>
</faqs>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
