1 <?xml version="1.0" encoding="UTF-8"?> 2 <!-- 3 Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved. 4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 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. 11 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). 17 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. 21 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 --> 26 27 <!DOCTYPE html 28 PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 29 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 30 31 <html xmlns="http://www.w3.org/1999/xhtml"> 32 33 <head> 34 <title>Transformation API For XML</title> 35 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> 42 43 <h2>Transformation API For XML</h2> 44 45 46 <h3>Introduction</h3> 47 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> 51 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> 63 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> 67 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> 73 74 75 <h3>General Terminology</h3> 76 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> 80 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> 177 178 179 180 <h3>Model</h3> 181 182 <p>The section defines the abstract model for TrAX, apart from the details 183 of the interfaces.</p> 184 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> 192 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> 205 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> 210 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> 288 289 290 </body> 291 </html>