1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3 Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
   6 This code is free software; you can redistribute it and/or modify it
   7 under the terms of the GNU General Public License version 2 only, as
   8 published by the Free Software Foundation.  Oracle designates this
   9 particular file as subject to the "Classpath" exception as provided
  10 by Oracle in the LICENSE file that accompanied this code.
  12 This code is distributed in the hope that it will be useful, but WITHOUT
  13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 version 2 for more details (a copy is included in the LICENSE file that
  16 accompanied this code).
  18 You should have received a copy of the GNU General Public License version
  19 2 along with this work; if not, write to the Free Software Foundation,
  20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  23 or visit www.oracle.com if you need additional information or have any
  24 questions. 
  25 -->
  27 <!DOCTYPE html
  28      PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  29      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  31 <html xmlns="http://www.w3.org/1999/xhtml">
  33 <head>
  34   <title>Transformation API For XML</title>
  36   <meta name="CVS"
  37         content="$Id: overview.html,v 1.2 2005/06/10 03:50:39 jeffsuttor Exp $" />
  38   <meta name="AUTHOR"
  39         content="Jeff.Suttor@Sun.com" />
  40 </head>
  41 <body> 
  43 <h2>Transformation API For XML</h2> 
  46 <h3>Introduction</h3> 
  48 <p>This overview describes the set of APIs contained in
  49          javax.xml.transform. For the sake of brevity, these interfaces are referred to
  50          as TrAX (Transformations for XML). </p> 
  52 <p>There is a broad need for Java applications to be able to transform XML
  53          and related tree-shaped data structures. In fact, XML is not normally very
  54          useful to an application without going through some sort of transformation,
  55          unless the semantic structure is used directly as data. Almost all XML-related
  56          applications need to perform transformations. Transformations may be described
  57          by Java code, Perl code, <A href="http://www.w3.org/TR/xslt">XSLT</A>
  58          Stylesheets, other types of script, or by proprietary formats. The inputs, one
  59          or multiple, to a transformation, may be a URL, XML stream, a DOM tree, SAX
  60          Events, or a proprietary format or data structure. The output types are the
  61          pretty much the same types as the inputs, but different inputs may need to be
  62          combined with different outputs.</p> 
  64 <p>The great challenge of a transformation API is how to deal with all the
  65          possible combinations of inputs and outputs, without becoming specialized for
  66          any of the given types.</p> 
  68 <p>The Java community will greatly benefit from a common API that will
  69          allow them to understand and apply a single model, write to consistent
  70          interfaces, and apply the transformations polymorphically. TrAX attempts to
  71          define a model that is clean and generic, yet fills general application
  72          requirements across a wide variety of uses. </p> 
  75 <h3>General Terminology</h3> 
  77 <p>This section will explain some general terminology used in this
  78                 document. Technical terminology will be explained in the Model section. In many
  79                 cases, the general terminology overlaps with the technical terminology.</p> 
  81 <ul>
  82 <li>
  83 <p>
  84 <b>Tree</b>
  85 <br>This term, as used within this document, describes an
  86                          abstract structure that consists of nodes or events that may be produced by
  87                          XML. A Tree physically may be a DOM tree, a series of well balanced parse
  88                          events (such as those coming from a SAX2 ContentHander), a series of requests
  89                          (the result of which can describe a tree), or a stream of marked-up
  90                          characters.</p>
  91 </li>
  92 <li>
  93 <p>
  94 <b>Source Tree(s)</b>
  95 <br>One or more trees that are the inputs to the
  96                          transformation.</p>
  97 </li>
  98 <li>
  99 <p>
 100 <b>Result Tree(s)</b>
 101 <br>One or more trees that are the output of the
 102                          transformation.</p>
 103 </li>
 104 <li>
 105 <p>
 106 <b>Transformation</b>
 107 <br>The processor of consuming a stream or tree to produce
 108                          another stream or tree.</p>
 109 </li>
 110 <li>
 111 <p>
 112 <b>Identity (or Copy) Transformation</b>
 113 <br>The process of transformation from a source to a result,
 114                          making as few structural changes as possible and no informational changes. The
 115                          term is somewhat loosely used, as the process is really a copy. from one
 116                          "format" (such as a DOM tree, stream, or set of SAX events) to
 117                          another.</p>
 118 </li>
 119 <li>
 120 <p>
 121 <b>Serialization</b>
 122 <br>The process of taking a tree and turning it into a stream. In
 123                          some sense, a serialization is a specialized transformation.</p>
 124 </li>
 125 <li>
 126 <p>
 127 <b>Parsing</b>
 128 <br>The process of taking a stream and turning it into a tree. In
 129                          some sense, parsing is a specialized transformation.</p>
 130 </li>
 131 <li>
 132 <p>
 133 <b>Transformer</b>
 134 <br>A Transformer is the object that executes the transformation.
 135                          </p>
 136 </li>
 137 <li>
 138 <p>
 139 <b>Transformation instructions</b>
 140 <br>Describes the transformation. A form of code, script, or
 141                          simply a declaration or series of declarations.</p>
 142 </li>
 143 <li>
 144 <p>
 145 <b>Stylesheet</b>
 146 <br>The same as "transformation instructions," except it is
 147                          likely to be used in conjunction with <A href="http://www.w3.org/TR/xslt">XSLT</A>.</p>
 148 </li>
 149 <li>
 150 <p>
 151 <b>Templates</b>
 152 <br>Another form of "transformation instructions." In the TrAX
 153                          interface, this term is used to describe processed or compiled transformation
 154                          instructions. The Source flows through a Templates object to be formed into the
 155                          Result.</p>
 156 </li>
 157 <li>
 158 <p>
 159 <b>Processor</b>
 160 <br>A general term for the thing that may both process the
 161                          transformation instructions, and perform the transformation.</p>
 162 </li>
 163 <li>
 164 <p>
 165 <b>DOM</b>
 166 <br>Document Object Model, specifically referring to the
 167                          <A href="#http://www.w3.org/TR/DOM-Level-2%20">Document Object Model
 168                          (DOM) Level 2 Specification</A>.</p>
 169 </li>
 170 <li>
 171         <p>
 172                 <b>SAX</b><br>
 173                 Simple API for XML, specifically referring to the <a href="http://sax.sourceforge.net/">SAX 2.0.2 release</a>.
 174         </p>
 175 </li>
 176 </ul> 
 180 <h3>Model</h3> 
 182 <p>The section defines the abstract model for TrAX, apart from the details
 183          of the interfaces.</p> 
 185 <p>A TRaX <A href="#pattern-TransformerFactory">TransformerFactory</A> is an object
 186          that processes transformation instructions, and produces
 187          <A href="#pattern-Templates">Templates</A> (in the technical
 188          terminology). A <A href="#pattern-Templates">Templates</A>
 189          object provides a <A href="#pattern-Transformer">Transformer</A>, which transforms one or
 190          more <A href="#pattern-Source">Source</A>s into one or more
 191          <A href="#pattern-Result">Result</A>s.</p> 
 193 <p>To use the TRaX interface, you create a
 194          <A href="#pattern-TransformerFactory">TransformerFactory</A>,
 195          which may directly provide a <A href="#pattern-Transformers">Transformers</A>, or which can provide
 196          <A href="#pattern-Templates">Templates</A> from a variety of
 197          <A href="#pattern-Source">Source</A>s. The
 198          <A href="#pattern-Templates">Templates</A> object is a processed
 199          or compiled representation of the transformation instructions, and provides a
 200          <A href="#pattern-Transformer">Transformer</A>. The
 201          <A href="#pattern-Transformer">Transformer</A> processes a
 202          <A href="#pattern-Transformer">Source</A> according to the
 203          instructions found in the <A href="#pattern-Templates">Templates</A>, and produces a
 204          <A href="#pattern-Result">Result</A>.</p> 
 206 <p>The process of transformation from a tree, either in the form of an
 207          object model, or in the form of parse events, into a stream, is known as
 208          <code>serialization</code>. We believe this is the most suitable term for
 209          this process, despite the overlap with Java object serialization.</p>
 211 <H3>TRaX Patterns</H3>
 212 <ul>
 213 <p>
 214 <b><a name="pattern-Processor">Processor</a></b>
 215 <br>
 216 <br>
 217 <i>Intent: </i>Generic concept for the
 218   set of objects that implement the TrAX interfaces.<br>
 219 <i>Responsibilities: </i>Create compiled transformation instructions, transform
 220   sources, and manage transformation parameters and
 221   properties.<br>
 222 <i>Thread safety: </i>Only the Templates object can be
 223   used concurrently in multiple threads. The rest of the processor does not do
 224   synchronized blocking, and so may not be used to perform multiple concurrent
 225   operations. Different Processors can be used concurrently by different
 226   threads.</p>
 227 <p>
 228 <b><a name="pattern-TransformerFactory">TransformerFactory</a></b>
 229 <br>
 230 <br>
 231 <i>Intent: </i>Serve as a vendor-neutral Processor interface for
 232   <A href="http://www.w3.org/TR/xslt">XSLT</A> and similar
 233   processors.<br>
 234 <i>Responsibilities: </i>Serve as a factory for a concrete
 235   implementation of an TransformerFactory, serve as a direct factory for
 236   Transformer objects, serve as a factory for Templates objects, and manage
 237   processor specific features.<br>
 238 <i>Thread safety: </i>A
 239   TransformerFactory may not perform mulitple concurrent
 240   operations.</p>
 241 <p>
 242 <b><a name="pattern-Templates">Templates</a></b>
 243 <br>
 244 <br>
 245 <i>Intent: </i>The
 246   runtime representation of the transformation instructions.<br>
 247 <i>Responsibilities: </i>A data bag for transformation instructions; act as a factory
 248   for Transformers.<br>
 249 <i>Thread safety: </i>Threadsafe for concurrent
 250   usage over multiple threads once construction is complete.</p>
 251 <p>
 252 <b><a name="pattern-Transformer">Transformer</a></b>
 253 <br>
 254 <br>
 255 <i>Intent: </i>Act as a per-thread
 256   execution context for transformations, act as an interface for performing the
 257   transformation.<br>
 258 <i>Responsibilities: </i>Perform the
 259   transformation.<br>
 260 <i>Thread safety: </i>Only one instance per thread
 261   is safe.<br>
 262 <i>Notes: </i>The Transformer is bound to the Templates
 263   object that created it.</p>
 264 <p>
 265 <b><a name="pattern-Source">Source</a></b>
 266 <br>
 267 <br>
 268 <i>Intent: </i>Serve as a
 269   single vendor-neutral object for multiple types of input.<br>
 270 <i>Responsibilities: </i>Act as simple data holder for System IDs, DOM nodes, streams,
 271   etc.<br>
 272 <i>Thread safety: </i>Threadsafe concurrently over multiple
 273   threads for read-only operations; must be synchronized for edit
 274   operations.</p>
 275 <p>
 276 <b><a name="pattern-Result">Result</a></b>
 277 <br>
 278 <br>
 279 <i>Potential alternate name: </i>ResultTarget<br>
 280 <i>Intent: </i>Serve
 281   as a single object for multiple types of output, so there can be simple process
 282   method signatures.<br>
 283 <i>Responsibilities: </i>Act as simple data holder for
 284   output stream, DOM node, ContentHandler, etc.<br>
 285 <i>Thread safety: </i>Threadsafe concurrently over multiple threads for read-only,
 286   must be synchronized for edit.</p>
 287 </ul> 
 290 </body>
 291 </html>