Processing XML with Javaв„ў: A Guide to SAX, DOM, JDOM, JAXP, and TrAX

The Transformations API for XML (TrAX) integrates XSLT processing into Java in a manner that is independent of both the specific XSLT processor and the document model. It works equally well with DOM, JDOM, SAX, and raw streams. Indeed, identity transforms can be used to transform one into the other.

javax.xml.transform

The javax.xml.transform package includes the base interfaces and abstract classes that provide abstract representations of both source and result XML documents and of the transformation itself. The subpackages specialize the sources and results for particular document models and APIs.

ErrorListener

ErrorListener is a callback interface that Transformer s use to report problems which occur during a transformation. There are three levels of errors: fatal errors that prevent the transformation from continuing, recoverable errors, and warnings. If a Transformer does not have an ErrorListener , then it prints error messages on System.err .

package javax.xml.transform; public interface ErrorListener { public void warning (TransformerException exception ) throws TransformerException; public void error (TransformerException exception ) throws TransformerException; public void fatalError (TransformerException exception ) throws TransformerException; }

OutputKeys

The OutputKeys class defines named constants for serialization parameters that are normally set by an xsl:output element in an XSLT stylesheet. In TrAX, these are used as the name arguments to the setOutputProperty() and getOutputProperty() methods of the Transformer class.

package javax.xml.transform; public class OutputKeys { public static final String METHOD = "method"; public static final String VERSION = "version"; public static final String ENCODING = "encoding"; public static final String OMIT_XML_DECLARATION = "omit-xml-declaration"; public static final String STANDALONE = "standalone"; public static final String DOCTYPE_PUBLIC = "doctype-public"; public static final String DOCTYPE_SYSTEM = "doctype-system"; public static final String CDATA_SECTION_ELEMENTS = "cdata-section-elements"; public static final String INDENT = "indent"; public static final String MEDIA_TYPE = "media-type"; }

Result

The Result interface is a generic container for an XML document that will be produced by a transformation. Concrete classes implement this interface for SAX event sequences, DOM nodes, streams, and more.

package javax.xml.transform; public interface Result { public static final String PI_DISABLE_OUTPUT_ESCAPING; public static final String PI_ENABLE_OUTPUT_ESCAPING; public void setSystemId (String url ); public String getSystemId (); }

Source

The Source interface is a generic container for existing XML documents that will be used in a transformation as either the input document or the stylesheet. Concrete classes implement this interface for SAX event sequences, DOM nodes, streams, and more.

package javax.xml.transform; public interface Source { public void setSystemId (String systemID ); public String getSystemId (); }

SourceLocator

SourceLocator objects are used by the various kinds of TransformerException to indicate where in which file the problem that caused the exception lies.

package javax.xml.transform; public interface SourceLocator { public String getPublicId (); public String getSystemId (); public int getLineNumber (); public int getColumnNumber (); }

Templates

Templates is a thread-safe class that represents a compiled stylesheet. It can quickly create new Transformer objects without having to reread and reparse the original stylesheet. It's particularly useful when you want to use the same stylesheet in multiple threads.

package javax.xml.transform; public interface Templates { public Transformer newTransformer () throws TransformerConfigurationException; public Properties getOutputProperties (); }

Transformer

Transformer is the class that represents a compiled stylesheet. It transforms Source objects into Result objects. A single Transformer can transform multiple input documents in sequence but not in parallel.

package javax.xml.transform; public abstract class Transformer { protected Transformer (); public void transform (Source input, Result output ) throws TransformerException; public void setParameter (String name, Object value ); public Object getParameter (String name ); public void clearParameters (); public void setURIResolver (URIResolver resolver ); public URIResolver getURIResolver (); public void setOutputProperties (Properties serialization ) throws IllegalArgumentException; public Properties getOutputProperties (); public void setOutputProperty (String name, String value ) throws IllegalArgumentException; public String getOutputProperty (String name ) throws IllegalArgumentException; public void setErrorListener (ErrorListener listener ) throws IllegalArgumentException; public ErrorListener getErrorListener (); }

TransformerFactory

TransformerFactory is an abstract factory that creates new Transformer and Templates objects. The concrete subclass that newInstance() instantiates is specified by the javax.xml.transform.TransformerFactory Java system property. If this class is not set, a platform-dependent default class is chosen .

package javax.xml.transform; public abstract class TransformerFactory { protected TransformerFactory (); public static TransformerFactory newInstance () throws TransformerFactoryConfigurationError; public Transformer newTransformer (Source source ) throws TransformerConfigurationException; public Transformer newTransformer () throws TransformerConfigurationException; public Templates newTemplates (Source source ) throws TransformerConfigurationException; public Source getAssociatedStylesheet (Source source, String media, String title, String charset ) throws TransformerConfigurationException; public void setURIResolver (URIResolver resolver ); public URIResolver getURIResolver (); public boolean getFeature (String name ); public void setAttribute (String name, Object value ) throws IllegalArgumentException; public Object getAttribute (String name ) throws IllegalArgumentException; public void setErrorListener (ErrorListener listener ) throws IllegalArgumentException; public ErrorListener getErrorListener (); }

URIResolver

The XSLT processor passes any URLs encountered in the stylesheet's xsl:import or xsl:include elements or referenced by the document() function to its URIResolver in order to give the program a chance to substitute a different resource. Returning null indicates that the default resolution mechanism should be used. The pattern is very similar to that of the SAX EntityResolver class. You can specify a URIResolver object by passing it to the setURIResolver() method of either Transformer or TransformerFactory .

package javax.xml.transform; public interface URIResolver { public Source resolve (String href, String base ) throws TransformerException; }

Exceptions and Errors

TrAX includes several exceptions and errors for signaling problems that occur during a transformation. Most TrAX methods wrap all checked exceptions that occur during processing in one of the TrAX exception classes. For example, the transform() method does not throw an IOException if the network connection goes down while it's reading a remote input document. Instead it throws a TransformerException .

TransformerConfigurationException

A TransformerConfigurationException is a checked exception thrown when an attempt to create a new Transformer or Templates object fails. The usual reason is a syntax error in the stylesheet or an IOException that prevents the stylesheet from being read completely.

package javax.xml.transform; public class TransformerConfigurationException extends TransformerException { public TransformerConfigurationException (); public TransformerConfigurationException (String message ); public TransformerConfigurationException (Throwable t ); public TransformerConfigurationException (String message, Throwable t ); public TransformerConfigurationException (String message, SourceLocator locator ); public TransformerConfigurationException (String message, SourceLocator locator, Throwable t ); }

TransformerException

TransformerException is a checked exception that signals a problem which occurred during an attempted transformation. Possible causes include malformed input documents, and IOException s that prevent either the input document from being read or the output document from being written.

package javax.xml.transform; public class TransformerException extends Exception { public TransformerException (String message ); public TransformerException (Throwable t ); public TransformerException (String message, Throwable t ); public TransformerException (String message, SourceLocator locator ); public TransformerException (String message, SourceLocator locator, Throwable t ); public SourceLocator getLocator (); public void setLocator (SourceLocator location ); public Throwable getException (); public Throwable getCause (); public Throwable initCause (Throwable cause ); public String getMessageAndLocation (); public String getLocationAsString (); public void printStackTrace (); public void printStackTrace (PrintStream s ); public void printStackTrace (PrintWriter s ); }

TransformerFactoryConfigurationError

A TransformerFactoryConfigurationError indicates a problem with the TransformerFactory . The most common cause is that the specific concrete subclass of TransformerFactory indicated by the javax.xml.transform.TransformerFactory system property could not be found in the local class path . Unlike most errors, it's not a bad idea to catch this and handle it appropriately.

package javax.xml.transform; public class TransformerFactoryConfigurationError extends Error { public TransformerFactoryConfigurationError (); public TransformerFactoryConfigurationError (String message ); public TransformerFactoryConfigurationError (Exception e ); public TransformerFactoryConfigurationError (Exception e, String message ); public String getMessage (); public Exception getException (); }

javax.xml.transform.stream

The javax.xml.transform.stream package contains classes that wrap streams as either input to a transformation or output from a transformation. Supported streams include files, InputStream s and OutputStream s, Reader s and Writer s, files, and URLs.

StreamResult

A StreamResult directs the output of an XSLT transformation onto an OutputStream , Writer , URL, file, or other sink of bytes or characters .

package javax.xml.transform.stream; public class StreamResult implements Result { public static final String FEATURE; public StreamResult (); public StreamResult (OutputStream out ); public StreamResult (Writer writer ); public StreamResult (String systemID ); public StreamResult (File f ); public void setOutputStream (OutputStream out ); public OutputStream getOutputStream (); public void setWriter (Writer out ); public Writer getWriter (); public void setSystemId (String url ); public void setSystemId (File f ); public String getSystemId (); }

If possible, use an OutputStream or a File instead of a Writer so that TrAX can determine where it might need to emit a character reference instead of the actual character. If you specify more than one of these three possibilities, then the one to which the processor writes will be implementation dependent.

StreamSource

A StreamSource provides input to an XSLT processor from an InputStream , Reader , URL, file, or other source of bytes or characters.

package javax.xml.transform.stream; public class StreamSource implements Source { public static final String FEATURE; public StreamSource (); public StreamSource (InputStream in ); public StreamSource (InputStream in, String systemID ); public StreamSource (Reader in ); public StreamSource (Reader in, String systemID ); public StreamSource (String url ); public StreamSource (File f ); public void setInputStream (InputStream in ); public InputStream getInputStream (); public void set"Reader (Reader in ); public Reader get"Reader (); public void setPublicId (String publicID ); public String getPublicId (); public void setSystemId (String url ); public String getSystemId (); public void setSystemId (File f ); }

Always specify a system ID URL when creating a StreamSource . This is needed for resolving relative URLs that occur in the document. If you also specify an InputStream , File , or Reader , then that actual content will be read from that source instead of the URL. If you specify more than one of these three possibilities, then the one from which the processor reads will be implementation dependent.

javax.xml.transform.dom

The javax.xml.transform.dom package contains the classes needed to hook up DOM Node objects to TrAX transformations.

DOMLocator

The DOMLocator interface allows a Transformer reading from a DOMSource to report the actual DOM Node where an error occurred. To use this, you'll need to cast the SourceLocator returned by the getLocator() method in Transformer to DOMLocator . (Naturally this will fail if the original source was not a DOMSource .)

package javax.xml.transform.dom; public interface DOMLocator extends SourceLocator { public Node getOriginatingNode (); }

DOMResult

A DOMResult uses the output of an XSLT transformation to create a new DOM Document or DocumentFragment object.

package javax.xml.transform.dom; public class DOMResult implements Result { public static final String FEATURE; public DOMResult (); public DOMResult (Node node ); public DOMResult (Node node, String systemID ); public void setNode (Node node ); public Node getNode (); public void setSystemId (String url ); public String getSystemId (); }

DOMSource

A DOMSource provides input to an XSLT processor from a DOM Node object. In practice, only DOM Document objects can be transformed reliably, not arbitrary types of nodes.

package javax.xml.transform.dom; public class DOMSource implements Source { public static final String FEATURE; public DOMSource (); public DOMSource (Node node ); public DOMSource (Node node, String systemID ); public void setNode (Node node ); public Node getNode (); public void setSystemId (String url ); public String getSystemId (); }

javax.xml.transform.sax

The javax.xml.transform.sax package contains the classes needed to hook up SAX event sequences (normally represented as ContentHandler s) to TrAX transformations.

SAXResult

A SAXResult passes the output of an XSLT transformation into a SAX ContentHandler (and optionally into a LexicalHandler ). This allows you to post-process the output of a transform with a SAX program.

package javax.xml.transform.sax; public class SAXResult implements Result { public static final String FEATURE; public SAXResult (); public SAXResult (ContentHandler handler ); public void setHandler (ContentHandler handler ); public ContentHandler getHandler (); public void setLexicalHandler (LexicalHandler handler ); public LexicalHandler getLexicalHandler (); public void setSystemId (String systemID ); public String getSystemId (); }

SAXSource

A SAXSource provides input to an XSLT processor from a SAX event sequence. This is especially useful when you want to apply a SAX filter to a document before transforming it.

package javax.xml.transform.sax; public class SAXSource implements Source { public static final String FEATURE; public SAXSource (); public SAXSource (XMLReader reader, InputSource input ); public SAXSource (InputSource input ); public void setXMLReader (XMLReader reader ); public XMLReader getXMLReader (); public void setInputSource (InputSource input ); public InputSource getInputSource (); public void setSystemId (String url ); public String getSystemId (); public static InputSource sourceToInputSource (Source source ); }

SAXTransformerFactory

The SAXTransformerFactory class enables you to create Transformer and Templates objects that apply a SAX filter to the source document before transforming it.

package javax.xml.transform.sax; public abstract class SAXTransformerFactory extends TransformerFactory { public static final String FEATURE; public static final String FEATURE_XMLFILTER; protected SAXTransformerFactory (); public TransformerHandler newTransformerHandler (Source source ) throws TransformerConfigurationException; public TransformerHandler newTransformerHandler ( Templates templates ) throws TransformerConfigurationException; public TransformerHandler newTransformerHandler () throws TransformerConfigurationException; public TemplatesHandler newTemplatesHandler () throws TransformerConfigurationException; public XMLFilter newXMLFilter (Source source ) throws TransformerConfigurationException; public XMLFilter newXMLFilter (Templates templates ) throws TransformerConfigurationException; }

TemplatesHandler

TemplatesHandler is a ContentHandler that builds a Templates object from a SAX event sequence that reads a stylesheet. Client applications do not normally need to use this class directly.

package javax.xml.transform.sax; public interface TemplatesHandler extends ContentHandler { public Templates getTemplates (); public void setSystemId (String url ); public String getSystemId (); }

TransformerHandler

TransformerHandler objects receive SAX events from a transformation and convert them into output. Client applications do not normally need to use this class directly.

package javax.xml.transform.sax; public interface TransformerHandler extends ContentHandler, LexicalHandler, DTDHandler { public void setResult (Result result ) throws IllegalArgumentException; public void setSystemId (String url ); public String getSystemId (); public Transformer getTransformer (); }