Package org.xml.sax

packageorg.xml.sax
Provides the interfaces for the Simple API for XML (SAX). Supports both the SAX1 and SAX2 APIs.

SAX2 Standard Feature Flags

One of the essential characteristics of SAX2 is that it added feature flags which can be used to examine and perhaps modify parser modes, in particular modes such as validation. Since features are identified by (absolute) URIs, anyone can define such features. Currently defined standard feature URIs have the prefixhttp://xml.org/sax/features/ before an identifier such asvalidation. Turn features on or off usingsetFeature. Those standard identifiers are:

Standard Features
Feature IDAccessDefaultDescription
external-general-entitiesread/writeunspecified Reports whether this parser processes external general entities; always true if validating.
external-parameter-entitiesread/writeunspecified Reports whether this parser processes external parameter entities; always true if validating.
is-standalone(parsing)read-only, (not parsing)nonenot applicable May be examined only during a parse, after thestartDocument() callback has been completed; read-only. The value is true if the document specified standalone="yes" in its XML declaration, and otherwise is false.
lexical-handler/parameter-entitiesread/writeunspecified A value of "true" indicates that the LexicalHandler will report the beginning and end of parameter entities.
namespacesread/writetrue A value of "true" indicates namespace URIs and unprefixed local names for element and attribute names will be available.
namespace-prefixesread/writefalse A value of "true" indicates that XML qualified names (with prefixes) and attributes (includingxmlns* attributes) will be available.
resolve-dtd-urisread/writetrue A value of "true" indicates that system IDs in declarations will be absolutized (relative to their base URIs) before reporting. (That is the default behavior for all SAX2 XML parsers.) A value of "false" indicates those IDs will not be absolutized; parsers will provide the base URI fromLocator.getSystemId(). This applies to system IDs passed in
  • DTDHandler.notationDecl(),
  • DTDHandler.unparsedEntityDecl(), and
  • DeclHandler.externalEntityDecl().
It does not apply toEntityResolver.resolveEntity(), which is not used to report declarations, or toLexicalHandler.startDTD(), which already provides the non-absolutized URI.
string-interningread/writeunspecified Has a value of "true" if all XML names (for elements, prefixes, attributes, entities, notations, and local names), as well as Namespace URIs, will have been interned usingjava.lang.String.intern. This supports fast testing of equality/inequality against string constants, rather than forcing slower calls toString.equals().
unicode-normalization-checkingread/writefalse Controls whether the parser reports Unicode normalization errors as described in section 2.13 and Appendix B of the XML 1.1 Recommendation. If true, Unicode normalization errors are reported using the ErrorHandler.error() callback. Such errors are not fatal in themselves (though, obviously, other Unicode-related encoding errors may be).
use-attributes2read-onlynot applicable Returns "true" if theAttributes objects passed by this parser inContentHandler.startElement() implement theorg.xml.sax.ext.Attributes2 interface. That interface exposes additional DTD-related information, such as whether the attribute was specified in the source text rather than defaulted.
use-locator2read-onlynot applicable Returns "true" if theLocator objects passed by this parser inContentHandler.setDocumentLocator() implement theorg.xml.sax.ext.Locator2 interface. That interface exposes additional entity information, such as the character encoding and XML version used.
use-entity-resolver2read/writetrue Returns "true" if, whensetEntityResolver is given an object implementing theorg.xml.sax.ext.EntityResolver2 interface, those new methods will be used. Returns "false" to indicate that those methods will not be used.
validationread/writeunspecified Controls whether the parser is reporting all validity errors; if true, all external entities will be read.
xmlns-urisread/writefalse Controls whether, when thenamespace-prefixes feature is set, the parser treats namespace declaration attributes as being in thehttp://www.w3.org/2000/xmlns/ namespace. By default, SAX2 conforms to the original "Namespaces in XML" Recommendation, which explicitly states that such attributes are not in any namespace. Setting this optional flag to "true" makes the SAX2 events conform to a later backwards-incompatible revision of that recommendation, placing those attributes in a namespace.
xml-1.1read-onlynot applicable Returns "true" if the parser supports both XML 1.1 and XML 1.0. Returns "false" if the parser supports only XML 1.0.

Support for the default values of thenamespaces andnamespace-prefixes properties is required. Support for any other feature flags is entirely optional.

For default values not specified by SAX2, each XMLReader implementation specifies its default, or may choose not to expose the feature flag. Unless otherwise specified here, implementations may support changing current values of these standard feature flags, but not while parsing.

SAX2 Standard Handler and Property IDs

For parser interface characteristics that are described as objects, a separate namespace is defined. The objects in this namespace are again identified by URI, and the standard property URIs have the prefixhttp://xml.org/sax/properties/ before an identifier such aslexical-handler ordom-node. Manage those properties usingsetProperty(). Those identifiers are:

Standard Property IDs
Property IDDescription
declaration-handler Used to see most DTD declarations except those treated as lexical ("document element name is ...") or which are mandatory for all SAX parsers (DTDHandler). The Object must implementorg.xml.sax.ext.DeclHandler.
document-xml-version May be examined only during a parse, after the startDocument() callback has been completed; read-only. This property is a literal string describing the actual XML version of the document, such as "1.0" or "1.1".
dom-node For "DOM Walker" style parsers, which ignore theirparser.parse() parameters, this is used to specify the DOM (sub)tree being walked by the parser. The Object must implement theorg.w3c.dom.Node interface.
lexical-handler Used to see some syntax events that are essential in some applications: comments, CDATA delimiters, selected general entity inclusions, and the start and end of the DTD (and declaration of document element name). The Object must implementorg.xml.sax.ext.LexicalHandler.
xml-string Readable only during a parser callback, this exposes aTBS chunk of characters responsible for the current event.

All of these standard properties are optional. XMLReader implementations are not required to support them.

API Note:
The SAX API, originally developed atthe SAX Project, has been defined by Java SE since 1.4.
Since:
1.4
  • Related Packages
    Package
    Description
    Provides interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
    Provides helper classes, including support for bootstrapping SAX-based applications.
  • Class
    Description
    Deprecated.
    This interface has been replaced by the SAX2Attributes interface, which includes Namespace support.
    Interface for a list of XML attributes.
    Receive notification of the logical content of a document.
    Deprecated.
    This interface has been replaced by the SAX2ContentHandler interface, which includes Namespace support.
    Receive notification of basic DTD-related events.
    Basic interface for resolving entities.
    Basic interface for SAX error handlers.
    Deprecated.
    This class works with the deprecatedDocumentHandler interface.
    A single input source for an XML entity.
    Interface for associating a SAX event with a document location.
    Deprecated.
    This interface has been replaced by the SAX2XMLReader interface, which includes Namespace support.
    Encapsulate a general SAX error or warning.
    Exception class for an unrecognized identifier.
    Exception class for an unsupported operation.
    Encapsulate an XML parse error or warning.
    Interface for an XML filter.
    Interface for reading an XML document using callbacks.