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

javax.xml.transform.Source

Source
is an interface; it exists as an abstraction of the three classes
SAXSource
,
DOMSource
, and
StreamSource
, which are different ways of representing an XML document. This allows any of these different kinds of object to be supplied as the source document to the
Transformer.transform()
method, or as the stylesheet to the
TransformerFactory.newTemplates()
method.

The interface defines two methods, allowing any of the different types of
Source
to have a system identifier. Specifying a system identifier on a
Sourc
e
object is important, because it will be used as the base URI when relative URIs within the
Source
are resolved.

javax.xml.transform.SourceLocator

SourceLocator
is an interface modeled on the SAX
Locator
interface. A
SourceLocator
is used to indicate where in the stylesheet an error occurred. Normally, a
SourceLocator
will be produced by the XSLT processor, and the application will access it using the
TransformerException.getLocator()
method.

The methods available are:

You can supply a
StreamResult
as the result of a transformation if you want the result tree to be serialized. The format of the resulting file will be XML, HTML, or plain text, depending on the output method defined using

or the
Transformer
methods
setOutputProperty()
and
setOutputProperties()
. With an XSLT 2.0 engine, XHTML output will also be supported.

Note that if you supply a
Writer
(which represents a stream of characters rather than bytes), then the XSLT processor will ignore the
encoding
attribute specified on

. The way in which characters are translated to bytes in this situation depends on how the
Writer
is configured, and not on the XSLT serializer. One consequence of this is that because the
Writer
knows nothing about XML, it will not be able to replace characters that aren't available in the chosen encoding by XML character references of the form
€
.

StreamResult
is defined analogously to
StreamSource
, which in turn is based on the SAX
InputSource
class. A
StreamResult
may be a file (represented by a URL or a Java
File
object), or a character stream (
Writer
), or a byte stream (
OutputStream
).

Most XSLT processors will support stream output, but it is not mandatory. If the processor does support it, then calling
getFeature(StreamResult.FEATURE)
on the
TransformerFactory
will return
true
.

Although the output destination can be expressed as a URI, this must be a writable destination. In practice, this usually means it should be a URI that uses the
file:
prefix, but it could potentially be an FTP or WebDAV destination. If you're running the processor in an applet, writing the output to a file is probably not feasible. The specification doesn't say what happens if you supply a relative URI, but since relative URIs are not allowed in a SAX
InputSource
, on which this class is modeled, it's best to avoid them. Some processors might interpret a relative URI as being relative to the current directory.

The class has constructors for each of the possible output destinations. The constructor for a
String
expects the string to contain a system identifier (URL).

The methods are straightforward:

javax.xml.transform.stream.StreamSource

A
StreamSource
represents XML input in the form of a character or byte stream. It is modeled on the SAX
InputSource
class; the only reason
StreamSource
is necessary is that
InputSource
does not implement the
Source
interface, so it cannot be supplied directly as the input to methods such as
Transformer.transform(Source, Result)
.

Most XSLT processors will support stream input, but it is not mandatory. If the processor does support it, then
getFeature(StreamSource.FEATURE)
will return
true
.

If input is from a byte stream (
InputStream
) or character stream (
Reader
), it is a good idea to call
setSystemId()
to supply a URI for the document, so that relative URIs (for example, those used in the
document()
function) can be resolved. The stream itself does not hold this information, so it must be supplied extraneously.

The constructors are as follows:

In each case, the effect is the same as using the default constructor followed by the relevant
setXXX()
method. The
String
argument is always a system identifier for the document.

The methods are straightforward:

javax.xml.transform.Templates

Templates
is an interface representing a compiled stylesheet. Compiled stylesheets cannot be saved directly to disk (unless the processor provides extensions to enable this), but they are held in memory and can be used as often as required. To use a
Templates
object to perform a transformation, first create a
Transformer
by calling its
newTransformer()
method, then configure the
Transformer
as required (for example, setting its parameters and output properties), and then run the transformation using the
Transformer.transform()
method.

The methods available on the
Templates
object are: