About SAX
 Copyright Status
 Events vs. Trees

Java API
 Features and Properties

SAX Evolution
 SAX 1.0 Overview
 SAX 2.0 Changes
 SAX 2.0 Extensions
 Other Languages

SourceForge Services
 Project Page

SourceForge Logo

SAX 2.0 Extensions

The SAX2 core includes the org.xml.sax and org.xml.sax.helpers packages, but that's not all there is to SAX. The org.xml.sax.ext package includes standardized extensions, and anyone can define and implement nonstandard ones using the SAX2 core "feature flags" and "property objects" mechanisms.

SAX2 Extensions 1.0

Part of the original motivation to create SAX2 was to let it support better "round tripping" of XML data, so that parser outputs would more closely match the inputs. Another was to let it expose more of the useful DTD information. Because not every parser would want to support those two tasks, they were supported in optional handlers that are part of a new SAX2 Extensions package. These needs were met using handlers that are bound using the SAX2 XMLReader.setProperty() method, and they can be accessed using XMLReader.getProperty().

The DeclHandler and LexicalHandler interface, and the whole org.xml.sax.ext package, were part of SAX2 development up through the beta2 release. After that time they were put into a separate distribution; core-only SAX2 distributions do not need to include those interfaces. Final versions of those interface were delivered many months after the original SAX2 interfaces were defined.

The SAX2r2 release re-bundles those two interfaces. They're still optional in the sense that SAX2 distributions don't need to include them. In practice, all distributions are already including them, and any distribution conforming to the JAXP 1.1 interface specification needs to include them.

SAX2 Extensions 1.1 (beta1)

Since the original release of SAX2, and 1.0 extensions, many folk have gained experience with SAX2. Naturally, some of these have led to requests for new standardized SAX features. Notably, not all of the XML Infoset information was available, so that applications which needed it couldn't be written on top of the raw SAX API. Rather than changing the SAX2 core, these new features are part of the optional extensions package.

Functionality defined in the SAX2 Extensions 1.1beta1 release includes several new classes and interfaces:

  • The Attributes2 interface, and its Attributes2Impl implementation class. This exposes which attributes were specified in the source text, rather than defaulted through the DTD. This is important when implementing DOM as a clean layer over SAX.
  • DefaultHandler2 is a new class which extends org.xml.sax.helpers.DefaultHandler to provide stubs for all the DeclHandler, LexicalHandler, and EntityResolver2 methods. Most folk using these new handlers need such a class. Defining it here prevents some duplication of effort.
  • EntityResolver2 is a new interface supporting two new functionalities, with a clean transition mode in the API. First, it lets you provide external DTD subsets for documents that don't have one. That lets you validate, or at least perform attribute defaulting and normalization, for documents that would otherwise "only" be well-formed XML. Second, it provides a resolveEntity() method with more parameters, which lets you cope with situations where the base URI of the document and the entity declaration have become mismatched.
  • The Locator2 interface, and its Locator2Impl implementation class. This exposes entity information found in the XML and text declarations, packaging it with the other entity information which parsers may expose.

There are also several new feature flags. These are documented with all the others, in the main SAX package summary. The feature flags have the usual URI prefix. To summarize them:

  • is-standalone ... exposes whether the document is declared to be standalone
  • resolve-dtd-uris ... if explicitly set to false, then system IDs in DTDHandler and DeclHandler won't be resolved against the declaration's base URI. This supports working with new URI schemes, and certain error-prone document management practices.
  • use-attributes2 ... exposes whether the Attributes object passed in ContentHandler.startElement() supports the new Attributes2 interface (see above).
  • use-locator2 ... exposes whether the Locator object passed in ContentHandler.setDocumentLocator() supports the new Locator2 interface (see above).
  • use-entity-resolver2 ... says whether to use EntityResolver2 methods, if the object passed to XMLReader.setEntityResolver() supports them and the parser is processing that class of external entity.

At this writing, only the Ælfred2 parser supports many of these extensions. Conformance tests for them are yet to be developed.