5.2.1. JAXP 1.1 Implementation

public static void main(String[] args)
        throws javax.xml.transform.TransformerException {

This is a general-purpose exception representing anything that might go wrong during the transformation process. In other processors, SAX-specific exceptions are typically propagated to the caller. In JAXP, TransformerException can be wrapped around any type of Exception object that various XSLT processors may throw.

Next, the command-line arguments are converted into File objects. In the SAXON and Xalan examples, we created a system ID for each of these files. Since JAXP can read directly from a File object, the extra conversion to a URI is not needed:

File xmlFile = new File(args[0]);
File xsltFile = new File(args[1]);

javax.xml.transform.Source xmlSource =
        new javax.xml.transform.stream.StreamSource(xmlFile);
javax.xml.transform.Source xsltSource =
        new javax.xml.transform.stream.StreamSource(xsltFile);

javax.xml.transform.Result result =
        new javax.xml.transform.stream.StreamResult(System.out);

javax.xml.transform.TransformerFactory transFact =
        javax.xml.transform.TransformerFactory.newInstance( );

The TransformerFactory is responsible for creating Transformer and Template objects. In our simple example, we create a Transformer object:

javax.xml.transform.Transformer trans =
        transFact.newTransformer(xsltSource);

The transformer instance is then used to perform the actual transformation:

trans.transform(xmlSource, result);

This applies the XSLT stylesheet to the XML data, sending the result to System.out.

5.2.2. XSLT Plugability Layer

JAXP 1.1 defines a specific lookup procedure to locate an appropriate XSLT processor. This must be accomplished without hardcoding vendor-specific code into applications, so Java system properties and JAR file service providers are used. Within your code, first locate an instance of the TransformerFactory class as follows:

javax.xml.transform.TransformerFactory transFact =
        javax.xml.transform.TransformerFactory.newInstance( );

java -Djavax.xml.transform.TransformerFactory=com.foobar.AcmeTransformer MyApp

Provided that JAXP is able to instantiate an instance of AcmeTransformer, this is the XSLT processor that will be used. Of course, AcmeTransformer must be a subclass of TransformerFactory for this to work, so it is up to vendors to offer support for JAXP.

If the system property is not specified, JAXP next looks for a property file named lib/jaxp.properties in the JRE directory. A property file consists of name=value pairs, and JAXP looks for a line like this:

javax.xml.transform.TransformerFactory=com.foobar.AcmeTransformer

You can obtain the location of the JRE with the following code:

String javaHomeDir = System.getProperty("java.home");

NOTE: Some popular development tools change the value of java.home when they are installed, which could prevent JAXP from locating jaxp.properties. JBuilder, for instance, installs its own version of Java 2 that it uses by default.

The advantage of creating jaxp.properties in this directory is that you can use your preferred processor for all of your applications that use JAXP without having to specify the system property on the command line. You can still override this file with the -D command-line syntax, however.

If jaxp.properties is not found, JAXP uses the JAR file service provider mechanism to locate an appropriate subclass of TransformerFactory. The service provider mechanism is outlined in the JAR file specification from Sun and simply means that you must create a file in the META-INF/services directory of a JAR file. In JAXP, this file is called javax.xml.transform.TransformerFactory. It contains a single line that specifies the implementation of TransformerFactory: com.foobar.AcmeTransformer in our fictitious example. If you look inside of xalan.jar in JAXP 1.1, you will find this file. In order to utilize a different parser that follows the JAXP 1.1 convention, simply make sure its JAR file is located first on your CLASSPATH.

1. Use the value of the javax.xml.transform.TransformerFactory system property if it exists.

2. If JRE/lib/jaxp.properties exists, then look for a javax.xml.transform.TransformerFactory=ImplementationClass entry in that file.

3. Use a JAR file service provider to look for a file called META-INF/services/javax.xml.transform.TransformerFactory in any JAR file on the CLASSPATH.

4. Use the default TransformerFactory instance.

The JAXP 1.1 plugability layers for SAX and DOM follow the exact same process as the XSLT layer, only they use the javax.xml.parsers.SAXParserFactory and javax.xml.parsers.DocumentBuilderFactory system properties respectively. It should be noted that JAXP 1.0 uses a much simpler algorithm where it checks only for the existence of the system property. If that property is not set, the default implementation is used.

5.2.3. The Transformer Class

abstract void transform(Source xmlSource, Result outputTarget)
    throws TransformerException

This method is abstract because the TransformerFactory returns a subclass of Transformer that does the actual work. The Source interface defines where the XML data comes from and the Result interface specifies where the transformation result is sent. The TransformerException will be thrown if anything goes wrong during the transformation process and may contain the location of the error and a reference to the original exception. The ability to properly report the location of the error is entirely dependent upon the quality of the underlying XSLT transformer implementation's error reporting. We will talk about specific classes that implement the Source and Result interfaces later in this chapter.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="html"/>
  <xsl:param name="image_dir" select="'images'"/>
  
  <xsl:template match="/">
    <html>
      <body>
        <h1>Stylesheet Parameter Example</h1>
        <img src="{$image_dir}/sample.gif"/>
      </body>
    </html>
  </xsl:template>
</xsl:stylesheet>

Passing a variable for the location of your images is a common technique because your development environment might use a different directory name than your production web server. Another common use for a stylesheet parameter is to pass in data that a servlet generates dynamically, such as a unique ID for session tracking.

From JAXP, pass this parameter via the Transformer instance. The code is simple enough:

javax.xml.transform.Transformer trans =
        transFact.newTransformer(xsltSource);
trans.setParameter("image_dir", "graphics");

You can set as many parameters as you like, and these parameters will be saved and reused for every transformation you make with this Transformer instance. If you wish to remove a parameter, you must call clearParameters( ), which clears all parameters for this Transformer instance. Parameters work similarly to a java.util.Map; if you set the same parameter twice, the second value overwrites the first value.

Another use for the Transformer class is to get and set output properties through one of the following methods:

void setOutputProperties(java.util.Properties props)
void setOutputProperty(String name, String value)
java.util.Properties getOutputProperties( )
String getOutputProperty(String name)

Table 5-1. Constants defined in javax.xml.transform.OutputKeys

It is no coincidence that these output properties are the same as the properties you can set on the <xsl:output> element in your stylesheets. For example:

<xsl:output method="xml" indent="yes" encoding="UTF-8"/>

Using JAXP, you can either specify additional output properties or override those set in the stylesheet. To change the encoding, write this code:

// this will take precedence over any encoding specified in the stylesheet
trans.setOutputProperty(OutputKeys.ENCODING, "UTF-16");

5.2.4. JAXP XSLT Design

Table 5-2. JAXP transformation packages

Figure 5-2. javax.xml.transform class diagram

The URIResolver is responsible for resolving URIs found within stylesheets and is generally something you will not need to deal with directly. It is used when a stylesheet imports or includes another document, and the processor needs to figure out where to look for that document. For example:

<xsl:import href="commonFooter.xslt"/>

ErrorListener, as you may guess, is an interface that allows your code to register as a listener for error conditions. This interface defines the following three methods:

void error(TransformerException ex)
void fatalError(TransformerException ex)
void warning(TransformerException ex)