<?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://apache.org/xml/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 and report validity errors.</true>
   <false>Do not report validity errors.</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. By default, validation will occur against DTD. For more information, please, refer to the  <link idref='faq-pcfp'>FAQ</link>.
    If this feature is set to false, and document specifies a grammar 
    that grammar might be parsed but no validation of the document contents 
    will be performed.
   </note>
   <see idref='validation.dynamic'/>
   <see idref='namespaces'/>
   <see idref='nonvalidating.load-external-dtd'/>
  </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>
  <feature name='http://apache.org/xml/features/validation/schema'
           id='validation.schema'>
   <true>Turn on XML Schema validation by inserting XML Schema validator in the pipeline.
   </true>
   <false>Do not report validation errors against XML Schema.</false>
   <default value='false'/>   
   <access parsing='read-only' not-parsing='read-write'/>
   <note> Validation errors will only be reported if <link anchor="validation">validation feature</link> is set to true. For more information, please, refer to the <link idref='faq-pcfp'>FAQ</link>
   </note>  
   <see idref='validation'/>
   <see idref='validation.dynamic'/>
   <see idref='namespaces'/>
  </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://apache.org/xml/features/validation/schema/normalized-value'
           id='validation.schema.normalized-value'>
   <true>Expose via SAX and DOM XML Schema normalized values for attributes and elements.
   </true>
   <false>Expose the infoset values</false>
   <default value='true'/>   
   <access parsing='read-only' not-parsing='read-write'/>
   <note> XML Schema normalized values will be exposed only if 
          both <link anchor="validation.schema">schema validation</link> and
          <link anchor="validation">validation</link> features are set to true. 
   </note>  
   <see idref='validation'/>
   <see idref='validation.schema'/> 
   <see idref='validation.schema.element-default'/>
  </feature>
  
   <feature name='http://apache.org/xml/features/validation/schema/element-default'
           id='validation.schema.element-default'>
   <true>Send XML Schema element default values via characters().
   </true>
   <false>Do not send XML Schema default values in XNI</false>
   <default value='true'/>   
   <access parsing='read-only' not-parsing='read-write'/>
   <note> XML Schema default values will be send via characters() if both <link anchor="validation.schema">schema validation</link> and
          <link anchor="validation">validation</link> features are set to true.
   </note>  
   <see idref='validation'/>
   <see idref='validation.schema'/>
   <see idref='validation.schema.normalized-value'/>
  </feature>

  <feature name='http://apache.org/xml/features/validation/schema/augment-psvi'
           id='validation.schema.augment-psvi'>
   <true>Augment Post-Schema-Validation-Infoset.</true>
   <false>Do not augment Post-Schema-Validation-Infoset.</false>
   <default value='true'/>
   <access parsing='read-only' not-parsing='read-write'/>
   <note> This feature can be turned off to improve parsing performance. 
   </note>  
   <see idref='validation'/>
   <see idref='validation.schema'/> 
  </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='false'/>
  </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='false'/>
  </feature>
  
  <feature name='http://apache.org/xml/features/warn-on-duplicate-entitydef'
           id='warn-on-duplicate-entitydef'>
   <true>Report a warning for duplicate entity declaration.</true>
   <false>
    Do not report warning for duplicate entity declaration.
   </false>
   <default value='false'/>
  </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>

  <feature name='http://apache.org/xml/features/scanner/notify-char-refs'
           id='scanner.notify-char-refs'>
   <true>
    Notifies the handler of character entity boundaries in the
    document via the start/endEntity callbacks.
   </true>
   <false>Does not notify of character entity boundaries.</false>
   <default value='false'/>
   <see idref='scanner.notify-builtin-refs'/>
  </feature>

  <feature name='http://apache.org/xml/features/scanner/notify-builtin-refs'
           id='scanner.notify-builtin-refs'>
   <true>
    Notifies the handler of built-in entity boundaries (e.g &amp;amp;)
    in the document via the start/endEntity callbacks.
   </true>
   <false>Does not notify of built-in entity boundaries.</false>
   <default value='false'/>
   <see idref='scanner.notify-char-refs'/>
  </feature>

  <feature name='http://apache.org/xml/features/disallow-doctype-decl'
           id='disallow-doctype-decl'>
   <true>
    A fatal error is thrown if the incoming document contains a DOCTYPE
    declaration.
   </true>
   <false>DOCTYPE declaration is allowed.</false>
   <default value='false'/>
  </feature>

  <feature name='http://apache.org/xml/features/standard-uri-conformant'
           id='standard-uri-conformant'>
   <true>Requires that a URI has to be provided where a URI is expected.</true>
   <false>
    Some invalid URI's are accepted as valid values when a URI is expected.
    Examples include: using platform dependent file separator in place of '/';
    using Windows/DOS path names like "c:\blah" and "\\host\dir\blah"; using
    invalid URI characters (space, for example).
   </false>
   <default value='false'/>
   <note>
    It's recommended to set this feature to true if you want your
    application/documents to be truly portable across different XML processors.
   </note>
  </feature>

 </fcategory>
 <fcategory name='DOM Features'>
  <feature name='http://apache.org/xml/features/dom/defer-node-expansion'
           id="dom.defer-node-expansion">
   <true>
    Lazily expand the DOM nodes.
   </true>
   <false>
    Fully expand the DOM nodes.
   </false>
   <default value='true**'/>
   <note>In the <code>DOMBuilder</code> implementation the default value of 
    this feature is <strong>false</strong>. 
   </note>
   <note>
<!--
    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.
-->
    When this feature is set to true, the DOM nodes in the returned document
    are expanded as the tree is traversed. This 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.
    </note>

  </feature>
  <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>
    Include text nodes that can be considered "ignorable whitespace" in 
    the DOM tree.
   </true>
   <false>Do 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. 
    This feature is relevant only when the grammar is <strong>DTD</strong>. 
   </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='false'/>
   <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='true'/>
   <access parsing='read-only' not-parsing='read-write'/>
   <note>
    &ParserName; always internalizes all strings mentioned above
    using the <code>String#intern()</code> method. This feature
    can only be set to true.
   </note>
  </feature>
 </fcategory>
</features>
