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