xdocs/sources/xalan/trax.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<!-- 
 * The Apache Software License, Version 1.1
 *
 *
 * Copyright (c) 1999 The Apache Software Foundation.  All rights 
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:  
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Xalan" and "Apache Software Foundation" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written 
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache",
 *    nor may "Apache" appear in their name, without prior written
 *    permission of the Apache Software Foundation.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation and was
 * originally based on software copyright (c) 1999, Lotus
 * Development Corporation., http://www.lotus.com.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 -->
<s1 title="Transformation API For XML">
<ul>
 <li><link anchor="intro">Introduction</link></li>
 <li><link anchor="terminology">General Terminology</link></li>
 <li><link anchor="requirements">Requirements</link></li>
 <li><link anchor="model">Model</link></li>
 <li><link anchor="patterns">Patterns</link></li> 
</ul><anchor name="intro"/>
<s2 title="Introduction">   
<p>This document describes the transformation API for XML (TrAX), the set of APIs contained in
	 <jump href="apidocs/javax/xml/transform/package-summary.html">javax.xml.transform</jump>, <jump href="apidocs/javax/xml/transform/stream/package-summary.html">javax.xml.transform.stream</jump>, <jump href="apidocs/javax/xml/transform/dom/package-summary.html">javax.xml.transform.dom</jump>, and <jump href="apidocs/javax/xml/transform/sax/package-summary.html">javax.xml.transform.sax</jump>.</p> 
  
<p>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, <jump href="http://www.w3.org/TR/xslt">XSLT</jump>
	 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.</p> 
  
<p>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.</p> 
  
<p>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. </p> 
   
</s2><anchor name="terminology"/>	 
<s2 title="General Terminology"> 
	 
<p>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.</p> 
	 
<gloss>
<label>Tree</label>
<item>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.</item>

<label>Source Tree(s)</label>
<item>One or more trees that are the inputs to the
			 transformation.</item>

<label>Result Tree(s)</label>
<item>One or more trees that are the output of the
			 transformation.</item>



<label>Transformation</label>
<item>The process of consuming a stream or tree to produce
			 another stream or tree.</item>



<label>Identity (or Copy) Transformation</label>
<item>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.</item>



<label>Serialization</label>
<item>The process of taking a tree and turning it into a stream. In
			 some sense, a serialization is a specialized transformation.</item>



<label>Parsing</label>
<item>The process of taking a stream and turning it into a tree. In
			 some sense, parsing is a specialized transformation.</item>



<label>Transformer</label>
<item>A Transformer is the object that executes the transformation.
			 </item>



<label>Transformation instructions</label>
<item>Describes the transformation. A form of code, script, or
			 simply a declaration or series of declarations.</item>



<label>Stylesheet</label>
<item>The same as "transformation instructions," except it is
			 likely to be used in conjunction with <jump href="http://www.w3.org/TR/xslt">XSLT</jump>.</item>



<label>Templates</label>
<item>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.</item>



<label>Processor</label>
<item>A general term for the thing that may both process the
			 transformation instructions, and perform the transformation.</item>

       


<label>DOM</label>
<item>Document Object Model, specifically referring to the
			 <jump href="http://www.w3.org/TR/DOM-Level-2%20">Document Object Model
			 (DOM) Level 2 Specification</jump>.</item>


<label>SAX</label>
<item>Simple API for XML, specifically referring to the
			 <jump href="http://www.megginson.com/SAX/SAX2">SAX 2.0
			 release</jump>.</item>
</gloss> 
</s2> <anchor name="requirements"/>
<s2 title="Requirements"> 
  
<p>The following requirements have been determined from broad experience
	 with XML projects from the various members participating on the JCP.</p> 
  
<ul>
<li>TrAX must provide a clean, simple
		interface for simple uses.</li>
<li>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.</li>
<li>A processor that implements a TrAX
		interface must be optimizeable. Performance is a critical issue for most
		transformation use cases.</li>
<li>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.</li>
<li>TrAX must not be dependent an any
		given type of transformation instructions. For instance, it must remain
		independent of <jump href="http://www.w3.org/TR/xslt">XSLT</jump>.</li>
<li>TrAX must be able to allow processors
		to transform DOM trees.</li>
<li>TrAX must be able to allow processors to
		produce DOM trees.</li>
<li>TrAX must allow processors to transform
		SAX events.</li>
<li>TrAX must allow processors to produce SAX
		events.</li>
<li>TrAX must allow processors to
		transform streams of XML.</li>
<li>TrAX must allow processors to produce
		XML, HTML, and other types of streams.</li>
<li>TrAX must allow processors to
		implement the various combinations of inputs and outputs within a single
		processor.</li>
<li>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.</li>
<li>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.</li>
<li>TrAX must allow the setting
		of serialization properties, without constraint as to what the details of those
		properties are.</li>
<li>TrAX must allow the setting
		of parameters to the transformation instructions.</li>
<li>TrAX must support the
		setting of parameters and properties as XML Namespaced items (i.e., qualified
		names).</li>
<li>TrAX must support URL
		resolution from within the transformation, and have it return the needed data
		structure.</li>
<li>TrAX must have a mechanism for
		reporting errors and warnings to the calling application.</li>
</ul>  
   
</s2> <anchor name="model"/>
<s2 title="Model"> 
  
<p>The section defines the abstract model for TrAX, apart from the details
	 of the interfaces.</p> 
  
<p>A TRaX <link anchor="pattern-TransformerFactory">TransformerFactory</link> is an object
	 that processes transformation instructions, and produces
	 <link anchor="pattern-Templates">Templates</link> (in the technical
	 terminology). A <link anchor="pattern-Templates">Templates</link>
	 object provides a <link anchor="pattern-Transformer">Transformer</link>, which transforms one or
	 more <link anchor="pattern-Source">Source</link>s into one or more
	 <link anchor="pattern-Result">Result</link>s.</p> 
  
<p>To use the TRaX interface, you create a
	 <link anchor="pattern-TransformerFactory">TransformerFactory</link>,
	 which may directly provide a <link anchor="pattern-Transformer">Transformers</link>, or which can provide
	 <link anchor="pattern-Templates">Templates</link> from a variety of
	 <link anchor="pattern-Source">Source</link>s. The
	 <link anchor="pattern-Templates">Templates</link> object is a processed
	 or compiled representation of the transformation instructions, and provides a
	 <link anchor="pattern-Transformer">Transformer</link>. The
	 <link anchor="pattern-Transformer">Transformer</link> processes a
	 <link anchor="pattern-Transformer">Source</link> according to the
	 instructions found in the <link anchor="pattern-Templates">Templates</link>, and produces a
	 <link anchor="pattern-Result">Result</link>.</p> 
  
<p>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
	 <ref>serialization</ref>. We believe this is the most suitable term for
	 this process, despite the overlap with Java object serialization.</p> 
</s2><anchor name="patterns"/>
<s2 title="TRaX Patterns">
<p>The intent, responsibilities, and thread safety of TrAX objects:</p>
<ul>
  <li><link anchor="pattern-Processor">Processor</link></li>
  <li><link anchor="pattern-TransformerFactory">TransformerFactory</link></li>
  <li><link anchor="pattern-Templates">Templates</link></li>
  <li><link anchor="pattern-Transformer">Transformer</link></li>
  <li><link anchor="pattern-Source">Source</link></li>
  <li><link anchor="pattern-Result">Result</link></li>  
</ul>
<anchor name="pattern-Processor"/><s3 title="Processor">
<gloss>
<label>Intent</label>
<item>Generic concept for the
  set of objects that implement the TrAX interfaces.</item>
<label>Responsibilities</label>
<item>Create compiled transformation instructions, transform
  sources, and manage transformation parameters and
  properties.</item>
<label>Thread safety</label>
<item>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.</item>
</gloss>
</s3> <anchor name="pattern-TransformerFactory"/>
<s3 title="TransformerFactory">
<gloss>
<label>Intent</label>
<item>Serve as a vendor-neutral Processor interface for
  <jump href="http://www.w3.org/TR/xslt">XSLT</jump> and similar
  processors.</item>
<label>Responsibilities</label>
<item>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.</item>
<label>Thread safety</label>
<item>A TransformerFactory may not perform mulitple concurrent
  operations.</item>
</gloss>  
</s3><anchor name="pattern-Templates"/>
<s3 title="Templates">
<gloss>
<label>Intent</label>
<item>The runtime representation of the transformation instructions.</item>
<label>Responsibilities</label>
<item>A data bag for transformation instructions; act as a factory
  for Transformers.</item>
<label>Thread safety</label>
<item>Threadsafe for concurrent
  usage over multiple threads once construction is complete.</item>
</gloss>  
</s3><anchor name="pattern-Transformer"/>
<s3 title="Transformer">
<gloss>
<label>Intent</label>
<item>Act as a per-thread
  execution context for transformations, act as an interface for performing the
  transformation.</item>
<label>Responsibilities</label>
<item>Perform the
  transformation.</item>
<label>Thread safety</label>
<item>Only one instance per thread
  is safe.</item>
</gloss>  
<note>The Transformer is bound to the Templates
  object that created it.</note>
</s3><anchor name="pattern-Source"/>
<s3 title="Source">
<gloss>
<label>Intent</label>
<item>Serve as a
  single vendor-neutral object for multiple types of input.</item>
<label>Responsibilities</label>
<item>Act as simple data holder for System IDs, DOM nodes, streams,
  etc.</item>
<label>Thread safety</label>
<item>Threadsafe concurrently over multiple
  threads for read-only operations; must be synchronized for edit
  operations.</item>
</gloss>  
</s3><anchor name="pattern-Result"/>
<s3 title="Result">
<p>Alternative name: ResultTarget.</p>
<gloss>
<label>Intent</label>
<item>Serve
  as a single object for multiple types of output, so there can be simple process
  method signatures.</item>
<label>Responsibilities</label>
<item>Act as simple data holder for
  output stream, DOM node, ContentHandler, etc.</item>
<label>Thread safety</label>
<item>Threadsafe concurrently over multiple threads for read-only,
  must be synchronized for edit.</item>
</gloss>
</s3> 
 </s2>
 </s1>