SAX1 Support (SAX2)

5.2. SAX1 Support

This section provides a brief overview of the SAX1 classes and migration support and of differences between SAX1 and SAX2. SAX1 is a subset of SAX2, so SAX2 is backward compatible. The only reason you might not want to have the SAX2 classes and interfaces in your class path is to avoid compiler warnings telling you when you're using now-deprecated APIs.

You shouldn't be using SAX1 APIs to write new code, but you may need to maintain or migrate older code written using these classes. As soon as possible, plan a maintenance step that involves switching to the new SAX2 versions of the APIs. This may include getting rid of some "home-brew" solutions for namespace support. (Some applications have found previously unsuspected bugs when they've made such changes; be alert!) This section has been written to highlight those changes.

If your parser supplier hasn't provided SAX2 support by now, it's probably also time to switch suppliers; however, you can use the ParserAdapter class to make these changes without changing parsers. In fact, if you're using ParserFactory to get the system default parser and haven't set a SAX2 XMLReader default, the reference XMLReaderFactory distribution will automatically wrap the SAX1 parser you've probably already identified using the org.xml.sax.parser system property. That is, just putting the SAX2 classes in your class path normally lets you start using SAX2 without needing to change your application configuration. (You can go the other way around with an XMLReaderAdapter if you want to use a more current parser while letting the application code continue to use older SAX1 APIs.)

You'll most likely be interested in these classes if you're working with an older, SAX1-based application or tool, such as the XT 0.5 XSLT engine. This includes applications written to the JAXP 1.0 API specification, which doesn't include SAX2 support. If so, the main difference you'll see is that SAX1 has a much simpler way of naming elements and attributes: it only needs to support the qName (qualified name) access style, not the namespace-aware style. This eliminates some opportunities for confusion, unless you're writing namespace-aware applications.

The following classes provide SAX1 support:

org.xml.sax.Parser: This interface corresponds to the SAX2 XMLReader. It uses the DocumentHandler interface (instead of ContentHandler) and has no "getter" methods for handlers or the entity resolver. The SAX2 feature and property management methods are not available. There is a setLocale() method to control the locale used with diagnostics, which was dropped in SAX2.

With SAX1, there was no standard way to indicate whether a parser validated or not. SAX1 applications had to be written to not rely on having validity errors reported, unless either a configuration mechanism enforced the use of a validating parser (specifying validating or nonvalidating classes) or use of some specific implementation's alternative configuration mechanism was hardwired.

Similarly, SAX1 had no standard way to provide the additional infoset data that SAX2 shows using the DeclHandler and LexicalHandler interfaces. Applications needing such support needed to use implementation-specific APIs.
org.xml.sax.DocumentHandler: This interface corresponds to the SAX2 ContentHandler interface. Namespace information is not available on the element callbacks, and startElement() uses AttributeList. Prefix-mapping scopes are not reported. In SAX2, skipped entities are reported; this was an XML 1.0 conformance requirement that was not met by the SAX1 API. SAX1 will not report skipped entities even if you were to wire it into a SAX2 environment.
org.xml.sax.HandlerBase: This class corresponds to the SAX2 DefaultHandler class, except that it's a core class, not a helper class. (Consider that an evolutionary accident.) It supports the older DocumentHandler interface.
org.xml.sax.AttributeList: This interface corresponds to the SAX2 Attributes interface. It doesn't include namespace information and is accordingly much simpler. The only name for an attribute is what the namespace specification called the "qName." (In SAX2, providing the qName is optional unless the namespace-prefixes property has been set, but most parsers provide it at all times.)
org.xml.sax.helpers.AttributeListImpl: This class corresponds to the SAX2 AttributesImpl class. It doesn't include namespace information and is accordingly much simpler.
org.xml.sax.helpers.ParserAdapter: This class is intended to help migrate SAX1 parser implementations to the SAX2 namespace-aware API. If you have a SAX1 parser (perhaps it turns some non-XML data into a SAX1 event stream), you can use this class to bring it into the SAX2 world.
org.xml.sax.helpers.ParserFactory: This class corresponds to the SAX2 XMLReaderFactory class. It returns a SAX1 Parser and it is controlled only using the org.xml.sax.parser system property. It throws many more exceptions than its SAX2 analogue.
org.xml.sax.helpers.XMLReaderAdapter: This class supports backward migration of SAX2 parsers into SAX1-based applications. You probably won't ever need to use it.

If your environment supports SAX1 but not SAX2, you can just add the SAX2 version of sax.jar to your class path, somewhere before the older SAX1 files. (Otherwise, you might get package-sealing violations, because the JVM might mix versions of the package. It may be best if you remove older copies of the SAX1 classes from your class path.) If you set the SAX1 org.xml.sax.parser system property to point to a SAX1 parser so that applications can rely on org.xml.sax.helpers.ParserFactory bootstrapping, you'll be glad that the SAX2 org.xml.sax.helpers.XMLReaderFactory knows how to use this property as a backup in case no default SAX2 parser has been configured.