<?xml version="1.0"?>
<!DOCTYPE spec SYSTEM "../../style/dtd/spec.dtd">
<spec> 
  <title>Transformation API For XML (TrAX)</title>
  <frontmatter> 
  <pubdate>November 12, 2000</pubdate> 
  <copyright>Copyright 2000 Java Community Process (Sun Microsystems,
	 Inc.)</copyright> 
  <author><firstname>Scott</firstname> 
	 <surname>Boag</surname> 
	 <orgname>IBM Research</orgname> 
	 <address> 
		<email>sboag@lotus.com</email> 
	 </address> 
  </author></frontmatter> 
  <introduction> 
  <title>Introduction</title> 
  <para>This overview describes the set of APIs contained in
	 <ulink url="package-summary.html">javax.xml.transform</ulink>, <ulink url="package-summary.html">javax.xml.transform.stream</ulink>, <ulink url="package-summary.html">javax.xml.transform.dom</ulink>, and <ulink url="package-summary.html">javax.xml.transform.sax</ulink>. For the sake of brevity, these interfaces are referred to
	 as TrAX (Transformation API for XML). </para> 
  <para>There is a broad need for Java applications to be able to transform XML
	 and related tree-shaped data structures. In fact, XML is not normally very
	 useful to an application without going through some sort of transformation,
	 unless the semantic structure is used directly as data. Almost all XML-related
	 applications need to perform transformations. Transformations may be described
	 by Java code, Perl code, <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink>
	 Stylesheets, other types of script, or by proprietary formats. The inputs, one
	 or multiple, to a transformation, may be a URL, XML stream, a DOM tree, SAX
	 Events, or a proprietary format or data structure. The output types are the
	 pretty much the same types as the inputs, but different inputs may need to be
	 combined with different outputs.</para> 
  <para>The great challenge of a transformation API is how to deal with all the
	 possible combinations of inputs and outputs, without becoming specialized for
	 any of the given types.</para> 
  <para>The Java community will greatly benefit from a common API that will
	 allow them to understand and apply a single model, write to consistent
	 interfaces, and apply the transformations polymorphically. TrAX attempts to
	 define a model that is clean and generic, yet fills general application
	 requirements across a wide variety of uses. </para> 
  <sect2> 
	 <title>General Terminology</title> 
	 <para>This section will explain some general terminology used in this
		document. Technical terminology will be explained in the Model section. In many
		cases, the general terminology overlaps with the technical terminology.</para> 
	 <variablelist> 
		<varlistentry> 
		  <term>Tree</term> 
		  <listitem>This term, as used within this document, describes an
			 abstract structure that consists of nodes or events that may be produced by
			 XML. A Tree physically may be a DOM tree, a series of well balanced parse
			 events (such as those coming from a SAX2 ContentHander), a series of requests
			 (the result of which can describe a tree), or a stream of marked-up
			 characters.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Source Tree(s)</term> 
		  <listitem>One or more trees that are the inputs to the
			 transformation.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Result Tree(s)</term> 
		  <listitem>One or more trees that are the output of the
			 transformation.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Transformation</term> 
		  <listitem>The processor of consuming a stream or tree to produce
			 another stream or tree.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Identity (or Copy) Transformation</term> 
		  <listitem>The process of transformation from a source to a result,
			 making as few structural changes as possible and no informational changes. The
			 term is somewhat loosely used, as the process is really a copy. from one
			 "format" (such as a DOM tree, stream, or set of SAX events) to
			 another.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Serialization</term> 
		  <listitem>The process of taking a tree and turning it into a stream. In
			 some sense, a serialization is a specialized transformation.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Parsing</term> 
		  <listitem>The process of taking a stream and turning it into a tree. In
			 some sense, parsing is a specialized transformation.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Transformer</term> 
		  <listitem>A Transformer is the object that executes the transformation.
			 </listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Transformation instructions</term> 
		  <listitem>Describes the transformation. A form of code, script, or
			 simply a declaration or series of declarations.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Stylesheet</term> 
		  <listitem>The same as "transformation instructions," except it is
			 likely to be used in conjunction with <ulink
			 url="http://www.w3.org/TR/xslt">XSLT</ulink>.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Templates</term> 
		  <listitem>Another form of "transformation instructions." In the TrAX
			 interface, this term is used to describe processed or compiled transformation
			 instructions. The Source flows through a Templates object to be formed into the
			 Result.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>Processor</term> 
		  <listitem>A general term for the thing that may both process the
			 transformation instructions, and perform the transformation.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>DOM</term> 
		  <listitem>Document Object Model, specifically referring to the
			 <termref link-url="http://www.w3.org/TR/DOM-Level-2 ">Document Object Model
			 (DOM) Level 2 Specification</termref>.</listitem> 
		</varlistentry> 
		<varlistentry> 
		  <term>SAX</term> 
		  <listitem>Simple API for XML, specifically referring to the
			 <termref link-url="http://www.megginson.com/SAX/SAX2">SAX 2.0
			 release</termref>.</listitem> 
		</varlistentry> 
	 </variablelist> 
  </sect2></introduction>
  <requirements> 
  <title>Requirements</title> 
  <para>The following requirements have been determined from broad experience
	 with XML projects from the various members participating on the JCP.</para> 
  <orderedlist> 
	 <listitem id="requirement-simple">TrAX must provide a clean, simple
		interface for simple uses.</listitem> 
	 <listitem id="requirement-general">TrAX must be powerful enough to be
		applied to a wide range of uses, such as, e-commerce, content management,
		server content delivery, and client applications.</listitem> 
	 <listitem id="requirement-optimizeable">A processor that implements a TrAX
		interface must be optimizeable. Performance is a critical issue for most
		transformation use cases.</listitem> 
	 <listitem id="requirement-compiled-model">As a specialization of the above
		requirement, a TrAX processor must be able to support a compiled model, so that
		a single set of transformation instructions can be compiled, optimized, and
		applied to a large set of input sources.</listitem> 
	 <listitem id="requirement-independence">TrAX must not be dependent an any
		given type of transformation instructions. For instance, it must remain
		independent of <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink>.</listitem> 
	 <listitem id="requirement-from-dom">TrAX must be able to allow processors
		to transform DOM trees.</listitem> 
	 <listitem id="requirement-to-dom">TrAX must be able to allow processors to
		produce DOM trees.</listitem> 
	 <listitem id="requirement-from-sax">TrAX must allow processors to transform
		SAX events.</listitem> 
	 <listitem id="requirement-to-sax">TrAX must allow processors to produce SAX
		events.</listitem> 
	 <listitem id="requirement-from-stream">TrAX must allow processors to
		transform streams of XML.</listitem> 
	 <listitem id="requirement-to-stream">TrAX must allow processors to produce
		XML, HTML, and other types of streams.</listitem> 
	 <listitem id="requirement-combo-input-output">TrAX must allow processors to
		implement the various combinations of inputs and outputs within a single
		processor.</listitem> 
	 <listitem id="requirement-limited-input-output">TrAX must allow processors
		to implement only a limited set of inputs. For instance, it should be possible
		to write a processor that implements the TrAX interfaces and that only
		processes DOM trees, not streams or SAX events.</listitem> 
	 <listitem id="requirement-proprietary-data-structures">TrAX should allow a
		processor to implement transformations of proprietary data structures. For
		instance, it should be possible to implement a processor that provides TrAX
		interfaces that performs transformation of JDOM trees.</listitem> 
	 <listitem id="requirement-serialization-props">TrAX must allow the setting
		of serialization properties, without constraint as to what the details of those
		properties are.</listitem> 
	 <listitem id="requirement-setting-parameters">TrAX must allow the setting
		of parameters to the transformation instructions.</listitem> 
	 <listitem id="requirement-namespaced-properties">TrAX must support the
		setting of parameters and properties as XML Namespaced items (i.e., qualified
		names).</listitem> 
	 <listitem id="requirement-relative-url-resolution">TrAX must support URL
		resolution from within the transformation, and have it return the needed data
		structure.</listitem> 
	 <listitem id="requirement-error-reporting">TrAX must have a mechanism for
		reporting errors and warnings to the calling application.</listitem> 
  </orderedlist> </requirements> 
  <model> 
  <title>Model</title> 
  <para>The section defines the abstract model for TrAX, apart from the details
	 of the interfaces.</para> 
  <para>A TRaX <termref
	 link-url="pattern-TransformerFactory">TransformerFactory</termref> is an object
	 that processes transformation instructions, and produces
	 <termref link-url="pattern-Templates">Templates</termref> (in the technical
	 terminology). A <termref link-url="pattern-Templates">Templates</termref>
	 object provides a <termref
	 link-url="pattern-Transformer">Transformer</termref>, which transforms one or
	 more <termref link-url="pattern-Source">Source</termref>s into one or more
	 <termref link-url="pattern-Result">Result</termref>s.</para> 
  <para>To use the TRaX interface, you create a
	 <termref link-url="pattern-TransformerFactory">TransformerFactory</termref>,
	 which may directly provide a <termref
	 link-url="pattern-Transformers">Transformers</termref>, or which can provide
	 <termref link-url="pattern-Templates">Templates</termref> from a variety of
	 <termref link-url="pattern-Source">Source</termref>s. The
	 <termref link-url="pattern-Templates">Templates</termref> object is a processed
	 or compiled representation of the transformation instructions, and provides a
	 <termref link-url="pattern-Transformer">Transformer</termref>. The
	 <termref link-url="pattern-Transformer">Transformer</termref> processes a
	 <termref link-url="pattern-Transformer">Source</termref> according to the
	 instructions found in the <termref
	 link-url="pattern-Templates">Templates</termref>, and produces a
	 <termref link-url="pattern-Result">Result</termref>.</para> 
  <para>The process of transformation from a tree, either in the form of an
	 object model, or in the form of parse events, into a stream, is known as
	 <termref>serialization</termref>. We believe this is the most suitable term for
	 this process, despite the overlap with Java object serialization.</para> 
  <patterns module="TRaX"> <pattern><pattern-name
  id="pattern-Processor">Processor</pattern-name><intent>Generic concept for the
  set of objects that implement the TrAX interfaces.</intent>
  <responsibilities>Create compiled transformation instructions, transform
  sources, and manage transformation parameters and
  properties.</responsibilities><thread-safety>Only the Templates object can be
  used concurrently in multiple threads. The rest of the processor does not do
  synchronized blocking, and so may not be used to perform multiple concurrent
  operations.</thread-safety></pattern><pattern> 
  <pattern-name id="pattern-TransformerFactory">TransformerFactory</pattern-name>
  <intent>Serve as a vendor-neutral Processor interface for
  <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink> and similar
  processors.</intent> <responsibilities>Serve as a factory for a concrete
  implementation of an TransformerFactory, serve as a direct factory for
  Transformer objects, serve as a factory for Templates objects, and manage
  processor specific features.</responsibilities> <thread-safety>A
  TransformerFactory may not perform mulitple concurrent
  operations.</thread-safety> </pattern> <pattern> 
  <pattern-name id="pattern-Templates">Templates</pattern-name> <intent>The
  runtime representation of the transformation instructions.</intent> 
  <responsibilities>A data bag for transformation instructions; act as a factory
  for Transformers.</responsibilities> <thread-safety>Threadsafe for concurrent
  usage over multiple threads once construction is complete.</thread-safety>
  </pattern> <pattern> <pattern-name
  id="pattern-Transformer">Transformer</pattern-name> <intent>Act as a per-thread
  execution context for transformations, act as an interface for performing the
  transformation.</intent><responsibilities>Perform the
  transformation.</responsibilities> <thread-safety>Only one instance per thread
  is safe.</thread-safety> <notes>The Transformer is bound to the Templates
  object that created it.</notes> </pattern> <pattern> 
  <pattern-name id="pattern-Source">Source</pattern-name> <intent>Serve as a
  single vendor-neutral object for multiple types of input.</intent> 
  <responsibilities>Act as simple data holder for System IDs, DOM nodes, streams,
  etc.</responsibilities> <thread-safety>Threadsafe concurrently over multiple
  threads for read-only operations; must be synchronized for edit
  operations.</thread-safety> </pattern><pattern> 
  <pattern-name id="pattern-Result">Result</pattern-name> 
  <potential-alternate-name>ResultTarget</potential-alternate-name> <intent>Serve
  as a single object for multiple types of output, so there can be simple process
  method signatures.</intent> <responsibilities>Act as simple data holder for
  output stream, DOM node, ContentHandler, etc.</responsibilities> 
  <thread-safety>Threadsafe concurrently over multiple threads for read-only,
  must be synchronized for edit.</thread-safety> </pattern> </patterns></model> 
  <sect1 id="package"> 
	 <title>javax.xml.transform</title> 
	 <para>This package defines the generic APIs for processing transformation instructions,
		and performing a transformation from source to result. These 
		interfaces have no dependencies on SAX or the DOM standard, and try to make as
		few assumptions as possible about the details of the source and result of a
		transformation. The API achieves this by defining 
		<plink>javax.xml.transform.Source</plink> and 
		<plink>javax.xml.transform.Result</plink> interfaces.</para> 
	 <para>To define concrete classes for the user, the API defines specializations
		of the interfaces found at the root level. These interfaces are found in 
		<plink>javax.xml.transform.sax</plink>, <plink>javax.xml.transform.dom</plink>,
		and <plink>javax.xml.transform.stream</plink>.</para> 
	 <sect2> 
		<title>Creating Objects</title> 
		<para>The API allows a concrete 
		  <plink>javax.xml.transform.TransformerFactory</plink> object to be created from
		  the static function 
		  <plink>javax.xml.transform.TransformerFactory#newInstance</plink>. The
		  "javax.xml.transform.TransformerFactory" system property determines which
		  factory implementation to instantiate. This property names a concrete subclass
		  of the TransformerFactory abstract class. If this system property is not
		  defined, a platform default is used.</para> 
	 </sect2> 
	 <sect2> 
		<title>Specification of Inputs and Outputs</title> 
		<para>This API defines two interface objects called 
		  <plink>javax.xml.transform.Source</plink> and 
		  <plink>javax.xml.transform.Result</plink>. In order to pass Source and Result
		  objects to the interfaces, concrete classes must be used. The transformation API defines
		  three concrete representations for each of these objects: 
		  <plink>javax.xml.transform.stream.StreamSource</plink> and 
		  <plink>javax.xml.transform.stream.StreamResult</plink>,
		  <plink>javax.xml.transform.sax.SAXSource</plink> and 
		  <plink>javax.xml.transform.sax.SAXResult</plink>, and 
		  <plink>javax.xml.transform.dom.DOMSource</plink> and 
		  <plink>javax.xml.transform.dom.DOMResult</plink>. Each of these objects defines
		  a FEATURE string (which is i the form of a URL), which can be passed into 
		  <plink>javax.xml.transform.TransformerFactory#getFeature</plink> to see if the
		  given type of Source or Result object is supported. For instance, to test if a
		  DOMSource and a StreamResult is supported, you can apply the following
		  test.</para> 
		<programlisting>    TransformerFactory tfactory = TransformerFactory.newInstance();

    if (tfactory.getFeature(DOMSource.FEATURE) &amp;&amp; tfactory.getFeature(StreamResult.FEATURE))
    {
       ...
    }</programlisting>
  </sect2> 
  <sect2> 
	 <title id="qname-delimiter">Qualified Name representation</title> 
	 <para><ulink url="http://www.w3.org/TR/REC-xml-names">Namespaces</ulink>
		present something of a problem area when dealing with XML objects. Qualified
		Names appear in XML markup as prefixed names. But the prefixes themselves do
		not hold identity. Rather, it is the URIs that they contextually map to that
		hold the identity. Therefore, when passing a Qualified Name like "xyz:foo"
		among Java programs, one must provide a means to map "xyz" to a namespace.
		</para> 
	 <para>One solution has been to create a "QName" object that holds the
		namespace URI, as well as the prefix and local name, but this is not always an
		optimal solution, as when, for example, you want to use unique strings as keys
		in a dictionary object. Not having a string representation also makes it
		difficult to specify a namespaced identity outside the context of an XML
		document.</para> 
	 <para>In order to pass namespaced values to transformations, for instance
		as a set of properties to the Serializer, this specification defines that a
		String "qname" object parameter be passed as two-part string, the namespace URI
		enclosed in curly braces ({}), followed by the local name. If the qname has a
		null URI, then the String object only contains the local name. An application
		can safely check for a non-null URI by testing to see if the first character of
		the name is a '{' character.</para> 
	 <para>For example, if a URI and local name were obtained from an element
		defined with &lt;xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/&gt;,
		then the transformation API Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo".
		Note that the prefix is lost.</para> 
  </sect2> 
  <sect2> 
	 <title>Result Tree Serialization</title> 
	 <para>Serialization of the result tree to a stream can be controlled with
		the <plink>javax.xml.transform.Transformer#setOutputProperties</plink> and the 
		<plink>javax.xml.transform.Transformer#setOutputProperty</plink> methods.
		Strings that match the <ulink url="http://www.w3.org/TR/xslt#output">XSLT
		specification for xsl:output attributes</ulink> can be referenced from the 
		<plink>javax.xml.transform.OutputKeys</plink> class. Other strings can be
		specified as well. If the transformer does not recognize an output key, a 
		<plink>java.lang.IllegalArgumentException</plink> is thrown, unless the 
		<emphasis>unless</emphasis> the key name is <link
		linkend="qname-delimiter">namespace qualified</link>. Output key names that are
		qualified by a namespace are ignored or passed on to the serializer
		mechanism.</para> 
	 <para>If all that is desired is the simple identity transformation of a
		source to a result, then <plink>javax.xml.transform.TransformerFactory</plink>
		provides a
		<plink>javax.xml.transform.TransformerFactory#newTransformer()</plink> method
		with no arguments. This method creates a Transformer that effectively copies
		the source to the result. This method may be used to create a DOM from SAX
		events or to create an XML or HTML stream from a DOM or SAX events.</para>
</sect2> 
<sect2> 
  <title>Exceptions and Error Reporting</title> 
  <para>The transformation API throws three types of specialized exceptions. A
	 <plink>javax.xml.transform.TransformerFactoryConfigurationError</plink> is parallel to
	 the <plink>javax.xml.parsers.FactoryConfigurationError</plink>, and is thrown
	 when a configuration problem with the TransformerFactory exists. This error
	 will typically be thrown when the transformation factory class specified with
	 the "javax.xml.transform.TransformerFactory" system property cannot be found or
	 instantiated.</para> 
  <para>A <plink>javax.xml.transform.TransformerConfigurationException</plink>
	 may be thrown if for any reason a Transformer can not be created. A
	 TransformerConfigurationException may be thrown if there is a syntax error in
	 the transformation instructions, for example when
	 <plink>javax.xml.transform.TransformerFactory#newTransformer</plink> is
	 called.</para> 
  <para><plink>javax.xml.transform.TransformerException</plink> is a general
	 exception that occurs during the course of a transformation. A transformer
	 exception may wrap another exception, and if any of the
	 <plink>javax.xml.transform.TransformerException#printStackTrace()</plink>
	 methods are called on it, it will produce a list of stack dumps, starting from
	 the most recent. The transformer exception also provides a
	 <plink>javax.xml.transform.SourceLocator</plink> object which indicates where
	 in the source tree or transformation instructions the error occurred.
	 <plink>javax.xml.transform.TransformerException#getMessageAndLocation()</plink>
	 may be called to get an error message with location info, and
	 <plink>javax.xml.transform.TransformerException#getLocationAsString()</plink>
	 may be called to get just the location string.</para> 
  <para>Transformation warnings and errors are normally first sent to a
	 <plink>javax.xml.transform.ErrorListener</plink>, at which point the
	 implementor may decide to report the error or warning, and may decide to throw
	 an exception for a non-fatal error. The error listener may be set via
	 <plink>javax.xml.transform.TransformerFactory#setErrorListener</plink> for
	 reporting errors that have to do with syntax errors in the transformation
	 instructions, or via
	 <plink>javax.xml.transform.Transformer#setErrorListener</plink> to report
	 errors that occur during the transformation. The error listener on both objects
	 should always be valid and non-null, whether set by the user or a default
	 implementation provided by the processor.</para> 
</sect2> 
<sect2> 
  <title>Resolution of URIs within a transformation</title> 
  <para>The API provides a way for URIs referenced from within the stylesheet
	 instructions or within the transformation to be resolved by the calling
	 application. This can be done by creating a class that implements the
	 URIResolver interface, with its one method,
	 <plink>javax.xml.transform.URIResolver#resolve</plink>, and use this class to
	 set the URI resolution for the transformation instructions or transformation
	 with <plink>javax.xml.transform.TransformerFactory#setURIResolver</plink> or
	 <plink>javax.xml.transform.Transformer#setURIResolver</plink>. The
	 URIResolver.resolve method takes two String arguments, the URI found in the
	 stylesheet instructions or built as part of the transformation process, and the
	 base URI in effect when the URI passed as the first argument was encountered.
	 The returned <plink>javax.xml.transform.Source</plink> object must be usable by
	 the transformer, as specified in its implemented features.</para> 
</sect2> 
<sect2 id="specialized-packages"> 
<title>Specialized Packages</title> 
<sect3> 
  <title>javax.xml.transform.stream</title> 
  <para>This package implements stream- and URI- specific transformation APIs.
	 </para> 
  <para>The <plink>javax.xml.transform.stream.StreamSource</plink> class
	 provides methods for specifying <plink>java.io.InputStream</plink> input,
	 <plink>java.io.Reader</plink> input, and URL input in the form of strings. Even
	 if an input stream or reader is specified as the source,
	 <plink>javax.xml.transform.stream.StreamSource#setSystemId</plink> should still
	 be called, so that the transformer can know from where it should resolve
	 relative URIs. The public identifier is always optional: if the application
	 writer includes one, it will be provided as part of the
	 <plink>javax.xml.transform.SourceLocator</plink> information.</para> 
  <para>The <plink>javax.xml.transform.stream.StreamResult</plink> class
	 provides methods for specifying <plink>java.io.OutputStream</plink>,
	 <plink>java.io.Writer</plink>, or an output system ID, as the output of the
	 transformation result.</para> 
  <para>Normally streams should be used rather than readers or writers, for
	 both the Source and Result, since readers and writers already have the encoding
	 established to and from the internal Unicode format. However, there are times
	 when it is useful to write to a character stream, such as when using a
	 StringWriter in order to write to a String, or in the case of reading source
	 XML from a StringReader.</para> 
</sect3> 
<sect3> 
<title>javax.xml.transform.sax</title> 
<para>This package implements SAX2-specific transformation APIs. It provides
  classes which allow input from <plink>org.xml.sax.ContentHandler</plink>
  events, and also classes that produce org.xml.sax.ContentHandler events. It
  also provides methods to set the input source as an
  <plink>org.xml.sax.XMLReader</plink>, or to use a
  <plink>org.xml.sax.InputSource</plink> as the source. It also allows the
  creation of a <plink>org.xml.sax.XMLFilter</plink>, which enables
  transformations to "pull" from other transformations, and lets the transformer
  to be used polymorphically as an <plink>org.xml.sax.XMLReader</plink>.</para> 
<para>The <plink>javax.xml.transform.sax.SAXSource</plink> class allows the
  setting of an <plink>org.xml.sax.XMLReader</plink> to be used for "pulling"
  parse events, and an <plink>org.xml.sax.InputSource</plink> that may be used to
  specify the SAX source.</para> 
<para>The <plink>javax.xml.transform.sax.SAXResult</plink> class allows the
  setting of a <plink>org.xml.sax.ContentHandler</plink> to be the receiver of
  SAX2 events from the transformation.</para>
<para>The <plink>javax.xml.transform.sax.SAXTransformerFactory</plink> extends
  <plink>javax.xml.transform.TransformerFactory</plink> to provide factory
  methods for creating <plink>javax.xml.transform.sax.TemplatesHandler</plink>,
  <plink>javax.xml.transform.sax.TransformerHandler</plink>, and
  <plink>org.xml.sax.XMLReader</plink> instances.</para> 
<para>To obtain a <plink>javax.xml.transform.sax.SAXTransformerFactory</plink>,
  the caller must cast the <plink>javax.xml.transform.TransformerFactory</plink>
  instance returned from
  <plink>javax.xml.transform.TransformerFactory#newInstance</plink>.</para>
<para>The <plink>javax.xml.transform.sax.TransformerHandler</plink> interface
  allows a transformation to be created from SAX2 parse events, which is a "push"
  model rather than the "pull" model that normally occurs for a transformation.
  Normal parse events are received through the
  <plink>org.xml.sax.ContentHandler</plink> interface, lexical events such as
  startCDATA and endCDATA are received through the
  <plink>org.xml.sax.ext.LexicalHandler</plink> interface, and events that signal
  the start or end of disabling output escaping are received via
  <plink>org.xml.sax.ContentHandler#processingInstruction</plink>, with the
  target parameter being
  <plink>javax.xml.transform.Result#PI_DISABLE_OUTPUT_ESCAPING</plink> and
  <plink>javax.xml.transform.Result#PI_ENABLE_OUTPUT_ESCAPING</plink>. If
  parameters, output properties, or other features need to be set on the
  Transformer handler, a <plink>javax.xml.transform.Transformer</plink> reference
  will need to be obtained from
  <plink>javax.xml.transform.sax.TransformerHandler#getTransformer</plink>, and
  the methods invoked from that reference.</para>
<para>The <plink>javax.xml.transform.sax.TemplatesHandler</plink> interface
  allows the creation of <plink>javax.xml.transform.Templates</plink> objects
  from SAX2 parse events. Once the <plink>org.xml.sax.ContentHandler</plink>
  events are complete, the Templates object may be obtained from
  <plink>javax.xml.transform.sax.TemplatesHandler#getTemplates</plink>. Note that 
  <plink>javax.xml.transform.sax.TemplatesHandler#setSystemId</plink> should
  normally be called in order to establish a base system ID from which relative
  URLs may be resolved.</para>
<para>The
  <plink>javax.xml.transform.sax.SAXTransformerFactory#newXMLFilter</plink>
  method allows the creation of a <plink>org.xml.sax.XMLFilter</plink>, which
  encapsulates the SAX2 notion of a "pull" transformation. The following
  illustrates several transformations chained together. Each filter points to a
  parent <plink>org.xml.sax.XMLReader</plink>, and the final transformation is
  caused by invoking <plink>org.xml.sax.XMLReader#parse</plink> on the final
  reader in the chain.</para>
</sect3> 
<sect3> 
<title>javax.xml.transform.dom</title> 
<para>This package implements DOM-specific transformation APIs.</para> 
<para>The <plink>javax.xml.transform.dom.DOMSource</plink> class allows the
client of the implementation of this API to specify a DOM
<plink>org.w3c.dom.Node</plink> as the source of the input tree. The model of
how the Transformer deals with the DOM tree in terms of mismatches with the
<ulink url="http://www.w3.org/TR/xslt#data-model">XSLT data model</ulink> or
other data models is beyond the scope of this document. Any of the nodes
derived from <plink>org.w3c.dom.Node</plink> are legal input.</para>
<para>The <plink>javax.xml.transform.dom.DOMResult</plink> class allows a
<plink>org.w3c.dom.Node</plink> to be specified to which result DOM nodes will
be appended. If an output node is not specified, the transformer will use 
<plink>javax.xml.parsers.DocumentBuilder#newDocument</plink> to create an
output <plink>org.w3c.dom.Document</plink> node. If a node is specified, it
should be one of the following: <plink>org.w3c.dom.Document</plink>, 
<plink>org.w3c.dom.Element</plink>, or 
<plink>org.w3c.dom.DocumentFragment</plink>. Specification of any other node
type is implementation dependent and undefined by this API. If the result is a 
<plink>org.w3c.dom.Document</plink>, the output of the transformation must have
a single element root to set as the document element.</para>
<para>The <plink>javax.xml.transform.dom.DOMLocator</plink> node may be passed
to <plink>javax.xml.transform.TransformerException</plink> objects, and
retrieved by trying to cast the result of
the <plink>javax.xml.transform.TransformerException#getLocator()</plink> method.
The implementation has no responsibility to use a DOMLocator instead of
a <plink>javax.xml.transform.SourceLocator</plink> (though line numbers and the
like do not make much sense for a DOM), so the result of getLocator must always
be tested with an instanceof. </para>
</sect3> 
</sect2>
</sect1>
</spec>