http://xml.apache.org/http://www.apache.org/http://www.w3.org/

Home

Readme
Charter
Release Info

Installation
Download
Bug-Reporting

FAQs
Samples
API JavaDoc

Features
Properties

XNI Manual
XML Schema
SAX
DOM
Limitations

Source Repository
User Mail Archive
Dev Mail Archive

Setting Features
 

If you have created a DOM document builder or a SAX parser using the JAXP 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 setFeature(String,boolean) method which can be used to set features on the underlying parser. For example:

import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
  
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);

try {
    dbf.setFeature("http://apache.org/xml/features/allow-java-encodings", 
                   true);
} 
catch (ParserConfigurationException e) {
    System.err.println("could not set parser feature");
}

The SAXParserFactory interface contains a setFeature(String,boolean) method which can be used to set features on the underlying implementation of XMLReader. Once you create the SAXParser you can retrieve the underlying XMLReader allowing you to set and query features on it directly. 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/use-entity-resolver2
 
True:  The methods of the org.xml.sax.ext.EntityResolver2 interface will be used when an object implementing this interface is registered with the parser using setEntityResolver.  
False:  The methods of the org.xml.sax.ext.EntityResolver2 interface will not be used.  
Default:  true 
Access:  read-write 
Since:  Xerces-J 2.7.0 
Note:  If the disallow DOCTYPE declaration feature is set to true org.xml.sax.ext.EntityResolver2.getExternalSubset() will not be called when the document contains no DOCTYPE declaration.  
See:  http://apache.org/xml/features/disallow-doctype-decl 
See:  http://xml.org/sax/features/validation 
See:  http://apache.org/xml/features/nonvalidating/load-external-dtd 

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 an XML Schema validator into 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 the validation feature is set to true. For more information, please, refer to the FAQ  
Note:  Checking of constraints on a schema grammar which are either time-consuming or memory intensive such as unique particle attribution will only occur if the schema full checking feature is set to true.  
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, unique particle attribution constraint checking and particle derivation restriction 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://apache.org/xml/features/generate-synthetic-annotations
 
True:  Enable generation of synthetic annotations. A synthetic annotation will be generated when a schema component has non-schema attributes but no child annotation. 
False:  Do not generate synthetic annotations. 
Default:  false 
Access:  (parsing) read-only; (not parsing) read-write;  
Since:  Xerces-J 2.7.0 
See:  http://xml.org/sax/features/validation 
See:  http://apache.org/xml/features/validation/schema 
See:  http://apache.org/xml/features/validate-annotations 

http://apache.org/xml/features/validate-annotations
 
True:  Schema annotations will be laxly validated against available schema components. 
False:  Do not validate schema annotations. 
Default:  false 
Access:  (parsing) read-only; (not parsing) read-write;  
Since:  Xerces-J 2.7.0 
See:  http://xml.org/sax/features/validation 
See:  http://apache.org/xml/features/validation/schema 
See:  http://apache.org/xml/features/generate-synthetic-annotations 

http://apache.org/xml/features/honour-all-schemaLocations
 
True:  All schema location hints will be used to locate the components for a given target namespace. 
False:  Only the first schema location hint encountered by the processor will be used to locate the components for a given target namespace. 
Default:  false 
Access:  (parsing) read-only; (not parsing) read-write;  
Since:  Xerces-J 2.7.0 

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 
Since:  Xerces-J 2.3.0 

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 
Since:  Xerces-J 2.3.0 
Note:  It's recommended to set this feature to true if you want your application/documents to be truly portable across different XML processors.  

http://apache.org/xml/features/xinclude
 
True:  Enable XInclude processing. 
False:  Do not perform XInclude processing. 
Default:  false 
Since:  Xerces-J 2.7.0 
See:  http://apache.org/xml/features/xinclude/fixup-base-uris 
See:  http://apache.org/xml/features/xinclude/fixup-language 

http://apache.org/xml/features/xinclude/fixup-base-uris
 
True:  Perform base URI fixup as specified by the XInclude Recommendation. 
False:  Do not perform base URI fixup. The XInclude processor will not add xml:base attributes. 
Default:  true 
Since:  Xerces-J 2.7.0 
See:  http://apache.org/xml/features/xinclude 

http://apache.org/xml/features/xinclude/fixup-language
 
True:  Perform language fixup as specified by the XInclude Recommendation. 
False:  Do not perform language fixup. The XInclude processor will not add xml:lang attributes. 
Default:  true 
Since:  Xerces-J 2.7.0 
See:  http://apache.org/xml/features/xinclude 


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.  

http://xml.org/sax/features/lexical-handler/parameter-entities
 
True:  Report the beginning and end of parameter entities to a registered LexicalHandler.  
False:  Do not report the beginning and end of parameter entities to a registered LexicalHandler.  
Default:  true 
Since:  Xerces-J 2.7.0 

http://xml.org/sax/features/is-standalone
 
True:  The document specified standalone="yes" in its XML declaration.  
False:  The document specified standalone="no" in its XML declaration or the standalone document declaration was absent.  
Access:  (parsing) read-only; (not parsing) none;  
Since:  Xerces-J 2.7.0 

http://xml.org/sax/features/resolve-dtd-uris
 
True:  The system identifiers passed to the notationDecl, unparsedEntityDecl, and externalEntityDecl events will be absolutized relative to their base URIs before reporting.  
False:  System identifiers in declarations will not be absolutized before reporting.  
Default:  true 
Since:  Xerces-J 2.7.0 
Note:  This feature does not apply to EntityResolver.resolveEntity(), which is not used to report declarations, or to LexicalHandler.startDTD(), which already provides the non-absolutized URI.  

http://xml.org/sax/features/unicode-normalization-checking
 
True:  Perform Unicode normalization checking (as described in section 2.13 and Appendix B of the XML 1.1 Recommendation) and report normalization errors.  
False:  Do not report Unicode normalization errors.  
Default:  false 
Since:  Xerces-J 2.7.0 
Note:  As there is currently no support for Unicode normalization checking, this feature can only be set to false.  

http://xml.org/sax/features/use-attributes2
 
True:  The Attributes objects passed by the parser in org.xml.sax.ContentHandler.startElement() implement the org.xml.sax.ext.Attributes2 interface.  
False:  The Attributes objects passed by the parser do not implement the org.xml.sax.ext.Attributes2 interface.  
Access:  read-only 
Since:  Xerces-J 2.7.0 
Note:  Xerces-J will always report Attributes objects that also implement org.xml.sax.ext.Attributes2 so the value of this feature will always be true.  

http://xml.org/sax/features/use-locator2
 
True:  The Locator objects passed by the parser in org.xml.sax.ContentHandler.setDocumentLocator() implement the org.xml.sax.ext.Locator2 interface.  
False:  The Locator objects passed by the parser do not implement the org.xml.sax.ext.Locator2 interface.  
Access:  read-only 
Since:  Xerces-J 2.7.0 
Note:  Xerces-J will always report Locator objects that also implement org.xml.sax.ext.Locator2 so the value of this feature will always be true.  

http://xml.org/sax/features/xmlns-uris
 
True:  When the namespace-prefixes feature is set to true, namespace declaration attributes will be reported as being in the http://www.w3.org/2000/xmlns/ namespace.  
False:  Namespace declaration attributes are reported as having no namespace.  
Default:  false 
Since:  Xerces-J 2.7.0 
See:  http://xml.org/sax/features/namespaces 
See:  http://xml.org/sax/features/namespace-prefixes 

http://xml.org/sax/features/xml-1.1
 
True:  The parser supports both XML 1.1 and XML 1.0.  
False:  The parser supports only XML 1.0.  
Access:  read-only 
Since:  Xerces-J 2.7.0 
Note:  The value of this feature will depend on whether the parser configuration owned by the SAX parser is known to support XML 1.1.  


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** 
Since:  Xerces-J 2.5.0 
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 j-users@xerces.apache.org mailing list.  



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