Writing Application FAQs


	Questions

Creating a SAX Parser
Handling Errors
What does "non-validating" mean?
Parsing Several Documents
Pull-parsing documents


	Answers


	How do I create a SAX parser?

You can create a SAX parser by using the Java APIs for XML Processing (JAXP). The following source code shows how:

import java.io.IOException; 
import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import org.xml.sax.SAXException;
import org.xml.sax.helpers.DefaultHandler;

  ...

String xmlFile = "file:///xerces-2_1_0/data/personal.xml"; 
try {
    SAXParserFactory factory = SAXParserFactory.newInstance();
    SAXParser parser = factory.newSAXParser();
    DefaultHandler handler = /* custom handler class */;
    parser.parse(xmlFile, handler);
} 
catch (FactoryConfigurationError e) {
    // unable to get a document builder factory
} 
catch (ParserConfigurationException e) {
    // parser was unable to be configured
catch (SAXException e) {
    // parsing error
} 
catch (IOException e) {
    // i/o error
}


	How do handle errors?

You should register an error handler with the parser by supplying a class which implements the org.xml.sax.ErrorHandler interface. This is true regardless of whether your parser is a DOM based or SAX based parser.

You can register an error handler on a DocumentBuilder created using JAXP like this:

import javax.xml.parsers.DocumentBuilder;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;

ErrorHandler handler = new ErrorHandler() {
    public void warning(SAXParseException e) throws SAXException {
        System.err.println("[warning] "+e.getMessage());
    }
    public void error(SAXParseException e) throws SAXException {
        System.err.println("[error] "+e.getMessage());
    }
    public void fatalError(SAXParseException e) throws SAXException {
        System.err.println("[fatal error] "+e.getMessage());
    throw e;
    }
};

DocumentBuilder builder = /* builder instance */;
builder.setErrorHandler(handler);

If you are using DOM Level 3 you can register an error handler with the DOMBuilder by supplying a class which implements the org.w3c.dom.DOMErrorHandler interface. For more information, refer to FAQ

You can also register an error handler on a SAXParser using JAXP like this:

import javax.xml.parsers.SAXParser;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;

ErrorHandler handler = new ErrorHandler() {
    public void warning(SAXParseException e) throws SAXException {
        System.err.println("[warning] "+e.getMessage());
    }
    public void error(SAXParseException e) throws SAXException {
        System.err.println("[error] "+e.getMessage());
    }
    public void fatalError(SAXParseException e) throws SAXException {
        System.err.println("[fatal error] "+e.getMessage());
    throw e;
    }
};

SAXParser parser = /* parser instance */;
parser.getXMLReader().setErrorHandler(handler);


	Why does "non-validating" not mean "well-formedness checking only"?

Using a "non-validating" parser does not mean that only well-formedness checking is done! There are still many things that the XML specification requires of the parser, including entity substitution, defaulting of attribute values, and attribute normalization.

This table describes what "non-validating" really means for Xerces-J parsers. In this table, "no DTD" means no internal or external DTD subset is present.

	non-validating parsers		validating parsers
	DTD present	no DTD	DTD present	no DTD
DTD is read	Yes	No	Yes	Error
entity substitution	Yes	No	Yes	Error
defaulting of attributes	Yes	No	Yes	Error
attribute normalization	Yes	No	Yes	Error
checking against model	No	No	Yes	Error


	How do I more efficiently parse several documents sharing a common DTD?

By default, the parser does not cache DTD's. The common DTD, since it is specified in each XML document, will be re-parsed once for each document.

However, there are things that you can do to make the process of reading DTD's more efficient:

First, have a look at the grammar caching/preparsing FAQ:
keep your DTD and DTD references local
use internal DTD subsets, if possible
load files from server to local client before parsing
Cache document files into a local client cache. You should do an HTTP header request to check whether the document has changed, before accessing it over the network.
Do not reference an external DTD or internal DTD subset at all. In this case, no DTD will be read.
Use a custom EntityResolver and keep common DTDs in a memory buffer.


	How can I parse documents in a pull-parsing fashion?

Since the pull-parsing API is specific to Xerces, you have to use Xerces-specific way to create parsers, and parse documents.

You first need to create a parser configuration that implements the XMLPullParserConfiguration interface. Then you need to create a parser from this configuration. To parse documents, method parse(boolean) should be called.

import org.apache.xerces.parsers.StandardParserConfiguration;
import org.apache.xerces.parsers.SAXParser;
import org.apache.xerces.xni.parser.XMLInputSource;

  ...

boolean continueParse = true;
void pullParse(XMLInputSource input) throws Exception {
    StandardParserConfiguration config = new StandardParserConfiguration();
    SAXParser parser = new SAXParser(config);
    config.setInputSource(input);
    parser.reset();
    while (continueParse) {
        continueParse = continueParse && config.parse(false);
    }
}

In the above example, a SAXParser is used to pull-parse an XMLInputSource. DOMParser can be used in a similar way. A flag continueParse is used to indicate whether to continue parsing the document. The application can stop the parsing by setting this flag to false.