| Setting Features |

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.

The DocumentBuilderFactory interface contains a `setAttribute(String,Object)` method which may 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:

    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");
    }

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:

    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");
    }

| General Features |

| http://xml.org/sax/features/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.
False: | Do not perform namespace processing.
Default: | 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.
See: | http://xml.org/sax/features/namespace-prefixes
See: | http://xml.org/sax/features/validation

| http://xml.org/sax/features/validation |

True: | Validate the document and report validity errors.
False: | Do not report validity errors.
Default: | 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 FAQ. 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.
See: | http://apache.org/xml/features/validation/dynamic
See: | http://xml.org/sax/features/namespaces
See: | http://apache.org/xml/features/nonvalidating/load-external-dtd

| http://apache.org/xml/features/validation/dynamic |

True: | The parser will validate the document only if a grammar is specified.
False: | Validation is determined by the state of the validation feature.
Default: | false
See: | http://xml.org/sax/features/validation

| http://apache.org/xml/features/validation/schema |

True: | Turn on XML Schema validation by inserting XML Schema validator in the pipeline.
False: | Do not report validation errors against XML Schema.
Default: | false
Access: | (parsing) read-only; (not parsing) read-write;
Note: | Validation errors will only be reported if validation feature is set to true. For more information, please, refer to the FAQ
See: | http://xml.org/sax/features/validation
See: | http://apache.org/xml/features/validation/dynamic
See: | http://xml.org/sax/features/namespaces

| http://apache.org/xml/features/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.
False: | Disable full constraint checking.
Default: | false
Note: | This feature checks the Schema grammar itself for additional errors that are time-consuming or memory intensive. It does not affect the level of checking performed on document instances that use Schema grammars.

| http://apache.org/xml/features/validation/schema/normalized-value |

True: | Expose via SAX and DOM XML Schema normalized values for attributes and elements.
False: | Expose the infoset values
Default: | true
Access: | (parsing) read-only; (not parsing) read-write;
Note: | XML Schema normalized values will be exposed only if both schema validation and validation features are set to true.
See: | http://xml.org/sax/features/validation
See: | http://apache.org/xml/features/validation/schema
See: | http://apache.org/xml/features/validation/schema/element-default

| http://apache.org/xml/features/validation/schema/element-default |

True: | Send XML Schema element default values via characters().
False: | Do not send XML Schema default values in XNI
Default: | true
Access: | (parsing) read-only; (not parsing) read-write;
Note: | XML Schema default values will be send via characters() if both schema validation and validation features are set to true.
See: | http://xml.org/sax/features/validation
See: | http://apache.org/xml/features/validation/schema
See: | http://apache.org/xml/features/validation/schema/normalized-value

| http://apache.org/xml/features/validation/schema/augment-psvi |

True: | Augment Post-Schema-Validation-Infoset.
False: | Do not augment Post-Schema-Validation-Infoset.
Default: | true
Access: | (parsing) read-only; (not parsing) read-write;
Note: | This feature can be turned off to improve parsing performance.
See: | http://xml.org/sax/features/validation
See: | http://apache.org/xml/features/validation/schema

| http://xml.org/sax/features/external-general-entities |

True: | Include external general entities.
False: | Do not include external general entities.
Default: | true
Access: | (parsing) read-only; (not parsing) read-write;
See: | http://xml.org/sax/features/external-parameter-entities

| http://xml.org/sax/features/external-parameter-entities |

True: | Include external parameter entities and the external DTD subset.
False: | Do not include external parameter entities or the external DTD subset.
Default: | true
Access: | (parsing) read-only; (not parsing) read-write;
See: | http://xml.org/sax/features/external-general-entities

| http://apache.org/xml/features/validation/warn-on-duplicate-attdef |

True: | Report a warning when a duplicate attribute is re-declared.
False: | Do not report a warning when a duplicate attribute is re-declared.
Default: | false

| http://apache.org/xml/features/validation/warn-on-undeclared-elemdef |

True: | Report a warning if an element referenced in a content model is not declared.
False: | Do not report a warning if an element referenced in a content model is not declared.
Default: | false

| http://apache.org/xml/features/warn-on-duplicate-entitydef |

True: | Report a warning for duplicate entity declaration.
False: | Do not report warning for duplicate entity declaration.
Default: | false

| http://apache.org/xml/features/allow-java-encodings |

True: | Allow Java encoding names in XMLDecl and TextDecl line.
False: | Do not allow Java encoding names in XMLDecl and TextDecl line.
Default: | 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.

| http://apache.org/xml/features/continue-after-fatal-error |

True: | Attempt to continue parsing after a fatal error.
False: | Stops parse on first fatal error.
Default: | false
Note: | The behavior of the parser when this feature is set to `true` is undetermined! Therefore use this feature with extreme caution because the parser may get stuck in an infinite loop or worse.

| http://apache.org/xml/features/nonvalidating/load-dtd-grammar |

True: | Load the DTD and use it to add default attributes and set attribute types when parsing.
False: | Build the grammar but do not use the default attributes and attribute types information it contains.
Default: | true
Note: | This feature is always on when validation is on.
See: | http://xml.org/sax/features/validation
See: | http://apache.org/xml/features/nonvalidating/load-external-dtd

| http://apache.org/xml/features/nonvalidating/load-external-dtd |

True: | Load the external DTD.
False: | Ignore the external DTD completely.
Default: | true
Note: | This feature is always on when validation is on.
See: | http://xml.org/sax/features/validation
See: | http://apache.org/xml/features/nonvalidating/load-dtd-grammar

| http://apache.org/xml/features/scanner/notify-char-refs |

True: | Notifies the handler of character entity boundaries in the document via the start/endEntity callbacks.
False: | Does not notify of character entity boundaries.
Default: | false
See: | http://apache.org/xml/features/scanner/notify-builtin-refs

| http://apache.org/xml/features/scanner/notify-builtin-refs |

True: | Notifies the handler of built-in entity boundaries (e.g &amp;) in the document via the start/endEntity callbacks.
False: | Does not notify of built-in entity boundaries.
Default: | false
See: | http://apache.org/xml/features/scanner/notify-char-refs

| http://apache.org/xml/features/disallow-doctype-decl |

True: | A fatal error is thrown if the incoming document contains a DOCTYPE declaration.
False: | DOCTYPE declaration is allowed.
Default: | false

| http://apache.org/xml/features/standard-uri-conformant |

True: | Requires that a URI has to be provided where a URI is expected.
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).
Default: | 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.

| DOM Features |

| http://apache.org/xml/features/dom/defer-node-expansion |

True: | Lazily expand the DOM nodes.
False: | Fully expand the DOM nodes.
Default: | true**
Note: | In the `DOMBuilder` implementation the default value of this feature is false.
Note: | 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.

| http://apache.org/xml/features/dom/create-entity-ref-nodes |

True: | Create EntityReference nodes in the DOM tree. The EntityReference nodes and their child nodes will be read-only.
False: | Do not create EntityReference nodes in the DOM tree. No EntityReference nodes will be created, only the nodes corresponding to their fully expanded sustitution text will be created.
Default: | true
Note: | This feature only affects the appearance of `EntityReference` nodes in the DOM tree. The document will always contain the entity reference child nodes.

| http://apache.org/xml/features/dom/include-ignorable-whitespace |

True: | Include text nodes that can be considered "ignorable whitespace" in the DOM tree.
False: | Do not include ignorable whitespace in the DOM tree.
Default: | 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 `TextImpl#isIgnorableWhitespace():boolean` method. This feature is relevant only when the grammar is DTD.

| SAX Features |

| http://xml.org/sax/features/namespace-prefixes |

True: | Report the original prefixed names and attributes used for namespace declarations.
False: | Do not report attributes used for Namespace declarations, and optionally do not report original prefixed names.
Default: | false
Access: | (parsing) read-only; (not parsing) read-write;

| http://xml.org/sax/features/string-interning |

True: | All element names, prefixes, attribute names, namespace URIs, and local names are internalized using the java.lang.String#intern(String):String method.
False: | Names are not necessarily internalized.
Default: | true
Access: | (parsing) read-only; (not parsing) read-write;
Note: | Xerces-J always internalizes all strings mentioned above using the `String#intern()` method. This feature can only be set to true.

Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.