overview.html revision 286
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiCopyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiDO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiThis code is free software; you can redistribute it and/or modify it
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchiunder the terms of the GNU General Public License version 2 only, as
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchipublished by the Free Software Foundation. Oracle designates this
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchiparticular file as subject to the "Classpath" exception as provided
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchiby Oracle in the LICENSE file that accompanied this code.
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiThis code is distributed in the hope that it will be useful, but WITHOUT
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchiversion 2 for more details (a copy is included in the LICENSE file that
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchiaccompanied this code).
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiYou should have received a copy of the GNU General Public License version
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi2 along with this work; if not, write to the Free Software Foundation,
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert MustacchiPlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchior visit www.oracle.com if you need additional information or have any
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi content="$Id: overview.html,v 1.2 2005/06/10 03:50:39 jeffsuttor Exp $" />
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi content="Jeff.Suttor@Sun.com" />
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>This overview describes the set of APIs contained in
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi javax.xml.transform. For the sake of brevity, these interfaces are referred to
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi as TrAX (Transformations for XML). </p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>There is a broad need for Java applications to be able to transform XML
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi and related tree-shaped data structures. In fact, XML is not normally very
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi useful to an application without going through some sort of transformation,
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi unless the semantic structure is used directly as data. Almost all XML-related
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi applications need to perform transformations. Transformations may be described
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi by Java code, Perl code, <A href="http://www.w3.org/TR/xslt">XSLT</A>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi Stylesheets, other types of script, or by proprietary formats. The inputs, one
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi or multiple, to a transformation, may be a URL, XML stream, a DOM tree, SAX
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi Events, or a proprietary format or data structure. The output types are the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi pretty much the same types as the inputs, but different inputs may need to be
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi combined with different outputs.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>The great challenge of a transformation API is how to deal with all the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi possible combinations of inputs and outputs, without becoming specialized for
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi any of the given types.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>The Java community will greatly benefit from a common API that will
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi allow them to understand and apply a single model, write to consistent
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi interfaces, and apply the transformations polymorphically. TrAX attempts to
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi define a model that is clean and generic, yet fills general application
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi requirements across a wide variety of uses. </p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>This section will explain some general terminology used in this
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi document. Technical terminology will be explained in the Model section. In many
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi cases, the general terminology overlaps with the technical terminology.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>This term, as used within this document, describes an
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi abstract structure that consists of nodes or events that may be produced by
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi XML. A Tree physically may be a DOM tree, a series of well balanced parse
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi events (such as those coming from a SAX2 ContentHander), a series of requests
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi (the result of which can describe a tree), or a stream of marked-up
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi characters.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>One or more trees that are the inputs to the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi transformation.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>One or more trees that are the output of the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi transformation.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>The processor of consuming a stream or tree to produce
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi another stream or tree.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>The process of transformation from a source to a result,
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi making as few structural changes as possible and no informational changes. The
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi term is somewhat loosely used, as the process is really a copy. from one
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi "format" (such as a DOM tree, stream, or set of SAX events) to
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>The process of taking a tree and turning it into a stream. In
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi some sense, a serialization is a specialized transformation.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>The process of taking a stream and turning it into a tree. In
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi some sense, parsing is a specialized transformation.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>A Transformer is the object that executes the transformation.
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>Describes the transformation. A form of code, script, or
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi simply a declaration or series of declarations.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>The same as "transformation instructions," except it is
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi likely to be used in conjunction with <A href="http://www.w3.org/TR/xslt">XSLT</A>.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>Another form of "transformation instructions." In the TrAX
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi interface, this term is used to describe processed or compiled transformation
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi instructions. The Source flows through a Templates object to be formed into the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>A general term for the thing that may both process the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi transformation instructions, and perform the transformation.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<br>Document Object Model, specifically referring to the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#http://www.w3.org/TR/DOM-Level-2%20">Document Object Model
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi Simple API for XML, specifically referring to the <a href="http://sax.sourceforge.net/">SAX 2.0.2 release</a>.
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>The section defines the abstract model for TrAX, apart from the details
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi of the interfaces.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>A TRaX <A href="#pattern-TransformerFactory">TransformerFactory</A> is an object
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi that processes transformation instructions, and produces
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#pattern-Templates">Templates</A> (in the technical
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi terminology). A <A href="#pattern-Templates">Templates</A>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi object provides a <A href="#pattern-Transformer">Transformer</A>, which transforms one or
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi more <A href="#pattern-Source">Source</A>s into one or more
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>To use the TRaX interface, you create a
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#pattern-TransformerFactory">TransformerFactory</A>,
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi which may directly provide a <A href="#pattern-Transformers">Transformers</A>, or which can provide
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#pattern-Templates">Templates</A> from a variety of
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#pattern-Templates">Templates</A> object is a processed
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi or compiled representation of the transformation instructions, and provides a
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#pattern-Transformer">Transformer</A>. The
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#pattern-Transformer">Transformer</A> processes a
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="#pattern-Transformer">Source</A> according to the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi instructions found in the <A href="#pattern-Templates">Templates</A>, and produces a
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<p>The process of transformation from a tree, either in the form of an
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi object model, or in the form of parse events, into a stream, is known as
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <code>serialization</code>. We believe this is the most suitable term for
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi this process, despite the overlap with Java object serialization.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<b><a name="pattern-Processor">Processor</a></b>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi set of objects that implement the TrAX interfaces.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Responsibilities: </i>Create compiled transformation instructions, transform
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi sources, and manage transformation parameters and
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi properties.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Thread safety: </i>Only the Templates object can be
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi used concurrently in multiple threads. The rest of the processor does not do
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi synchronized blocking, and so may not be used to perform multiple concurrent
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi operations. Different Processors can be used concurrently by different
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<b><a name="pattern-TransformerFactory">TransformerFactory</a></b>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Intent: </i>Serve as a vendor-neutral Processor interface for
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi <A href="http://www.w3.org/TR/xslt">XSLT</A> and similar
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi processors.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Responsibilities: </i>Serve as a factory for a concrete
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi implementation of an TransformerFactory, serve as a direct factory for
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi Transformer objects, serve as a factory for Templates objects, and manage
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi processor specific features.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi TransformerFactory may not perform mulitple concurrent
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi operations.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<b><a name="pattern-Templates">Templates</a></b>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi runtime representation of the transformation instructions.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Responsibilities: </i>A data bag for transformation instructions; act as a factory
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi for Transformers.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Thread safety: </i>Threadsafe for concurrent
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi usage over multiple threads once construction is complete.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<b><a name="pattern-Transformer">Transformer</a></b>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi execution context for transformations, act as an interface for performing the
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi transformation.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi transformation.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Thread safety: </i>Only one instance per thread
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Notes: </i>The Transformer is bound to the Templates
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi object that created it.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi single vendor-neutral object for multiple types of input.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Responsibilities: </i>Act as simple data holder for System IDs, DOM nodes, streams,
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Thread safety: </i>Threadsafe concurrently over multiple
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi threads for read-only operations; must be synchronized for edit
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi operations.</p>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Potential alternate name: </i>ResultTarget<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi as a single object for multiple types of output, so there can be simple process
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi method signatures.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Responsibilities: </i>Act as simple data holder for
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi output stream, DOM node, ContentHandler, etc.<br>
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi<i>Thread safety: </i>Threadsafe concurrently over multiple threads for read-only,
75eba5b6d79ed4d2ce3daf7b2806306b6b69a938Robert Mustacchi must be synchronized for edit.</p>