ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.

advertisement

AddThis Social Bookmark Button

XSLT Processing with Java
Pages: 1, 2, 3, 4, 5, 6, 7, 8, 9

The Transformer Class

As shown in Example 5-3, a Transformer object can be obtained from the TransformerFactory as follows:



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

The Transformer instance is wrapped around an XSLT stylesheet and allows you to perform as many transformations as you wish. The main caveat is thread safety, because many threads cannot use a single Transformer instance concurrently. For each transformation, invoke the transform method:

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

System properties can also be specified in Ant build files.

This method is abstract because the TransformerFactory actually 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.

Aside from actually performing the transformation, the Transformer implementation allows you to set output properties and stylesheet parameters. In XSLT, a stylesheet parameter is declared and used as follows:

<?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</h2>

    <img src="{$image_dir}/sample.gif"/>
   </body>
</html>
</xsl:template>
</xsl:stylesheet>

The <xsl:param> element declares the parameter name and an optional select attribute. This attribute specifies the default value if the stylesheet parameter is not provided. In this case, the string 'images' is the default value and is enclosed in apostrophes so it is treated as a string instead of an XPath expression. Later, the image_dir variable is referred to with the attribute value template syntax: {$image_dir}.

Passing a variable for the location of your images is a common technique for a web application 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)

As you can see, properties are specified as name/value pairs of Strings and can be set and retrieved individually or as a group. Unlike stylesheet parameters, you can un-set an individual property by simply passing in null for the value. The permitted property names are defined in the javax.xml.transform.OutputKeys class and are explained in Table 5-1.

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

Constant

Meaning

CDATA_SECTION_ELEMENTS

Specifies a whitespace-separated list of element names whose content should be output as CDATA sections. See the XSLT specification from the W3C for examples.

DOCTYPE_PUBLIC

Only used if DOCTYPE_SYSTEM is also used, this instructs the processor to output a PUBLIC document type declaration. For example: <!DOCTYPE rootElem PUBLIC "public id" "system id">

DOCTYPE_SYSTEM

Instructs the processor to output a document-type declaration. For example: <!DOCTYPE rootElem SYSTEM "system id">

ENCODING

Specifies the character encoding of the result tree, such as UTF-8 or UTF-16.

INDENT

Specifies whether or not whitespace may be added to the result tree, making the output more readable. Acceptable values are yes and no. Although indentation makes the output more readable, it does make the file size larger, thus harming performance.

MEDIA_TYPE

The MIME type of the result tree.

METHOD

The output method, either xml, html, or text. Although other values are possible, such as xhtml, these are implementation-defined and may be rejected by your processor.

OMIT_XML_DECLARATION

Acceptable values are yes and no, specifying whether or not to include the XML declaration on the first line of the result tree.

STANDALONE

Acceptable values are yes and no, specifying whether or not the XML declaration indicates that the document is standalone. For example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

VERSION

Specifies the version of the output method, typically 1.0 for XML output. This shows up in the XML declaration as follows: <?xml version="1.0" encoding="UTF-8"?>

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");

Keep in mind that this will, in addition to adding encoding="UTF-16" to the XML declaration, actually cause the processor to use that encoding in the result tree. For a value of UTF-16, this means that 16-bit Unicode characters will be generated, so you may have trouble viewing the result tree in many ASCII-only text editors.

JAXP XSLT Design

Now that we have seen some example code and have begun our exploration of the Transformer class, let's step back and look at the overall design of the XSLT plugability layer. JAXP support for XSLT is broken down into the packages listed in Table 5-2

.
Table 5-2: JAXP transformation packages

Package

Description

javax.xml.transform

Defines a general-purpose API for XML transformations without any dependencies on SAX or DOM. The Transformer class is obtained from the TransformerFactory class. The Transformer transforms from a Source to a Result.

javax.xml.transform.dom

Defines how transformations can be performed using DOM. Provides implementations of Source and Result: DOMSource and DOMResult.

javax.xml.transform.sax

Supports SAX2 transformations. Defines SAX versions of Source and Result: SAXSource and SAXResult. Also defines a subclass of TransformerFactory that allows SAX2 events to be fed into an XSLT processor.

javax.xml.transform.stream

Defines I/O stream implementations of Source and Result: StreamSource and StreamResult.

The heart of JAXP XSLT support lies in the javax.xml.transform package, which lays out the mechanics and overall process for any transformation that is performed. This package mostly consists of interfaces and abstract classes, except for OutputKeys and a few exception and error classes. Figure 5-2 presents a UML class diagram that shows all of the pieces in this important package.

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

As you can see, this is a small package, indicative of the fact that JAXP is merely a wrapper around the tools that actually perform transformations. The entry point is TransformerFactory, which creates instances of Transformer, as we have already seen, as well as instances of the Templates abstract class. A Templates object represents a compiled stylesheet and will be covered in detail later in this chapter.

The exact definition of a "compiled" stylesheet is vague. XSLT processors are free to optimize cached stylesheets however they see fit.

The advantage of compilation is performance: the same Templates object can be used over and over by many threads without reparsing the XSLT file.

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)

The TransformerException has the ability to wrap around another Exception or Throwable object and may return an instance of the SourceLocator class. If the underlying XSLT implementation does not provide a SourceLocator, null is returned. The SourceLocator interface defines methods to locate where a TransformerException originated. In the case of error(...) and warning(...), the XSLT processor is required to continue processing the document until the end. For fatalError(...), on the other hand, the XSLT processor is not required to continue. If you do not register an ErrorListener object, then all errors, fatal errors, and warnings are normally written to System.err.

TransformerFactoryConfigurationError and TransformerConfigurationException round out the error-handling APIs for JAXP, indicating problems configuring the underlying XSLT processor implementation. The TransformerFactoryConfigurationError class is generally used when the implementation class cannot be found on the CLASSPATH or cannot be instantiated at all. TransformerConfigurationException simply indicates a "serious configuration error" according to its documentation.

Pages: 1, 2, 3, 4, 5, 6, 7, 8, 9

Next Pagearrow