XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (792 page)

javax.xml.transform.sax.TemplatesHandler

The
TemplatesHandler
interface represents a specialized SAX
ContentHandler
that treats the stream of SAX events supplied to it as the contents of a stylesheet. When the full document has been supplied, the stylesheet is compiled, and the compiled stylesheet can be retrieved using the
getTemplates()
method.

This provides an alternative to calling
TransformerFactory.newTemplates()
and supplying a
SAXSource
as the source of the stylesheet. The case for using a
TemplatesHandler
arises when the source of the SAX events is something other than a SAX
XMLReader;
for example, when the stylesheet is the output of another transformation, in which case the source of the SAX events is a JAXP
Transformer
. In this situation the
TemplatesHandler
can be wrapped into a
SAXResult
and used as the
Result
of the earlier transformation.

A
TemplatesHandler
is always created using the
newTemplatesHandler(
)
method of a
SAXTransformerFactory
. It provides the following methods in addition to those defined in the SAX
ContentHandler
interface:

javax.xml.transform.Transformer

A
Transformer
represents the collection of resources needed to perform a transformation of a
Source
to a
Result
. This includes the compiled stylesheet, the parameter values, and the output properties, as well as details such as an
ErrorListener
and a
URIResolver
.

This interface is analogous to the
IXSLProcessor
class in Microsoft's MSXML API.

A
Transformer
is always created by calling the
newTransformer()
method of either the
Templates
object, or the
TransformerFactory
object.

A transformer can be used to perform more than one transformation, but it is not thread-safe: You should not start one transformation until another has finished. If you want to perform several transformations in parallel, obtain several
Transformers
from the same
Templates
object.

The principal method is
transform()
, which takes two arguments, representing the
Source
and the
Result
. There are several different kinds of
Source
defined, and several kinds of
Result
. These are described elsewhere in this appendix.

The full set of methods is as follows.

Method	Description
void clearParameters()	Clears all parameters set using setParameter() .
ErrorListener getErrorListener()	Gets the ErrorListener for this transformation.
java.util.Properties getOutputProperties()	Gets the output properties defined for this transformation. This will be a combination of those defined in the stylesheet and those defined using setOutputProperty() and setOutput Properties() .
String getOutputProperty(String)	Gets a specific output property defined for this transformation. The argument should be one of the constants defined in OutputKeys , or a vendor-specific property name.
Object getParameter(String)	Gets the value of a parameter defined for this transformation.
URIResolver getURIResolver()	Gets the URIResolver used for this transformation, or null if none has been supplied.
void setErrorListener(ErrorListener)	Sets the ErrorListener to be used to handle errors reported during this transformation.
void setOutputProperties(java.util.Properties)	Sets output properties for the result of this transformation. These properties override any values set using in the stylesheet. The property names will normally be constants defined in OutputKeys , or vendor-defined properties, but they can also be user-defined properties provided they are namespace-qualified. Names are namespace-qualified using the {uri}localname notation, in the same way as parameters.
void setOutputProperty(String, String)	Sets the value of a specific output property for the result of this transformation.
void setParameter(String, Object)	Supplies a parameter for the transformation. The first argument corresponds to the parameter name, as defined in a global element in the stylesheet; if this is namespace-qualified, it should be written in the form urilocal-name . The second argument is the parameter value. It's not defined in the JAXP specification what the mapping from Java objects to XPath data types is. Using a String , a Double , a Boolean , or a DOM Node is likely to work in most processors, but beyond this, it depends on the implementation.
void setURIResolver(URIResolver)	Sets the URIResolver to be used to resolve all URIs encountered during this transformation, especially when evaluating the document() function.
void transform(Source, Result)	Performs the transformation. Source and Result are interfaces, allowing a wide range of different types of Source and Result to be supplied.

javax.xml.transform.TransformerConfigurationException

This class defines a compile-time error, generally an error in the stylesheet. It is a subclass of
TransformerException
and has the same methods as its parent class,
TransformerException
.

There are several constructors defined, but since this object will usually be created by the XSLT processor itself, I won't list them here.

javax.xml.transform.TransformerException

A
TransformerException
represents an error that might be detected either at compile time or at runtime. The exception may contain any or all of the following:

• A message explaining the error.
  
• A nested exception, generally containing additional information about this error. (Actually, despite the name
  getException()
  , this need not be an
  Exception
  object; it can be any
  Throwable
  , allowing an
  Error
  as well as an
  Exception
  .)
  
• A
  SourceLocator
  , indicating where in the stylesheet the error occurred.
  
• A cause. This is likely to be the same as the nested exception. Nested exceptions were introduced in JAXP before they became a standard Java feature in JDK 1.4, which is why there are two methods that appear to do the same thing.
  

There are several constructors defined, but since this object will usually be created by the XSLT processor itself, I won't list them here.

The methods available are:

javax.xml.transform.TransformerFactory

Like the
SAXParserFactory
and
DocumentBuilderFactory
in the
javax.xml.parsers
package, described in the first part of this appendix, this factory class enables you to select a specific vendor's XSLT implementation.

The first thing an application must do is obtain a
TransformerFactory
, which it can do by calling the static method
TransformerFactory.newInstance()
. Different vendors of XSLT processors will each implement their own subclass of
TransformerFactory
, and this method call determines which vendor's processor your application will end up using. If there are several available, the one that is used is based on the following decision process: