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/08/22 12:45:10 UTC

cvs commit: xml-xerces/java/docs xni-design.xml xni-xerces2.xml

andyc       01/08/22 03:45:10

  Modified:    java/docs Tag: xerces_j_2 xni-design.xml xni-xerces2.xml
  Log:
  Added more XNI documentation regarding how to use the standard
  components in the Xerces2 reference implementation. Still needs
  to be finished.
  
  Revision  Changes    Path
  No                   revision
  
  
  No                   revision
  
  
  1.1.2.4   +1 -0      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.3
  retrieving revision 1.1.2.4
  diff -u -r1.1.2.3 -r1.1.2.4
  --- xni-design.xml	2001/08/21 10:32:46	1.1.2.3
  +++ xni-design.xml	2001/08/22 10:45:10	1.1.2.4
  @@ -30,6 +30,7 @@
     <ul>
      <li><link idref='xni-core'>Core Interfaces</link></li>
      <li><link idref='xni-config'>Parser Configuration</link></li>
  +   <li><link idref='xni-xerces2'>Xerces2 Parser Components</link></li>
     </ul>
    </s2>
    <anchor name='pipeline'/>
  
  
  
  1.1.2.2   +354 -7    xml-xerces/java/docs/Attic/xni-xerces2.xml
  
  Index: xni-xerces2.xml
  ===================================================================
  RCS file: /home/cvs/xml-xerces/java/docs/Attic/xni-xerces2.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-xerces2.xml	2001/08/21 10:32:46	1.1.2.1
  +++ xni-xerces2.xml	2001/08/22 10:45:10	1.1.2.2
  @@ -1,30 +1,377 @@
   <?xml version='1.0' encoding='UTF-8'?>
   <!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
   <s1 title='Xerces2 Components'>
  - <s2 title='Reusing Xerces2 Parser Components'>
  + <s2 title='Re-using Xerces2 Parser Components'>
     <p>
      The Xerces Native Interface (XNI) defines a general way to build
      parser components and configurations. The Xerces2 reference
      implementation is written using this framework so that the parser
  -   components can be reused to create new parser configurations. In
  -   order to reuse the Xerces2 parser components, however, the
  +   components can be re-used to create new parser configurations. In
  +   order to re-use the Xerces2 parser components, however, the
      developer must know the dependencies of each standard component.
      This document provides an overview of the Xerces2 parser components
      and lists the relevent dependencies.
     </p>
     <p>
  -   An overview of the general dependencies and the dependicies for
  +   An overview of the general dependencies and the dependencies for
      each standard component are detailed below:
     </p>
     <ul>
      <li><link anchor='overview'>Overview</link></li>
  -   <li><strong>TODO</strong></li>
  +   <li>Fundamental Dependencies</li>
  +   <ul>
  +    <li><link anchor='symbol-table'>Symbol Table</link></li>
  +    <li><link anchor='error-reporter'>Error Reporter</link></li>
  +   </ul>
  +   <li>Individual Component Dependencies</li>
  +   <ul>
  +    <li><link anchor='document-scanner'>Document Scanner</link></li>
  +    <li><link anchor='dtd-scanner'>DTD Scanner</link></li>
  +    <li><link anchor='entity-manager'>Entity Manager</link></li>
  +    <li><link anchor='dtd-validator'>DTD Validator</link></li>
  +    <li><link anchor='namespace-binder'>Namespace Binder</link></li>
  +    <!--
  +      - NOTE: This is to be added in when XML Schema support is
  +      -       implemented in the Xerces2 reference implementation.
  +    <li><link anchor='schema-validator'>Schema Validator</link></li>
  +    -->
  +   </ul>
  +   <!-- NOTE:
  +     - More components and their dependencies may be added as
  +     - they are made and integrated into the standard Xerces2
  +     - configuration.
  +     -->
     </ul>
    </s2>
    <anchor name='overview'/>
    <s2 title='Overview'>
     <p>
  -   <strong>TODO</strong>
  +   The standard parser configuration for the Xerces2 reference
  +   implementation of XNI is defined in the
  +   <code>org.apache.xerces.parsers.StandardParserConfiguration</code>
  +   class. This configuration is comprised of a number of 
  +   components. Some of these components are configurable and some 
  +   are shared within the configuration but do not implement the
  +   <link idref='xni-config' anchor='component'>XMLComponent</link>
  +   interface.
     </p>
  +  <p>
  +   The following list details the set of components used in the 
  +   Xerces2 standard configuration. The components marked with an
  +   asterisk (*) are configurable.
  +  </p>
  +  <ul>
  +   <li>Symbol Table</li>
  +   <li>Error Reporter (*)</li>
  +   <li>Document Scanner (*)</li>
  +   <li>DTD Scanner (*)</li>
  +   <li>Entity Manager (*)</li>
  +   <li>DTD Validator (*)</li>
  +   <li>Namespace Binder (*)</li>
  +   <li>Schema Validator (*)</li>
  +  </ul>
  +  <note>
  +   As of this writing, the Schema Validator does not exist in the
  +   Xerces2 standard configuration because XML Schema is not yet
  +   supported. When it is supported, the Schema Validator will be
  +   added to this documentation.
  +  </note>
  +  <note>
  +   There are additional components other than those in the above
  +   list, such as the "Grammar Pool" and "Datatype Validator
  +   Factory". However, the validation engine in the Xerces2
  +   reference implementation is currently being re-designed and
  +   re-implemented. Therefore, these components are subject to
  +   change and should not be used or relied upon.
  +  </note>
  +  <p>
  +   In general, there are levels of dependency among the components
  +   in the standard configuration. Some components are required by
  +   all of the configurable components, where as there are certain
  +   components required by other components. The following diagram
  +   illustrates these basic levels of dependency.
  +  </p>
  +  <p>
  +   <img alt='Xerces2 Component Dependencies' src='xni-components-dependence.gif'/>
  +  </p>
  +  <p>
  +   The dependencies of each component are detailed in subsequent
  +   sections of this document but the basic dependencies are 
  +   listed below:
  +  </p>
  +  <ul>
  +   <li>
  +    All of the configurable Xerces2 components in the standard 
  +    configuration depend on the 
  +    "<link anchor='symbol-table'>Symbol Table</link>" and the
  +    "<link anchor='error-reporter'>Error Reporter</link>".
  +   </li>
  +   <li>
  +    Both the "<link anchor='document-scanner'>Document Scanner</link>"
  +    and the "<link anchor='dtd-scanner'>DTD Scanner</link>" depend 
  +    on the "<link anchor='entity-manager'>Entity Manager</link>"
  +    component.
  +   </li>
  +   <li>
  +    In addition to the other dependencies, the 
  +    "<link anchor='document-scanner'>Document Scanner</link>" also
  +    depends on the 
  +    "<link anchor='dtd-scanner'>DTD Scanner</link>" for scanning of
  +    the internal and external subsets of the DTD.
  +   </li>
  +  </ul>
  +  <p>
  +   Each configurable component queries the components that it
  +   depends on before each document is parsed. The configuration 
  +   is required to call the 
  +   <link idref='xni-config' anchor='component'>XMLComponent</link>'s 
  +   "reset" method. From the 
  +   <link idref='xni-config' anchor='component-manager'>XMLComponentManager</link>
  +   object that is passed to the "reset" method, the component
  +   can query the other components that it needs. Therefore, each
  +   component is assigned a unique property identifier used to
  +   query the components from the component manager.
  +  </p>
  +  <p>
  +   The following example source code shows how one of the
  +   standard Xerces2 components is queried within a configurable
  +   component. However, for complete dependency details and the 
  +   property identifiers defined for each component, refer to the
  +   appropriate sections of this document.
  +  </p>
  +  <source><![CDATA[import org.apache.xerces.xni.parser.XMLComponent;
  +import org.apache.xerces.xni.parser.XMLComponentManager;
  +import org.apache.xerces.xni.parser.XMLConfigurationException;
  +
  +public class MyComponent
  +    implements XMLComponent {
  +    
  +    // Constants
  +    
  +    public static final String SYMBOL_TABLE =
  +        "http://apache.org/xml/properties/internal/symbol-table";
  +
  +    // XMLComponent methods
  +    
  +    public void reset(XMLComponentManager manager)
  +        throws XMLConfigurationException {
  +        SymbolTable symbolTable = 
  +	    (SymbolTable)manager.getProperty(SYMBOL_TABLE);
  +    }
  +
  +}]]></source>
  + </s2>
  + <anchor name='symbol-table'/>
  + <s2 title='Symbol Table'>
  +  <p>Property information:</p>
  +  <table>
  +   <tr>
  +    <th>Property Id</th>
  +    <td>http://apache.org/xml/properties/internal/symbol-table</td>
  +   </tr>
  +   <tr>
  +    <th>Type</th>
  +    <td>org.apache.xerces.util.SymbolTable</td>
  +   </tr>
  +  </table>
  +  <p>
  +   For performance reasons, the Xerces2 reference implementation
  +   uses a custom symbol table in order to re-use common strings
  +   that appear in the document. The symbol table is responsible
  +   for keeping track of these common strings and always return
  +   the same <code>java.lang.String</code> reference for lexically
  +   equivalent strings. This not only reduces the amount of unique
  +   objects created while parsing, it also allows components (e.g.
  +   the validators, etc) to perform comparisons directly on the
  +   references for certain string objects without having to call
  +   the "equals" method.
  +  </p>
  +  <p>
  +   <strong>Note:</strong> 
  +   Nearly all of the standard components depend on this component.
  +   Therefore, if you write a parser configuration that re-uses any
  +   of the standard components, you must have an instance of this
  +   component registered with the appropriate property identifier.
  +  </p>
  + </s2>
  + <anchor name='error-reporter'/>
  + <s2 title='Error Reporter'>
  +  <p>Property information:</p>
  +  <table>
  +   <tr>
  +    <th>Property Id</th>
  +    <td>http://apache.org/xml/properties/internal/error-reporter</td>
  +   </tr>
  +   <tr>
  +    <th>Type</th>
  +    <td>org.apache.xerces.impl.XMLErrorReporter</td>
  +   </tr>
  +  </table>
  +  <p>Recognized features:</p>
  +  <ul>
  +   <li>http://apache.org/xml/features/continue-after-fatal-error</li>
  +  </ul>
  +  <p>Recognized properties:</p>
  +  <ul>
  +   <li>http://apache.org/xml/properties/internal/error-handler</li>
  +  </ul>
  +  <p>
  +   In any parser instance, there must be a way for components to
  +   report errors in a uniform way. The "Error Reporter" component
  +   serves this purpose and simplifies the process of localizing
  +   error messages and notifying the registered
  +   <link idref='xni-parser' anchor='error-handler'>XMLErrorHandler</link>.
  +  </p>
  +  <p>
  +   In general, errors are identified by the domain of the error 
  +   and a unique key within that domain. The XMLErrorReporter class
  +   allows message formatters to be set for each domain and then
  +   delegates the formatting of error messages (with replacement
  +   text) to the message formatter assigned to that error domain.
  +   The localized error message is then sent to the registered
  +   error handler.
  +  </p>
  +  <p>
  +   An error message formatter is any class that implements the
  +   <code>org.apache.xerces.util.MessageFormatter</code> interface.
  +   If you write a new parser component for use with the existing
  +   Xerces2 components, you should implement your own message 
  +   formatter and register it with the Error Reporter. For
  +   example:
  +  </p>
  +  <source><![CDATA[import java.util.Locale;
  +import java.util.MissingResourceException;
  +import org.apache.xerces.util.MessageFormatter;
  +
  +public class MyFormatter
  +    implements MessageFormatter {
  +
  +    // MessageFormatter methods
  +    
  +    public String formatMessage(Locale locale, String key, Object[] args)
  +        throws MissingResourceException {
  +        // localize and format message based on locale, key, 
  +	// and replacement text arguments
  +	return "MY ERROR ("+key+")";
  +    }
  +
  +}]]></source>
  +  <source><![CDATA[import org.apache.xerces.impl.XMLErrorReporter;
  +import org.apache.xerces.xni.parser.XMLComponent;
  +import org.apache.xerces.xni.parser.XMLComponentManager;
  +import org.apache.xerces.xni.parser.XMLConfigurationException;
  +
  +public class MyComponent
  +    implements XMLComponent {
  +    
  +    // Constants
  +    
  +    public static final String ERROR_REPORTER =
  +        "http://apache.org/xml/properties/internal/error-reporter";
  +
  +    public static final String DOMAIN = "http://example.com/mydomain";
  +
  +    // XMLComponent methods
  +    
  +    public void reset(XMLComponentManager manager)
  +        throws XMLConfigurationException {
  +        XMLErrorReporter reporter = 
  +	    (XMLErrorReporter)manager.getProperty(ERROR_REPORTER);
  +	if (reporter.getMessageFormatter(DOMAIN) == null) {
  +	    reporter.putMesssageFormatter(DOMAIN, new MyFormatter());
  +	}
  +    }
  +
  +}]]></source>
  +  <p>
  +   <strong>Note:</strong>
  +   It is <em>strongly</em> encouraged that any new error domains
  +   that you create follow the standard URI syntax. While there is
  +   no requirement that the URI must point to an actual resource on 
  +   the Internet, it is a common way to separate domains and it
  +   provides more useful information to the application. 
  +  </p>
  +  <p>
  +   <strong>Note:</strong> 
  +   Nearly all of the standard components depend on this component.
  +   Therefore, if you write a parser configuration that re-uses any
  +   of the standard components, you must have an instance of this
  +   component registered with the appropriate property identifier.
  +  </p>
  + </s2>
  + <anchor name='document-scanner'/>
  + <s2 title='Document Scanner'>
  +  <p>Property information:</p>
  +  <table>
  +   <tr>
  +    <th>Property Id</th>
  +    <td>http://apache.org/xml/properties/internal/document-scanner</td>
  +   </tr>
  +   <tr>
  +    <th>Type</th>
  +    <td>org.apache.xerces.xni.parser.XMLDocumentScanner</td>
  +   </tr>
  +  </table>
  +  <p><strong>TODO</strong></p>
  + </s2>
  + <anchor name='dtd-scanner'/>
  + <s2 title='DTD Scanner'>
  +  <p>Property information:</p>
  +  <table>
  +   <tr>
  +    <th>Property Id</th>
  +    <td>http://apache.org/xml/properties/internal/dtd-scanner</td>
  +   </tr>
  +   <tr>
  +    <th>Type</th>
  +    <td>org.apache.xerces.xni.parser.XMLDTDScanner</td>
  +   </tr>
  +  </table>
  +  <p><strong>TODO</strong></p>
  + </s2>
  + <anchor name='entity-manager'/>
  + <s2 title='Entity Manager'>
  +  <p>Property information:</p>
  +  <table>
  +   <tr>
  +    <th>Property Id</th>
  +    <td>http://apache.org/xml/properties/internal/entity-manager</td>
  +   </tr>
  +   <tr>
  +    <th>Type</th>
  +    <td>org.apache.xerces.impl.XMLEntityManager</td>
  +   </tr>
  +  </table>
  +  <p><strong>TODO</strong></p>
  + </s2>
  + <anchor name='dtd-validator'/>
  + <s2 title='DTD Validator'>
  +  <p>Property information:</p>
  +  <table>
  +   <tr>
  +    <th>Property Id</th>
  +    <td>http://apache.org/xml/properties/internal/validator/dtd</td>
  +   </tr>
  +   <tr>
  +    <th>Type</th>
  +    <td>org.apache.xerces.impl.XMLDTDValidator</td>
  +   </tr>
  +  </table>
  +  <p><strong>TODO</strong></p>
  + </s2>
  + <anchor name='namespace-binder'/>
  + <s2 title='Namespace Binder'>
  +  <p>Property information:</p>
  +  <table>
  +   <tr>
  +    <th>Property Id</th>
  +    <td>http://apache.org/xml/properties/internal/namespace-binder</td>
  +   </tr>
  +   <tr>
  +    <th>Type</th>
  +    <td>org.apache.xerces.impl.XMLNamespaceBinder</td>
  +   </tr>
  +  </table>
  +  <p><strong>TODO</strong></p>
    </s2>
  -</s1>
  +</s1> 
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org