ErrorListener is a callback interface Transformers use to report problems that 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;

}

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";

}

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();

}

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 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 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 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 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();

}

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 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;

}

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 instance, 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.

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);

}

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);

}

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();

}

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, you should 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, which one the processor writes to is implementation dependent.

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);

}

You should 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, which one the processor reads from is implementation dependent.

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();

}

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();

}

A DOMSource provides input to an XSLT processor from a DOM Node object. In practice, only DOM Document objects can be reliably transformed, 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();

}

A SAXResult passes the output of an XSLT transformation into a SAX ContentHandler (and optionally 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();

}

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);

}

The SAXTransformerFactory class allows 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 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 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();

}