JAXP Support for SAX

JAXP 1.2 supports SAX2, but remains backwards compatible with earlier versions that supported SAX1. In the interests of brevity, I will leave out the features that are relevant only to SAX1.

javax.xml.parsers.SAXParserFactory

The first thing an application must do is to obtain a SAXParserFactory , which it can do by calling the static method SAXParserFactory . newInstance() . Different vendors of SAX parsers will each implement their own subclass of SAXParserFactory , and this call determines which vendor's parser your application will end up using. If there are several available, the one that is used is based on the following decision process:

1. Use the value of the system property javax.xml.parsers.SAXParserFactory if it is available. You can typically set system properties using the -D option on the Java command line, or by calling System.setProperty() from your application.

2. Look for a properties file $JAVA_HOME/lib/jaxp.properties , and within this file, for the property named javax.xml.parsers.SAXParserFactory .

3. Use the services API, which is part of the JAR specification. This effectively means that the parser that is used will be the first one to be found on your classpath.

It is likely that when you install a particular SAX parser, it will contain a file within its .jar archive that causes that particular parser to be the default, so if you don't do anything to select a specific parser, the one chosen will depend on the order of files and directories on your class path .

The default parser in Sun's JDK 1.4 is the Crimson parser. If you want to use Xerces instead, set the property to the value org.apache.xerces.jaxp.SAXParserFactoryImpl .

Once you have obtained a SAXParserFactory , you can use a number of methods to configure it. Finally, you can call the newSAXParser() method to return a SAXParser . The methods available are as follows . The codes in square brackets indicate the exceptions thrown, according to the table at the start of this appendix.

Method	Description
boolean getFeature (String) [SAXNRE, SAXNSE, PCE]	Determines whether the parser factory is configured to support a particular feature. The names of features correspond to those defined in SAX2 for the XMLReader class
boolean isNamespaceAware()	Determines whether parsers produced using this factory will be namespace aware
boolean isValidating()	Determines whether parsers produced using this factory will perform XML validation
static SAXParserFactory newInstance() [FCE]	Produces a SAXParserFactory for a specific vendor's parser, decided according to the rules given above
SAxParser newSAXParser() [PCE]	Returns a SAXParser that can be used to perform parsing. This is a wrapper around the SAX2 XMLReader object
void setFeature (String, boolean) [SAXNRE, SAXNSE, PCE]	Sets a particular feature on or off. The names of features correspond to those defined in SAX2 for the XMLReader class
void setNamespaceAware (boolean)	Indicates whether parsers produced using this factory are required to be namespace aware
void setValidating (boolean)	Indicates whether parsers produced using this factory are required to perform XML validation

javax.xml.parsers.SAXParser

A SAXParser is obtained using the newSAXParser() method of a SAXParserFactory . A SAXParser is a wrapper around a SAX2 XMLReader . You can use the getXMLReader() method to get the underlying XMLReader , but in simple cases you won't need to, since you can perform a parse and nominate a handler for all the parsing events using this class alone.

The methods relevant to SAX2 parsers are:

Method	Description
Object getProperty (String) [SAXNRE , SAXNSE]	Gets the named property of the underlying SAX2 XMLReader
XMLReader getXMLReader() [SAXE]	Gets the underlying SAX2 XMLReader
boolean isNamespaceAware()	Determines whether the underlying SAX2 XMLReader is namespace aware
boolean isValidating()	Determines whether the underlying SAX2 XMLReader performs XML validation
void parse (File, DefaultHandler) [IOE, IAE, SAXE]	Parses the contents of the specified file, passing all parsing events to the specified event handler. Normally of course this will not actually be a SAX2 DefaultHandler , but a user -defined subclass of DefaultHandler written to process selected events
void parse (InputSource, DefaultHandler) [IOE, IAE, SAXE]	Parses the contents of the specified SAX InputSource , passing all parsing events to the specified event handler
void parse (InputStream, DefaultHandler) [IOE, IAE, SAXE]	Parses the contents of the specified InputStream, passing all parsing events to the specified event handler. Note that in this case the System ID of the input is unknown, so the parser has no way of resolving relative URIs contained in the XML source
void parse (InputStream, DefaultHandler, String) [IOE, IAE, SAXE]	Parses the contents of the specified InputStream, passing all parsing events to the specified event handler. The third argument contains a System ID that will be used for resolving relative URIs
void parse (String, DefaultHandler) [IOE, IAE, SAXE]	Parses the XML document identified by the URI in the first argument, passing all parsing events to the specified event handler
void setProperty(String, Object) [SAXNSE, SAXNRE]	Sets a property of the underlying SAX2 XMLReader