Parsing XML

XML is pretty much useless unless you can get at the data it represents, so any good API begins with the parsing process. JAXP uses SAX and DOM to get the job done, so this section is largely about how JAXP interacts with those APIs; you should already have the intricacies of SAX and DOM down, and I'll leave out repeated discussions of how these underlying APIs work. JAXP makes heavy use of the factory model. In general, you'll get a factory for the type of parsing you want to use with a static method on the factory itself. Then, you perform optional configuration on the factory, and obtain a parser. Once you've got the parser, you can set some more options, and then actually parse XML. This is the same process used in both SAX and DOM (as well as TrAX), and it's illustrated by the simple flowchart in .

The JAXP parsing process is the same for both SAX and DOM

Reading XML with SAX

Working with JAXP and SAX is really just a matter of plugging in the right class and interface names. Along those lines, you need to familiarize yourself with the javax.xml.parsers package.

By now, I'm assuming you've got a current version of Java and the JDK. As I write this text, Java 5.0 is still somewhat new, but I imagine by the time you're holding this tutorial, it will be fairly commonplace. I recommend moving to Java 5.0 (even if you choose not to take advantage of its new features), simply for JAXP 1.3. That's the version of JAXP covered in this chapter, and throughout the rest of this tutorial. If you can't move to Java 5.0 for any reason, don't worry, JAXP 1.3 is available as a separate download from https://jaxp.dev.java.net.

There are only two classes to worry about, as well as an Exception and an Error. It can't get much simpler than that, can it? The UML for these is shown in .

The SAX portion of JAXP uses a factory, a parser, an Exception, and an Error, all of which are almost completely self-explanatory

Creating a parser factory

Review , and it should be obvious that you're going to start with SAXParserFactory. You need to bootstrap an instance of this class, which is done with the newInstance( ) method (this chapter is full of really complex material, isn't it?):

SAXParserFactory factory = SAXParserFactory.newInstance( );

Configuring the factory

Now you need to set configuration options on the parser. These are options that apply to all parser instances that you obtain from the factory. Each feature has a setXXX( ) method, and a getXXX( ) or isXXX( ) method to determine that feature's current setting on the factory:

Namespace awareness ( setNamespaceAware( )/isNamespaceAware( ) )

Setting this feature to true ensures that the parser is namespace-aware; in other words, it will see an element named oracle:book as an element with a local name of book, and a namespace prefix of oracle. By default, parsers are not namespace-aware; that said, I almost always set this feature to TRue.

Validation schema ( setSchema( )/getSchema( ) )

This allows you to specify a javax.xml.validation.Schema object to be used for validating the XML. I'll cover JAXP validation in detail in "XML Validation," so just hold the thought for now. By default, the Schema object is set to null, and won't affect your parsing. It's also worth noting at this point that a Schema is an object type, and doesn't refer to a specific constraint model. You can validate against DTDs, XML Schema, Relax NG schemas, or anything else that implements the Schema interface.

JAXP will validate XML documents against a Schemaif one is referenced in the XML documenteven if isValidating( ) is set to false.

Validation ( setValidating( )/isValidating( ) )

This option ensures that all parsers created by the parser factory are validating parsers. In a formal sense, that means validating according to the XML 1.0 specification; in other words, validating parsers validate against DTDs. This option does not affect XML Schema or Relax NG validation, and has nothing to do with the javax.xml.validation package. It's largely still available for backward compatibility with JAXP 1.2, and I'd advise against using it in favor of setSchema( ) and the JAXP 1.3 validation framework. By default, this feature is set to false.

XInclude processing ( setXIncludeAware( )/isXIncludeAware( ) )

This feature controls whether parsers recognize XInclude markup in parsed XML documents. This feature is set to false by default, and can really affect the time it takes to parse an XML document; it's recommended you only set this feature to true if you're sure you need XInclude information.

Passthrough features ( setFeature( )/getFeature( ) )

This is the catch-all method that allows you to set features on a parser that aren't explicitly supported by JAXP. This could be a new feature that JAXP hasn't caught up with yet, or a parser-specific feature that doesn't make sense for the JAXP API to add. For example:

SAXParserFactory factory = SAXParserFactory.newInstance( );
// Set a Xerces specific feature factory.setFeature("http://apache.org/xml/features/allow-java-encodings", true);

In this case, the code instructs the Apache Xerces parser to allow Java encoding names in addition to ISO-standard encoding names in the XML declaration. If the requested feature isn't supported, the factory will throw an org.xml.sax.SAXNotSupportedException ; if the parser doesn't recognize the feature at all, you'll get an org.xml.sax.SAXNotRecognizedException.

That's a mouthful, but turns out to be really simple to use in practice. The following code shows a simple method that creates a parser factory and then sets several configuration options on the factory:

// Get SAX Parser Factory SAXParserFactory factory = SAXParserFactory.newInstance( );
// Turn on validation, and turn off namespaces factory.setValidating(true);
factory.setNamespaceAware(false);
factory.setXIncludeAware(true);

Keep in mind that these features affect all parser instances created by this factory, at least until the features are changed or reset.

Obtaining a parser

Once you've done all your setup and configuration, actually getting a parser is a piece of cake:

// Get a new instance of a SAXParser SAXParser parser = factory.newSAXParser( );

That's it; if you were expecting something more complicated, I'm sorry to disappoint.

Parsing with JAXP and SAX

SAXParser is the JAXP wrapper for SAX's XMLReader interface. As such, it provides a whole slew of various methods to parse XML, all conveniently called parse( ), as illustrated by .

SAXParser adds variations on the parse( ) theme, but not much else, to the underlying XMLReader implementation

There's not nearly as much going on here as it may seem; first, there are permutations for accepting the XML as an InputSource, a File, an InputStream, and via a String URI. Then, because JAXP works with both SAX 1.x and 2.x implementations, you'll find that there will be a versionfor each type of inputthat takes a HandlerBase, as well as a version that accepts a DefaultHandler. HandlerBase is essentially the SAX 1.x version of SAX 2's DefaultHandler. HandlerBase implements DocumentHandlerreplaced in SAX 2 by ContentHandleras well as EntityResolver, DTDHandler, and ErrorHandler. Finally, for the versions of parse( ) that accept an InputStream, JAXP allows you to pass in a system ID, to help resolve relative document references within the XML. Of course, you can bypass this by using an InputSource (which can wrap an InputStream and provide a system ID as well). Do the math, and this results in a whopping 10 versions of parse( )! Ultimately, all end up in the same place: parsing the XML document. You can also pass through properties to set on the XMLReader using the setProperty( ) method. Essentially, then, SAXParser is just a JAXP-specific stand-in for XMLReader:

public static void main(String[] args) {
 try {
 if (args.length != 1) {
 System.err.println ("Usage: java SAXTester [XML filename]");
 System.exit (1);
 }
 // Get SAX Parser Factory
 SAXParserFactory factory = SAXParserFactory.newInstance( );
 // Turn on validation, and turn off namespaces
 factory.setValidating(true);
 factory.setNamespaceAware(false);
 factory.setXIncludeAware(true);
 SAXParser parser = factory.newSAXParser( );
 parser.parse(new File(args[0]), new MyHandler( ));
 } catch (ParserConfigurationException e) {
 System.out.println("The underlying parser does not support " +
 " the requested features.");
 } catch (FactoryConfigurationError e) {
 System.out.println("Error occurred obtaining SAX Parser Factory.");
 } catch (Exception e) {
 e.printStackTrace( );
 }
}

This should look remarkably similar to your SAX code, although you do need to remember to use DefaultHandler as the input, rather than calling setContentHandler( ), setErrorHandler( ), and so forth individually.

This would seem to be at odds with my early admonition to avoid lumping your EntityResolver in with the other SAX handlers. You can't separate out behavior when you only have the one DefaultHandler parameter to pass to parse( ). However, by accessing XMLReader directly, as described in the next section, you can still achieve this functionality; and in fact, that's how I'd urge you to use SAXParseras an intermediary object, by which you then get access to the underlying XMLReader.

Accessing XMLReader directly

In many cases, you will want to get the SAXParser object and then immediately access the XMLReader object directly. XMLReader offers you direct access to parsing behavior, the ability to register handlers individually, and keeps JAXP doing what JAXP does best: providing vendor-independence for your code (not actual parsing). To get the XMLReader that SAXParser wraps, just call getXMLReader( ):

XMLReader reader = parser.getXMLReader( );

You can then use methods available on XMLReader that aren't accessible through the JAXP interface:

// Get SAX Parser Factory SAXParserFactory factory = SAXParserFactory.newInstance( );
// Turn on validation, and turn off namespaces factory.setValidating(true);
factory.setNamespaceAware(false);
factory.setXIncludeAware(true);
SAXParser parser = factory.newSAXParser( );
XMLReader reader = parser.getXMLReader( );
DefaultHandler myHandler = new MyHandler( );
reader.setContentHandler(myHandler);
reader.setErrorHandler(myHandler);
// Set EntityResolver from a separate class reader.setEntityResolver(new LocalEntityResolver(new File("/usr/local/entities/")));
// Parse reader.parse(new InputSource(args[0]));

If you're thinking you need to take a break to gear up for the challenge of DOM, you can save yourself some rest. The process of using DOM with JAXP is nearly identical to that with SAX; all you do is change two class names and a return type, and you are pretty much there. If you understand how SAX works and what DOM is, you won't have any problem. While SAX consists of an event-based set of callbacks, DOM has an in-memory tree structure. SAX, therefore, does not offer the ability to modify an XML document. DOM provides exactly this type of functionality. Recall that the org.w3c.dom.Document class represents an XML document, and is made up of DOM nodes that represent the elements, attributes, and other XML constructs. So JAXP doesn't have to fire SAX callbacks; it is only responsible for returning a DOM Document object from parsing. outlines the DOM-related parsing classes.

DocumentBuilderFactory is the analog to SAXParserFactory, and DocumentBuilder replaces SAXParser in the DOM-related portion of JAXP

From SAXParserFactory to DOMBuilderFactory

With a basic understanding of DOM (which you should have from Chapters 5 and 6), along with what you've already seen about JAXP, there is little else to say. You essentially replace the JAXP SAX classes with their DOM-related counterparts, and obtain a Document object from parse( ); that's all there is to it:

// Get DOM Parser Factory DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance( );
// Turn on validation, and turn off namespaces factory.setValidating(true);
factory.setNamespaceAware(false);
DocumentBuilder builder = factory.newDocumentBuilder( );
Document doc = builder.parse(new File(args[0]));
// Serialize DOMSerializer serializer = new DOMSerializer( );
serializer.setIndent(2);
serializer.serialize(doc, System.out);

First, a DocumentBuilderFactory is obtained (in the same way that SAXParserFactory was in SAX). Then the factory is configured to handle validation and namespaces (in the same way that it was in SAX). Next, a DocumentBuilder instancethe analog to SAXParseris retrieved from the factory. Parsing can then occur, and the resultant DOM Document object is handed off to a class that prints the DOM tree.

Two different problems can arise with this code (the same as with SAX-related JAXP parsing): FactoryConfigurationError and ParserConfigurationException. If there's a problem present in the implementation classes, JAXP throws a FactoryConfigurationError; if the parser provided doesn't support the requested features, you'll get a ParserConfigurationException.

DOM factory configuration options

In SAX, even SAXParserFactory had little in the way of configuration. That's largely because SAX developers control quite a bit in terms of what XML events are handled, via the callback implementations in ContentHandler. In DOM, though, DocumentBuilder simply returns to you a parsed and constructed DOM Document object. As a result, DocumentBuilderFactory offers quite a bit more in the way of configuration.

Just as in SAX, options set on the factory affect all instances that the factory creates. The options listed here are in addition to the options already detailed for SAX in "Configuring the factory."

CDATA awareness ( setCoalescing( )/isCoalescing( ) )

If set to true, the DOM parser will convert CDATA nodes into Text nodes. Additionally, if the CDATA section is next to other Text nodes, the converted Text node will be appended (or prepended, as the case may be) to those adjacent nodes. If you only want character dataand don't care about how that data was representedthen you should set this property to true; otherwise, use the default value of false.

Entity reference expansion ( setExpandEntityReferences( )/isExpandEntityReferences( ) )

This property determines whether entity references are expanded (which is the default). You might set this to false if you were interested in the lexical content of just the current document, without any data from external sources.

Comment processing ( setIgnoringComments( )/isIgnoringComments( ) )

By default, comments are not ignored (meaning that the default value of isIgnoringComments( ) is false). However, if you're not interested in comments, then you can set this property to TRue and ignore them, dropping all Comment nodes from the resulting DOM tree.

Ignorable whitespace ( setIgnoringElementContentWhitespace( )/isIgnoringElementContentWhitespace( ) )

This setting tells the DocumentBuilder to drop all ignorable whitespace (discussed in detail in 3). For elements that may only contain other elements, whitespace is ignored; however, because of a reliance on validation, this optionwhen set to TRueis only actually used when isValidating( ) is also true. The default value is false.

All of these options result in loss of information in the DOM tree produced by parse( ). While it's very easy to perform this processing as an extra layer of filtering after the DOM tree has been produced, it is not possible to get "back" to the original XML document if these features are used before you can access the DOM Document directly. For this reason, I'd recommend you perform any DOM processing yourself, rather than letting JAXP strip information from the DOM tree before your program has access to it.

Changing the Parser Implementation

One of JAXP's core strengths is its abstraction of parser implementation details. Along those lines, it's trivial to change the parser that JAXP uses. Even more important, this change won't affect your code. Just supply the parser class to use to JAXP via the javax.xml.parsers.SAXParserFactory system property (for SAX) and the javax.xml.parsers.DocumentBuilderFactory property (for DOM). This can most easily be done via the command line:

java -Djavax.xml.transform.TransformerFactory=org.apache.xerces.parsers.SAXParser javaxml3.SAXTester ibm-jaxp-article.xml

You might also have a class of constants or initialization code that sets these values; while using that approach will require recompilation if you change the parser, it still keeps you clear of the core of your parsing code.

You can also modify the lib/jaxp.properties file in your Java Runtime Environment (JRE), a file in the Java properties file format (name=value pairs). This is dangerous, though, as it's not a portable solution: changes on one JRE will not make it to another JRE, unless you remember to manually update the new properties file.

• Java and XML
• Previous
• Next