You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by an...@apache.org on 2001/07/19 08:43:11 UTC
cvs commit: xml-xerces/java/docs/dtd releases.dtd settings.dtd book.dtd entities.ent markup.ent
andyc 01/07/18 23:43:11
Modified: java Tag: xerces_j_2 build.xml
java/docs Tag: xerces_j_2 api.xml docs-book.xml
faq-build.xml faq-common.xml faq-general.xml
faq-performance.xml faq-write.xml features.xml
install.xml properties.xml readme.xml releases.xml
samples.xml
java/docs/dtd Tag: xerces_j_2 book.dtd entities.ent
markup.ent
Added: java/docs Tag: xerces_j_2 limitations.xml samples-dom.xml
samples-sax.xml samples-socket.xml samples-ui.xml
samples-xni.xml xni.xml
java/docs/dtd Tag: xerces_j_2 releases.dtd settings.dtd
Removed: java/docs Tag: xerces_j_2 caveats.xml faq-migrate.xml
feedback.xml javapurecheck.xml sam-domcount.xml
sam-domfilter.xml sam-domwriter.xml
sam-iterator.xml sam-tree.xml sam-treeview.xml
schema.xml site-book.xml y2k.xml
Log:
New documentation. More work still needs to be done but
at least the new core docs are in place. Now, where did
I put my tech writers?...
Revision Changes Path
No revision
No revision
1.14.2.12 +2 -2 xml-xerces/java/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/build.xml,v
retrieving revision 1.14.2.11
retrieving revision 1.14.2.12
diff -u -r1.14.2.11 -r1.14.2.12
--- build.xml 2001/07/06 19:22:17 1.14.2.11
+++ build.xml 2001/07/19 06:43:10 1.14.2.12
@@ -51,7 +51,7 @@
Copyright:
Copyright (c) 2000 The Apache Software Foundation.
- $Id: build.xml,v 1.14.2.11 2001/07/06 19:22:17 neilg Exp $
+ $Id: build.xml,v 1.14.2.12 2001/07/19 06:43:10 andyc Exp $
==================================================================== -->
@@ -85,7 +85,7 @@
<property name="doc.generator" value="org.apache.stylebook.StyleBook"/>
<property name="doc.generator.package" value="${tools.dir}/stylebook-1.0-b2.jar"/>
- <property name="doc.style" value="${tools.dir}/style-apachexml.jar"/>
+ <property name="doc.style" value="${docs.dir}/style"/>
<property name="build.dir" value="./build"/>
<property name="build.src" value="${build.dir}/src"/>
No revision
No revision
1.5.2.1 +10 -149 xml-xerces/java/docs/api.xml
Index: api.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/api.xml,v
retrieving revision 1.5
retrieving revision 1.5.2.1
diff -u -r1.5 -r1.5.2.1
--- api.xml 2000/05/23 20:28:52 1.5
+++ api.xml 2001/07/19 06:43:10 1.5.2.1
@@ -1,149 +1,10 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
-
-<s1 title="API Documentation">
- <s2 title="Javadoc Generated Documentation">
- <p>&javaparsernamelong; comes packaged with API documentation for SAX and DOM,
- the two most common interfaces for programming XML. In addition,
- we provide documentation for classes that are not part of the SAX
- and DOM API's, but are useful for writing &javaparsername; programs. </p>
- <p>This documentation is generated automatically from the Javadoc-style
- comments inside the source files. Click on one of the links below to
- go to the appropriate API documentation.</p>
- </s2>
- <s2 title="&javaparsername; API Documentation">
- <ul>
- <li><jump href="../apiDocs/index.html">Full API documentation</jump></li>
- <li><jump href="../apiDocs/overview-tree.html">Hierarchy for all the packages</jump></li>
- </ul>
- <s3 title="Package org.apache.xerces.parsers">
- <s4 title="Classes">
- <ul>
- <li>DOMParser</li>
- <li>SAXParser</li>
- </ul>
- </s4>
- <s4 title="Interfaces">
- <ul>
- <li>Attr
- <br/>The Attr interface represents an attribute in an Element object</li>
- <li>CDATASection
- <br/>CDATA sections are used to escape blocks of text containing characters
- that would otherwise be regarded as markup</li>
- <li>CharacterData
- <br/>The CharacterData interface extends Node with a set of attributes and
- methods for accessing character data in the DOM</li>
- <li>Comment
- <br/>This represents the content of a comment</li>
- <li>Document
- <br/>The Document interface represents the entire HTML or XML document</li>
- <li>DocumentFragment
- <br/>DocumentFragment is a "lightweight" or "minimal" Document object</li>
- <li>DocumentType
- <br/>Each Document has a doctype attribute whose value is either null or a
- DocumentType object</li>
- <li>DOMImplementation
- <br/>The DOMImplementation interface provides methods for performing
- operations independent of a particular document object model instance</li>
- <li>Element
- <br/>The majority of objects (apart from text) in a document are Element nodes</li>
- <li>Entity
- <br/>This interface represents an entity, either parsed or unparsed, in a XML
- document</li>
- <li>EntityReference
- <br/>EntityReference objects may be inserted into the structure model</li>
- <li>NamedNodeMap
- <br/>Objects implementing the NamedNodeMap interface are used to represent
- collections of nodes that can be accessed by name</li>
- <li>Node
- <br/>The Node interface is the primary datatype for the entire Document Object
- Model</li>
- <li>NodeList
- <br/>The NodeList interface provides the abstraction of an ordered collection
- of nodes</li>
- <li>Notation
- <br/>This interface represents a notation declared in the DTD</li>
- <li>ProcessingInstruction
- <br/>The ProcessingInstruction is a way to keep processor-specific
- information in the text of the document</li>
- <li>Text
- <br/>The Text interface represents the textual content (termed character data in
- XML) of an Element or Attr</li>
- </ul>
- </s4>
- <s4 title="Exceptions">
- <ul>
- <li>DOMException
- <br/>Encapsulate an "exceptional" DOM error </li>
- </ul>
- </s4>
- </s3>
- <s3 title="Package org.xml.sax">
- <s4 title="Classes">
- <ul>
- <li>HandlerBase
- <br/>Default base class for handlers</li>
- <li>InputSource
- <br/>A single input source for an XML entity </li>
- </ul>
- </s4>
- <s4 title="Interfaces">
- <ul>
- <li>AttributeList
- <br/>Interface for an element's attribute specifications</li>
- <li>DocumentHandler
- <br/>Receive notification of general document events</li>
- <li>DTDHandler
- <br/>Receive notification of basic DTD-related events</li>
- <li>EntityResolver
- <br/>Basic interface for resolving entities</li>
- <li>ErrorHandler
- <br/>Basic interface for SAX error handlers </li>
- <li>Locator
- <br/>Interface for associating a SAX event with a document location</li>
- <li>Parser
- <br/>Basic interface for SAX (Simple API for XML) parsers</li>
- </ul>
- </s4>
- <s4 title="Exceptions">
- <ul>
- <li>SAXException
- <br/>Encapsulate a general SAX error or warning</li>
- <li>SAXParseException
- <br/>Encapsulate an XML parse error or warning </li>
- </ul>
- </s4>
- </s3>
- <s3 title="Package org.xml.sax.helpers">
- <s4 title="Classes">
- <ul>
- <li>AttributeListImpl
- <br/>Convenience implementation for AttributeList</li>
- <li>LocatorImpl
- <br/>Convenience implementation for Locator</li>
- <li>ParserFactory
- <br/>Java-specific class for dynamically loading SAX parsers</li>
- </ul>
- </s4>
- </s3>
- <s3 title="Package org.apache.xerces.dom.traversal">
- <s4 title="Classes">
- <ul>
- <li>DocumentTraversal
- <br/>DocumentTraversal contains methods that creates Iterators to traverse a
- node and its children</li>
- <li>DocumentTWIF
- <br/>DocumentTWIF contains methods that create Iterators to traverse a node
- and its children</li>
- <li>NodeFilter
- <br/>Filters are objects that know how to "filter out" nodes</li>
- <li>NodeIterator
- <br/>NodeIterators are used to step through a set of nodes</li>
- <li>TreeWalker
- <br/>TreeWalker objects are used to navigate a document tree or subtree using
- the view of the document </li>
- </ul>
- </s4>
- </s3>
- </s2>
-</s1>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
+<s1 title='API JavaDoc'>
+ <s2 title='Standard API Documentation'>
+ </s2>
+ <s2 title='Xerces-J User API Documentation'>
+ </s2>
+ <s2 title='Xerces-J Developer API Documentation'>
+ </s2>
+</s1>
\ No newline at end of file
1.5.2.3 +57 -53 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.5.2.2
retrieving revision 1.5.2.3
diff -u -r1.5.2.2 -r1.5.2.3
--- docs-book.xml 2001/02/14 18:28:44 1.5.2.2
+++ docs-book.xml 2001/07/19 06:43:10 1.5.2.3
@@ -1,54 +1,58 @@
-<?xml version="1.0"?>
-<!DOCTYPE book SYSTEM "./dtd/book.dtd">
-
-<book title="Xerces-J Documentation" copyright="1999, 2000 The Apache Software Foundation">
- <external href="../index.html" label="Home"/>
-
- <separator/>
- <document id="index" label="Readme" source="readme.xml" />
- <external href="http://xml.apache.org/dist/xerces-j/" label="Download"/>
- <external href="http://xml.apache.org/websrc/cvsweb.cgi/xml-xerces/java/" label="Repository"/>
- <document id="install" label="Installation" source="install.xml" />
-
- <separator/>
- <document id="api" label="API Docs" source="api.xml" />
- <!--
- <container id="samples" label="Samples" source="samples.xml">
- <entry id="domcount" source="sam-domcount.xml" />
- <entry id="domwriter" source="sam-domwriter.xml"/>
- <entry id="domfilter" source="sam-domfilter.xml"/>
- <entry id="iterator" source="sam-iterator.xml" />
- <entry id="tree" source="sam-tree.xml" />
- <entry id="treeview" source="sam-treeview.xml" />
- </container>
- -->
- <document id='samples' label='Samples' source='samples.xml'/>
- <hidden id='domcount' source='sam-domcount.xml'/>
- <hidden id="domwriter" source="sam-domwriter.xml"/>
- <hidden id="domfilter" source="sam-domfilter.xml"/>
- <hidden id="iterator" source="sam-iterator.xml" />
- <hidden id="tree" source="sam-tree.xml" />
- <hidden id="treeview" source="sam-treeview.xml" />
- <document id="schema" label="Schema" source="schema.xml" />
-
- <separator/>
- <document id="properties" label="Properties" source="properties.xml" />
- <document id="features" label="Features" source="features.xml" />
- <group id="faqs" title="Frequently Asked Questions" label="FAQs">
- <entry id="faq-general" source="faq-general.xml" />
- <entry id="faq-build" source="faq-build.xml" />
- <entry id="faq-write" source="faq-write.xml" />
- <entry id="faq-performance" source="faq-performance.xml" />
- <entry id="faq-migrate" source="faq-migrate.xml" />
- <entry id="faq-common" source="faq-common.xml" />
- </group>
- <hidden id="jpc" source="javapurecheck.xml"/>
-
- <separator/>
- <document id="releases" label="Releases" source="releases.xml" />
- <document id="caveats" label="Caveats" source="caveats.xml" />
- <document id="feedback" label="Feedback" source="feedback.xml" />
-
- <separator/>
- <document id="y2k" label="Y2K Compliance" source="y2k.xml" />
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE book SYSTEM 'dtd/book.dtd'>
+<book title='Xerces-J Documentation'
+ copyright='1999-2001 The Apache Software Foundation'>
+ <external label='Home' href='http://xml.apache.org/'/>
+ <separator/>
+ <document label='Readme' title='Xerces2 Java Parser Readme'
+ id='index' source='readme.xml'/>
+ <document label='Installation' title='Installation Instructions'
+ id='install' source='install.xml'/>
+ <external label='Download' href='http://xml.apache.org/dist/xerces-j/'/>
+ <external label='CVS Repository'
+ href='http://xml.apache.org/websrc/cvsweb.cgi/xml-xerces/java/?only_with_tag=xerces_j_2&hideattic=0'/>
+ <separator/>
+ <document label='Samples' title='Sample Programs'
+ id='samples' source='samples.xml'/>
+ <hidden title='DOM Samples' id='samples-dom' source='samples-dom.xml'/>
+ <hidden title='SAX Samples' id='samples-sax' source='samples-sax.xml'/>
+ <hidden title='Socket Samples' id='samples-socket' source='samples-socket.xml'/>
+ <hidden title='User Interface Samples'
+ id='samples-ui' source='samples-ui.xml'/>
+ <hidden title='XNI Samples' id='samples-xni' source='samples-xni.xml'/>
+ <!--
+ <document label='API JavaDoc' title='API JavaDoc'
+ id='api' source='api.xml'/>
+ -->
+ <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' id='xni-design' source='xni-design.xml'/>
+ <hidden title='XNI API' id='xni-api' source='xni-api.xml'/>
+ <hidden title='XNI Parser Configurations'
+ id='xni-config' source='xni-config.xml'/>
+ -->
+ <faqs label='FAQs' title='Frequently Asked Questions' id='faqs'>
+ <faq title='Common FAQs' id='faq-common' source='faq-common.xml'/>
+ <faq title='General FAQs' id='faq-general' source='faq-general.xml'/>
+ <faq title='Building and Running FAQs'
+ id='faq-build' source='faq-build.xml'/>
+ <faq title='Writing Applications FAQs'
+ id='faq-write' source='faq-write.xml'/>
+ <faq title='Performance FAQs'
+ id='faq-performance' source='faq-performance.xml'/>
+ </faqs>
+ <separator/>
+ <settings title='Parser Features' label='Features'
+ id='features' source='features.xml'/>
+ <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='Limitations' title='Parser Limitations'
+ id='limitations' source='limitations.xml'/>
+ <external label='Report a Bug'
+ href='http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Xerces2-J'/>
</book>
1.5.2.1 +382 -207 xml-xerces/java/docs/faq-build.xml
Index: faq-build.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/faq-build.xml,v
retrieving revision 1.5
retrieving revision 1.5.2.1
diff -u -r1.5 -r1.5.2.1
--- faq-build.xml 2000/05/23 20:28:55 1.5
+++ faq-build.xml 2001/07/19 06:43:10 1.5.2.1
@@ -1,212 +1,387 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd">
-
-<faqs title="Building and Running FAQs">
- <faq title="Swing version?">
- <q>Which version of Swing is required?</q>
- <a> <p>This release uses Swing 1.1 (JFC 1.1).
- Swing is only used by the sample programs and is not
- required by the parser itself.</p>
- </a>
- </faq>
- <faq title="Recompling source files?">
- <q>How do I recompile the source files?</q>
- <a> <p>To build &javaparsername; on Windows, you need a copy of Cygnus's Cygwin.
-See <jump href="http://sourceware.cygnus.com/cygwin">http://sourceware.cygnus.com/cygwin</jump>.
-Once Cygwin is installed, you need to set two environment variables. Edit the batch file
-BuildAll.bat to set these variables. Execute BuildAll.bat, and then
-set your classpath to point to the src and samples directories in the
-&javaparsername; distribution. You can then go to the top of the
-&javaparsername; tree and type 'make'.
-</p>
-<p>
-To build &javaparsername; Java on UNIX, you need to set an environment
-variable. Edit the shell script BuildAll to set this variables.
-Execute BuildAll, and then set your classpath to point to the src
-and samples directories in the &javaparsername; distribution. You can then
-go to the top of the &javaparsername; tree and type 'make'.
- </p>
- </a>
- </faq>
- <faq title="Regenerating API documention?">
- <q>How do I regenerate the api documentation?</q>
- <a> <p>To regenerate the api documentation, you need to set up
-your environment to build &javaparsername;. Instead of typing 'make', you
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
+<faqs title='Building and Running FAQs'>
+ <faq title='Swing version?'>
+ <q>Which version of Swing is required?</q>
+ <a>
+ <p>
+ This release uses Swing 1.1 (JFC 1.1). Swing is only used by
+ the sample programs and is not required by the parser itself.
+ </p>
+ </a>
+ </faq>
+ <faq title='Recompling source files?'>
+ <q>How do I recompile the source files?</q>
+ <a>
+ <p>
+ To build &javaparsername; you need the Java Development
+ Kit (JDK) version 1.2 (or higher) installed on your machine.
+ The actual build is performed by the Ant program which is
+ written in Java and is a subproject of the Apache
+ <jump href='http://jakarta.apache.org/'>Jakarta</jump>
+ project. The build also requires a few other tools but
+ all of the tools you need (including Ant) are contained
+ in the <ref>&javaparsername;-tools.&javaparserversion;.zip</ref>
+ file, packaged separately. Go to the Xerces-J
+ <jump href='http://xml.apache.org/dist/xerces-j/'>download</jump>
+ page to download the tools package and then extract it in the
+ same location as the source package.
+ </p>
+ <p>
+ On Windows machines, you can start the build by running
+ the <ref>build.bat</ref> file from an MS-DOS Prompt. On a
+ UNIX machine, use the <ref>build.sh</ref> shell script.
+ If the build process complains about a missing
+ <ref>JAVA_HOME</ref> environment variable, set the
+ environment variable to the location where JDK 1.2 (or higher)
+ is installed on your system, and run the build script again.
+ </p>
+ </a>
+ </faq>
+ <faq title='Regenerating API documention?'>
+ <q>How do I regenerate the api documentation?</q>
+ <a>
+ <p>
+ To regenerate the api documentation, you need to set up
+ your environment to build &javaparsername;. Instead of typing 'make', you
type 'make apidocs'.
</p>
</a>
- </faq>
-<!-- TBD
- <faq title="Packaging?">
- <q>How do I package the parser?</q>
- <a> <p>blah
- </p>
- </a>
- </faq>
--->
- <faq title="How do I use Visual Age?">
- <q>How do I import &javaparsername; into Visual Age for Java</q>
- <a>
- <ul>
- <li>Why does VisualAge for Java 2.0 report problems when I import the &javaparsername; parser?
- <br/>The current version of the &javaparsername; parser uses Swing 1.1,
- while VisualAge for Java 2.0 comes with Swing 1.0.2. The free update for the
- Professional version of VisualAge for Java 2.0 installs Swing 1.0.3.
- The most important difference between Swing 1.0.2 - 1.0.3 and 1.1 is
- the Java package was changed from com.sun.java.swing.* to javax.swing.*.
- <br/>To fix the errors, you must download the Java Foundation Classes 1.1
- with Swing 1.1 from Sun's Java home page and import the "swingall.jar"
- file into VisualAge for Java 2.0. The Swing 1.1 package can be found at
- the following URL:
- <br/><jump href="http://java.sun.com/products/jfc/index.html">http://java.sun.com/products/jfc/index.html</jump>
- <br/>Refer to the VisualAge for Java 2.0 documentation for information about
- how to import a JAR file into the repository and add that code to your workspace.
- </li>
- <li>Are there any other tips for importing the &javaparsername; parser into VisualAge
- for Java 2.0?
- <br/>The most useful tip applies to <em>any</em> updated code that you import
- into the VisualAge for Java 2.0 product. Before updating code, do the following:
- <br/>1. version the old code
- <br/>2. delete it from your workspace
- <br/>3. import the new code
- <br/>Deleting code from your workspace does not actually delete the code
- permanently -- the versioned code is moved to the repository where it can be
- retrieved later. Be aware, though, that removing code from your
- workspace will cause problems with all of the other classes that use that code.
- VisualAge for Java 2.0 will flag them as errors but this situation is temporary.
- When you import the new code, the errors found when deleting the old code will be fixed.
- <br/>If you are unsure as to how to perform any of these steps, refer to the VisualAge
- for Java 2.0 documentation.
- </li>
- </ul>
- </a>
- </faq>
- <faq title="100% Pure Java compliant?">
- <q>Is this &javaparsername; version 100% pure Java compliant?</q>
- <a> <p>Running JavaPureCheck on the Xerces-J parser code indicated 339
- pure Java classes, 9 warnings, and 0 errors. The nine warnings are
- enumerated below with explanations. To see the entire report, click
- <link idref="jpc">here</link>. </p>
-
- <p>There are many common cases where JavaPureCheck issues warnings
- even though the code is pure Java. These are the most common reasons:</p>
- <ol>
- <li>Warning: method reference:
- <code>java.lang.Class.forName(java.lang.String)</code>
- <br/>This warning is issued in the following two cases:</li>
- <ol>
- <li>Program code calls the <code>Class.forName(String)</code> method to
- dynamically load a class file. In this situation, the
- specified class may contain impure Java code. In the
- cases where this method is called directly in the parser
- code, an explanation is provided detailing why this
- warning can be ignored.</li>
- <li>Program code makes direct reference to an object's
- class. For example: <code>Class stringClass = String.class;</code>.
- In this situation the Java compiler converts
- <code>String.class</code> to the method call
- <code>Class.forName("java.lang.String")</code>.
- As long as the object whose class is being referenced is
- pure Java, the code making the reference remains pure.</li>
- </ol>
- <li>Warning: possible hard-coded path: ...
- <br/>When a String literal contains a common path separator
- character (e.g. '/' or '\'), JavaPureCheck assumes that
- it is a hard-coded path and that the class may not
- contain portable code. While a human tester can verify
- that the string is not a path, JavaPureCheck must be
- conservative and issue a warning.</li>
- </ol>
- <p>Explanations:</p>
- <ul>
- <li>Class: org.xml.sax.helpers.ParserFactory</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: The ParserFactory class is part of the standard SAX 1.0 distribution. The warning given that this class "may load impure class" is correct -- the ParserFactory class may load impure Java class files. However, the purpose of this utility class is to load parser classes by name and therefore cannot dynamically check the pureness of parser classes loaded in this fashion. Since the Xerces-J parser does not use this method directly, it is not a problem that concerns the Xerces-J parser. </li></ul>
- <li>Class: org.apache.xml.serialize.SerializerFactory</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: The SerializerFactory supports querying a system property to dynamically instantiate a serializer by class name. However, all of the serializer classes provided in this distribution are pure. The only way to load an impure serializer is if the user provided an impure serializer implementation.</li></ul>
- <li>Class: org.apache.xml.serialize.OutputFormat</li>
- <ul><li>Warning: possible hard-coded path: text/xml</li></ul>
- <ul><li>Warning: possible hard-coded path: text/plain</li></ul>
- <ul><li>Warning: possible hard-coded path: application/pdf</li></ul>
- <ul><li>Warning: possible hard-coded path: text/html</li></ul>
- <ul><li>Warning: possible hard-coded path: -//W3C//DTD XHTML 1.0 Strict//EN</li></ul>
- <ul><li>Explanation: These strings are not filenames.</li></ul>
- <li>Class: org.apache.xml.serialize.HTMLdtd</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: Referencing class object that is pure Java.</li></ul>
- <li>Class: org.apache.html.dom.HTMLDocumentImpl</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: Referencing class object that is pure Java.</li></ul>
- <li>Class: org.apache.xerces.readers.StringReader</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: Referencing class object that is pure Java.</li></ul>
- <li>Class: org.apache.xerces.parsers.DOMParser</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: The DOMParser class allows the user to set the DOM implemenation to use, by name. However, the default DOM implementation is pure Java.</li></ul>
- <ul><li>Explanation: Referencing class object that is pure Java.</li></ul>
- <li>Class: org.apache.xerces.utils.CharDataChunk</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: Referencing class object that is pure Java.</li></ul>
- <li>Class: org.apache.xerces.utils.UTF8DataChunk</li>
- <ul><li>Warning: method reference: java.lang.Class.forName(java.lang.String)</li></ul>
- <ul><li>Explanation: Referencing class object that is pure Java.</li></ul>
- </ul>
- <p>The results file of the JavaPureCheck can be viewed by clicking <link idref="jpc">here</link>.</p>
- <note>The samples were not checked with JavaPureCheck and are not
- guaranteed to be pure Java. We reserve the right to write samples
- in the future that are platform specific and therefore may not
- pass as pure Java. The parser, however, will remain pure Java.</note>
- </a>
- </faq>
- <faq title="Running on the Mac?">
- <q>How do I get &javaparsername; to run on the Mac under MRJ?</q>
- <a> <p><em>Prerequisites</em> (available from
- <jump href="http://developer.apple.com/java/">http://developer.apple.com/java/</jump>):</p>
- <ul>
- <li>MRJ 2.1 (this is the most recent version of the JVM)</li>
- <li>MRJ SDK 2.1 (this is the most recent version of the Java developer tools)</li>
- </ul>
- <p><em>Instructions </em>(other variations would work also):</p>
- <ol>
- <li>Download the .tar.gz file containing &javaparsername;.</li>
- <li>Use Stuffit Expander(tm), Suntar, or some other Macintosh tool that
- <br/>supports the .tar.gz format to expand the downloaded file.</li>
- <li>JBindery, part of MRJ SDK 2.1, is used to create a double-clickable
- Java application with the necessary configuration information built in.
- It is analogous to writing a .bat or .sh script. </li>
- <li><em>To run the dom.DOMWriter example:</em></li>
- <ol>
- <li>Double click on JBindery to start it up.</li>
- <li>Click on the Classpath panel.</li>
- <li>Click on the "Add .zip File" button and add both the
- "Xerces-J.jar" and "Xerces-JSamples.jar" files.</li>
- <li>Click on the Command panel.</li>
- <li>Enter "dom.DOMWriter" as the Class name. Enter
- "data/personal.xml" in the Optional parameters box.</li>
- <li>Click on Save Settings button, pick a name such as "Run <code>dom.DOMWriter</code>"
- for the file, and <em>be sure</em> that "Save as Application"
- is selected (this is the default) and save the file.</li>
- <li>Quit JBindery.</li>
- <li>You can now double click on the file you created in step f to run the XJParse example.</li>
- </ol>
- </ol>
- </a>
- </faq>
- <faq title="Visual Cafe exception error?">
- <q>Why do I get ArrayIndexOutOfBoundsException in the Symantec Visual Cafe debugger?</q>
- <a> <p>The Visual Cafe debugger is set to trap <code>ArrayIndexOutOfBoundsException</code> exceptions by
- default. &javaparsername; uses <code>ArrayIndexOutOfBoundsException</code> internally to signal
- exceptional, but not erroneous conditions. In order to run &javaparsername;2 inside
- Visual Cafe's debugger, you need to turn off the trapping of these
- exceptions.</p>
- <p><em>To do this:</em></p>
- <ol>
- <li>Select the "Options" item in the "Project" menu.</li>
- <li>Select the "Debugger" tab in the dialog which appears.</li>
- <li>Select "Exceptions" from the popup menu.</li>
- <li>Remove the check from the checkbox for <code>java.lang.ArrayIndexOutOfBoundsException</code>.</li>
- </ol>
- </a>
</faq>
+ <faq title="How do I use Visual Age?">
+ <q>How do I import &javaparsername; into Visual Age for Java</q>
+ <a>
+ <ul>
+ <li>
+ Why does VisualAge for Java 2.0 report problems when I import
+ the &javaparsername; parser?
+ <br/>
+ The current version of the &javaparsername; parser uses Swing
+ 1.1, while VisualAge for Java 2.0 comes with Swing 1.0.2. The
+ free update for the Professional version of VisualAge for Java
+ 2.0 installs Swing 1.0.3. The most important difference between
+ Swing 1.0.2 - 1.0.3 and 1.1 is the Java package was changed
+ from com.sun.java.swing.* to javax.swing.*.
+ <br/>
+ To fix the errors, you must download the Java Foundation Classes
+ 1.1 with Swing 1.1 from Sun's Java home page and import the
+ "swingall.jar" file into VisualAge for Java 2.0. The
+ Swing 1.1 package can be found at the following URL:
+ <br/>
+ <jump href="http://java.sun.com/products/jfc/index.html">http://java.sun.com/products/jfc/index.html</jump>
+ <br/>
+ Refer to the VisualAge for Java 2.0 documentation for information
+ about how to import a JAR file into the repository and add that
+ code to your workspace.
+ </li>
+ <li>
+ Are there any other tips for importing the &javaparsername;
+ parser into VisualAge for Java 2.0?
+ <br/>
+ The most useful tip applies to <em>any</em> updated code that you
+ import into the VisualAge for Java 2.0 product. Before updating
+ code, do the following:
+ <br/>
+ 1. version the old code
+ <br/>
+ 2. delete it from your workspace
+ <br/>
+ 3. import the new code
+ <br/>
+ Deleting code from your workspace does not actually delete
+ the code permanently - the versioned code is moved to the
+ repository where it can be retrieved later. Be aware, though,
+ that removing code from your workspace will cause problems with
+ all of the other classes that use that code. VisualAge for Java
+ 2.0 will flag them as errors but this situation is temporary.
+ When you import the new code, the errors found when deleting the
+ old code will be fixed.
+ <br/>
+ If you are unsure as to how to perform any of these steps, refer
+ to the VisualAge for Java 2.0 documentation.
+ </li>
+ </ul>
+ </a>
+ </faq>
+ <!--
+ - REVISIT: This needs to be re-run and re-verified before we
+ - put this FAQ item back in.
+ <faq title='100% Pure Java compliant?'>
+ <q>Is this &javaparsername; version 100% pure Java compliant?</q>
+ <a>
+ <p>
+ Running JavaPureCheck on the Xerces-J parser code indicated 339
+ pure Java classes, 9 warnings, and 0 errors. The nine warnings are
+ enumerated below with explanations. To see the entire report, click
+ <link idref="jpc">here</link>.
+ </p>
+ <p>
+ There are many common cases where JavaPureCheck issues warnings
+ even though the code is pure Java. These are the most common
+ reasons:
+ </p>
+ <ol>
+ <li>
+ Warning: method reference:
+ <code>java.lang.Class.forName(java.lang.String)</code>
+ <br/>
+ This warning is issued in the following two cases:
+ </li>
+ <ol>
+ <li>
+ Program code calls the <code>Class.forName(String)</code>
+ method to dynamically load a class file. In this situation,
+ the specified class may contain impure Java code. In the
+ cases where this method is called directly in the parser
+ code, an explanation is provided detailing why this warning
+ can be ignored.
+ </li>
+ <li>
+ Program code makes direct reference to an object's
+ class. For example: <code>Class stringClass = String.class;</code>.
+ In this situation the Java compiler converts
+ <code>String.class</code> to the method call
+ <code>Class.forName("java.lang.String")</code>.
+ As long as the object whose class is being referenced is
+ pure Java, the code making the reference remains pure.
+ </li>
+ </ol>
+ <li>
+ Warning: possible hard-coded path: ...
+ <br/>
+ When a String literal contains a common path separator character
+ (e.g. '/' or '\'), JavaPureCheck assumes that
+ it is a hard-coded path and that the class may not contain
+ portable code. While a human tester can verify that the string is
+ not a path, JavaPureCheck must be conservative and issue a
+ warning.
+ </li>
+ </ol>
+ <p>Explanations:</p>
+ <ul>
+ <li>Class: org.xml.sax.helpers.ParserFactory</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>
+ Explanation: The ParserFactory class is part of the standard
+ SAX 1.0 distribution. The warning given that this class "may
+ load impure class" is correct - the ParserFactory class may
+ load impure Java class files. However, the purpose of this
+ utility class is to load parser classes by name and therefore
+ cannot dynamically check the pureness of parser classes loaded
+ in this fashion. Since the Xerces-J parser does not use this
+ method directly, it is not a problem that concerns the Xerces-J
+ parser.
+ </li>
+ </ul>
+ <li>Class: org.apache.xml.serialize.SerializerFactory</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>
+ Explanation: The SerializerFactory supports querying a system
+ property to dynamically instantiate a serializer by class name.
+ However, all of the serializer classes provided in this
+ distribution are pure. The only way to load an impure
+ serializer is if the user provided an impure serializer
+ implementation.
+ </li>
+ </ul>
+ <li>Class: org.apache.xml.serialize.OutputFormat</li>
+ <ul>
+ <li>Warning: possible hard-coded path: text/xml</li>
+ </ul>
+ <ul>
+ <li>Warning: possible hard-coded path: text/plain</li>
+ </ul>
+ <ul>
+ <li>Warning: possible hard-coded path: application/pdf</li>
+ </ul>
+ <ul>
+ <li>Warning: possible hard-coded path: text/html</li>
+ </ul>
+ <ul>
+ <li>
+ Warning: possible hard-coded path:
+ -//W3C//DTD XHTML 1.0 Strict//EN
+ </li>
+ </ul>
+ <ul>
+ <li>Explanation: These strings are not filenames.</li>
+ </ul>
+ <li>Class: org.apache.xml.serialize.HTMLdtd</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>Explanation: Referencing class object that is pure Java.</li>
+ </ul>
+ <li>Class: org.apache.html.dom.HTMLDocumentImpl</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>Explanation: Referencing class object that is pure Java.</li>
+ </ul>
+ <li>Class: org.apache.xerces.readers.StringReader</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>Explanation: Referencing class object that is pure Java.</li>
+ </ul>
+ <li>Class: org.apache.xerces.parsers.DOMParser</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>
+ Explanation: The DOMParser class allows the user to set the
+ DOM implemenation to use, by name. However, the default DOM
+ implementation is pure Java.
+ </li>
+ </ul>
+ <ul>
+ <li>Explanation: Referencing class object that is pure Java.</li>
+ </ul>
+ <li>Class: org.apache.xerces.utils.CharDataChunk</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>Explanation: Referencing class object that is pure Java.</li>
+ </ul>
+ <li>Class: org.apache.xerces.utils.UTF8DataChunk</li>
+ <ul>
+ <li>
+ Warning: method reference:
+ java.lang.Class.forName(java.lang.String)
+ </li>
+ </ul>
+ <ul>
+ <li>Explanation: Referencing class object that is pure Java.</li>
+ </ul>
+ </ul>
+ <p>
+ The results file of the JavaPureCheck can be viewed by clicking
+ <link idref="jpc">here</link>.
+ </p>
+ <note>
+ The samples were not checked with JavaPureCheck and are not
+ guaranteed to be pure Java. We reserve the right to write samples
+ in the future that are platform specific and therefore may not
+ pass as pure Java. The parser, however, will remain pure Java.
+ </note>
+ </a>
+ </faq>
+ -->
+ <faq title='Running on the Mac?'>
+ <q>How do I get &javaparsername; to run on the Mac under MRJ?</q>
+ <a>
+ <p>
+ <em>Prerequisites</em> (available from
+ <jump href="http://developer.apple.com/java/">http://developer.apple.com/java/</jump>):
+ </p>
+ <ul>
+ <li>MRJ 2.1 (this is the most recent version of the JVM)</li>
+ <li>
+ MRJ SDK 2.1 (this is the most recent version of the Java
+ developer tools)
+ </li>
+ </ul>
+ <p>
+ <em>Instructions </em>(other variations would work also):
+ </p>
+ <ol>
+ <li>Download the .tar.gz file containing &javaparsername;.</li>
+ <li>
+ Use Stuffit Expander(tm), Suntar, or some other Macintosh tool
+ that supports the .tar.gz format to expand the downloaded file.
+ </li>
+ <li>
+ JBindery, part of MRJ SDK 2.1, is used to create a double-clickable
+ Java application with the necessary configuration information built
+ in. It is analogous to writing a .bat or .sh script.
+ </li>
+ <li><em>To run the dom.DOMWriter example:</em></li>
+ <ol>
+ <li>Double click on JBindery to start it up.</li>
+ <li>Click on the Classpath panel.</li>
+ <li>
+ Click on the "Add .zip File" button and add both the
+ "Xerces-J.jar" and "Xerces-JSamples.jar" files.
+ </li>
+ <li>Click on the Command panel.</li>
+ <li>
+ Enter "dom.DOMWriter" as the Class name. Enter
+ "data/personal.xml" in the Optional parameters box.
+ </li>
+ <li>
+ Click on Save Settings button, pick a name such as "Run
+ <code>dom.DOMWriter</code>" for the file, and <em>be
+ sure</em> that "Save as Application" is selected
+ (this is the default) and save the file.
+ </li>
+ <li>Quit JBindery.</li>
+ <li>
+ You can now double click on the file you created in step (f) to
+ run the XJParse example.
+ </li>
+ </ol>
+ </ol>
+ </a>
+ </faq>
+ <faq title='Visual Cafe exception error?'>
+ <q>
+ Why do I get ArrayIndexOutOfBoundsException in the Symantec Visual
+ Cafe debugger?
+ </q>
+ <a>
+ <p>
+ The Visual Cafe debugger is set to trap
+ <code>ArrayIndexOutOfBoundsException</code> exceptions by
+ default. &javaparsername; uses
+ <code>ArrayIndexOutOfBoundsException</code> internally to
+ signal exceptional, but not erroneous conditions. In order to
+ run &javaparsername; inside Visual Cafe's debugger, you need to
+ turn off the trapping of these exceptions.
+ </p>
+ <p><em>To do this:</em></p>
+ <ol>
+ <li>Select the "Options" item in the "Project" menu.</li>
+ <li>
+ Select the "Debugger" tab in the dialog which appears.
+ </li>
+ <li>Select "Exceptions" from the popup menu.</li>
+ <li>
+ Remove the check from the checkbox for
+ <code>java.lang.ArrayIndexOutOfBoundsException</code>.
+ </li>
+ </ol>
+ </a>
+ </faq>
</faqs>
1.4.2.2 +113 -67 xml-xerces/java/docs/faq-common.xml
Index: faq-common.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/faq-common.xml,v
retrieving revision 1.4.2.1
retrieving revision 1.4.2.2
diff -u -r1.4.2.1 -r1.4.2.2
--- faq-common.xml 2000/12/12 19:07:11 1.4.2.1
+++ faq-common.xml 2001/07/19 06:43:10 1.4.2.2
@@ -1,68 +1,114 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd">
-
-<faqs title="Common Problems">
- <faq title="Parsing HTML Generated an Error.">
- <q>I tried to use &javaparsername; to parse an HTML file and it generated an error. What did I do wrong?</q>
- <a><p>Unfortunately, HTML does not, in general, follow the XML grammar rules.
- Most HTML files do not meet the XML style quidelines. Therefore, the XML parser
- generates XML well-formedness errors.</p>
- <p>Typical errors include:</p>
- <ul>
- <li>Missing end tags, e.g. <P> with no </P> (end tags are not required in HTML)</li>
- <li>Missing closing slash on <IMG HREF="foo" <em>/</em>> (not required in HTML)</li>
- <li>Missing quotes on attribute values, e.g. <IMG width="600"> (not generally required in HTML)</li>
- </ul>
- <p>HTML must match the XHTML standard for well-formedness before it
- can be parsed by Xerces-J or any other XML parser. You can find the
- <jump href="http://www.w3c.org/TR/1999/PR-xhtml1-19991210">XHTML standard</jump>
- on the <jump href="http://www.w3c.org">W3C web site</jump>.</p>
- </a>
- </faq>
- <faq title="UTF-8 Character Error">
- <q>I get an "invalid UTF-8 character" error.</q>
- <a><p>There are many Unicode characters that are not allowed in an XML document,
- according to the XML spec. Typical disallowed characters are control
- characters, even if you escape them using the Character Reference form:
- &#xxxx; . See the XML spec, sections
- <jump href="http://www.w3.org/TR/REC-xml#charsets">2.2</jump> and
- <jump href="http://www.w3.org/TR/REC-xml#sec-references">4.1</jump>
- for details. If the parser is generating this error, it is very likely
- that there is a character in the file that you can not see.
- You can generally use a UNIX command like "od -hc" to find it.</p>
-
- </a>
- </faq>
- <faq title="Error Accessing EBCDIC XML Files">
- <q>I get an error when I access EBCDIC XML files, what is happening?</q>
- <a><p>If an XML document/file is not UTF-8, then you MUST specify the encoding.
- When transcoding a UTF8 document to EBCDIC, remember to change this:</p>
- <ul>
- <li><?xml version="1.0" encoding="UTF-8"?>
- <br/>to something like this:
- <br/><?xml version="1.0" encoding="ebcdic-cp-us"?>
- </li>
- </ul>
- </a>
- </faq>
- <faq title="EOF Character Error">
- <q>I get an error on the EOF character (0x1A) -- what is happening?</q>
- <a><p>You are probably using the <em>LPEX</em>
- editor, which automatically inserts an End-of-file character (0x1A) at the end of your
- XML document (other editors might do this as well). Unfortunately, the
- EOF character (0x1A) is an illegal character according to the XML specification,
- and &javaparsername; correctly generates an error.</p>
- </a>
- </faq>
- <faq title='DOS Filenames No Longer Work'>
- <q>I used to be able to use DOS filenames with the parser and now
- they don't work. Why not?</q>
- <a><p>DOS filenames are not legal URIs as required by the XML 1.0
- specification. Therefore, it was an error for the parser to accept
- DOS filenames. This bug is now fixed.</p>
- <p>DOS filenames can be converted to legal URIs, however. For
- example, the DOS filename "c:\xerces\data\personal.xml" would become
- "file:///c:/xerces/data/personal.xml", which is a legal URI.</p>
- </a>
- </faq>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
+<faqs title='Common Problems FAQs'>
+ <faq title='DOS Filenames No Longer Work'>
+ <q>
+ I used to be able to use DOS filenames with the parser and now
+ they don't work. Why not?
+ </q>
+ <a>
+ <p>
+ DOS filenames are not legal URIs as required by the XML 1.0
+ specification. Therefore, it was an error for the parser to
+ accept DOS filenames. This bug is now fixed.
+ </p>
+ <p>
+ DOS filenames can be converted to legal URIs, however. For
+ example, the DOS filename "c:\xerces\data\personal.xml" would
+ become "file:///c:/xerces/data/personal.xml", which is a legal
+ URI.
+ </p>
+ </a>
+ </faq>
+ <faq title='Parsing HTML Generated an Error.'>
+ <q>
+ I tried to use &javaparsername; to parse an HTML file and it
+ generated an error. What did I do wrong?
+ </q>
+ <a>
+ <p>
+ Unfortunately, HTML does not, in general, follow the XML
+ grammar rules. Most HTML files do not meet the XML style
+ quidelines. Therefore, the XML parser generates XML
+ well-formedness errors.
+ </p>
+ <p>Typical errors include:</p>
+ <ul>
+ <li>
+ Missing end tags, e.g. <P> with no </P> (end
+ tags are not required in HTML)
+ </li>
+ <li>
+ Missing closing slash on <IMG HREF="foo" <em>/</em>>
+ (not required in HTML)
+ </li>
+ <li>
+ Missing quotes on attribute values, e.g. <IMG width="600">
+ (not generally required in HTML)
+ </li>
+ </ul>
+ <p>
+ HTML must match the XHTML standard for well-formedness before it
+ can be parsed by Xerces-J or any other XML parser. You can find the
+ <jump href="http://www.w3c.org/TR/1999/PR-xhtml1-19991210">XHTML
+ standard</jump> on the
+ <jump href="http://www.w3c.org">W3C web site</jump>.
+ </p>
+ </a>
+ </faq>
+ <faq title='UTF-8 Character Error'>
+ <q>I get an "invalid UTF-8 character" error.</q>
+ <a>
+ <p>
+ There are many Unicode characters that are not allowed in an
+ XML document, according to the XML spec. Typical disallowed
+ characters are control characters, even if you escape them
+ using the Character Reference form: &#xxxx; . See the XML
+ spec, sections
+ <jump href="http://www.w3.org/TR/REC-xml#charsets">2.2</jump>
+ and
+ <jump href="http://www.w3.org/TR/REC-xml#sec-references">4.1</jump>
+ for details. If the parser is generating this error, it is very
+ likely that there is a character in the file that you can not see.
+ You can generally use a UNIX command like "od -hc" to
+ find it.
+ </p>
+ </a>
+ </faq>
+ <faq title='Error Accessing EBCDIC XML Files'>
+ <q>
+ I get an error when I access EBCDIC XML files, what is happening?
+ </q>
+ <a>
+ <p>
+ If an XML document/file is not UTF-8, then you MUST specify the
+ encoding. When transcoding a UTF8 document to EBCDIC, remember
+ to change this:
+ </p>
+ <ul>
+ <li>
+ <?xml version="1.0" encoding="UTF-8"?>
+ <br/>
+ to something like this:
+ <br/>
+ <?xml version="1.0" encoding="ebcdic-cp-us"?>
+ </li>
+ </ul>
+ </a>
+ </faq>
+ <faq title='EOF Character Error'>
+ <q>
+ I get an error on the EOF character (0x1A) -- what is happening?
+ </q>
+ <a>
+ <p>
+ You are probably using the <em>LPEX</em> editor, which
+ automatically inserts an End-of-file character (0x1A) at the end
+ of your XML document (other editors might do this as well).
+ Unfortunately, the EOF character (0x1A) is an illegal character
+ according to the XML specification, and &javaparsername;
+ correctly generates an error.
+ </p>
+ </a>
+ </faq>
</faqs>
1.6.2.2 +78 -91 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.6.2.1
retrieving revision 1.6.2.2
diff -u -r1.6.2.1 -r1.6.2.2
--- faq-general.xml 2000/12/12 19:07:11 1.6.2.1
+++ faq-general.xml 2001/07/19 06:43:10 1.6.2.2
@@ -1,92 +1,79 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd">
-
-<faqs title="General FAQs">
-
- <faq title="New Features?">
- <q>What are the new features?</q>
- <a>
- <p>Here are some of the new features in &javaparsername;:</p>
- <ul>
- <li>Additional support for W3C XML Schema Language.</li>
- <li>DOS filenames no longer work. See Common Problems
- section of the FAQ.</li>
- </ul>
- <anchor name="valid"/>
- </a>
- </faq>
-
- <faq title="Validation">
- <q>How do I turn on validation?</q>
- <a>
- <p>You can turn validation on and off via methods available
- on the SAX2 <code>XMLFilter</code> interface. While only the
- <code>SAXParser</code> implements the <code>XMLFilter</code>
- interface, the methods required for turning on validation
- are available to both parser classes, DOM and SAX.
- <br/>
- The code snippet below shows how to turn validation on -- assume that <ref>parser</ref>
- is an instance of either
- <code>org.apache.xerces.parsers.SAXParser</code> or
- <code>org.apache.xerces.parsers.DOMParser</code>. <br/><br/>
- <code>parser.setFeature("http://xml.org/sax/features/validation", true);</code>
- </p>
- </a>
- </faq>
-
- <faq title="International Encodings">
- <q>What international encodings are supported by &javaparsername;?</q>
- <a>
- <ul>
- <li>UTF-8</li>
- <li>UTF-16 Big Endian, UTF-16 Little Endian</li>
- <li>IBM-1208</li>
- <li>ISO Latin-1 (ISO-8859-1)</li>
- <li>ISO Latin-2 (ISO-8859-2) [Bosnian, Croatian, Czech,
- Hungarian, Polish, Romanian, Serbian (in Latin transcription),
- Serbocroatian, Slovak, Slovenian, Upper and Lower Sorbian]</li>
- <li>ISO Latin-3 (ISO-8859-3) [Maltese, Esperanto]</li>
- <li>ISO Latin-4 (ISO-8859-4)</li>
- <li>ISO Latin Cyrillic (ISO-8859-5)</li>
- <li>ISO Latin Arabic (ISO-8859-6)</li>
- <li>ISO Latin Greek (ISO-8859-7)</li>
- <li>ISO Latin Hebrew (ISO-8859-8)</li>
- <li>ISO Latin-5 (ISO-8859-9) [Turkish]</li>
- <li>Extended Unix Code, packed for Japanese (euc-jp, eucjis)</li>
- <li>Japanese Shift JIS (shift-jis)</li>
- <li>Chinese (big5)</li>
- <li>Chinese for PRC (mixed 1/2 byte) (gb2312)</li>
- <li>Japanese ISO-2022-JP (iso-2022-jp)</li>
- <li>Cyrllic (koi8-r)</li>
- <li>Extended Unix Code, packed for Korean (euc-kr)</li>
- <li>Russian Unix, Cyrillic (koi8-r)</li>
- <li>Windows Thai (cp874)</li>
- <li>Latin 1 Windows (cp1252)</li>
- <li>cp858</li>
- <li>EBCDIC encodings:</li>
- <ul>
- <li>EBCDIC US (ebcdic-cp-us)</li>
- <li>EBCDIC Canada (ebcdic-cp-ca)</li>
- <li>EBCDIC Netherland (ebcdic-cp-nl)</li>
- <li>EBCDIC Denmark (ebcdic-cp-dk)</li>
- <li>EBCDIC Norway (ebcdic-cp-no)</li>
- <li>EBCDIC Finland (ebcdic-cp-fi)</li>
- <li>EBCDIC Sweden (ebcdic-cp-se)</li>
- <li>EBCDIC Italy (ebcdic-cp-it)</li>
- <li>EBCDIC Spain, Latin America (ebcdic-cp-es)</li>
- <li>EBCDIC Great Britain (ebcdic-cp-gb)</li>
- <li>EBCDIC France (ebcdic-cp-fr)</li>
- <li>EBCDIC Hebrew (ebcdic-cp-he)</li>
- <li>EBCDIC Switzerland (ebcdic-cp-ch)</li>
- <li>EBCDIC Roece (ebcdic-cp-roece)</li>
- <li>EBCDIC Yugoslavia (ebcdic-cp-yu)</li>
- <li>EBCDIC Iceland (ebcdic-cp-is)</li>
- <li>EBCDIC Urdu (ebcdic-cp-ar2)</li>
- <li>Latin 0 EBCDIC</li>
- <li>EBCDIC Arabic (ebcdic-cp-ar1)</li>
- </ul>
- </ul>
- </a>
- </faq>
-
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
+<faqs title='General FAQs'>
+ <faq title='Validation'>
+ <q>How do I turn on validation?</q>
+ <a>
+ <p>
+ You can turn validation on and off via methods available
+ on the SAX2 <code>XMLFilter</code> interface. While only the
+ <code>SAXParser</code> implements the <code>XMLFilter</code>
+ interface, the methods required for turning on validation
+ are available to both parser classes, DOM and SAX.
+ <br/>
+ The code snippet below shows how to turn validation on -- assume
+ that <ref>parser</ref> is an instance of either
+ <code>org.apache.xerces.parsers.SAXParser</code> or
+ <code>org.apache.xerces.parsers.DOMParser</code>.
+ <br/><br/>
+ <code>parser.setFeature("http://xml.org/sax/features/validation", true);</code>
+ </p>
+ </a>
+ </faq>
+ <faq title='International Encodings'>
+ <q>What international encodings are supported by &javaparsername;?</q>
+ <a>
+ <ul>
+ <li>UTF-8</li>
+ <li>UTF-16 Big Endian, UTF-16 Little Endian</li>
+ <li>IBM-1208</li>
+ <li>ISO Latin-1 (ISO-8859-1)</li>
+ <li>
+ ISO Latin-2 (ISO-8859-2) [Bosnian, Croatian, Czech,
+ Hungarian, Polish, Romanian, Serbian (in Latin transcription),
+ Serbocroatian, Slovak, Slovenian, Upper and Lower Sorbian]
+ </li>
+ <li>ISO Latin-3 (ISO-8859-3) [Maltese, Esperanto]</li>
+ <li>ISO Latin-4 (ISO-8859-4)</li>
+ <li>ISO Latin Cyrillic (ISO-8859-5)</li>
+ <li>ISO Latin Arabic (ISO-8859-6)</li>
+ <li>ISO Latin Greek (ISO-8859-7)</li>
+ <li>ISO Latin Hebrew (ISO-8859-8)</li>
+ <li>ISO Latin-5 (ISO-8859-9) [Turkish]</li>
+ <li>Extended Unix Code, packed for Japanese (euc-jp, eucjis)</li>
+ <li>Japanese Shift JIS (shift-jis)</li>
+ <li>Chinese (big5)</li>
+ <li>Chinese for PRC (mixed 1/2 byte) (gb2312)</li>
+ <li>Japanese ISO-2022-JP (iso-2022-jp)</li>
+ <li>Cyrllic (koi8-r)</li>
+ <li>Extended Unix Code, packed for Korean (euc-kr)</li>
+ <li>Russian Unix, Cyrillic (koi8-r)</li>
+ <li>Windows Thai (cp874)</li>
+ <li>Latin 1 Windows (cp1252)</li>
+ <li>cp858</li>
+ <li>EBCDIC encodings:</li>
+ <ul>
+ <li>EBCDIC US (ebcdic-cp-us)</li>
+ <li>EBCDIC Canada (ebcdic-cp-ca)</li>
+ <li>EBCDIC Netherland (ebcdic-cp-nl)</li>
+ <li>EBCDIC Denmark (ebcdic-cp-dk)</li>
+ <li>EBCDIC Norway (ebcdic-cp-no)</li>
+ <li>EBCDIC Finland (ebcdic-cp-fi)</li>
+ <li>EBCDIC Sweden (ebcdic-cp-se)</li>
+ <li>EBCDIC Italy (ebcdic-cp-it)</li>
+ <li>EBCDIC Spain, Latin America (ebcdic-cp-es)</li>
+ <li>EBCDIC Great Britain (ebcdic-cp-gb)</li>
+ <li>EBCDIC France (ebcdic-cp-fr)</li>
+ <li>EBCDIC Hebrew (ebcdic-cp-he)</li>
+ <li>EBCDIC Switzerland (ebcdic-cp-ch)</li>
+ <li>EBCDIC Roece (ebcdic-cp-roece)</li>
+ <li>EBCDIC Yugoslavia (ebcdic-cp-yu)</li>
+ <li>EBCDIC Iceland (ebcdic-cp-is)</li>
+ <li>EBCDIC Urdu (ebcdic-cp-ar2)</li>
+ <li>Latin 0 EBCDIC</li>
+ <li>EBCDIC Arabic (ebcdic-cp-ar1)</li>
+ </ul>
+ </ul>
+ </a>
+ </faq>
</faqs>
1.2.2.1 +87 -64 xml-xerces/java/docs/faq-performance.xml
Index: faq-performance.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/faq-performance.xml,v
retrieving revision 1.2
retrieving revision 1.2.2.1
diff -u -r1.2 -r1.2.2.1
--- faq-performance.xml 2000/05/23 20:28:56 1.2
+++ faq-performance.xml 2001/07/19 06:43:10 1.2.2.1
@@ -1,65 +1,88 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd">
-
-<faqs title="Performance FAQs">
-
- <faq title="General Performance">
- <q>General Performance</q>
- <a><p>Don't use XML where it doesn't make sense. XML is not a panacea.
- You will not get good performance by transferring and parsing a
- lot of XML files. </p>
- <p>Using XML is memory, CPU, and network intensive.</p></a>
- </faq>
-
- <faq title="Parser Performance">
- <q>Parser Performance</q>
- <a><p>Avoid creating a new parser each time you parse; reuse parser
- instances. A pool of reusable parser instances might be a good idea
- if you have multiple threads parsing at the same time.</p>
- </a>
- </faq>
- <faq title="Parsing Documents Performance">
- <q>Parsing Documents Performance</q>
- <a><ul>
- <li>Convert the document to US ASCII ("US-ASCII") or Unicode
- ("UTF-8" or "UTF-16") before parsing. Documents written using
- ASCII are the fastest to parse because each character is
- guaranteed to be a single byte and map directly to their
- equivalent Unicode value. For documents that contain Unicode
- characters beyond the ASCII range, multiple byte sequences
- must be read and converted for each character. There is a
- performance penalty for this conversion. The UTF-16 encoding
- alleviates some of this penalty because each character is
- specified using two bytes, assuming no surrogate characters.
- However, using UTF-16 can roughly double the size of the
- original document which takes longer to parse.</li>
- <li>Explicitly specify "US-ASCII" encoding if your document is in
- ASCII format. If no encoding is specified, the XML specification
- requires the parser to assume UTF-8 which is slower to process.</li>
- <li>Avoid external entities and external DTDs. The extra file
- opens and transcoding setup is expensive.</li>
- <li>Reduce character count; smaller documents are parsed quicker.
- Replace elements with attributes where it makes sense. Avoid
- gratuitous use of whitespace because the parser must scan past it.</li>
- <li>Avoid using too many default attributes. Defaulting
- attribute values slows down processing.</li>
- </ul>
- </a>
- </faq>
- <faq title="XML Application Performance">
- <q>XML Application Performance</q>
- <a><ul>
- <li>Turn validation off if you don't need it. Validation is
- expensive. Also, avoid using a DOCTYPE line in your XML document.
- The current version of the parser will always read the DTD if the
- DOCTYPE line is specified even when not validating.</li>
- <li>For large documents, avoid using DOM which uses a lot of
- memory. Instead, use SAX if appropriate. The DOM parser requires
- that the entire document be read into memory before the
- application processes the document. The SAX parser uses very
- little memory and notifies the application as parts of the
- document are parsed.</li>
- </ul>
- </a>
- </faq>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
+<faqs title='Performance FAQs'>
+ <faq title='General Performance'>
+ <q>General Performance</q>
+ <a>
+ <p>
+ Don't use XML where it doesn't make sense. XML is not a panacea.
+ You will not get good performance by transferring and parsing a
+ lot of XML files.
+ </p>
+ <p>Using XML is memory, CPU, and network intensive.</p>
+ </a>
+ </faq>
+ <faq title='Parser Performance'>
+ <q>Parser Performance</q>
+ <a>
+ <p>
+ Avoid creating a new parser each time you parse; reuse parser
+ instances. A pool of reusable parser instances might be a good idea
+ if you have multiple threads parsing at the same time.
+ </p>
+ </a>
+ </faq>
+ <faq title='Parsing Documents Performance'>
+ <q>Parsing Documents Performance</q>
+ <a>
+ <p>
+ There are a variety of things that you can do to improve the
+ performance when parsing documents:
+ </p>
+ <ul>
+ <li>
+ Convert the document to US ASCII ("US-ASCII") or Unicode
+ ("UTF-8" or "UTF-16") before parsing. Documents written using
+ ASCII are the fastest to parse because each character is
+ guaranteed to be a single byte and map directly to their
+ equivalent Unicode value. For documents that contain Unicode
+ characters beyond the ASCII range, multiple byte sequences
+ must be read and converted for each character. There is a
+ performance penalty for this conversion. The UTF-16 encoding
+ alleviates some of this penalty because each character is
+ specified using two bytes, assuming no surrogate characters.
+ However, using UTF-16 can roughly double the size of the
+ original document which takes longer to parse.
+ </li>
+ <li>
+ Explicitly specify "US-ASCII" encoding if your document is in
+ ASCII format. If no encoding is specified, the XML specification
+ requires the parser to assume UTF-8 which is slower to process.
+ </li>
+ <li>
+ Avoid external entities and external DTDs. The extra file
+ opens and transcoding setup is expensive.
+ </li>
+ <li>
+ Reduce character count; smaller documents are parsed quicker.
+ Replace elements with attributes where it makes sense. Avoid
+ gratuitous use of whitespace because the parser must scan past it.
+ </li>
+ <li>
+ Avoid using too many default attributes. Defaulting attribute
+ values slows down processing.
+ </li>
+ </ul>
+ </a>
+ </faq>
+ <faq title='XML Application Performance'>
+ <q>XML Application Performance</q>
+ <a>
+ <ul>
+ <li>
+ Turn validation off if you don't need it. Validation is expensive.
+ Also, avoid using a DOCTYPE line in your XML document. The current
+ version of the parser will always read the DTD if the DOCTYPE line
+ is specified even when not validating.
+ </li>
+ <li>
+ For large documents, avoid using DOM which uses a lot of memory.
+ Instead, use SAX if appropriate. The DOM parser requires that
+ the entire document be read into memory before the application
+ processes the document. The SAX parser uses very little memory
+ and notifies the application as parts of the document are parsed.
+ </li>
+ </ul>
+ </a>
+ </faq>
</faqs>
1.10.2.2 +317 -323 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.10.2.1
retrieving revision 1.10.2.2
diff -u -r1.10.2.1 -r1.10.2.2
--- faq-write.xml 2000/12/12 19:07:11 1.10.2.1
+++ faq-write.xml 2001/07/19 06:43:10 1.10.2.2
@@ -1,327 +1,327 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE faqs SYSTEM "./dtd/faqs.dtd">
-
-<faqs title="Writing Application FAQs">
- <faq title="Creating a DOM Parser">
- <q>How do I create a DOM parser?</q>
- <a>
-<source>import org.apache.xerces.parsers.DOMParser;
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
+<faqs title='Writing Application FAQs'>
+ <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). The following source code shows
+ how:
+ </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;
-import java.io.IOException;
...
String xmlFile = "file:///&javaparserdirectory;/data/personal.xml";
-
-DOMParser parser = new DOMParser();
-
try {
- parser.parse(xmlFile);
-
-} catch (SAXException se) {
- se.printStackTrace();
-} catch (IOException ioe) {
- ioe.printStackTrace();
+ DocumentBuilderFactory factory =
+ DocumentBuilderFactory.newInstance();
+ DocumentBuilder builder = factory.newDocumentBuilder();
+ Document document = builder.parse(xmlFile);
}
-
-Document document = parser.getDocument();</source>
- </a>
- </faq>
-
- <faq title="Creating a SAX Parser">
- <q>How do I create a SAX parser?</q>
- <a>
-<source>import org.apache.xerces.parsers.SAXParser;
-import org.xml.sax.Parser;
-import org.xml.sax.ParserFactory;
-import org.xml.sax.SAXException;
+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>
+ </a>
+ </faq>
+ <faq title="Creating a SAX Parser">
+ <q>How do I create a SAX parser?</q>
+ <a>
+ <p>
+ You can create a SAX parser by using the Java APIs for
+ XML Processing (JAXP). The following source code shows
+ how:
+ </p>
+ <source>
import java.io.IOException;
+import javax.xml.parsers.FactoryConfigurationError;
+import javax.xml.parsers.ParserConfigurationException;
+import javax.xml.parsers.SAXParser;
+import javax.xml.parsers.SAXParserFactory;
+import org.xml.sax.SAXException;
+import org.xml.sax.helpers.DefaultHandler;
...
String xmlFile = "file:///&javaparserdirectory;/data/personal.xml";
-
-String parserClass = "org.apache.xerces.parsers.SAXParser";
-Parser parser = ParserFactory.makeParser(parserClass);
-
try {
- parser.parse(xmlFile);
-} catch (SAXException se) {
- se.printStackTrace();
-} catch (IOException ioe) {
- ioe.printStackTrace();
+ SAXParserFactory factory = SAXParserFactory.newInstance();
+ SAXParser parser = factory.newSAXParser();
+ DefaultHandler handler = /* custom handler class */;
+ parser.parse(xmlFile, handler);
+}
+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>
- </a>
- </faq>
-
- <faq title="Controlling parser options">
- <q>How do I control the various parser options?</q>
- <a><p>For this release, all of the parser control API's have
- been switched over to the SAX2 Configurable interface. This
- provide a uniform and extensible mechanism for setting and
- querying parser options. Here are guides to the set of
- available <link idref="features">features</link> and
- <link idref="properties">properties</link>.</p>
- </a>
- </faq>
- <faq title="Using lazy DOM">
- <q>How do I use the lazy evaluating DOM implementation?</q>
- <a><p>The DOM parser class <code>org.apache.xerces.parsers.DOMParser</code> uses a
- DOM implementation that can take advantage of lazy evaluation to
- improve performance. There is also a mode where the parser creates
- all of the nodes as the document is parsed. By default, the parser
- uses the lazy evaluation DOM implementation.</p>
- <p>Nodes in the DOM tree are only created when they are accessed.
- The initial call to <code>getDocument()</code> will return a DOM tree that
- consists only of the Document node. All of the immediate children
- of a Node are created when any of that Node's children are accessed.
- This shortens the time it takes to parse an XML file and create a DOM
- tree at the expense of requiring more memory during parsing and
- traversing the document.</p>
- <p>The lazy evaluation feature is set using the SAX2 Configurable
- interface. To turn off this feature, use the following code:</p>
-<source>DOMParser parser = new DOMParser();
-parser.setFeature("http://apache.org/xml/features/dom/defer-node-expansion", false);</source>
- <p>To turn the lazy evaluation feature back on, use the following code:</p>
-
-<source>parser.setFeature("http://apache.org/xml/features/dom/defer-node-expansion", true);</source>
- </a>
- </faq>
-
- <faq title="Handling Errors">
- <q>How do handle errors?</q>
- <a><p>When you create a parser instance, the default error handler does nothing.
- This means that your program will fail silently when it encounters an error.
- 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>
- </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 feature <code>http://apache.org/xml/features/dom/create-entity-ref-nodes</code>
- controls how entities appear in the DOM tree. When this
- feature 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 property 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 checking only"?</q>
- <a><p>Using a "non-validating" parser does not mean that only well-formedness
- checking is done! There are still many things that the XML specification
- requires of the parser, including entity substitution, defaulting of
- attribute values, and attribute normalization.</p>
- <p>This table describes what "non-validating" really means for &javaparsername; parsers.
- In this table, "no DTD" means no internal or external DTD subset is present.</p>
-
- <table>
- <tr><tn/>
- <th colspan="2">non-validating parsers</th>
- <th colspan="2">validating parsers</th>
- </tr>
- <tr><tn/> <th>DTD present</th> <th>no DTD</th> <th>DTD present</th> <th>no DTD</th></tr>
- <tr><th>DTD is read</th> <td>Yes</td> <td>No</td> <td>Yes</td> <td>Error</td></tr>
- <tr><th>entity substitution</th> <td>Yes</td> <td>No</td> <td>Yest</td> <td>Error</td></tr>
- <tr><th>defaulting of attributes</th> <td>Yes</td> <td>No</td> <td>Yes</td> <td>Error</td></tr>
- <tr><th>attribute normalization</th> <td>Yes</td> <td>No</td> <td>Yes</td> <td>Error</td></tr>
- <tr><th>checking against model</th> <td>No</td> <td>No</td> <td>Yes</td> <td>Error</td></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 whole document is.</p>
- </a>
- </faq>
-
- <faq title="Parsing Several Documents">
- <q>How do I more efficiently parse several documents sharing a common DTD?</q>
- <a> <p>DTDs are not currently cached by the parser. The common DTD, since it is
- specified in each XML document, will be re-parsed once for each document.</p>
- <p>However, there are things that you can do now, to make the process of
- reading DTD's more efficient:</p>
- <ul>
- <li>keep your DTD and DTD references local</li>
- <li>use internal DTD subsets, if possible</li>
- <li>load files from server to local client before parsing</li>
- <li>Cache document files into a local client cache. You should do an
- HTTP header request to check whether the document has changed,
- before accessing it over the network.</li>
- <li>Do not reference an external DTD or internal DTD subset at all.
- In this case, no DTD will be read.</li>
- <li>Use a custom <code>EntityResolver</code> and keep common
- DTDs in a memory buffer.</li>
- </ul>
- </a>
- </faq>
-
- <faq title="How do I access the DOM Level 2 functionality?">
- <q>How do I access the DOM Level 2 functionality?</q>
- <a><p>The <jump href="http://www.w3.org/TR/DOM-Level-2/">DOM Level 2</jump>
- specification is at the stage of
- "Candidate Recommendation" (CR), which allows feedback from implementors
- before it becomes a "Recommedation". It is comprised of "core"
- functionality, which is mainly the DOM
- <jump href="http://www.w3.org/TR/REC-xml-names/">Namespaces</jump> implementation,
- and a number of optional modules (called Chapters in the spec).</p>
- <p>Please refer to:</p>
- <p><jump href="http://www.w3.org/TR/DOM-Level-2/">
- http://www.w3.org/TR/DOM-Level-2/</jump> for the
- latest DOM Level 2 specification.</p>
- <p>The following DOM Level 2 modules are fully implemented in &javaparsername;: </p>
- <ul>
- <li><jump href="http://www.w3.org/TR/DOM-Level-2/core.html">
- Chapter 1: Core</jump> - most of these enhancements are for
- Namespaces, and can be acessed through additional functions which
- have been added directly to the <ref>org.w3c.dom.*</ref> classes.</li>
-
- <li><jump href="http://www.w3.org/TR/DOM-Level-2/events.html">
- Chapter 6: Events</jump> - The <ref>org.w3c.dom.events.EventTarget</ref>
- interface is implemented by all <code>Nodes</code> of the DOM.
- The &javaparsername; DOM implementation handles all of the event
- triggering, capture and flow.</li>
-
- <li><jump href="http://www.w3.org/TR/DOM-Level-2/traversal.html">
- Chapter 7: Traversal</jump> - The Traversal module interfaces
- are located in <ref>org.w3c.dom.traversal</ref>.
- The <code>NodeIterator</code> and <code>TreeWalker</code>, and
- <code>NodeFilter</code> interfaces have been supplied to allow
- traversal of the DOM at a higher-level. Our DOM Document
- implementation class, <code>DocumentImpl</code> class now
- implements <code>DocumentTraversal</code>, which supplies the
- factory methods to create the iterators and treewalkers.</li>
-
- <li><jump href="http://www.w3.org/TR/DOM-Level-2/range.html">
- Chapter 8. Range</jump> - The Range module interfaces are
- located in <ref>org.w3c.dom.range</ref>. The Range interface
- allows you to specify ranges or selections using boundary
- points in the DOM, along with functions (like delete,
- clone, extract..) that can be performed on these ranges.
- Our DOM Document implementation class, <code>DocumentImpl</code>
- class now implements <code>DocumentRange</code>, that supplies
- the factory method to create a <code>Range</code>.</li>
- </ul>
- <note>Since the DOM Level 2 is still in the CR phase, some changes
- to these specs are still possible. The purpose of this phase is to
- provide feedback to the W3C, so that the specs can be clarified and
- implementation concerns can be addressed.</note>
- </a>
- </faq>
-
- <faq title="How do I read data from a stream as it arrives?">
- <q>How do I read data from a stream as it arrives?</q>
- <a><p>There are 3 problems you have to deal with:</p>
-
-<ol>
-<li>The Apache parsers read the entire data stream into a buffer before they start
- parsing; you need to change this behaviour, so that they analyse "on the fly"</li>
-<li>The Apache parsers terminate when they reach end-of-file; with a data stream,
- unless the sender drops the socket, you have no end-of-file, so you need to
- terminate in some other way</li>
-<li>The Apache parsers close the input stream on termination, and this closes the
- socket; you normally don't want this, because you'll want to send an ack to the
- data stream source, and you may want to have further exchanges on the socket
- anyway.</li>
-</ol>
-
-
-<p>Preventing the buffering</p>
-<p>To do this, create a subclass of org.apache.xerces.readers.DefaultReaderFactory
-and override createCharReader and createUTF8Reader as shown below.</p>
-
-<source>
-package org.apache.xerces.readers;
-
-import org.apache.xerces.framework.XMLErrorReporter;
-import org.apache.xerces.utils.ChunkyByteArray;
-import org.apache.xerces.utils.StringPool;
-import org.xml.sax.InputSource;
-import java.io.InputStream;
-import java.io.InputStreamReader;
-import java.io.Reader;
-import java.net.URL;
-import java.util.Stack;
-
-public class StreamingCharFactory extends org.apache.xerces.readers.DefaultReaderFactory {
- public XMLEntityHandler.EntityReader createCharReader(XMLEntityHandler entityHandler,
- XMLErrorReporter errorReporter,boolean sendCharDataAsCharArray,
- Reader reader,
- StringPool stringPool)
- throws Exception
- {
- return new org.apache.xerces.readers.StreamingCharReader(entityHandler,
- errorReporter,
- sendCharDataAsCharArray,
- reader,
- stringPool);
- }
+ </a>
+ </faq>
+ <!--
+ - REVISIT: make sure that JAXP implementation can handle
+ - passing features and properties through to the
+ - parser implementation. Then complete this section.
+ <faq title='Controlling parser options'>
+ <q>How do I control the various parser options?</q>
+ <a>TBD</a>
+ </faq>
+ -->
+ <faq title='Handling Errors'>
+ <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;
- public XMLEntityHandler.EntityReader createUTF8Reader(XMLEntityHandler entityHandler,
- XMLErrorReporter errorReporter,
- boolean sendCharDataAsCharArray,
- InputStream data,StringPool stringPool)
- throws Exception
- {
- XMLEntityHandler.EntityReader reader;
- reader = new org.apache.xerces.readers.StreamingCharReader(entityHandler,
- errorReporter,
- sendCharDataAsCharArray,
- new InputStreamReader(data, "UTF8"),
- stringPool);
- return reader;
+ErrorHandler handler = new ErrorHandler() {
+ public void warning(SAXParseException e) throws SAXException {
+ System.err.println("[warning] "+e.getMessage());
}
-}
-</source>
-
-<p>
-In your program, after you instantiate a parser class, replace the
-DefaultReaderFactory with StreamingCharFactory. You'll need to instantiate your
-parser as a SAXParser, rather than simply as an XMLReader, because the XMLReader
-interface doesn't have the setReaderFactory method. Be sure to wrap the
-InputStream that you are reading from with an InputStreamReader.
-</p>
+ 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;
+ }
+};
-<source>
-try {
- SAXParser parser =
- (SAXParser)Class.forName("org.apache.xerces.parsers.SAXParser").newInstance();
- parser.setContentHandler(new DocProcessor(out));
- parser.setReaderFactory(new StreamingCharFactory());
- parser.parse(new InputSource(bufferedReader));
-} catch (Exception ex) {
-}
-</source>
+DocumentBuilder builder = /* builder instance */;
+builder.setErrorHandler(handler);</source>
+ <p>
+ You can also register an error handler on a SAXParser using JAXP
+ like this:
+ </p>
+ <source>import javax.xml.parsers.SAXParser;
+import org.xml.sax.ErrorHandler;
+import org.xml.sax.SAXException;
+import org.xml.sax.SAXParseException;
-<p>Terminating the parse</p>
-<p>One way that works forSAX is to throw an exception when you detect the logical
-end-of-document.</p>
-<p>For instance, in your class extending DefaultHandler, you can have:</p>
+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;
+ }
+};
-<source>
-public class DocProcessor extends DefaultHandler {
+SAXParser parser = /* parser instance */;
+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 feature
+ <code>http://apache.org/xml/features/dom/create-entity-ref-nodes</code>
+ controls how entities appear in the DOM tree. When this feature
+ 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 property 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
+ checking only"?
+ </q>
+ <a>
+ <p>
+ Using a "non-validating" parser does not mean that
+ only well-formedness checking is done! There are still many
+ things that the XML specification requires of the parser,
+ including entity substitution, defaulting of attribute values,
+ and attribute normalization.
+ </p>
+ <p>
+ This table describes what "non-validating" really
+ means for &javaparsername; parsers. In this table, "no DTD"
+ means no internal or external DTD subset is present.
+ </p>
+ <table>
+ <tr>
+ <tn/>
+ <th colspan="2">non-validating parsers</th>
+ <th colspan="2">validating parsers</th>
+ </tr>
+ <tr>
+ <tn/>
+ <th>DTD present</th>
+ <th>no DTD</th>
+ <th>DTD present</th>
+ <th>no DTD</th>
+ </tr>
+ <tr>
+ <th>DTD is read</th>
+ <td>Yes</td>
+ <td>No</td>
+ <td>Yes</td>
+ <td>Error</td>
+ </tr>
+ <tr>
+ <th>entity substitution</th>
+ <td>Yes</td>
+ <td>No</td>
+ <td>Yes</td>
+ <td>Error</td>
+ </tr>
+ <tr>
+ <th>defaulting of attributes</th>
+ <td>Yes</td>
+ <td>No</td>
+ <td>Yes</td>
+ <td>Error</td>
+ </tr>
+ <tr>
+ <th>attribute normalization</th>
+ <td>Yes</td>
+ <td>No</td>
+ <td>Yes</td>
+ <td>Error</td>
+ </tr>
+ <tr>
+ <th>checking against model</th>
+ <td>No</td>
+ <td>No</td>
+ <td>Yes</td>
+ <td>Error</td>
+ </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>
+ </a>
+ </faq>
+ <faq title='Parsing Several Documents'>
+ <q>
+ How do I more efficiently parse several documents sharing a
+ common DTD?
+ </q>
+ <a>
+ <p>
+ DTDs are not currently cached by the parser. The common DTD,
+ since it is specified in each XML document, will be re-parsed
+ once for each document.
+ </p>
+ <p>
+ However, there are things that you can do now, to make the
+ process of reading DTD's more efficient:
+ </p>
+ <ul>
+ <li>keep your DTD and DTD references local</li>
+ <li>use internal DTD subsets, if possible</li>
+ <li>load files from server to local client before parsing</li>
+ <li>
+ Cache document files into a local client cache. You should do an
+ HTTP header request to check whether the document has changed,
+ before accessing it over the network.
+ </li>
+ <li>
+ Do not reference an external DTD or internal DTD subset at all.
+ In this case, no DTD will be read.
+ </li>
+ <li>
+ Use a custom <code>EntityResolver</code> and keep common
+ DTDs in a memory buffer.
+ </li>
+ </ul>
+ </a>
+ </faq>
+ <!--
+ - REVISIT: Rewrite this section with better information.
+ <faq title='How do I read data from a stream as it arrives?'>
+ <q>How do I read data from a stream as it arrives?</q>
+ <a>
+ <p>There are 2 problems you have to deal with:</p>
+ <ol>
+ <li>
+ The Apache parsers terminate when they reach end-of-file; with
+ a data stream, unless the sender drops the socket, you have no
+ end-of-file, so you need to terminate in some other way
+ </li>
+ <li>
+ The Apache parsers close the input stream on termination, and
+ this closes the socket; you normally don't want this, because
+ you'll want to send an ack to the data stream source, and you
+ may want to have further exchanges on the socket anyway.
+ </li>
+ </ol>
+ <p>Terminating the parse</p>
+ <p>
+ One way that works forSAX is to throw an exception when you
+ detect the logical end-of-document.
+ </p>
+ <p>
+ For instance, in your class extending DefaultHandler, you can
+ have:
+ </p>
+ <source>public class DocProcessor extends DefaultHandler {
private int level;
.
.
@@ -337,24 +337,18 @@
String localName,
String qName) throws SAXException
{
- if ((--level) == 0) {
+ level = level - 1;
+ if (level == 0) {
throw new SAXException ("Finished");
}
- }
-</source>
-
-<p>
- Preventing the parser from closing the socket
-
- One way is to subclass BufferedReader to provide an empty close method.
-
- So, invoke the parser as follows:
-</p>
+ }</source>
+ <p>Preventing the parser from closing the socket</p>
+ <p>
+ One way is to subclass BufferedReader to provide an empty close
+ method. So, invoke the parser as follows:
+ </p>
+ <source>Socket socket;
-<source>
-
- Socket socket;
-
// code to set the socket
parser.parse(new InputSource(new MyBufferedReader(new InputStreamReader(socket.getInputStream()))));
@@ -368,8 +362,8 @@
public void close() {
}
- }
-</source>
-
-</a></faq>
+ }</source>
+ </a>
+ </faq>
+ -->
</faqs>
1.8.2.2 +286 -262 xml-xerces/java/docs/features.xml
Index: features.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/features.xml,v
retrieving revision 1.8.2.1
retrieving revision 1.8.2.2
diff -u -r1.8.2.1 -r1.8.2.2
--- features.xml 2000/12/12 19:07:11 1.8.2.1
+++ features.xml 2001/07/19 06:43:10 1.8.2.2
@@ -1,265 +1,289 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
-
-<s1 title="Features">
- <s2 title="Setting Features">
- <anchor name="features"/>
- <p>To set a feature on either org.apache.xerces.parsers.SAXParser or
- org.apache.xerces.parsers.DOMParser, you should use the SAX2
- method <code>setFeature(String,boolean)</code>. To query a
- feature, use the SAX2 method <code>getFeature(String)</code>.</p>
- <p>For example, to turn on validation:</p>
-<source>SAXParser p=new SAXParser();
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE features SYSTEM 'dtd/settings.dtd'>
+<features>
+ <desc name='Setting Features'>
+ <p>
+ If you have created a DOM document builder or a SAX parser using
+ the JAXP interfaces, you may have difficulty setting features and
+ properties directly using those interfaces. The following
+ instructions tell you how to set features on document builders
+ and SAX parsers created from the JAXP interfaces.
+ </p>
+ <p>
+ The DocumentBuilderFactory interface contains a
+ <code>setAttribute(String,Object)</code> method which <em>may</em>
+ provide a means to set features and properties on the underyling
+ parser. However, it cannot be relied upon. Therefore, you must
+ use the Xerces DOMParser object directly. For example:
+ </p>
+ <source>import org.apache.xerces.parsers.DOMParser;
+import org.xml.sax.SAXException;
+
+DOMParser parser = new DOMParser();
try {
- p.setFeature("http://xml.org/sax/features/validation", true);
-} catch (SAXException e) {
- System.out.println("error in setting up parser feature");
+ parser.setFeature("http://xml.org/sax/features/allow-java-encodings",
+ true);
+}
+catch (SAXException e) {
+ System.err.println("could not set parser feature");
}</source>
- </s2>
-
- <s2 title="General Features">
- <anchor name="validation"/>
- <p>http://xml.org/sax/features/validation</p>
- <table>
- <tr><th>True:</th> <td>Validate the document.</td></tr>
- <tr><th>False:</th> <td>Do not validate the document.</td></tr>
- <tr><th>Default:</th> <td>false</td></tr>
- <tr><th>Access:</th> <td>(parsing) read-only; (not parsing) read/write</td></tr>
- <tr><th>Note:</th> <td>If this feature is set to true, the document must specify a grammar.
- If this feature is set to false, the document may specify a grammar
- and that grammar will be parsed but no validation of the document
- contents will be performed.</td></tr>
- <tr><th>See:</th> <td><link anchor="dynamic">http://apache.org/xml/features/validation/dynamic</link>
- <br/><link anchor="namespaces">http://xml.org/sax/features/namespaces</link></td></tr>
- </table>
-
- <anchor name="external-general-entities"/>
- <p>http://xml.org/sax/features/external-general-entities</p>
- <table>
- <tr><th>True:</th> <td>Include external general (text) entities.</td></tr>
- <tr><th>False:</th> <td>Do not include external general entities.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Access:</th> <td>(parsing) read-only; (not parsing) read/write</td></tr>
- <tr><th>See:</th>
- <td><link anchor="external-parameter-entities">http://xml.org/sax/features/external-parameter-entities</link></td></tr>
- </table>
-
- <anchor name="external-parameter-entities"/>
- <p>http://xml.org/sax/features/external-parameter-entities</p>
- <table>
- <tr><th>True:</th> <td>Include external parameter entities and the external DTD subset.</td></tr>
- <tr><th>False:</th> <td>Do not include external parameter entities or the external DTD subset.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Access:</th> <td>(parsing) read-only; (not parsing) read/write</td></tr>
- <tr><th>See:</th>
- <td><link anchor="external-parameter-entities">http://xml.org/sax/features/external-parameter-entities</link></td></tr>
- </table>
-
- <anchor name="namespaces"/>
- <p>http://xml.org/sax/features/namespaces</p>
- <table>
- <tr><th>True:</th> <td>Perform namespace processing: prefixes will be stripped off element and
- attribute names and replaced with the corresponding namespace URIs. By
- default, the two will simply be concatenated, but the namespace-sep core
- property allows the application to specify a delimiter string for
- separating the URI part and the local part.</td></tr>
- <tr><th>False:</th> <td>Do not perform namespace processing.</td></tr>
- <tr><th>Default:</th> <td>false</td></tr>
- <tr><th>Access:</th> <td>(parsing) read-only; (not parsing) read/write</td></tr>
- <tr><th>Note:</th> <td>If the validation feature is set to true, then the document must contain
- a grammar that supports the use of namespaces.</td></tr>
- <tr><th>See:</th> <td><link anchor="validation">http://xml.org/sax/features/validation</link>
- <br/><link idref="properties" anchor="namespace-sep">http://xml.org/sax/properties/namespace-sep</link></td></tr>
- </table>
-
-<!--
- <anchor name="schema"/>
- <p>http://apache.org/xml/features/validation/schema</p>
- <table>
- <tr><th>True:</th> <td>Turn on XML Schema support.</td></tr>
- <tr><th>False:</th> <td>Turn off XML Schema support.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- </table>
--->
- <anchor name="dynamic"/>
- <p>http://apache.org/xml/features/validation/dynamic</p>
- <table>
- <tr><th>True:</th> <td>The parser will validate the document only if a grammar is specified.</td></tr>
- <tr><th>False:</th> <td>Validation is determined by the state of the
- <link anchor="validation">http://xml.org/sax/features/validation</link> feature.</td></tr>
- <tr><th>Default:</th> <td>false</td></tr>
- <tr><th>See:</th> <td><link anchor="validation">http://xml.org/sax/features/validation</link></td></tr>
- </table>
-
- <anchor name="warn-on-duplicate-attdef"/>
- <p>http://apache.org/xml/features/validation/warn-on-duplicate-attdef</p>
- <table>
- <tr><th>True:</th><td>Warn on duplicate attribute declaration.</td></tr>
- <tr><th>False:</th><td>Do not warn on duplicate attribute declaration.</td></tr>
- <tr><th>Default:</th><td>true</td></tr>
- </table>
-
- <anchor name="warn-on-undeclared-elemdef"/>
- <p>http://apache.org/xml/features/validation/warn-on-undeclared-elemdef</p>
- <table>
- <tr><th>True:</th> <td>Warn if element referenced in content model is not declared.</td></tr>
- <tr><th>False:</th> <td>Do not warn if element referenced in content model is not declared.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- </table>
-
- <anchor name="allow-java-encodings"/>
- <p>http://apache.org/xml/features/allow-java-encodings</p>
- <table>
- <tr><th>True:</th> <td>Allow Java encoding names in XMLDecl and TextDecl line.</td></tr>
- <tr><th>False:</th> <td>Do not allow Java encoding names in XMLDecl and TextDecl line.</td></tr>
- <tr><th>Default:</th> <td>false</td></tr>
- <tr><th>Note:</th> <td>A true value for this feature allows the encoding of the file to be
- specified as a Java encoding name as well as the standard ISO encoding
- name. Be aware that other parsers may not be able to use Java encoding
- names. If this feature is set to false, an error will be generated if
- Java encoding names are used.</td></tr>
- </table>
-
- <anchor name="continue-after-fatal-error"/>
- <p>http://apache.org/xml/features/continue-after-fatal-error</p>
- <table>
- <tr><th>True:</th><td>Continue after fatal error.</td></tr>
- <tr><th>False:</th><td>Stops parse on first fatal error.</td></tr>
- <tr><th>Default:</th><td>false</td></tr>
- </table>
-
- <anchor name="load-dtd-grammar"/>
- <p>http://apache.org/xml/features/nonvalidating/load-dtd-grammar</p>
- <table>
- <tr><th>True:</th><td>Load the DTD and use it to
- add default attributes and set
-attribute types when parsing.</td></tr>
- <tr><th>False:</th><td>Build the grammar but do not use
-the default attributes and attribute types information it contains.</td></tr>
- <tr><th>Default:</th><td>true</td></tr>
- <tr><th>Note:</th> <td>This feature is always on when
-validation is on.</td></tr>
- </table>
-
- <anchor name="load-external-dtd"/>
- <p>http://apache.org/xml/features/nonvalidating/load-external-dtd</p>
- <table>
- <tr><th>True:</th><td>Load the external DTD.</td></tr>
- <tr><th>False:</th><td>Ignore the external DTD completely.</td></tr>
- <tr><th>Default:</th><td>true</td></tr>
- <tr><th>Note:</th> <td>This feature is
-always on when validation is on.</td></tr>
- </table>
- </s2>
- <s2 title="DOM Features">
- <anchor name="defer-node-expansion"/>
- <p>http://apache.org/xml/features/dom/defer-node-expansion</p>
- <table>
- <tr><th>True:</th> <td>Lazy DOM node expansion.</td></tr>
- <tr><th>False:</th> <td>Full DOM node expansion.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Note:</th> <td>This feature only applies when the
- <link idref="properties" anchor="document-class-name">http://apache.org/xml/properties/dom/document-class-name</link> property is
- set to a value other than the name of the default document factory.
- If this feature is set to true, the DOM nodes in the returned
- document are expanded as the tree is traversed. This feature 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.</td></tr>
- <tr><th>See</th> <td><link idref="properties" anchor="document-class-name">http://apache.org/xml/properties/dom/document-class-name</link></td></tr>
- </table>
-
- <anchor name="create-entity-ref-nodes"/>
- <p>http://apache.org/xml/features/dom/create-entity-ref-nodes</p>
- <table>
- <tr><th>True:</th> <td>Create EntityReference nodes in the DOM tree. The EntityReference nodes and their child nodes will be read-only.</td></tr>
- <tr><th>False:</th> <td>Do not create EntityReference nodes in the DOM tree. No EntityReference nodes will be created, only the nodes corresponding to their fully expanded sustitution text will be created.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Note:</th> <td>This feature only affects the appearance of EntityReference nodes in
- the DOM tree. The document will always contain the entity reference
- child nodes.</td></tr>
- </table>
-
- <anchor name="include-ignorable-whitespace"/>
- <p>http://apache.org/xml/features/dom/include-ignorable-whitespace</p>
- <table>
- <tr><th>True:</th> <td>Includes text nodes that can be
- considered "ignorable whitespace" in the DOM tree.</td></tr>
- <tr><th>False:</th> <td>Does not include ignorable whitespace in the DOM tree.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Note:</th> <td>The only way that the parser can determine if text is ignorable is
- by reading the associated grammar and having a content model for
- the document. When ignorable whitespace text nodes are included in
- the DOM tree, they will be flagged as ignorable. The ignorable flag
- can be queried by calling the TextImpl#isIgnorableWhitespace():boolean
- method.</td></tr>
- </table>
-
- <anchor name="grammar-access"/>
- <p>http://apache.org/xml/features/domx/grammar-access</p>
- <table>
- <tr><th>True:</th> <td>Creates nodes that describe the grammar in the DOM tree.</td></tr>
- <tr><th>False:</th> <td>Does not create create grammar access nodes in the DOM
- tree. This setting makes the DOM behave as a standard
- DOM Level 1 implementation.</td></tr>
- <tr><th>Default:</th> <td>false</td></tr>
- <tr><th>Note:</th> <td>The grammar access nodes are appended as children of the
- DocumentType node. The grammar is specified as an
- XML Schema document tree, whether it was read from a
- document with an associated DTD or XML Schema grammar.
- This is currently a violation of the DOM Level 1
- specification.
- <br/><em>**** This is an experimental feature that is not guaranteed </em>
- <br/><em>**** to be supported in future versions of
- the parser.</em></td></tr>
- </table>
- </s2>
- <s2 title="SAX Features">
- <!--
- <anchor name="use-locator"/>
- <p>http://xml.org/sax/features/use-locator</p>
- <table>
- <tr><th>True:</th> <td>Provide a Locator using the DocumentHandler setDocumentLocator callback.</td></tr>
- <tr><th>False:</th> <td>Explicitly allow the parser not to provide a Locator (but it still may).</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Note:</th> <td>Xerces-J always provides a Locator to the document handler</td></tr>
- </table>
-
- <anchor name="normalize-text"/>
- <p>http://xml.org/sax/features/normalize-text</p>
- <table>
- <tr><th>True:</th> <td>Ensure that all consecutive text is returned
- in a single callback to the DocumentHandler
- characters method.</td></tr>
- <tr><th>False:</th> <td>Explicitly allow the parser to split
- consecutive text into more than one callback
- (but it still may not do so).</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Note:</th> <td>Xerces-J currently does not support allowing
- consecutive text to be buffered and returned
- in a single callback to the DocumentHandler
- characters method.</td></tr>
- </table>
- -->
- <anchor name='namespace-prefixes'/>
- <p>http://xml.org/sax/features/namespace-prefixes</p>
- <table>
- <tr><th>True:</th> <td>Report the original prefixed names and attributes used for Namespace declarations.</td></tr>
- <tr><th>False:</th> <td>Do not report attributes used for Namespace declarations, and optionally do not report original prefixed names.</td></tr>
- <tr><th>Default:</th> <td>true</td></tr>
- <tr><th>Access:</th> <td>(parsing) read-only; (not parsing) read/write</td></tr>
- </table>
- <anchor name='string-interning'/>
- <p>http://xml.org/sax/features/string-interning</p>
- <table>
- <tr><th>True:</th> <td>All element names, prefixes, attribute names, Namespace URIs, and local names are internalized using java.lang.String.intern.</td></tr>
- <tr><th>False:</th> <td>Names are not necessarily internalized.</td></tr>
- <tr><th>Default:</th> <td>false</td></tr>
- <tr><th>Access:</th> <td>(parsing) read-only; (not parsing) read/write</td></tr>
- <tr><th>Note:</th> <td>Xerces-J does not support interning all strings using the
- String.intern() method because Xerces-J does its own intern
- optimizations for String objects.</td></tr>
- </table>
- </s2>
-</s1>
+ <p>
+ Using the SAXParser interface in JAXP is better because you can
+ query the underlying XMLReader implementation directly and that
+ interface contains methods to set and query features and
+ properties. For example:
+ </p>
+ <source>import javax.xml.parsers.SAXParser;
+import org.xml.sax.SAXException;
+import org.xml.sax.XMLReader;
+SAXParser parser = /* created from SAXParserFactory */;
+XMLReader reader = parser.getXMLReader();
+try {
+ reader.setFeature("http://xml.org/sax/features/allow-java-encodings",
+ true);
+}
+catch (SAXException e) {
+ System.err.println("could not set parser feature");
+}</source>
+ </desc>
+ <fcategory name='General Features'>
+ <feature name='http://xml.org/sax/features/namespaces'
+ id='namespaces'>
+ <true>
+ Perform namespace processing: prefixes will be stripped off
+ element and attribute names and replaced with the corresponding
+ namespace URIs. By default, the two will simply be concatenated,
+ but the namespace-sep core property allows the application to
+ specify a delimiter string for separating the URI part and the
+ local part.
+ </true>
+ <false>Do not perform namespace processing.</false>
+ <default value='true'/>
+ <access parsing='read-only' not-parsing='read-write'/>
+ <note>
+ If the validation feature is set to true, then the document
+ must contain a grammar that supports the use of namespaces.
+ </note>
+ <see idref='namespace-prefixes'/>
+ <see idref='validation'/>
+ </feature>
+ <feature name='http://xml.org/sax/features/validation'
+ id='validation'>
+ <true>Validate the document.</true>
+ <false>Do not validate the document.</false>
+ <default value='false'/>
+ <access parsing='read-only' not-parsing='read-write'/>
+ <note>
+ If this feature is set to true, the document must specify
+ a grammar. If this feature is set to false, the document
+ may specify a grammar and that grammar will be parsed but
+ no validation of the document contents will be performed.
+ </note>
+ <see idref='validation.dynamic'/>
+ <see idref='namespaces'/>
+ </feature>
+ <feature name='http://apache.org/xml/features/validation/dynamic'
+ id='validation.dynamic'>
+ <true>
+ The parser will validate the document only if a grammar is
+ specified.
+ </true>
+ <false>
+ Validation is determined by the state of the <ref>validation</ref>
+ feature.
+ </false>
+ <default value='false'/>
+ <see idref='validation'/>
+ </feature>
+ <!--
+ - REVISIT: Add these features back in once we have Schema
+ - support in this version.
+ -
+ <feature name='http://apache.org/xml/features/validation/schema'
+ id='validation.schema'>
+ <true>Turn on XML Schema support.</true>
+ <false>Turn off XML Schema support.</false>
+ <default value='true'/>
+ </feature>
+ <feature name='http://apache.org/xml/features/validation/schema-full-checking'
+ id='validation.schema-full-checking'>
+ <true>
+ Enable full schema grammar constraint checking, including checking
+ which may be time-consuming or memory intensive. Currently, particle
+ unique attribution constraint checking and particle derivation
+ resriction checking are controlled by this option.
+ </true>
+ <false>Disable full constraint checking.</false>
+ <default value='false'/>
+ <note>
+ This feature checks the Schema grammar itself for additional
+ errors that are time-consuming or memory intensive. It does
+ <strong>not</strong> affect the level of checking performed on
+ document instances that use Schema grammars.
+ </note>
+ </feature>
+ -->
+ <feature name='http://xml.org/sax/features/external-general-entities'
+ id='external-general-entities'>
+ <true>Include external general entities.</true>
+ <false>Do not include external general entities.</false>
+ <default value='true'/>
+ <access parsing='read-only' not-parsing='read-write'/>
+ <see idref='external-parameter-entities'/>
+ </feature>
+ <feature name='http://xml.org/sax/features/external-parameter-entities'
+ id='external-parameter-entities'>
+ <true>
+ Include external parameter entities and the external DTD subset.
+ </true>
+ <false>
+ Do not include external parameter entities or the external DTD subset.
+ </false>
+ <default value='true'/>
+ <access parsing='read-only' not-parsing='read-write'/>
+ <see idref='external-general-entities'/>
+ </feature>
+ <feature name='http://apache.org/xml/features/validation/warn-on-duplicate-attdef'
+ id='validation.warn-on-duplicate-attdef'>
+ <true>Report a warning when a duplicate attribute is re-declared.</true>
+ <false>
+ Do not report a warning when a duplicate attribute is re-declared.
+ </false>
+ <default value='true'/>
+ </feature>
+ <feature name='http://apache.org/xml/features/validation/warn-on-undeclared-elemdef'
+ id='validation.warn-on-undeclared-elemdef'>
+ <true>
+ Report a warning if an element referenced in a content model is
+ not declared.
+ </true>
+ <false>
+ Do not report a warning if an element referenced in a content model
+ is not declared.
+ </false>
+ <default value='true'/>
+ </feature>
+ <feature name='http://apache.org/xml/features/allow-java-encodings'
+ id='allow-java-encodings'>
+ <true>Allow Java encoding names in XMLDecl and TextDecl line.</true>
+ <false>
+ Do not allow Java encoding names in XMLDecl and TextDecl line.
+ </false>
+ <default value='false'/>
+ <note>
+ A true value for this feature allows the encoding of the file to
+ be specified as a Java encoding name as well as the standard ISO
+ encoding name. Be aware that other parsers may not be able to use
+ Java encoding names. If this feature is set to false, an error
+ will be generated if Java encoding names are used.
+ </note>
+ </feature>
+ <feature name='http://apache.org/xml/features/continue-after-fatal-error'
+ id='continue-after-fatal-error'>
+ <true>Attempt to continue parsing after a fatal error.</true>
+ <false>Stops parse on first fatal error.</false>
+ <default value='false'/>
+ <note>
+ The behavior of the parser when this feature is set to
+ <code>true</code> is <strong>undetermined</strong>! Therefore use
+ this feature with extreme caution because the parser may get stuck
+ in an infinite loop or worse.
+ </note>
+ </feature>
+ <feature name='http://apache.org/xml/features/nonvalidating/load-dtd-grammar'
+ id='nonvalidating.load-dtd-grammar'>
+ <true>
+ Load the DTD and use it to add default attributes and set attribute
+ types when parsing.
+ </true>
+ <false>
+ Build the grammar but do not use the default attributes and attribute
+ types information it contains.
+ </false>
+ <default value='true'/>
+ <note>This feature is always on when validation is on.</note>
+ <see idref='validation'/>
+ <see idref='nonvalidating.load-external-dtd'/>
+ </feature>
+ <feature name='http://apache.org/xml/features/nonvalidating/load-external-dtd'
+ id='nonvalidating.load-external-dtd'>
+ <true>Load the external DTD.</true>
+ <false>Ignore the external DTD completely.</false>
+ <default value='true'/>
+ <note>This feature is always on when validation is on.</note>
+ <see idref='validation'/>
+ <see idref='nonvalidating.load-dtd-grammar'/>
+ </feature>
+ </fcategory>
+ <fcategory name='DOM Features'>
+ <feature name='http://apache.org/xml/features/dom/create-entity-ref-nodes'
+ id='dom.create-entity-ref-nodes'>
+ <true>
+ Create <code>EntityReference</code> nodes in the DOM tree. The
+ <code>EntityReference</code> nodes and their child nodes will be
+ read-only.
+ </true>
+ <false>
+ Do not create <code>EntityReference</code> nodes in the DOM tree.
+ No <code>EntityReference</code> nodes will be created, only the
+ nodes corresponding to their fully expanded sustitution text will
+ be created.
+ </false>
+ <default value='true'/>
+ <note>
+ This feature only affects the appearance of <code>EntityReference</code>
+ nodes in the DOM tree. The document will always contain the entity
+ reference child nodes.
+ </note>
+ </feature>
+ <feature name='http://apache.org/xml/features/dom/include-ignorable-whitespace'
+ id='dom.include-ignorable-whitespace'>
+ <true>
+ Includes text nodes that can be considered "ignorable whitespace" in
+ the DOM tree.
+ </true>
+ <false>Does not include ignorable whitespace in the DOM tree.</false>
+ <default value='true'/>
+ <note>
+ The only way that the parser can determine if text is ignorable
+ is by reading the associated grammar and having a content model for
+ the document. When ignorable whitespace text nodes are included in
+ the DOM tree, they will be flagged as ignorable. The ignorable flag
+ can be queried by calling the
+ <code>TextImpl#isIgnorableWhitespace():boolean</code> method.
+ </note>
+ </feature>
+ </fcategory>
+ <fcategory name='SAX Features'>
+ <feature name='http://xml.org/sax/features/namespace-prefixes'
+ id='namespace-prefixes'>
+ <true>
+ Report the original prefixed names and attributes used for namespace
+ declarations.
+ </true>
+ <false>
+ Do not report attributes used for Namespace declarations, and
+ optionally do not report original prefixed names.
+ </false>
+ <default value='true'/>
+ <access parsing='read-only' not-parsing='read-write'/>
+ </feature>
+ <feature name='http://xml.org/sax/features/string-interning'
+ id='string-interning'>
+ <true>
+ All element names, prefixes, attribute names, namespace URIs, and
+ local names are internalized using the
+ <code>java.lang.String#intern(String):String</code> method.
+ </true>
+ <false>Names are not necessarily internalized.</false>
+ <default value='false'/>
+ <access parsing='read-only' not-parsing='read-write'/>
+ <note>
+ Xerces-J does not support interning all strings using the
+ <code>String#intern()</code> method because Xerces-J does its own
+ intern optimizations for String objects.
+ </note>
+ </feature>
+ </fcategory>
+</features>
1.9.2.1 +118 -42 xml-xerces/java/docs/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/install.xml,v
retrieving revision 1.9
retrieving revision 1.9.2.1
diff -u -r1.9 -r1.9.2.1
--- install.xml 2000/05/23 20:28:58 1.9
+++ install.xml 2001/07/19 06:43:10 1.9.2.1
@@ -1,43 +1,119 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
-
-<s1 title="Installation">
- <s2 title="Unpacking the files">
- <p>&javaparsername; is packaged as a ZIP file for all
- platforms and operating systems. You can run the Java
- <ref>jar</ref> command to unpack the distribution.</p>
- <ul>
- <li>jar xf &javaparsername;-bin.&javaparserversion;.zip</li>
- <li>jar xf &javaparsername;-src.&javaparserversion;.zip</li>
- <li>This command creates a "&javaparserdirectory;" sub-directory in the current directory containing all the files.</li>
- </ul>
- </s2>
- <s2 title="Files in the binary package release">
- <table>
- <tr><td>LICENSE</td><td>License for &javaparsername;</td></tr>
- <!--<tr><td>README</td><td>Build instructions</td></tr>-->
- <tr><td>Readme.html</td><td>Web page redirect to docs/html/index.html</td></tr>
- <!--<tr><td>STATUS</td><td>Project status list</td></tr>-->
- <tr><td>xerces.jar</td><td>Jar file containing all the parser class files</td></tr>
- <tr><td>xercesSamples.jar</td><td>Jar file containing all sample class files</td></tr>
- <tr><td>data/</td><td>Directory containing sample XML data files</td></tr>
- <tr><td>docs/html/</td><td>Directory containing documentation</td></tr>
- <tr><td>docs/apiDocs/</td><td>Directory containing Javadoc API for parser framework</td></tr>
- </table>
- <note>To use &javaparsername; you do not need the source files.
- </note>
- </s2>
- <s2 title="Files in the source package release">
- <table>
- <tr><td>LICENSE</td><td>License for &javaparsername;</td></tr>
- <tr><td>Makefile</td><td>Top level Makefile -- read README file before building</td></tr>
- <tr><td>README</td><td>Build instructions</td></tr>
- <tr><td>Readme.html</td><td>Web page redirect required for building documentation</td></tr>
- <tr><td>STATUS</td><td>Current source code status information</td></tr>
- <tr><td>data/</td><td>Directory containing sample XML data files</td></tr>
- <tr><td>docs/</td><td>Directory containing documentation, in XML form</td></tr>
- <tr><td>samples/</td><td>Directory containing source code for samples</td></tr>
- <tr><td>src/</td><td>Directory containing source code for parser and supplemental APIs</td></tr>
- </table>
- </s2>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
+<s1 title='Installation'>
+ <s2 title='Unpacking the Files'>
+ <p>
+ &javaparsername; is packaged as a ZIP file for all platforms
+ and operating systems. The parser release is also packaged
+ as Tar GZip files as a convenience for UNIX users. You can
+ extract the ZIP files using the Java <ref>jar</ref> command
+ to unpack the distribution.
+ </p>
+ <source>jar xf &javaparsername;-bin.&javaparserversion;.zip
+jar xf &javaparsername;-src.&javaparserversion;.zip
+jar xf &javaparsername;-tools.&javaparserversion;.zip</source>
+ <p>
+ All of these commands creates a sub-directory called
+ "&javaparserdirectory;" in the current directory.
+ </p>
+ </s2>
+ <s2 title='Files in the Binary Package'>
+ <table>
+ <tr>
+ <td>LICENSE</td>
+ <td>License for &javaparsername;</td>
+ </tr>
+ <tr>
+ <td>Readme.html</td>
+ <td>Web page redirect to docs/html/index.html</td>
+ </tr>
+ <tr>
+ <td>xerces.jar</td>
+ <td>Jar file containing all the parser class files</td>
+ </tr>
+ <tr>
+ <td>xercesSamples.jar</td>
+ <td>Jar file containing all sample class files</td>
+ </tr>
+ <tr>
+ <td>data/</td>
+ <td>Directory containing sample XML data files</td>
+ </tr>
+ <tr>
+ <td>docs/html/</td>
+ <td>Directory containing documentation</td>
+ </tr>
+ <tr>
+ <td>docs/apiDocs/</td>
+ <td>Directory containing Javadoc API for parser framework</td>
+ </tr>
+ <tr>
+ <td>samples/</td>
+ <td>Directory containing the source code for the samples</td>
+ </tr>
+ </table>
+ <note>
+ To use &javaparsername; you do not need the source files.
+ However, if you want to recompile the sources you need to
+ download the source package.
+ </note>
+ </s2>
+ <s2 title='Files in the Source Package'>
+ <table>
+ <tr>
+ <td>LICENSE</td>
+ <td>License for &javaparsername;</td>
+ </tr>
+ <tr>
+ <td>build.bat</td>
+ <td>Batch file for invoking Ant build for Windows users</td>
+ </tr>
+ <tr>
+ <td>build</td>
+ <td>Shell script for invoking Ant build for UNIX users</td>
+ </tr>
+ <tr>
+ <td>build.xml</td>
+ <td>Ant build file -- read README file before building</td>
+ </tr>
+ <tr>
+ <td>README</td>
+ <td>Build instructions</td>
+ </tr>
+ <tr>
+ <td>Readme.html</td>
+ <td>Web page redirect required for building documentation</td>
+ </tr>
+ <tr>
+ <td>STATUS</td>
+ <td>Current source code status information</td>
+ </tr>
+ <tr>
+ <td>data/</td>
+ <td>Directory containing sample XML data files</td>
+ </tr>
+ <tr>
+ <td>docs/</td>
+ <td>Directory containing documentation, in XML form</td>
+ </tr>
+ <tr>
+ <td>samples/</td>
+ <td>Directory containing source code for samples</td>
+ </tr>
+ <tr>
+ <td>src/</td>
+ <td>
+ Directory containing source code for parser and supplemental
+ APIs
+ </td>
+ </tr>
+ </table>
+ <note>
+ In order to compile the source code using Ant or build the
+ release packages, you must download the
+ <code>&javaparsername;-tools.&javaparserversion;.zip</code>
+ package and extract it in the same directory where you
+ extracted the source package.
+ </note>
+ </s2>
</s1>
1.5.2.1 +168 -129 xml-xerces/java/docs/properties.xml
Index: properties.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/properties.xml,v
retrieving revision 1.5
retrieving revision 1.5.2.1
diff -u -r1.5 -r1.5.2.1
--- properties.xml 2000/05/23 20:28:59 1.5
+++ properties.xml 2001/07/19 06:43:10 1.5.2.1
@@ -1,132 +1,171 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE properties SYSTEM 'dtd/settings.dtd'>
+<properties>
+ <desc name='Setting Properties'>
+ <p>
+ If you have created a DOM document builder or a SAX parser using
+ the JAXP interfaces, you may have difficulty setting features and
+ properties directly using those interfaces. The following
+ instructions tell you how to set properties on document builders
+ and SAX parsers created from the JAXP interfaces.
+ </p>
+ <p>
+ The DocumentBuilderFactory interface contains a
+ <code>setAttribute(String,Object)</code> method which <em>may</em>
+ provide a means to set features and properties on the underyling
+ parser. However, it cannot be relied upon. Therefore, you must
+ use the Xerces DOMParser object directly. For example:
+ </p>
+ <source>import org.apache.xerces.parsers.DOMParser;
+import org.xml.sax.SAXException;
+
+DOMParser parser = new DOMParser();
-<s1 title="Properties">
- <s2 title="Setting Features">
- <anchor name="properties"/>
- <p>To set a property on either org.apache.xerces.parsers.SAXParser
- or org.apache.xerces.parsers.DOMParser, you should use the SAX2
- method <code>setProperty(String,Object)</code>. To query a
- property, use the SAX2 method <code>getProperty(String)</code>.</p>
- <p>For example, to set the document factory by name:</p>
-<source>DOMParser p=new DOMParser();
-try {
- p.setProperty("http://apache.org/xml/properties/dom/document-class-name",
- "org.apache.xerces.dom.DocumentImpl");
-} catch (SAXException e) {
- System.out.println("error in setting up parser property");
+String id = "http://apache.org/xml/properties/dom/document-class-name";
+Object value = "org.apache.xerces.dom.DocumentImpl";
+try {
+ parser.setProperty(id, value);
+}
+catch (SAXException e) {
+ System.err.println("could not set parser feature");
}</source>
- </s2>
-
- <s2 title="General Properties">
- <!--
- <anchor name="namespace-sep"/>
- <p>http://xml.org/sax/properties/namespace-sep</p>
- <table>
- <tr><th>Type:</th> <td>java.lang.String</td></tr>
- <tr><th>Access:</th> <td>read-write</td></tr>
- <tr><th>Desc:</th> <td>The separator string that will appear between the namespace
- URI and the local part of the name when namespace processing is being
- performed. If the value is the empty string, the two parts will be
- concatenated. </td></tr>
- <tr><th> Default: </th> <td>""</td></tr>
- <tr><th>See:</th> <td><link idref="features" anchor="namespaces">http://xml.org/sax/features/namespaces</link></td></tr>
- </table>
- -->
-
- <anchor name="xml-string"/>
- <p>http://xml.org/sax/properties/xml-string</p>
- <table>
- <tr><th>Type:</th> <td>java.lang.String</td></tr>
- <tr><th>Access:</th> <td>read-only</td></tr>
- <tr><th>Desc:</th> <td>Get the string of characters associated with the current event. If the
- parser recognizes and supports this property but is not currently
- parsing text, it should return null.</td></tr>
- <tr><th>Note:</th> <td>This property is currently not supported because the contents of the
- XML string returned by this property is not well defined.</td></tr>
- </table>
- </s2>
-
- <s2 title="DOM Parser Properties">
- <anchor name="current-element-node"/>
- <p>http://apache.org/xml/properties/dom/current-element-node</p>
- <table>
- <tr><th>Type:</th> <td>org.w3c.dom.Node</td></tr>
- <tr><th>Access:</th> <td>read-only</td></tr>
- <tr><th>Desc:</th> <td>The current DOM element node while parsing.</td></tr>
- <tr><th>Note:</th> <td>This property is useful for determining the location
- with a DOM document when an error occurs.</td></tr>
- <tr><th>See:</th> <td><link anchor="dom-node">http://xml.org/sax/properties/dom-node</link></td></tr>
- </table>
-
- <anchor name="document-class-name"/>
- <p>http://apache.org/xml/properties/dom/document-class-name</p>
- <table>
- <tr><th>Type:</th> <td>java.lang.String</td></tr>
- <tr><th>Access:</th> <td>read-write</td></tr>
- <tr><th>Desc:</th> <td>The fully qualified class name of the DOM
- implementation. The implementation used must
- have a zero argument constructor.</td></tr>
- <tr><th>Default:</th> <td>"org.apache.xerces.dom.DocumentImpl"</td></tr>
- <tr><th>Note:</th> <td>When the document class name is set to a value other
- than the name of the default document factory, the
- deferred node expansion feature does not work. </td></tr>
- <tr><th>See:</th> <td><link idref="features" anchor="defer-node-expansion">http://apache.org/xml/features/dom/defer-node-expansion</link></td></tr>
- </table>
- </s2>
-
- <s2 title="SAX Parser Properties">
- <!--
- <anchor name="DeclHandler"/>
- <p>http://xml.org/sax/handlers/DeclHandler</p>
- <table>
- <tr><th>Type:</th> <td>org.xml.sax.misc.DeclHandler</td></tr>
- <tr><th>Access:</th> <td>read-write</td></tr>
- <tr><th>Desc:</th> <td>Set the handler for DTD declarations.</td></tr>
- </table>
-
- <anchor name="LexicalHandler"/>
- <p>http://xml.org/sax/handlers/LexicalHandler</p>
- <table>
- <tr><th>Type:</th> <td>org.xml.sax.misc.LexicalHandler</td></tr>
- <tr><th>Access:</th> <td>read-write</td></tr>
- <tr><th>Desc:</th> <td>Set the handler for lexical parsing events.</td></tr>
- </table>
-
- <anchor name="NamespaceHandler"/>
- <p>http://xml.org/sax/handlers/NamespaceHandler</p>
- <table>
- <tr><th>Type:</th> <td>org.xml.sax.misc.NamespaceHandler</td></tr>
- <tr><th>Access:</th> <td>read-write</td></tr>
- <tr><th>Desc:</th> <td>Set the handler for lexical parsing events.</td></tr>
- </table>
- -->
- <anchor name="declaration-handler"/>
- <p>http://xml.org/sax/properties/declaration-handler</p>
- <table>
- <tr><th>Type:</th> <td>org.xml.sax.ext.DeclHandler</td></tr>
- <tr><th>Access:</th> <td>read-write</td></tr>
- <tr><th>Desc:</th> <td>Set the handler for DTD declarations.</td></tr>
- </table>
-
- <anchor name="lexical-handler"/>
- <p>http://xml.org/sax/properties/lexical-handler</p>
- <table>
- <tr><th>Type:</th> <td>org.xml.sax.ext.LexicalHandler</td></tr>
- <tr><th>Access:</th> <td>read-write</td></tr>
- <tr><th>Desc:</th> <td>Set the handler for lexical parsing events.</td></tr>
- </table>
+ <p>
+ Using the SAXParser interface in JAXP is better because you can
+ query the underlying XMLReader implementation directly and that
+ interface contains methods to set and query features and
+ properties. For example:
+ </p>
+ <source>import javax.xml.parsers.SAXParser;
+import org.xml.sax.SAXException;
+import org.xml.sax.XMLReader;
- <anchor name="dom-node"/>
- <p>http://xml.org/sax/properties/dom-node</p>
- <table>
- <tr><th>Type:</th> <td>org.w3c.dom.Node</td></tr>
- <tr><th>Access:</th> <td>(parsing) read-only; (not parsing) read/write</td></tr>
- <tr><th>Desc:</th> <td>The DOM node currently being visited,
- if SAX is being used as a DOM iterator.
- If the parser recognizes and supports this property but is
- not currently visiting a DOM node, it should return null.</td></tr>
- </table>
-
- </s2>
-</s1>
+SAXParser parser = /* created from SAXParserFactory */;
+XMLReader reader = parser.getXMLReader();
+
+String id = "http://apache.org/xml/properties/dom/document-class-name";
+Object value = "org.apache.xerces.dom.DocumentImpl";
+try {
+ reader.setProperty(id, value);
+}
+catch (SAXException e) {
+ System.err.println("could not set parser feature");
+}</source>
+ </desc>
+ <pcategory name='General Properties'>
+ <property name='http://xml.org/sax/properties/xml-string'
+ id='xml-string'>
+ <desc>
+ Get the string of characters associated with the current event.
+ If the parser recognizes and supports this property but is not
+ currently parsing text, it should return null.
+ </desc>
+ <type>java.lang.String</type>
+ <access general='read-only'/>
+ <note>
+ This property is currently not supported because the contents of
+ the XML string returned by this property is not well defined.
+ </note>
+ </property>
+ <!--
+ - REVISIT: Reconsider adding these properties once parser has
+ - Schema support.
+ -
+ <property name='http://apache.org/xml/properties/schema/external-schemaLocation'
+ id='schema.external-schemaLocation'>
+ <desc>
+ The XML Schema Recommendation explicitly states that the inclusion
+ of schemaLocation/ noNamespaceSchemaLocation attributes is only a
+ hint; it does not mandate that these attributes must be used to
+ locate schemas. This property allows the user to specify a list of
+ schemas to use. If the targetNamespace of a schema (specified
+ using this property) matches the targetNamespace of a schema
+ occuring in the instance document in schemaLocation attribute, the
+ schema specified by the user using this property will be used
+ (i.e., the instance document's schemaLocation attribute will be
+ effectively ignored).
+ </desc>
+ <type>java.lang.String</type>
+ <access general='read-write'/>
+ <note>
+ The syntax is the same as for schemaLocation attributes in
+ instance documents: e.g, "http://www.example.com file_name.xsd".
+ The user can specify more than one XML Schema in the list.
+ </note>
+ </property>
+ <property name='http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation'
+ id='schema.external-noNamespaceSchemaLocation'>
+ <desc>
+ This property allows the user to specify an XML Schema with no
+ namespace.
+ </desc>
+ <type>java.lang.String</type>
+ <access general='read-write'/>
+ <note>
+ The syntax is a same as for the noNamespaceSchemaLocation attribute
+ that may occur in an instance document: e.g."file_name.xsd". The
+ user may specify only one XML Schema. For more information see the
+ documentation for the
+ http://apache.org/xml/properties/schema/external-schemaLocation
+ property.
+ </note>
+ </property>
+ -->
+ </pcategory>
+ <pcategory name='DOM Properties'>
+ <property name='http://apache.org/xml/properties/dom/current-element-node'
+ id='dom.current-element-node'>
+ <desc>The current DOM element node while parsing.</desc>
+ <type>org.w3c.dom.Element</type>
+ <access general='read-only'/>
+ <note>
+ This property is useful for determining the location with a DOM
+ document when an error occurs.
+ </note>
+ </property>
+ <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
+ implementation used must have a zero argument constructor.
+ </desc>
+ <type>java.lang.String</type>
+ <default value='"org.apache.xerces.dom.DocumentImpl"'/>
+ <access general='read-write'/>
+ <note>
+ When the document class name is set to a value other than the
+ name of the default document factory, the deferred node expansion
+ feature does not work.
+ </note>
+ </property>
+ </pcategory>
+ <pcategory name='SAX Properties'>
+ <property name='http://xml.org/sax/properties/declaration-handler'
+ id='declaration-handler'>
+ <desc>Set the handler for DTD declarations.</desc>
+ <type>org.xml.sax.ext.DeclHandler</type>
+ <access general='read-write'/>
+ </property>
+ <property name='http://xml.org/sax/properties/lexical-handler'
+ id='lexical-handler'>
+ <desc>Set the handler for lexical parsing events.</desc>
+ <type>org.xml.sax.ext.LexicalHandler</type>
+ <access general='read-write'/>
+ </property>
+ <property name='http://xml.org/sax/properties/dom-node'
+ id='dom-node'>
+ <desc>
+ The DOM node currently being visited, if SAX is being used as
+ a DOM iterator. If the parser recognizes and supports this
+ property but is not currently visiting a DOM node, it should
+ return null.
+ </desc>
+ <type>org.w3c.dom.Node</type>
+ <access parsing='read-only' not-parsing='read-write'/>
+ <note>
+ This property is only for SAX parser implementations used as
+ DOM tree walkers. Currently, Xerces does not have this
+ functionality.
+ </note>
+ </property>
+ </pcategory>
+</properties>
1.10.2.7 +100 -80 xml-xerces/java/docs/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/readme.xml,v
retrieving revision 1.10.2.6
retrieving revision 1.10.2.7
diff -u -r1.10.2.6 -r1.10.2.7
--- readme.xml 2000/12/12 19:07:11 1.10.2.6
+++ readme.xml 2001/07/19 06:43:10 1.10.2.7
@@ -1,81 +1,101 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
-
-<s1 title="&javaparsernamelong; Readme">
- <s2 title="&javaparsernamelong; &javaparserversion; Release">
- <p>The &javaparsernamelong; &javaparserversion; supports
- <jump href="http://www.w3.org/TR/1998/REC-xml-19980210">XML 1.0</jump>
- recommendation and contains advanced parser functionality, such as
- <jump href="http://www.w3.org/TR/DOM-Level-2/">DOM Level 2 version 1.0</jump>, and
- <jump href="http://www.megginson.com/SAX/">SAX Version 2</jump>,
- in addition to supporting the industry-standard
- <jump href="http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/level-one-core.html">DOM Level 1</jump> and
- <jump href="http://www.megginson.com/SAX/SAX1/">SAX version 1</jump>
- APIs.</p>
- <p>
-
- &javaparsername; &javaparserversion; is the first alpha release in a series of ongoing updates -
- Watch <jump href="http://xml.apache.org">xml.apache.org</jump>
- for new updates. Since it is an alpha release, defects are expected in the source code, documentation
- and packaging.
- </p>
- <p>
- Note that because some of the standards
- are still not complete, the stable API will definitely be
- different from its current form in &javaparsername; &javaparserversion;.
- This is your chance to give us
- feedback on the features that are important to you, and let us know
- whether the APIs that we are providing are the right ones. Please
- direct your feedback to the &javaparsername; mailing list.</p>
-
- </s2>
- <s2 title="License Information">
- <p>The &javaparsername; &javaparserversion; release is available in both source code
- and precompiled binary (JAR files) form. Both &javaparsername;
- packages are made available under the <jump href='../../LICENSE'>Apache
- Software License</jump>.
- </p>
- </s2>
- <s2 title="Applications of the &javaparsername; Parser">
- <p>The rich generating and validating capabilities allow the &javaparsername;
- Parser to be used for: </p>
- <ul>
- <li>Building XML-savvy Web servers. </li>
- <li>The next generation of vertical applications which will use
- XML as their data format. </li>
- <li>On-the-fly validation for creating XML editors. </li>
- <li>Ensuring the integrity of e-business data expressed in XML. </li>
- <li>Building truly internationalized XML applications. </li>
- </ul>
- </s2>
- <s2 title="XML Schema (alpha) Support">
- <p>!!! Not supported in this release !!! </p>
- <!--
- <p>
- This release includes preliminary
- support for the W3C XML Schema Language. The <link idref="schema">Schema</link>
- page contains a complete description of the
- schema capabilities of this release. We intend to track the W3C XML
- Schema Language in subsequent updates of &javaparsername;.</p> -->
- </s2>
- <s2 title="DOM Level 2 Support">
- <p>This release includes support for 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>,
- and <jump href="http://www.w3.org/TR/DOM-Level-2-Traversal-Range">Traversal and Range</jump> modules.
- The DOM Level 2 specification is now a W3C Recommendation.</p>
- </s2>
- <s2 title="SAX 2 Support">
- <p>This release includes support for the <jump href="http://www.megginson.com/SAX/">
- SAX Version 2</jump> API's which have been finalized.</p>
- </s2>
- <s2 title="Configuration Mechanism">
- <p>&javaparsername; &javaparserversion; uses a collection of methods to configure
- various settings in the parser. This release includes a new mechanism
- for setting parser switches. This mechanism uses the SAX2 configuration
- methods that are part of the XMLReader interface. We have defined a series
- of <link idref="properties">properties</link> and
- <link idref="features">features</link> for the &javaparsername;
- options. </p>
- </s2>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
+<s1 title='&javaparsernamelong; Readme'>
+ <s2 title='&javaparsernamelong; &javaparserversion; Release'>
+ <p>
+ Welcome to the future! Xerces2 is the next generation of
+ high performance, fully compliant XML parsers in the Apache
+ Xerces family. This new version of Xerces introduces the
+ Xerces Native Interface (XNI), a complete framework for
+ building parser components and configurations that is
+ extremely modular and easy to program.
+ </p>
+ <p>
+ The Apache Xerces2 parser is the reference implementation
+ of XNI but other parser components, configurations, and parsers
+ can be written using the Xerces Native Interface. For complete
+ design and implementation documents, refer to the
+ <link idref='xni'>XNI Manual</link>.
+ </p>
+ <p>
+ <strong>Note:</strong> Since this is a beta release, bugs are
+ to be expected. Please use
+ <jump href='http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Xerces2-J'>BugZilla</jump>
+ to report any bugs that you find.
+ </p>
+ </s2>
+ <s2 title='Features of This Release'>
+ <p>
+ The &javaparsernamelong; &javaparserversion; supports the
+ following standards and APIs:
+ </p>
+ <ul>
+ <li>
+ <jump href='http://www.w3.org/XML/'>eXtensible Markup Language</jump>
+ (XML) 1.0
+ <jump href='http://www.w3.org/TR/2000/REC-xml-20001006'>Second
+ Edition</jump> Recommendation
+ </li>
+ <li>
+ <jump href='http://www.w3.org/TR/REC-xml-names/'>Namespaces
+ in XML</jump> Recommendation
+ </li>
+ <li>
+ <jump href='http://www.w3.org/DOM/'>Document Object Model</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>,
+ and
+ <jump href='http://www.w3.org/TR/DOM-Level-2-Traversal-Range'>Traversal
+ and Range</jump> Recommendations
+ </li>
+ <li>
+ <jump href='http://www.megginson.com/SAX/'>Simple API for XML</jump>
+ (SAX) 2.0
+ <jump href='http://www.megginson.com/SAX/Java/sax2.zip'>Core</jump>,
+ and
+ <jump href='http://www.megginson.com/Software/sax2-ext-1.0.zip'>Extension</jump>
+ </li>
+ <li>
+ <jump href='http://java.sun.com/xml/xml_jaxp.html'>Java APIs for
+ XML Processing</jump> (JAXP) 1.1
+ </li>
+ </ul>
+ <p>
+ This release does <strong>NOT</strong> yet support the following
+ standards and/or APIs:
+ </p>
+ <ul>
+ <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>
+ and
+ <jump href='http://www.w3.org/TR/xmlschema-2/'>Datatypes</jump>
+ Recommendations
+ </li>
+ </ul>
+ </s2>
+ <s2 title='Changes from Xerces 1.x'>
+ <p>
+ Xerces2 is a nearly complete rewrite of the Xerces 1.x codebase
+ in order to make the code cleaner, more modular, and easier to
+ maintain. Applications using only the standard interfaces such as
+ JAXP, DOM, and SAX should not see any differences. However, the
+ following list details some of the more visible changes between
+ Xerces 1.x and Xerces2:
+ </p>
+ <ul>
+ <li>Deferred DOM implementation removed</li>
+ <li>XML Schema support not yet implemented</li>
+ </ul>
+ </s2>
+ <s2 title='License Information'>
+ <p>
+ The &javaparsername; &javaparserversion; release is available
+ in both source code and precompiled binary (JAR files) form.
+ Both &javaparsername; packages are made available under the
+ <jump href='http://xml.apache.org/LICENSE'>Apache Software
+ License</jump>.
+ </p>
+ </s2>
</s1>
1.16.2.8 +35 -14 xml-xerces/java/docs/releases.xml
Index: releases.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/releases.xml,v
retrieving revision 1.16.2.7
retrieving revision 1.16.2.8
diff -u -r1.16.2.7 -r1.16.2.8
--- releases.xml 2001/05/22 05:00:46 1.16.2.7
+++ releases.xml 2001/07/19 06:43:10 1.16.2.8
@@ -1,14 +1,35 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
-
-<s1 title="Releases">
- <s2 title='TBD'>
- <ul>
- <li>Fixed DTD method ordering problem for INCLUDE/IGNORE sections. [Petr Kuzel]</li>
- <li>Implemented basic support for XML Schema identity constraints [andyc]</li>
- <li>Updates to improve DFA build-time performance. [ATOZAWA@jp.ibm.com]</li>
- <li>Sync'ed with Xerces 1.3.0 [Arnaud Le Hors]</li>
-
- </ul>
- </s2>
-</s1>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE releases SYSTEM 'dtd/releases.dtd'>
+<releases>
+ <release version='2.0.0 beta (NOT YET RELEASED!)'>
+ <desc>
+ First beta release of the Xerces2 code. Besides numerous bug
+ fixes, this release has changes and additions to XNI. The new
+ XNI parser configuration framework has been added in this release.
+ </desc>
+ <changes>
+ <update>
+ <note>
+ Rewrote existing documentation, added XNI information, cleaned
+ up stylesheets, and converted some docs to use custom DTDs.
+ </note>
+ <submitter name='Andy Clark'/>
+ </update>
+ <fix>
+ <note>DTD method ordering problem for INCLUDE/IGNORE sections.</note>
+ <submitter name='Petr Kuzel'/>
+ </fix>
+ <update>
+ <note>Improved DFA build-time performance.</note>
+ <submitter name='ATOZAWA@jp.ibm.com' mailto='ATOZAWA@jp.ibm.com'/>
+ </update>
+ <update>
+ <note>Synchronized with Xerces 1.3.0</note>
+ <submitter name='Arnaud Le Hors'/>
+ </update>
+ </changes>
+ </release>
+ <release version='2.0.0 alpha'>
+ <desc>Initial alpha release of Xerces2 code.</desc>
+ </release>
+</releases>
1.6.2.2 +49 -109 xml-xerces/java/docs/samples.xml
Index: samples.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/samples.xml,v
retrieving revision 1.6.2.1
retrieving revision 1.6.2.2
diff -u -r1.6.2.1 -r1.6.2.2
--- samples.xml 2000/12/12 19:07:14 1.6.2.1
+++ samples.xml 2001/07/19 06:43:10 1.6.2.2
@@ -1,110 +1,50 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
-
-<s1 title="Samples">
- <s2 title="Introduction">
- <ul>
- <li><link idref="domcount">DOMCount</link></li>
- <li><link idref="domcount">SAXCount</link></li>
- <li><link idref="domwriter">DOMWriter</link></li>
- <li><link idref="domwriter">SAXWriter</link></li>
- <li><link idref="domfilter">DOMFilter</link></li>
- <li><link idref="iterator">IteratorView</link></li>
- <li><link idref="tree">TreeWalker</link></li>
- <li><link idref="treeview">TreeViewer</link></li>
- </ul>
- </s2>
- <s2 title="Caveats">
- <note>&javaparsername;: Running the sample applications
- requires that you have already loaded the &javaparsername; software on
- your computer.</note>
- <note>Java: Running the sample applications require that your computer has a
- correctly installed JDK. If you do not already have a JDK already on
- your computer download one from Sun's Java website:
- <jump href="http://java.sun.com">http://java.sun.com</jump> or from
- IBM's website
- <jump href="http://www.ibm.com/developer/java/">http://www.ibm.com/developer/java/</jump>
- where you can find an "Enhanced Windows JDK" that is optimized
- for the Windows platform. The sample applications
- described in the following pages support Java 1 - JDK 1.1.6. 1.1.7, 1.1.8 or
- Java 2 - JDK 1.2.2. </note>
- <note>UNIX: Command lines in the pages linked below use the Windows path
- separator ';' (semicolon) and directory separator '\' (backslash)..
- On UNIX, use the ':' (colon) character to separate the JAR files in the classpath,
- and replace Windows directory separator '\' (backslash)
- with '/' (forward slash).</note>
- </s2>
-
- <s2 title="DOMCount Sample">
- <p><link idref="domcount">DOMCount</link> parses your input file,
- and outputs the total parse time,
- along with counts of elements, attributes, text characters, and ignorable
- whitespace characters. DOMCount displays errors and
- warnings that occur during parsing.</p>
- </s2>
-
- <s2 title="SAXCount Sample">
- <p><link idref="domcount">SAXCount</link> parses your input file,
- and outputs the total parse time,
- along with counts of elements, attributes, text characters, and
- ignorable whitespace characters. SAXCount displays errors and
- warnings that occur during parsing.</p>
- </s2>
-
- <s2 title="DOMWriter Sample">
- <p><link idref="domwriter">DOMWriter</link> parses a file, and
- prints it out in XML format.
- The command line option, -c, is used to print files in
- "canonical" XML format, so that two XML documents can be compared.
- They also display any errors or warnings that occurred during the
- parse.
- DOMWriter also provides a feature to set the output Java encoding
- through the -e switch.</p>
- </s2>
-
- <s2 title="SAXWriter Sample">
- <p><link idref="domwriter">SAXWriter</link> parses a file, and
- prints it out in XML format. The command
- line option, -c, is used to print files in "canonical" XML format,
- so that two XML documents can be compared. They also display any
- errors or warnings that occurred during the parse.</p>
- </s2>
-
- <s2 title="DOMFilter Sample">
- <p><link idref="domfilter">DOMFilter</link> shows you how to
- search for specific elements in
- your XML document. It uses <code>getElementsByTagName()</code>
- to traverse the DOM tree, looking for elements or attributes that
- match your specification.</p>
- </s2>
-
- <s2 title="IteratorView Sample">
- <p><link idref="iterator">IteratorView</link> is an interactive
- UI sample that displays the DOM tree. It
- shows the progress of the iteration by moving the selection within the DOM tree.
- Buttons act as a control panel, allowing the user to interactively iterate through
- the tree, remove nodes, add nodes, and view the results immediately in the tree.</p>
- <p>The <code>IteratorView</code> uses an example filter,
- <code>NameNodeFilter</code>, that can be controlled
- from the UI and a <code>DOMTreeFull</code> class that displays the full DOM tree with all
- the nodes.</p>
- </s2>
-
- <s2 title="TreeWalker Sample">
- <p><link idref="tree">TreeWalkerviewView</link> is an interactive UI sample that displays the DOM
- tree. It show the progress of the tree traversal by moving the selection within the
- DOM tree. Buttons act as a control panel, allowing the user to interactively
- traverse the tree, remove nodes, add nodes, and view the results immediately in
- the tree.</p>
-
- <p>The <code>TreeWalkerviewView</code> uses an example filter,
- <code>NameNodeFilter</code>, that can be
- controlled from the UI and a <code>DOMTreeFull</code> class that
- displays the full DOM tree with all the nodes.</p>
- </s2>
-
- <s2 title="Treeviewer Sample">
- <p><link idref="tree">TreeViewer</link> displays the input XML file in a graphical tree-style
- interface. It will also highlight lines have well-formedness or validation errors.</p>
- </s2>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
+<s1 title='Sample Programs'>
+ <s2 title='Overview'>
+ <p>
+ Xerces contains many useful samples to help you get up-and-running
+ with writing XML applications. Many of the sample programs are
+ even useful as standalone programs to help in testing the validity
+ of XML documents and/or debugging applications.
+ </p>
+ <p>
+ The samples are organized either by API or by programming area in
+ the following categories:
+ </p>
+ <ul>
+ <li><link idref='samples-dom'>DOM Samples</link></li>
+ <li><link idref='samples-sax'>SAX Samples</link></li>
+ <li><link idref='samples-socket'>Socket Samples</link></li>
+ <li><link idref='samples-ui'>UI Samples</link></li>
+ <li><link idref='samples-xni'>XNI Samples</link></li>
+ </ul>
+ </s2>
+ <s2 title='Running the Samples'>
+ <p>
+ Running the sample applications requires that you have already
+ installed the Java Development Kit (JDK) or Java Runtime
+ Environment (JRE) on you computer and extracted the
+ &javaparsername; software.
+ </p>
+ <p>
+ If you do not already have a JDK already on your computer download
+ one from Sun's Java website:
+ <jump href="http://java.sun.com">http://java.sun.com</jump> or from
+ IBM's website
+ <jump href="http://www.ibm.com/developer/java/">http://www.ibm.com/developer/java/</jump>.
+ The sample applications described in the following pages support
+ Java 1.x (e.g. 1.1.8, etc) and/or Java 2 (e.g. 1.2.2, 1.3, etc).
+ The UI samples are written using Swing and require Java 2 in order
+ to run but all of the command line programs will run using Java 1.x.
+ </p>
+ <p>
+ Command lines examples on the following pages use the Windows path
+ separator ';' (semicolon) and directory separator
+ '\' (backslash). On UNIX, use the ':' (colon)
+ character to separate the JAR files in the classpath, and replace
+ Windows directory separator '\' (backslash) with
+ '/' (forward slash).
+ </p>
+ </s2>
</s1>
No revision
No revision
1.1.2.1 +18 -0 xml-xerces/java/docs/Attic/limitations.xml
1.1.2.1 +185 -0 xml-xerces/java/docs/Attic/samples-dom.xml
1.1.2.1 +170 -0 xml-xerces/java/docs/Attic/samples-sax.xml
1.1.2.1 +113 -0 xml-xerces/java/docs/Attic/samples-socket.xml
1.1.2.1 +25 -0 xml-xerces/java/docs/Attic/samples-ui.xml
1.1.2.1 +163 -0 xml-xerces/java/docs/Attic/samples-xni.xml
1.1.2.1 +5 -0 xml-xerces/java/docs/Attic/xni.xml
No revision
No revision
1.2.2.1 +30 -29 xml-xerces/java/docs/dtd/book.dtd
Index: book.dtd
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dtd/book.dtd,v
retrieving revision 1.2
retrieving revision 1.2.2.1
diff -u -r1.2 -r1.2.2.1
--- book.dtd 2000/06/02 17:30:36 1.2
+++ book.dtd 2001/07/19 06:43:11 1.2.2.1
@@ -6,7 +6,8 @@
<!ENTITY % externalEntity SYSTEM "entities.ent">
%externalEntity;
-<!ELEMENT book (resources?|document|hidden|faqs|changes|group|container|external|separator)+>
+<!ELEMENT book (resources?|document|hidden|faqs|releases|
+ external|separator|settings)+>
<!ATTLIST book title CDATA #REQUIRED
copyright CDATA #IMPLIED>
@@ -14,37 +15,31 @@
<!ATTLIST resources source CDATA #REQUIRED>
<!ELEMENT document EMPTY>
-<!ATTLIST document id ID #REQUIRED
- source CDATA #REQUIRED
- label CDATA #REQUIRED>
+<!ATTLIST document label CDATA #REQUIRED
+ title CDATA #REQUIRED
+ id ID #REQUIRED
+ source CDATA #REQUIRED>
<!ELEMENT hidden EMPTY>
-<!ATTLIST hidden id ID #REQUIRED
+<!ATTLIST hidden title CDATA #REQUIRED
+ id ID #REQUIRED
source CDATA #REQUIRED>
-<!ELEMENT faqs EMPTY>
-<!ATTLIST faqs id ID #REQUIRED
- source CDATA #REQUIRED
- label CDATA #REQUIRED>
-
-<!ELEMENT changes EMPTY>
-<!ATTLIST changes id ID #REQUIRED
- source CDATA #REQUIRED
- label CDATA #REQUIRED>
-
-<!ELEMENT group (entry)+>
-<!ATTLIST group id ID #IMPLIED
- label CDATA #REQUIRED
- title CDATA #REQUIRED>
-
-<!ELEMENT container (entry)+>
-<!ATTLIST container id ID #IMPLIED
- source CDATA #REQUIRED
- label CDATA #REQUIRED>
-
-<!ELEMENT entry EMPTY>
-<!ATTLIST entry id ID #REQUIRED
- source CDATA #REQUIRED>
+<!ELEMENT faqs (faq+)>
+<!ATTLIST faqs label CDATA #REQUIRED
+ title CDATA #REQUIRED
+ id ID #IMPLIED>
+
+<!ELEMENT faq EMPTY>
+<!ATTLIST faq title CDATA #REQUIRED
+ id ID #REQUIRED
+ source CDATA #REQUIRED>
+
+<!ELEMENT releases EMPTY>
+<!ATTLIST releases label CDATA #REQUIRED
+ title CDATA #REQUIRED
+ id ID #REQUIRED
+ source CDATA #REQUIRED>
<!ELEMENT external EMPTY>
<!ATTLIST external label CDATA #REQUIRED
@@ -52,4 +47,10 @@
<!ELEMENT separator EMPTY>
-<!-- CVS $Revision: 1.2 $ $Date: 2000/06/02 17:30:36 $ -->
+<!ELEMENT settings EMPTY>
+<!ATTLIST settings label CDATA #REQUIRED
+ title CDATA #REQUIRED
+ id ID #REQUIRED
+ source CDATA #REQUIRED>
+
+<!-- CVS $Revision: 1.2.2.1 $ $Date: 2001/07/19 06:43:11 $ -->
1.2.2.4 +6 -7 xml-xerces/java/docs/dtd/entities.ent
Index: entities.ent
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dtd/entities.ent,v
retrieving revision 1.2.2.3
retrieving revision 1.2.2.4
diff -u -r1.2.2.3 -r1.2.2.4
--- entities.ent 2000/12/12 19:07:20 1.2.2.3
+++ entities.ent 2001/07/19 06:43:11 1.2.2.4
@@ -1,7 +1,6 @@
-<?xml encoding="US-ASCII"?>
-
-<!ENTITY javaparsernamelong "Xerces Java Parser">
-<!ENTITY javaparsername "Xerces-J">
-<!ENTITY javaparserversion "2.0.0 (alpha)">
-<!ENTITY javaparserdirectory "xerces-2_0_0_alpha">
-<!ENTITY javaparserdistname "Xerces-J-bin"> <!-- name of binaries -->
+<?xml version='1.0' encoding='UTF-8'?>
+<!ENTITY javaparsernamelong 'Xerces2 Java Parser'>
+<!ENTITY javaparsername 'Xerces-J'>
+<!ENTITY javaparserversion '2.0.0.beta'>
+<!ENTITY javaparserdirectory 'xerces-2_0_0_beta'>
+<!ENTITY javaparserdistname 'Xerces-J-bin'>
1.1.2.1 +3 -2 xml-xerces/java/docs/dtd/markup.ent
Index: markup.ent
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/dtd/markup.ent,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -u -r1.1 -r1.1.2.1
--- markup.ent 2000/05/23 01:13:18 1.1
+++ markup.ent 2001/07/19 06:43:11 1.1.2.1
@@ -1,7 +1,7 @@
<?xml encoding='US-ASCII'?>
<!-- MARKUP ENTITY -->
-<!ENTITY % markup "em|ref|code|br">
+<!ENTITY % markup "em|strong|ref|code|br">
<!-- import the external source-specific dtd -->
<!ENTITY % externalEntity SYSTEM "entities.ent">
@@ -14,8 +14,9 @@
%linksEntity;
<!ELEMENT em (#PCDATA|%links;)*>
+<!ELEMENT strong (#PCDATA|%links;)*>
<!ELEMENT ref (#PCDATA|%links;)*>
<!ELEMENT code (#PCDATA|%links;)*>
<!ELEMENT br EMPTY>
-<!-- CVS $Revision: 1.1 $ $Date: 2000/05/23 01:13:18 $ -->
+<!-- CVS $Revision: 1.1.2.1 $ $Date: 2001/07/19 06:43:11 $ -->
No revision
No revision
1.1.2.1 +19 -0 xml-xerces/java/docs/dtd/Attic/releases.dtd
1.1.2.1 +39 -0 xml-xerces/java/docs/dtd/Attic/settings.dtd
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org