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

Supplying a
DOMResult
as the result of a transformation indicates that the output is to be written to a DOM in memory. This object will normally be created by the application and supplied to the processor as the second argument of the
Transformer.transform()
method.

The
DOMResult
identifies a
Node
(which will generally be a
Document
or an
Element
, or possibly a
DocumentFragment
) to hold the results of the transformation. The children of the root in the result tree will become children of this
Node
in the DOM. If no
Node
is supplied by the application, the system will create a
Document
node, which can be retrieved using
getNode()
.

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

If the XSLT stylesheet outputs text using
disable-output-escaping=“yes”
, then this text will be preceded in the tree 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
.

The class has five constructors allowing different combinations of the same three parameters:

• node
  , the node that will become the parent of the new tree. This must be a
  Document
  , an
  Element
  , or a
  DocumentFragment
  .
  
• nextSibling
  (new in JDK 1.5), indicating where in a sequence of existing nodes the new tree should be inserted.
  
• systemId
  , identifying the system identifier of the document, which will typically be used as its base URI.
  

The methods on the class are simply getters and setters for the same three properties.

javax.xml.transform.dom.DOMSource

A
DOMSource
packages a DOM
Document
as a
Source
, so it can be supplied as input to a transformation.

The
DOMSource
object will normally be created by the application and supplied to the processor as the first argument of the
Transformer.transform()
method. It can also be used to identify the stylesheet document, in which case it will be supplied as a parameter to
TransformerFactory.newTemplates()
.

It is a good idea to call
setSystemId()
to supply a base URI for the document, so that relative URIs (for example, those used in the
document()
function) can be resolved. The DOM itself does not hold this information, so it must be supplied extraneously.

The
DOMSource
can identify any node in the DOM; it does not have to be the
Document
node. For example, when you use a
DOMSource
to identify a stylesheet, this might be a stylesheet embedded within another document, in which case the
DOMSource
would identify the

element node. When you supply a node other than the
Document
node as input to the
transform()
method, the effect is not specified very clearly, but it is probably intended that it should behave like the
transformNode()
method in MSXML3. This means that the entire document containing the identified node forms the input to the transformation, but the transformation starts by looking for a template rule that matches the specified node, rather than the one that matches the root node.

Note that there are two different ways XSLT processors might handle the supplied document. They might create the XPath tree model as a view or wrapper around the DOM tree, or they might make a copy. The difference between these approaches will become apparent if the stylesheet makes calls to external Java functions that attempt to manipulate the tree as a DOM. It will also, of course, affect performance. Generally, it is best to supply input as a stream or SAX source if you can. Don't construct a DOM specially in order to supply it as input to a transformation, as you might do if you are used to the Microsoft MSXML API. Most implementations will have an internal tree model that is designed to optimize transformation speed, and this will often run several times faster than the same transformation using the DOM.

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

The class has three constructors:

Its methods are listed below:

javax.xml.transform.ErrorListener

ErrorListener
is an interface; if you want to do your own error handling you can write a class that implements this interface and supply it to the
setErrorListener()
methods of the
Transformer Factory
or
Transformer
class. The
ErrorListener
will be notified of both compile-time and runtime errors.

The class is modeled on the SAX
ErrorHandler
interface, and recognizes three categories of errors: warnings, errors, and fatal errors. After a warning, the transformation can proceed to a successful conclusion; after an error, the processor can continue for the purpose of finding further errors, but in the end it will fail, and after a fatal error, it will stop immediately.

Each method can throw an exception to cause processing to stop immediately, even where the processor is prepared to continue.

Some processors (Xalan in particular) report the output of

to the
ErrorListener
. If
terminate=“no”
is specified, the message is treated as a warning; if
terminate=“yes”
is specified, it is treated as a fatal error. JAXP doesn't dictate how

is handled, and other processors do it differently.

If no
ErrorListener
is supplied, errors will be reported on the standard
System.err
output stream.

The methods are listed below. Each method can throw a
TransformerException
, to terminate processing.

javax.xml.transform.OutputKeys

This class defines a set of constant strings used to represent the standard output properties defined in the

element. This list hasn't yet been updated to support the new properties found in XSLT 2.0. (If you're using Saxon, the missing constants can be found in class
net.sf.saxon.event.SaxonOutputKeys
).

The names of these constants are:

They correspond in the obvious way to the attributes of the

element.