9.3.1.1. The road to SAX 2.0

There are a few significant changes related to these standards updates, particularly with regard to SAX. In SAX 1.0, the parser interface implemented by vendors and XML parser projects was org.xml.sax.Parser. The JAXP class SAXParser, then, provided a method to get this underlying implementation class through the getParser( ) method. The signature for that method looks like this:

public interface SAXParser {

    public org.xml.sax.Parser getParser( );

    // Other methods
}

public interface SAXParser {

    public org.xml.sax.XMLReader getXMLReader( );

    public org.xml.sax.Parser getParser( );

    // Other methods
}

All these methods for parsing may seem a bit confusing, but it's only tricky if you're working with both versions of SAX. If you are using SAX 1.0, you'll be working with the Parser interface and HandlerBase class, and it will be obvious which methods to use. Similarly, when using SAX 2.0, it will be obvious that the methods that accept DefaultHandler instances and return XMLReader instances should be used. So take all this as a reference and don't worry too much about it! There are some other changes to the SAX portion of the API, as well.

9.3.1.2. Changes in SAX classes

9.3.1.3. Updates to the DOM

9.3.2.1. Working with the factory

TransformerFactory factory = TransformerFactory.newInstance( );

Nothing special here, just basic factory design principles at work, in conjunction with a singleton pattern.

This interface, when implemented, allows URIs found in XSL constructs like xsl:import and xsl:include to be handled. Returning a Source (which I'll cover in a moment), you can instruct your transformer to search for the specified document in various locations when a particular URI is encountered. For example, when an include of the URI http://www.oreilly.com/oreilly.xsl is encountered, you might instead return the local document alternateOreilly.xsl and prevent the need for network access. Implementations of the URIResolver interface can be set using the TransformerFactory's setURIResolver( ) method, and retrieved using the getURIResolver( ) method.

    // Get the factory
    TransformerFactory factory = TransformerFactory.newInstance( );

    // Configure the factory
    factory.setErrorResolver(myErrorResolver);
    factory.setURIResolver(myURIResolver);

    // Get a Transformer to work with, with the options specified
    Transformer transformer = 
        factory.newTransformer(new StreamSource("foundation.xsl"));

As you can see, this method takes the stylesheet as input to use in all transformations for that Transformer instance. In other words, if you wanted to transform a document using stylesheet A and stylesheet B, you would need two Transformer instances, one for each stylesheet. If you wanted to transform multiple documents with the same stylesheet (call it stylesheet C), however, you would need only a single Transformer instance, associated with stylesheet C. Don't worry about the StreamSource class; that's coming next.

9.3.2.2. Transforming XML

• Set the XSL stylesheet to use

• Perform the transformation, specifying the XML document and result target

As I have demonstrated, the first step is really the easiest. A stylesheet can be supplied when obtaining a Transformer instance from the factory. The location of this stylesheet must be specified by providing a javax.xml.transform.Source instance (actually an instance of an implementation of the Source interface) for its location. The Source interface, which you've seen in a few code samples, is the means of locating an input, be it a stylesheet, document, or other information set. TrAX provides the Source interface and three concrete implementations:

• javax.xml.transform.stream.StreamSource

• javax.xml.transform.dom.DOMSource

• javax.xml.transform.sax.SAXSource

The next Source implementation, DOMSource, provides for reading from an existing DOM tree. It provides a constructor for taking in a DOM org.w3c.dom.Node, and will read from that Node when used. This is ideal for supplying an existing DOM tree to a transformation, perhaps if parsing has already occurred and an XML document is already in memory as a DOM structure, or if you've built a DOM tree programmatically.

SAXSource provides for reading input from SAX producers. This Source implementation takes either a SAX org.xml.sax.InputSource, or an org.xml.sax.XMLReader as input, and uses the events from these sources. This is ideal for situations in which a SAX content handler is already in use, and callbacks are set up and need to be triggered prior to transformations.

    // Get the factory
    TransformerFactory factory = TransformerFactory.newInstance( );

    // Configure the factory
    factory.setErrorResolver(myErrorResolver);
    factory.setURIResolver(myURIResolver);

    // Get a Transformer to work with, with the options specified
    Transformer transformer = 
        factory.newTransformer(new StreamSource("foundation.xsl"));

    // Perform transformation on myDocument, and print out result
    transfomer.transform(new StreamSource("asimov.xml"),
                         new StreamResult("results.xml"));

The transform( ) method takes two arguments: a Source implementation, and a javax.xml.transform.Result implementation. You should already be seeing the symmetry in how this works and have an idea about the functionality within the Result interface. The Source provides the XML document to be transformed, and the Result provides an output target for the transformation. Like Source, there are three concrete implementations of the Result interface provided with TrAX and JAXP:

• javax.xml.transform.stream.StreamResult

• javax.xml.transform.dom.DOMResult

• javax.xml.transform.sax.SAXResult

While the previous example shows transforming from a stream to a stream, any combination of sources and results is possible. Here are a few examples:

    // Perform transformation on jordan.xml, and print out result
    transformer.transform(new StreamSource("jordan.xml"),
                         new StreamResult(System.out));

    // Transform from SAX and output results to a DOM Node
    transformer.transform(new SAXSource(
                              new InputSource(
                                  "http://www.oreilly.com/catalog.xml")),
                           new DOMResult(DocumentBuilder.newDocument( )));

    // Transform from DOM and output to a File
    transformer.transform(new DOMSource(domTree),
                          new StreamResult(
                              new FileOutputStream("results.xml")));

    // Use a custom source and result (JDOM)
    transformer.transform(new org.jdom.trax.JDOMSource(myJdomDocument),
                          new org.jdom.trax.JDOMResult(
                              new org.jdom.Document( )));

TrAX provides tremendous flexibility in moving from various input types to various output types, and in using XSL stylesheets in a variety of formats, such as files, in-memory DOM trees, SAX readers, and so on.

9.3.2.3. Odds and ends

Before closing shop on JAXP, there are a few bits and pieces of TrAX I haven't yet talked about. I won't treat these completely, as they are less commonly used, but I will touch on them briefly. First, TrAX introduces an interface called SourceLocator, also in the javax.xml.transform package. This class functions for transformations exactly as the Locator class did for SAX parsing: it supplies information about where action is occurring. Most commonly used for error reporting, the interface looks like this:

package javax.xml.transform;

public interface SourceLocator {
    public int getColumnNumber( );
    public int getLineNumber( );
    public String getPublicId( );
    public String getSystemId( );
}

I won't comment much on this interface, as it's pretty self-explanatory. However, you should know that in the javax.xml.transform.dom package, there is a subinterface called DOMLocator. This interface adds the getOriginatingNode( ) method, which returns the DOM node being processed. This makes error handling quite easy when working with a DOMSource, and is useful in applications that work with DOM trees.

TrAX also provides a concrete class, javax.xml.transform.OutputKeys, which defines several constants for use in output properties for transformations. These constants can then be used for setting properties on a Transformer or a Templates object. That leads me to the last subject dealing with TrAX.

The Templates interface in TrAX is used when a set of output properties is desired across multiple transformations, or when a set of transformation instructions can be used repeatedly. By supplying a Source to a TransformerFactory's newTemplates( ) method, you get an instance of the Templates object:

// Get a factory
TransformerFactory factory = TransformerFactory.newInstance( );

// Get a Templates object
Templates template = factory.newTemplates(new StreamSource("html.xsl"));

At this point, the template object would be a compiled representation of the transformation detailed in html.xsl (in this example, a stylesheet that converts XML to HTML). By using a Templates object, transformations can be performed from this template across threads, and you also get some optimizations, because instructions are precompiled. Once you have gone that far, you need to generate a Transformer, but from the Templates object, rather than the factory:

// Get a transformer
Transformer transformer = template.newTransformer( );

// Transform
transformer.transform(new DOMSource(orderForm), 
                      new StreamResult(res.getOutputStream( )));