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

These constants are useful when you call methods such as
getOutputProperty()
and
setOutputProperty()
on the
Transformer
object.

javax.xml.transform.Result

Result
is an interface; it exists as an abstraction of the three classes
SAXResult
,
DOMResult
, and
StreamResult
, which are different ways of representing an XML output destination. This allows any of these different kinds of destination to be supplied as the second argument to the
Transformer.transform()
method. Implementations can also define other kinds of
Result
objects if they wish.

This class defines the two static constants
PI_DISABLE_OUTPUT_ESCAPING
and
PI_ENABLE OUTPUT_ESCAPING
which are the names of the processing instructions generated as a result of setting
disable-output-escaping=“yes”
on the

or
xsl:value-of
instruction in the stylesheet.

The interface defines two methods, allowing any of the different types of
Result
to have a system identifier (or base URI):

javax.xml.transform.sax.SAXResult

Specifying a
SAXResult
as the output of the transformation causes the result tree produced by the transformation to be fed to a user-supplied SAX2
ContentHandler
as a sequence of SAX events, just as if the events came from an XML parser. The
SAXResult
object holds a reference to this
ContentHandler
, and also to a
String
containing a system identifier. (This system identifier might be made available to the
ContentHandler
code as part of the
Locator
object, though the specification doesn't make it clear that this is what should happen.)

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

There are several potential difficulties with supplying XSLT output to a
ContentHandler
:

• What happens about
  disable-output-escaping
  ? The JAXP specification solves this by saying that any text output using
  disable-output-escaping=“yes”
  will be preceded by a processing instruction named by the constant
  Result.PI_DISABLE_OUTPUT_ESCAPING
  , and followed by another processing instruction named by the constant
  Result.PI_ENABLE_OUTPUT_ESCAPING
  .
  
• What happens to comments in the result tree? JAXP solves this by allowing the
  SAXResult
  to hold a
  LexicalHandler
  as well as a
  ContentHandler
  . Comments can then be notified to the
  LexicalHandler
  .
  
• What happens if the result tree is not a well-formed document? The SAX
  ContentHandler
  interface is designed to receive a stream of events representing a well-formed document, and many
  ContentHandlers
  will fail (gracefully or otherwise) if they are sent anything else. However, as you saw in Chapter 2, the output of an XSLT transformation needs only to be well balanced. Unfortunately, the JAXP specification doesn't answer this question. (Saxon allows any sequence of events to be sent to the
  ContentHandler
  , whether it represents a well-formed sequence or not, unless the additional attribute
  saxon:require-well-formed=“yes”
  is present on the
  
  declaration.)
  

The class has two constructors:

and the following methods:

javax.xml.transform.sax.SAXSource

A
SAXSource
is a
Source
, so it is one of the possible inputs you can supply to the
Transformer.transform()
method (when it represents a source XML document) or to the
TransformerFactory.newTemplates()
method (when it represents a stylesheet).

Essentially, a
SAXSource
is the combination of a SAX parser (
XMLReader
) and a SAX
InputSource
, which can be a URI, a binary input stream, or a character input stream. A
SAXSource
delivers the source document in the form of a stream of SAX events. Usually it will achieve this by parsing XML held in a file or somewhere in memory, but by defining your own implementations of
XMLReader
and/or
InputSource
, you can supply the SAX events from anywhere; for example, you can generate them as the result of an SQL query or an LDAP directory search, or you could use an
XMLFilter
that modifies the events coming through from a real XML parser before passing them on to the transformation.

If no
XMLReader
is supplied, the system will use a default one. It may do this using the rules for the
javax.xml.parsers.SAXParserFactory
class described earlier in this appendix, but this is not guaranteed.

Not every XSLT processor will support SAX input. If the processor does so, then calling
getFeature(SAXSource.FEATURE)
on the
TransformerFactory
will return
true
.

There are three constructors:

plus the following methods:

javax.xml.transform.sax.SAXTransformerFactory

This class is a subclass of
TransformerFactory
that provides three additional facilities:

• The ability to construct a SAX
  ContentHandler
  (called a
  TemplatesHandler
  ), which will accept a stream of SAX events representing a stylesheet, and on completion return a
  Templates
  object for this stylesheet.
  
• The ability to construct a SAX
  ContentHandler
  (called a
  TransformerHandler
  ) that will accept a stream of SAX events representing a source document, and on completion automatically apply a given stylesheet to that source document.
  
• The ability to construct a SAX
  XMLFilter
  based on a particular stylesheet: the
  XMLFilter
  performs the same SAX-to-SAX transformation as the equivalent
  Transformer
  would perform, but using the interfaces defined for an
  XMLFilter
  . This makes it possible to insert this transformation filter into a pipeline of filters.
  

These facilities were made optional because it was assumed that not every JAXP processor will support them; in practice, all mainstream implementations do.

• If
  getFeature(SAXTransformerFactory.FEATURE)
  returns
  true
  , then the implementation's
  TransformerFactory
  will be a
  SAXTransformerFactory
  .
  
• If
  getFeature(SAXTransformerFactory.FEATURE_XMLFILTER)
  returns
  true
  , then the two
  newXMLFilter()
  methods can be used.
  

If a
SAXTransformerFactory
is available at all, then it will always be produced as a result of calling
TransformerFactory.newInstance()
.

The class has the following methods, in addition to those of
TransformerFactory
: