Creating and Modifying XML Documents - Beginning Java - page 1292

The Transformer class is the basis for applying Extensible Style Sheet Language Transformations (XSLT)
in Java. A Transformer object transforms an XML document, the sourcetree , into another XML document,
the result tree . What happens to the XML during the transformation depends on the XSL style sheet asso-
ciated with the source tree and how you set the parameters and properties for the Transformer object. I
am going to sidestep most of the details of that and just use a transformer that does nothing. Surprisingly, a
transformer that does nothing can do quite a lot. First I'll explain how you create a Transformer object and
then I'll describe how you might use it.
Creating Transformer Objects
There are no public constructors defined in the Transformer class, so you must call a method for a
TransformerFactory object to create one; this type is defined in the javax.xml.transform package. The
TransformerFactory class does not have any public constructors either, so you must call the static newIn-
stance() method to get a factory object for creating transformers. After you have a factory object, you can
call its newTransformer() method with no parameters to create a Transformer object that is an identity
transform; in other words, it does nothing in transferring the source XML to the result XML. This is the
method I use in examples.
Here's how you create a Transformer object that does nothing:
TransformerFactory factory = TransformerFactory.newInstance();
Transformer transformer = factory.newTransformer();
Both methods can throw exceptions, so you should call them from within a try block. The newIn-
stance() method can throw TransformerFactoryConfigurationError if the factory object cannot be
created. The newTransformer() method throws TransformerConfigurationException if the Trans-
former object cannot be created.
There is a newTranformer() method overload that requires an argument of type Source that encapsu-
lates an XSLT document that defines the transformation to be applied by the Transformer object .
Using Transformer Objects
You apply a transformation to a source document by calling the transform() method for a Transformer
object with the XML source and destination objects as arguments, in that order. You specify the source
as a reference of type javax.xml.transform.Source and the destination as a reference of type
javax.xml.transform.Result . Both Source and Result are interface types, so what you can use as a
source or destination for a transformation is determined by the classes that implement these interfaces.
There are five classes that implement the Source interface, but I use only the DOMSource class that
is defined in the javax.xml.transform.dom package and the StreamSource class that is defined in the
javax.xml.transform.stream package. The DOMSource object encapsulates a Document object contain-
ing an XML document, so a Document object can be a source for a transformation. You could create a
DOMSource object from a Document object, xmlDoc , like this:
DOMSource source = new DOMSource(xmlDoc.getDocumentNode());
A DOMSource object accesses the contents of a Document object through its XML root node. This con-
structor creates a DOMSource object from the document node for the Document object. Another constructor
accepts a String reference as a second argument that specifies the base URI associated with the root node.
You can construct a DOMSource object using the no-arg constructor and then call setNode() for the object