<?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 {
    parser.setFeature("http://xml.org/sax/features/allow-java-encodings", 
                      true);
} 
catch (SAXException e) {
    System.err.println("could not set parser feature");
}</source>
  <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>
    &ParserName; does not support interning all strings using the 
    <code>String#intern()</code> method because &ParserName; does its
    own intern optimizations for String objects.
   </note>
  </feature>
 </fcategory>
</features>
