docs/faq-xni.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE faqs SYSTEM 'dtd/faqs.dtd'>
<faqs title='Xerces Native Interface FAQs'>
  <faq title="Augmentations">
    <q>What are all these strange &quot;Augmentations&quot; parameters I see in so many methods?</q>
    <a>
        <p> They&apos;re intended to provide a way to augment the
        basic XML infoset available from the non-Augmentation
        parameters in the callbacks.  They can be used by a component to add arbitrary
        information to the streaming infoset, which can then
        be interpreted by some later component.</p>
        <p> For instance, a component can be written to transmit the
        post schema validation infoset through Augmentations
        callbacks.  This can then be translated into an XML
        representation.  This is exactly what is done in the PSVI
        Writer and PSVI Configuration samples--see <link
        idref="samples-xni">XNI sample documentation</link> for
        details.</p>
    </a>
 </faq>
 <faq title='Overriding Default Parser Configuration'>
  <q>How do I change the default parser configuration?</q>
  <a>
   <anchor name="override-default-config"/>
   <p>
    It is possible to override the default parser configuration used
    by the Xerces2 parsers without writing any code or changing the
    existing parser classes. Moreover, the DOM and SAX parsers created
    using the JAXP interfaces will use the specified parser configuration
    transparently and without need to call additional methods to set the
    parser configuration.
   </p>
   <p>
    The DOM and SAX parsers decide which parser configuration to use in
    the following order:
   </p>
   <ol>
    <li>
     First, the <code>org.apache.xerces.xni.parser.XMLParserConfiguration</code>
     system property is queried for the class name of the parser configuration.
    </li>
    <li>
     Next, if a file called <code>xerces.properties</code> exists in the lib
     subdirectory of the JRE installation and the 
     <code>org.apache.xerces.xni.parser.XMLParserConfiguration</code> property
     is defined it, then its value will be read from the file.
    </li>
    <li>
     Next, the <code>org.apache.xerces.xni.parser.XMLParserConfiguration</code>
     file is requested from the <code>META-INF/services/</code> directory. 
     This file contains the class name of the parser configuration.
    </li>
    <li>
     Finally, the <code>&DefaultConfigLong;</code>
     is used as the default parser configuration.
    </li>
   </ol>
   <note>
    In all cases, the parser configuration class must have a public,
    no argument constructor so that it can be instantiated dynamically.
   </note>
   <p>
    When using Java 2, it is not necessary to rebuild the Xerces jar files
    in order to override the default parser configuration using the first
    method. As long as a JAR file containing the appropriate file exists
    in the <code>META-INF/services/</code> directory appears <em>before</em>
    the Xerces JAR files, the parser will use the new parser configuration.
   </p>
   <p>
    The first method can always be used on the command line for the JVM
    by using the <code>-D</code> option. For example, to override the
    default parser configuration using a custom configuration named
    <code>MyConfig</code>, use the following command line:
   </p>
   <source>java -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=MyConfig application_class</source>
  </a>
 </faq>
</faqs>