Features


	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 &) 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.


	XInclude Features (Experimental)


	http://xml.org/sax/features/allow-dtd-events-after-endDTD

True:	Allows notationDecl and unparsedEntityDecl events to be sent in the XNI pipeline after the endDTD event has been sent.
False:	Ensures that notationDecl and unparsedEntityDecl events are not sent after the endDTD event has been sent (default SAX behaviour).
Default:	true**
Note:	The default value for this feature is true, except when using SAX, because SAX requires that no DTD events be sent after the `endDTD` event. Thus, in order to maintain SAX compatibility, this feature cannot be true by default for SAX. Setting this feature to false can result in loss of information, if notations and unparsed entities were needed to resolve references in the document.
Note:	This feature is only relevant when XInclude processing is being done. Due to the nature of implementing XInclude in a stream-based API, it is not possible to know the complete set of required unparsed entities and notations before the `endDTD` event from the source document is sent. If an `XIncludeHandler` is not present in your pipeline, the value of this feature is irrelevant.
Note:	This feature is currently experimental, and might be removed or changed in the next release. If you have any concerns or suggestions about its use, please contact the xerces-j-user mailing list.