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/31 11:56:32 UTC
cvs commit: xml-xerces/java/docs xni-core.xml docs-book.xml xni-config.xml xni-design.xml xni.xml xni-api.xml
andyc 01/07/31 02:56:32
Modified: java/docs Tag: xerces_j_2 docs-book.xml xni-config.xml
xni-design.xml xni.xml
Added: java/docs Tag: xerces_j_2 xni-core.xml
Removed: java/docs Tag: xerces_j_2 xni-api.xml
Log:
Adding more XNI documentation for parser configuration.
Revision Changes Path
No revision
No revision
1.5.2.7 +5 -7 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.6
retrieving revision 1.5.2.7
diff -u -r1.5.2.6 -r1.5.2.7
--- docs-book.xml 2001/07/30 08:21:56 1.5.2.6
+++ docs-book.xml 2001/07/31 09:56:31 1.5.2.7
@@ -27,13 +27,11 @@
<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'/>
- <!--
- <design title='Xerces Native Interface Design'
- id='design-xni' source='design-xni.xml'/>
--->
- <hidden title='XNI Parser Configuration'
+ <hidden title='XNI Design Details'
+ id='xni-design' source='xni-design.xml'/>
+ <hidden title='XNI Core Interfaces'
+ id='xni-core' source='xni-core.xml'/>
+ <hidden title='XNI Parser Configuration'
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'/>
1.1.2.3 +900 -11 xml-xerces/java/docs/Attic/xni-config.xml
Index: xni-config.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/Attic/xni-config.xml,v
retrieving revision 1.1.2.2
retrieving revision 1.1.2.3
diff -u -r1.1.2.2 -r1.1.2.3
--- xni-config.xml 2001/07/30 08:21:56 1.1.2.2
+++ xni-config.xml 2001/07/31 09:56:31 1.1.2.3
@@ -1,17 +1,906 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
<s1 title='XNI Parser Configuration'>
- <p><strong>TODO</strong></p>
- <!--
- <s2 title='XNI Parser Configuration'>
- <p>
- An XML application programmer can use the Xerces Native Interface
- parser configuration interfaces to build different parser
- configurations, either completely from scratch or by mixing
- and matching existing parser components. For advanced users
- that want to take advantage of this capability, an understanding
- of the parser configuration framework is required.
+ <s2 title='Parser Configuration'>
+ <p>
+ Parser configurations built using the Xerces Native Interface
+ are made from a series of parser components. This document
+ details the XNI API for these components and how they are put
+ together to construct a parser configuration in the following
+ section:
+ </p>
+ <ul>
+ <li><link anchor='components'>Components</link></li>
+ <li><link anchor='configurations'>Configurations</link></li>
+ </ul>
+ <p>
+ In addition, several <link anchor='examples'>examples</link>
+ are included to show how to create some parser components and
+ configurations:
+ </p>
+ <ul>
+ <li><link anchor='abstract-parser-config'>Abstract Parser Configuration</link></li>
+ <li><link anchor='csv-parser-config'>CSV Parser Configuration</link></li>
+ </ul>
+ <p>
+ <strong>Note:</strong>
+ All of the interfaces and classes defined in this document
+ reside in the <code>org.apache.xerces.xni.parser</code> package
+ but may use various interfaces and classes from the core XNI
+ package, <code>org.apache.xerces.xni</code>.
+ </p>
+ </s2>
+ <anchor name='components'/>
+ <s2 title='Components'>
+ <p>
+ Parser configurations are comprised of a number of parser
+ components that perform various tasks. For example, a parser
+ component may be responsible for the actual scanning of XML
+ documents to generate document "streaming" information
+ events; another component may manage commonly used symbols
+ within the parser configuration in order to improve
+ performance; and a third component may even manage the
+ resolution of external parsed entities and the transcoding
+ of these entities from various international encodings into
+ <jump href='http://www.unicode.org/'>Unicode</jump> used
+ within the Java virtual machine. When these components are
+ assembled in a certain way, they constitute a single parser
+ configuration but they can also be used interchangeably with
+ other components that implement the appropriate interfaces.
+ </p>
+ <p>
+ <strong>Note:</strong>
+ Even though a parser is comprised of a number of components,
+ not all of these components are <em>configurable</em>. In
+ other words, some components depend on knowing the state of
+ certain features and properties of the parser configuration
+ while others can operate completely independent of the parser
+ configuration. However, when we use the term "component" when
+ talking about XNI, we are talking about a <em>configurable
+ component</em> within the parser configuration.
+ </p>
+ <p>
+ The following diagram shows an example of this collection of
+ parser components: (Please note that this is not the <em>only</em>
+ configuration of parser components.)
+ </p>
+ <p>
+ <img alt='Parser Components' src='xni-components-overview.gif'/>
+ </p>
+ <p>
+ The only distinguishing feature of a component
+ is that it can be notified of the state
+ of parser features and properties. Features represent parser
+ state of type <code>boolean</code> whereas properties represent
+ parser state of type <code>java.lang.Object</code>. Each
+ component can also be queried for which features and properties
+ it recognizes.
+ </p>
+ <anchor name='component'/>
+ <s3 title='Interface XMLComponent'>
+ <p>
+ This interface is the basic configurable component in a parser
+ configuration. It is managed by the
+ <link anchor='component-manager'>XMLComponentManager</link>
+ which holds the parser state.
+ </p>
+ <table>
+ <tr><th>Methods</th></tr>
+ <tr>
+ <td>
+ <code>
+ public void reset(
+ <link anchor='component-manager'>XMLComponentManager</link> manager
+ ) throws <link anchor='configuration-exception'>XMLConfigurationException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setFeature(
+ String featureId,
+ boolean state
+ ) throws <link anchor='configuration-exception'>XMLConfigurationException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setProperty(
+ String propertyId,
+ Object value
+ ) throws <link anchor='configuration-exception'>XMLConfigurationException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr><td><code>public String[] getRecognizedFeatures();</code></td></tr>
+ <tr><td><code>public String[] getRecognizedProperties();</code></td></tr>
+ </table>
+ </s3>
+ <anchor name='configuration-exception'/>
+ <s3 title='Class XMLConfigurationException'>
+ <p>
+ </p>
+ <table>
+ <tr>
+ <th>
+ Extends <link idref='xni-core' anchor='exception'>XNIException</link>
+ </th>
+ </tr>
+ <tr><th>Constants</th></tr>
+ <tr>
+ <td><code>public static final short NOT_RECOGNIZED;</code></td>
+ </tr>
+ <tr>
+ <td><code>public static final short NOT_SUPPORTED;</code></td>
+ </tr>
+ <tr><th>Constructors</th></tr>
+ <tr>
+ <td>
+ <code>
+ public XMLConfigurationException(
+ short type,
+ String identifier
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public XMLConfigurationException(
+ short type,
+ String identifier,
+ String message
+ );
+ </code>
+ </td>
+ </tr>
+ <tr><th>Methods</th></tr>
+ <tr><td><code>public short getType();</code></td></tr>
+ <tr><td><code>public String getIdentifier();</code></td></tr>
+ </table>
+ </s3>
+ <p>
+ Components are managed by a component manager. The component
+ manager keeps track of the parser state for features and
+ properties. The component manager is responsible for notifying
+ each component when the value of those features and properties
+ change.
+ </p>
+ <p>
+ Before parsing a document, a parser configuration <em>must</em>
+ use the component manager to reset all of the parser components.
+ Then, during parsing, each time a feature or property value is
+ modified, all of the components <em>must</em> be informed of the
+ change.
+ </p>
+ <anchor name='component-manager'/>
+ <s3 title='Interface XMLComponentManager'>
+ <p>
+ The component manager interface allows components to query
+ needed features and properties during a call to the
+ <code>XMLComponent#reset(XMLComponentManager)</code> method.
+ However, components <em>should not</em> keep a reference to
+ the component manager. In other words, all necessary state
+ should be queried when the component is reset.
+ </p>
+ <table>
+ <tr><th>Methods</th></tr>
+ <tr>
+ <td>
+ <code>
+ public boolean getFeature(
+ String featureId
+ ) throws <link anchor='configuration-exception'>XMLConfigurationException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public Object getProperty(
+ String propertyId
+ ) throws <link anchor='configuration-exception'>XMLConfigurationException</link>;
+ </code>
+ </td>
+ </tr>
+ </table>
+ </s3>
+ <p>
+ <strong>Note:</strong>
+ A compliant XNI parser configuration is <em>not</em>
+ required to use any components that implement the
+ <code><link anchor='component'>XMLComponent</link></code>
+ interface. That interface is included as a convenience for
+ people building modular and configurable parser components.
+ The Xerces2 reference implementation uses the component
+ interface to implement its components so that they can be
+ used interchangeably in various configurations.
+ </p>
+ </s2>
+ <anchor name='configurations'/>
+ <s2 title='Configurations'>
+ <p>
+ An XNI parser configuration defines the entry point for a
+ parser to set features and properties, initiate a parse of
+ an XML instance document, perform entity resolution, and
+ receive notification of errors that occurred in the document.
+ </p>
+ <p>
+ A parser configuration is typically comprised of a series of
+ parser components. Some of these components may be
+ connected together to form the parsing pipeline. This parser
+ configuration is then used by a specific parser implementation
+ that generates a particular API, such as DOM or SAX. The
+ separation between the parser configuration and parser instance
+ allows the same API-generating parser to be used with an
+ unlimited number of different parser configurations.
+ </p>
+ <p>
+ When a document is parsed, the parser configuration resets the
+ configurable components and initiates the scanning of the
+ document. Typically, a scanner starts scanning the document
+ which generates XNI information set events that are sent to
+ the next component in the pipeline (e.g. the validator). The
+ information set events coming out of the end of the pipeline
+ are then communicated to the document and DTD handlers that
+ are registered with the parser configuration.
+ </p>
+ <p>
+ The following diagram shows both the generic parsing pipeline
+ contained within a parser configuration and the separation of
+ parser configuration and specific parser classes.
+ </p>
+ <p>
+ <img alt='Parser Configuration' src='xni-parser-configuration.gif'/>
+ </p>
+ <note>
+ At the time of this writing, the initiation of the scanning of
+ the XML document is parser configuration dependent. In other
+ words, the parser configuration must know how to connect specific
+ instances of components together to form the parsing pipeline
+ and then also use proprietary (internal) API to initiate a scan
+ that starts the pipeline. However, it is inteded that a future
+ release of XNI and the Xerces2 reference implementation will define
+ interfaces to allow dynamic generation of parsing pipelines and
+ also define interfaces to allow document and DTD scanners to be
+ swapped generically.
+ </note>
+ <anchor name='parser-configuration'/>
+ <s3 title='Interface XMLParserConfiguration'>
+ <p>
+ The parser configuration is the primary connection to specific
+ parser instances. Because the parser configuration is responsible
+ for holding the parser state, the
+ <code>addRecognizedFeatures(String[])</code> and
+ <code>addRecognizedProperties(String[])</code> methods allow the
+ parser instance to add recognized features and properties that
+ the parser configuration will store.
+ </p>
+ <table>
+ <tr>
+ <th>
+ Extends <link anchor='component-manager'>XMLComponentManager</link>
+ </th>
+ </tr>
+ <tr><th>Methods</th></tr>
+ <tr>
+ <td>
+ <code>
+ public void setFeature(
+ String featureId,
+ boolean state
+ ) throws <link anchor='configuration-exception'>XMLConfigurationException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setProperty(
+ String propertyId,
+ Object value
+ ) throws <link anchor='configuration-exception'>XMLConfigurationException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>public void addRecognizedFeatures(String[] featureIds);</code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>public void addRecognizedProperties(String[] propertyIds);</code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setEntityResolver(
+ <link anchor='entity-resolver'>XMLEntityResolver</link> resolver
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setErrorHandler(
+ <link anchor='error-handler'>XMLErrorHandler</link> handler
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setDocumentHandler(
+ <link idref='xni-core' anchor='document-handler'>XMLDocumentHandler</link> handler
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setDTDHandler(
+ <link idref='xni-core' anchor='dtd-handler'>XMLDTDHandler</link> handler
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void setDTDContentModelHandler(
+ <link idref='xni-core' anchor='dtd-content-model-handler'>XMLDTDContentModelHandler</link> handler
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void parse(
+ <link anchor='input-source'>XMLInputSource</link> source
+ ) throws java.io.IOException, <link anchor='parse-exception'>XMLParseException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr><td><code>public void setLocale(java.util.Locale);</code></td></tr>
+ </table>
+ </s3>
+ <anchor name='entity-resolver'/>
+ <s3 title='Interface XMLEntityResolver'>
+ <p>
+ This interface allows resolution of the external DTD subset and
+ external parsed entities appearing in the document instance.
+ </p>
+ <table>
+ <tr><th>Methods</th></tr>
+ <tr>
+ <td>
+ <code>
+ public <link anchor='input-source'>XMLInputSource</link> resolveEntity(
+ String publicId,
+ String systemId,
+ String baseSystemId
+ ) throws java.io.IOException, <link anchor='parse-exception'>XMLParseException</link>;
+ </code>
+ </td>
+ </tr>
+ </table>
+ </s3>
+ <anchor name='error-handler'/>
+ <s3 title='Interface XMLErrorHandler'>
+ <table>
+ <tr><th>Methods</th></tr>
+ <tr>
+ <td>
+ <code>
+ public void warning(
+ String domain,
+ String key,
+ <link anchor='parse-exception'>XMLParseException</link> exception
+ ) throws <link idref='xni-core' anchor='exception'>XNIException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void error(
+ String domain,
+ String key,
+ <link anchor='parse-exception'>XMLParseException</link> exception
+ ) throws <link idref='xni-core' anchor='exception'>XNIException</link>;
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public void fatalError(
+ String domain,
+ String key,
+ <link anchor='parse-exception'>XMLParseException</link> exception
+ ) throws <link idref='xni-core' anchor='exception'>XNIException</link>;
+ </code>
+ </td>
+ </tr>
+ </table>
+ </s3>
+ <anchor name='input-source'/>
+ <s3 title='Class XMLInputSource'>
+ <table>
+ <tr><th>Constructors</th></tr>
+ <tr>
+ <td>
+ <code>
+ public XMLInputSource(
+ String publicId,
+ String systemId,
+ String baseSystemId
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public XMLInputSource(
+ String publicId,
+ String systemId,
+ String baseSystemId,
+ java.io.InputStream byteStream,
+ String encoding
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public XMLInputSource(
+ String publicId,
+ String systemId,
+ String baseSystemId
+ java.io.Reader characterStream,
+ String encoding
+ );
+ </code>
+ </td>
+ </tr>
+ <tr><th>Methods</th></tr>
+ <tr><td><code>public void setPublicId(String publicId);</code></td></tr>
+ <tr><td><code>public String getPublicId();</code></td></tr>
+ <tr><td><code>public void setSystemId(String systemId);</code></td></tr>
+ <tr><td><code>public String getSystemId();</code></td></tr>
+ <tr><td><code>public void getBaseSystemId(String baseSystemId);</code></td></tr>
+ <tr><td><code>public String getBaseSystemId();</code></td></tr>
+ <tr><td><code>public void getByteStream(java.io.InputStream byteStream);</code></td></tr>
+ <tr><td><code>public java.io.InputStream getByteStream();</code></td></tr>
+ <tr><td><code>public void getCharacterStream(java.io.Reader characterStream);</code></td></tr>
+ <tr><td><code>public java.io.Reader getCharacterStream();</code></td></tr>
+ <tr><td><code>public void setEncoding(String encoding);</code></td></tr>
+ <tr><td><code>public String getEncoding();</code></td></tr>
+ </table>
+ </s3>
+ <anchor name='parse-exception'/>
+ <s3 title='Class XMLParseException'>
+ <table>
+ <tr>
+ <th>
+ Extends <link idref='xni-core' anchor='exception'>XNIException</link>
+ </th>
+ </tr>
+ <tr><th>Constructors</th></tr>
+ <tr>
+ <td>
+ <code>
+ public XMLParseException(
+ <link idref='xni-core' anchor='locator'>XMLLocator</link> location,
+ String message
+ );
+ </code>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <code>
+ public XMLParseException(
+ <link idref='xni-core' anchor='locator'>XMLLocator</link> location,
+ String message,
+ Exception exception
+ );
+ </code>
+ </td>
+ </tr>
+ <tr><th>Methods</th></tr>
+ <tr><td><code>public String getPublicId();</code></td></tr>
+ <tr><td><code>public String getSystemId();</code></td></tr>
+ <tr><td><code>public String getBaseSystemId();</code></td></tr>
+ <tr><td><code>public int getLineNumber();</code></td></tr>
+ <tr><td><code>public int getColumnNumber();</code></td></tr>
+ </table>
+ </s3>
+ </s2>
+ <anchor name='examples'/>
+ <s2 title='Examples'>
+ <p>
+ The following samples show how to create various parser components
+ and parser configurations. The XNI samples included with the Xerces2
+ reference release provide a convenient way to test a parser
+ configuration. For example, to test the
+ <link anchor='csv-parser-config'>CSV Parser Configuration</link>
+ example, run the following command:
+ </p>
+ <source>java xni.DocumentTracer -p CSVConfiguration document.csv</source>
+ <p>
+ Or a new CSV parser can be constructed that produces standard
+ SAX events. For example:
+ </p>
+ <source>import org.apache.xerces.parsers.AbstractSAXParser;
+
+public class CSVParser
+ extends AbstractSAXParser {
+
+ // Constructors
+
+ public CSVParser() {
+ super(new CSVConfiguration());
+ }
+
+} // class CSVParser</source>
+ <p>
+ The following samples are available:
</p>
+ <ul>
+ <li><link anchor='abstract-parser-config'>Abstract Parser Configuration</link></li>
+ <li><link anchor='csv-parser-config'>CSV Parser Configuration</link></li>
+ </ul>
+ <anchor name='abstract-parser-config'/>
+ <s3 title='Abstract Parser Configuration'>
+ <p>
+ This abstract parser configuration simply helps manage
+ components, features and properties, and other tasks common to
+ all parser configurations.
+ </p>
+ <source><![CDATA[import java.io.FileInputStream;
+import java.io.InputStream;
+import java.io.IOException;
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.util.Hashtable;
+import java.util.Locale;
+import java.util.Vector;
+
+import org.apache.xerces.xni.XMLDocumentHandler;
+import org.apache.xerces.xni.XMLDTDHandler;
+import org.apache.xerces.xni.XMLDTDContentModelHandler;
+import org.apache.xerces.xni.XNIException;
+
+import org.apache.xerces.xni.parser.XMLComponent;
+import org.apache.xerces.xni.parser.XMLConfigurationException;
+import org.apache.xerces.xni.parser.XMLEntityResolver;
+import org.apache.xerces.xni.parser.XMLErrorHandler;
+import org.apache.xerces.xni.parser.XMLInputSource;
+import org.apache.xerces.xni.parser.XMLParserConfiguration;
+
+public abstract class AbstractConfiguration
+ implements XMLParserConfiguration {
+
+ // Data
+
+ protected final Vector fRecognizedFeatures = new Vector();
+ protected final Vector fRecognizedProperties = new Vector();
+ protected final Hashtable fFeatures = new Hashtable();
+ protected final Hashtable fProperties = new Hashtable();
+
+ protected XMLEntityResolver fEntityResolver;
+ protected XMLErrorHandler fErrorHandler;
+ protected XMLDocumentHandler fDocumentHandler;
+ protected XMLDTDHandler fDTDHandler;
+ protected XMLDTDContentModelHandler fDTDContentModelHandler;
+
+ protected Locale fLocale;
+
+ protected final Vector fComponents = new Vector();
+
+ // XMLParserConfiguration methods
+
+ public void addRecognizedFeatures(String[] featureIds) {
+ int length = featureIds != null ? featureIds.length : 0;
+ for (int i = 0; i < length; i++) {
+ String featureId = featureIds[i];
+ if (!fRecognizedFeatures.contains(featureId)) {
+ fRecognizedFeatures.addElement(featureId);
+ }
+ }
+ }
+
+ public void setFeature(String featureId, boolean state)
+ throws XMLConfigurationException {
+ if (!fRecognizedFeatures.contains(featureId)) {
+ short type = XMLConfigurationException.NOT_RECOGNIZED;
+ throw new XMLConfigurationException(type, featureId);
+ }
+ int length = fComponents.size();
+ for (int i = 0; i < length; i++) {
+ XMLComponent component = (XMLComponent)fComponents.elementAt(i);
+ component.setFeature(featureId, state);
+ }
+ }
+
+ public boolean getFeature(String featureId)
+ throws XMLConfigurationException {
+ if (!fRecognizedFeatures.contains(featureId)) {
+ short type = XMLConfigurationException.NOT_RECOGNIZED;
+ throw new XMLConfigurationException(type, featureId);
+ }
+ Boolean state = (Boolean)fFeatures.get(featureId);
+ return state != null ? state.booleanValue() : false;
+ }
+
+ public void addRecognizedProperties(String[] propertyIds) {
+ int length = propertyIds != null ? propertyIds.length : 0;
+ for (int i = 0; i < length; i++) {
+ String propertyId = propertyIds[i];
+ if (!fRecognizedProperties.contains(propertyId)) {
+ fRecognizedProperties.addElement(propertyId);
+ }
+ }
+ }
+
+ public void setProperty(String propertyId, Object value)
+ throws XMLConfigurationException {
+ if (!fRecognizedProperties.contains(propertyId)) {
+ short type = XMLConfigurationException.NOT_RECOGNIZED;
+ throw new XMLConfigurationException(type, propertyId);
+ }
+ int length = fComponents.size();
+ for (int i = 0; i < length; i++) {
+ XMLComponent component = (XMLComponent)fComponents.elementAt(i);
+ component.setProperty(propertyId, value);
+ }
+ }
+
+ public Object getProperty(String propertyId)
+ throws XMLConfigurationException {
+ if (!fRecognizedProperties.contains(propertyId)) {
+ short type = XMLConfigurationException.NOT_RECOGNIZED;
+ throw new XMLConfigurationException(type, propertyId);
+ }
+ Object value = fProperties.get(propertyId);
+ return value;
+ }
+
+ public void setEntityResolver(XMLEntityResolver resolver) {
+ fEntityResolver = resolver;
+ }
+
+ public void setErrorHandler(XMLErrorHandler handler) {
+ fErrorHandler = handler;
+ }
+
+ public void setDocumentHandler(XMLDocumentHandler handler) {
+ fDocumentHandler = handler;
+ }
+
+ public void setDTDHandler(XMLDTDHandler handler) {
+ fDTDHandler = handler;
+ }
+
+ public void setDTDContentModelHandler(XMLDTDContentModelHandler handler) {
+ fDTDContentModelHandler = handler;
+ }
+
+ public abstract void parse(XMLInputSource inputSource)
+ throws IOException, XNIException;
+
+ public void setLocale(Locale locale) {
+ fLocale = locale;
+ }
+
+ // Protected methods
+
+ protected void addComponent(XMLComponent component) {
+ if (!fComponents.contains(component)) {
+ fComponents.addElement(component);
+ addRecognizedFeatures(component.getRecognizedFeatures());
+ addRecognizedProperties(component.getRecognizedProperties());
+ }
+ }
+
+ protected void resetComponents()
+ throws XMLConfigurationException {
+ int length = fComponents.size();
+ for (int i = 0; i < length; i++) {
+ XMLComponent component = (XMLComponent)fComponents.elementAt(i);
+ component.reset(this);
+ }
+ }
+
+ protected void openInputSourceStream(XMLInputSource source)
+ throws IOException {
+ if (source.getCharacterStream() != null) {
+ return;
+ }
+ InputStream stream = source.getByteStream();
+ if (stream == null) {
+ String systemId = source.getSystemId();
+ try {
+ URL url = new URL(systemId);
+ stream = url.openStream();
+ }
+ catch (MalformedURLException e) {
+ stream = new FileInputStream(systemId);
+ }
+ source.setByteStream(stream);
+ }
+ }
+
+} // class AbstractConfiguration]]></source>
+ </s3>
+ <anchor name='csv-parser-config'/>
+ <s3 title='CSV Parser Configuration'>
+ <p>
+ This example is a very simple parser configuration that can
+ parser files with comma-separated values (CSV) to generate
+ XML events. For example, the following CSV document:
+ </p>
+ <source>Andy Clark,16 Jan 1973,Cincinnati</source>
+ <p>
+ produces the following XML "document" as represented by the
+ the XNI streaming document information:
+ </p>
+ <source><![CDATA[<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE csv [
+<!ELEMENT csv (row)*>
+<!ELEMENT row (col)*>
+<!ELEMENT col (#PCDATA)>
+]>
+<csv>
+ <row>
+ <col>Andy Clark</col>
+ <col>16 Jan 1973</col>
+ <col>Cincinnati</col>
+ </row>
+</csv>]]></source>
+ <p>
+ Here is the source code for the CSV parser configuration.
+ Notice that it does not use any components. Rather, it implements
+ the CSV parsing directly in the parser configuration's
+ <code>parse(XMLInputSource)</code> method. This demonstrates
+ that you are <em>not</em> required to use the
+ <code>XMLComponent</code> interface but it is there for
+ building modular components that can be used in other
+ configurations.
+ </p>
+ <source><![CDATA[import java.io.BufferedReader;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.IOException;
+import java.io.Reader;
+import java.util.StringTokenizer;
+
+import org.apache.xerces.util.XMLAttributesImpl;
+import org.apache.xerces.util.XMLStringBuffer;
+
+import org.apache.xerces.xni.QName;
+import org.apache.xerces.xni.XMLAttributes;
+import org.apache.xerces.xni.XMLDTDContentModelHandler;
+import org.apache.xerces.xni.XNIException;
+
+import org.apache.xerces.xni.parser.XMLInputSource;
+
+public class CSVConfiguration
+ extends AbstractConfiguration {
+
+ // Constants
+
+ protected static final QName CSV = new QName(null, null, "csv", null);
+ protected static final QName ROW = new QName(null, null, "row", null);
+ protected static final QName COL = new QName(null, null, "col", null);
+ protected static final XMLAttributes EMPTY_ATTRS = new XMLAttributesImpl();
+
+ // Data
+
+ private final XMLStringBuffer fStringBuffer = new XMLStringBuffer();
+
+ // XMLParserConfiguration methods
+
+ public void setFeature(String featureId, boolean state) {}
+ public boolean getFeature(String featureId) { return false; }
+ public void setProperty(String propertyId, Object value) {}
+ public Object getProperty(String propertyId) { return null; }
+
+ public void parse(XMLInputSource source)
+ throws IOException, XNIException {
+
+ // get reader
+ openInputSourceStream(source);
+ Reader reader = source.getCharacterStream();
+ if (reader == null) {
+ InputStream stream = source.getByteStream();
+ reader = new InputStreamReader(stream);
+ }
+ BufferedReader bufferedReader = new BufferedReader(reader);
+
+ // start document
+ if (fDocumentHandler != null) {
+ fDocumentHandler.startDocument(null, "UTF-8");
+ fDocumentHandler.xmlDecl("1.0", "UTF-8", null);
+ fDocumentHandler.doctypeDecl("csv", null, null);
+ }
+ if (fDTDHandler != null) {
+ fDTDHandler.startDTD(null);
+ fDTDHandler.elementDecl("csv", "(row)*");
+ fDTDHandler.elementDecl("row", "(col)*");
+ fDTDHandler.elementDecl("col", "(#PCDATA)");
+ }
+ if (fDTDContentModelHandler != null) {
+ fDTDContentModelHandler.startContentModel("csv");
+ fDTDContentModelHandler.startGroup();
+ fDTDContentModelHandler.element("row");
+ fDTDContentModelHandler.endGroup();
+ short csvOccurs = XMLDTDContentModelHandler.OCCURS_ZERO_OR_MORE;
+ fDTDContentModelHandler.occurrence(csvOccurs);
+ fDTDContentModelHandler.endContentModel();
+
+ fDTDContentModelHandler.startContentModel("row");
+ fDTDContentModelHandler.startGroup();
+ fDTDContentModelHandler.element("col");
+ fDTDContentModelHandler.endGroup();
+ short rowOccurs = XMLDTDContentModelHandler.OCCURS_ZERO_OR_MORE;
+ fDTDContentModelHandler.occurrence(rowOccurs);
+ fDTDContentModelHandler.endContentModel();
+
+ fDTDContentModelHandler.startContentModel("col");
+ fDTDContentModelHandler.startGroup();
+ fDTDContentModelHandler.pcdata();
+ fDTDContentModelHandler.endGroup();
+ fDTDContentModelHandler.endContentModel();
+ }
+ if (fDTDHandler != null) {
+ fDTDHandler.endDTD();
+ }
+ if (fDocumentHandler != null) {
+ fDocumentHandler.startElement(CSV, EMPTY_ATTRS);
+ }
+
+ // read lines
+ String line;
+ while ((line = bufferedReader.readLine()) != null) {
+ if (fDocumentHandler != null) {
+ fDocumentHandler.startElement(ROW, EMPTY_ATTRS);
+ StringTokenizer tokenizer = new StringTokenizer(line, ",");
+ while (tokenizer.hasMoreTokens()) {
+ fDocumentHandler.startElement(COL, EMPTY_ATTRS);
+ String token = tokenizer.nextToken();
+ fStringBuffer.clear();
+ fStringBuffer.append(token);
+ fDocumentHandler.characters(fStringBuffer);
+ fDocumentHandler.endElement(COL);
+ }
+ fDocumentHandler.endElement(ROW);
+ }
+ }
+ bufferedReader.close();
+
+ // end document
+ if (fDocumentHandler != null) {
+ fDocumentHandler.endElement(CSV);
+ fDocumentHandler.endDocument();
+ }
+
+ }
+
+} // class CSVConfiguration]]></source>
+ </s3>
</s2>
- -->
</s1>
1.1.2.2 +20 -19 xml-xerces/java/docs/Attic/xni-design.xml
Index: xni-design.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/Attic/xni-design.xml,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -u -r1.1.2.1 -r1.1.2.2
--- xni-design.xml 2001/07/25 08:43:36 1.1.2.1
+++ xni-design.xml 2001/07/31 09:56:31 1.1.2.2
@@ -17,10 +17,23 @@
constructing these pipelines and parser configurations. This
document is designed to give you an overview of this framework
and what a parser looks like that is written to conform to the
- Xerces Native Interface.
+ Xerces Native Interface. An overview of these frameworks are
+ described below:
</p>
+ <ul>
+ <li><link anchor='pipeline'>Pipeline</link></li>
+ <li><link anchor='configuration'>Configuration</link></li>
+ </ul>
+ <p>
+ For more detailed information, refer to the following documents:
+ </p>
+ <ul>
+ <li><link idref='xni-core'>Core Interfaces</link></li>
+ <li><link idref='xni-config'>Parser Configuration</link></li>
+ </ul>
</s2>
- <s2 title='Parser Pipeline'>
+ <anchor name='pipeline'/>
+ <s2 title='Pipeline'>
<p>
The XNI parser pipeline is any combination of components that
are either capable of producing XNI events, consuming XNI events,
@@ -75,14 +88,15 @@
<p>
XNI defines the document information using a number of core
interfaces. (These interfaces are described in more detail in the
- <link idref='xni-api'>XNI API Documentation</link>.) But XNI also
- defines a set of interfaces to build parser configurations that
- assemble the pipelines in order to parse documents. The next
+ <link idref='xni-api-core'>Core API</link> documentation.) But XNI
+ also defines a set of interfaces to build parser configurations
+ that assemble the pipelines in order to parse documents. The next
section gives a general overview of the this parser configuration
provided by XNI.
</p>
</s2>
- <s2 title='Parser Configuration'>
+ <anchor name='configuration'/>
+ <s2 title='Configuration'>
<p>
A parser implementation written using the Xerces Native Interface
can be seen as a collection of components, some of which are
@@ -126,18 +140,5 @@
<p>
<img alt='Configuration and Parser Separation' src='xni-parser-configuration.gif'/>
</p>
- </s2>
- <s2 title='More Detailed Information'>
- <p>
- Take full advantage of the framework, you should at least be familiar
- with the Xerces Native Interface API. And if you want to create parser
- configurations from the existing library of parser parts, then you
- need to become familiar with the Xerces2 reference implementation. The
- following documents provide more information about XNI:
- </p>
- <ul>
- <li><link idref='xni-api'>API Documentation</link></li>
- <li><link idref='xni-config'>Parser Configuration</link></li>
- </ul>
</s2>
</s1>
1.1.2.5 +4 -3 xml-xerces/java/docs/Attic/xni.xml
Index: xni.xml
===================================================================
RCS file: /home/cvs/xml-xerces/java/docs/Attic/xni.xml,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- xni.xml 2001/07/30 08:21:56 1.1.2.4
+++ xni.xml 2001/07/31 09:56:31 1.1.2.5
@@ -37,7 +37,7 @@
<p>Design and implementation information:</p>
<ul>
<li><link idref='xni-design'>Design Details</link></li>
- <li><link idref='xni-api'>API Documentation</link></li>
+ <li><link idref='xni-core'>Core Interfaces</link></li>
<li><link idref='xni-config'>Parser Configuration</link></li>
</ul>
</s2>
@@ -109,7 +109,7 @@
</table>
<p>
For complete details of the Xerces Native Interface, refer to
- the <link idref='xni-api'>API Documentation</link>.
+ the <link idref='xni-core'>Core Interfaces</link> documentation.
</p>
</s2>
<anchor name='generic-parser-configurations'/>
@@ -159,7 +159,8 @@
This is just a small sample of what is possible when using the
XNI parser configuration framework. For complete details of the
XNI parser configurations, refer to the
- <link idref='xni-config'>Parser Configuration</link> documentation.
+ <link idref='xni-config'>Parser Configuration</link>
+ documentation.
</p>
</s2>
</s1>
No revision
No revision
1.1.2.1 +1347 -0 xml-xerces/java/docs/Attic/xni-core.xml
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org