1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 2 <html> 3 <head> 4 <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5 <title></title> 6 </head> 7 <body> 8 9 <h2>Transformation API For XML </h2> 10 11 12 <h3>Introduction</h3> 13 14 <p>This overview describes the set of APIs contained in 15 javax.xml.transform. For the sake of brevity, these interfaces are referred to 16 as TrAX (Transformations for XML). </p> 17 18 <p>There is a broad need for Java applications to be able to transform XML 19 and related tree-shaped data structures. In fact, XML is not normally very 20 useful to an application without going through some sort of transformation, 21 unless the semantic structure is used directly as data. Almost all XML-related 22 applications need to perform transformations. Transformations may be described 23 by Java code, Perl code, <A href="http://www.w3.org/TR/xslt">XSLT</A> 24 Stylesheets, other types of script, or by proprietary formats. The inputs, one 25 or multiple, to a transformation, may be a URL, XML stream, a DOM tree, SAX 26 Events, or a proprietary format or data structure. The output types are the 27 pretty much the same types as the inputs, but different inputs may need to be 28 combined with different outputs.</p> 29 30 <p>The great challenge of a transformation API is how to deal with all the 31 possible combinations of inputs and outputs, without becoming specialized for 32 any of the given types.</p> 33 34 <p>The Java community will greatly benefit from a common API that will 35 allow them to understand and apply a single model, write to consistent 36 interfaces, and apply the transformations polymorphically. TrAX attempts to 37 define a model that is clean and generic, yet fills general application 38 requirements across a wide variety of uses. </p> 39 40 41 <h3>General Terminology</h3> 42 43 <p>This section will explain some general terminology used in this 44 document. Technical terminology will be explained in the Model section. In many 45 cases, the general terminology overlaps with the technical terminology.</p> 46 47 <ul> 48 <li> 49 <p> 50 <b>Tree</b> 51 <br>This term, as used within this document, describes an 52 abstract structure that consists of nodes or events that may be produced by 53 XML. A Tree physically may be a DOM tree, a series of well balanced parse 54 events (such as those coming from a SAX2 ContentHander), a series of requests 55 (the result of which can describe a tree), or a stream of marked-up 56 characters.</p> 57 </li> 58 <li> 59 <p> 60 <b>Source Tree(s)</b> 61 <br>One or more trees that are the inputs to the 62 transformation.</p> 63 </li> 64 <li> 65 <p> 66 <b>Result Tree(s)</b> 67 <br>One or more trees that are the output of the 68 transformation.</p> 69 </li> 70 <li> 71 <p> 72 <b>Transformation</b> 73 <br>The processor of consuming a stream or tree to produce 74 another stream or tree.</p> 75 </li> 76 <li> 77 <p> 78 <b>Identity (or Copy) Transformation</b> 79 <br>The process of transformation from a source to a result, 80 making as few structural changes as possible and no informational changes. The 81 term is somewhat loosely used, as the process is really a copy. from one 82 "format" (such as a DOM tree, stream, or set of SAX events) to 83 another.</p> 84 </li> 85 <li> 86 <p> 87 <b>Serialization</b> 88 <br>The process of taking a tree and turning it into a stream. In 89 some sense, a serialization is a specialized transformation.</p> 90 </li> 91 <li> 92 <p> 93 <b>Parsing</b> 94 <br>The process of taking a stream and turning it into a tree. In 95 some sense, parsing is a specialized transformation.</p> 96 </li> 97 <li> 98 <p> 99 <b>Transformer</b> 100 <br>A Transformer is the object that executes the transformation. 101 </p> 102 </li> 103 <li> 104 <p> 105 <b>Transformation instructions</b> 106 <br>Describes the transformation. A form of code, script, or 107 simply a declaration or series of declarations.</p> 108 </li> 109 <li> 110 <p> 111 <b>Stylesheet</b> 112 <br>The same as "transformation instructions," except it is 113 likely to be used in conjunction with <A href="http://www.w3.org/TR/xslt">XSLT</A>.</p> 114 </li> 115 <li> 116 <p> 117 <b>Templates</b> 118 <br>Another form of "transformation instructions." In the TrAX 119 interface, this term is used to describe processed or compiled transformation 120 instructions. The Source flows through a Templates object to be formed into the 121 Result.</p> 122 </li> 123 <li> 124 <p> 125 <b>Processor</b> 126 <br>A general term for the thing that may both process the 127 transformation instructions, and perform the transformation.</p> 128 </li> 129 <li> 130 <p> 131 <b>DOM</b> 132 <br>Document Object Model, specifically referring to the 133 <A href="#http://www.w3.org/TR/DOM-Level-2%20">Document Object Model 134 (DOM) Level 2 Specification</A>.</p> 135 </li> 136 <li> 137 <p> 138 <b>SAX</b><br> 139 Simple API for XML, specifically referring to the <a href="http://sax.sourceforge.net/">SAX 2.0.2 release</a>. 140 </p> 141 </li> 142 </ul> 143 144 145 146 <h3>Model</h3> 147 148 <p>The section defines the abstract model for TrAX, apart from the details 149 of the interfaces.</p> 150 151 <p>A TRaX <A href="#pattern-TransformerFactory">TransformerFactory</A> is an object 152 that processes transformation instructions, and produces 153 <A href="#pattern-Templates">Templates</A> (in the technical 154 terminology). A <A href="#pattern-Templates">Templates</A> 155 object provides a <A href="#pattern-Transformer">Transformer</A>, which transforms one or 156 more <A href="#pattern-Source">Source</A>s into one or more 157 <A href="#pattern-Result">Result</A>s.</p> 158 159 <p>To use the TRaX interface, you create a 160 <A href="#pattern-TransformerFactory">TransformerFactory</A>, 161 which may directly provide a <A href="#pattern-Transformers">Transformers</A>, or which can provide 162 <A href="#pattern-Templates">Templates</A> from a variety of 163 <A href="#pattern-Source">Source</A>s. The 164 <A href="#pattern-Templates">Templates</A> object is a processed 165 or compiled representation of the transformation instructions, and provides a 166 <A href="#pattern-Transformer">Transformer</A>. The 167 <A href="#pattern-Transformer">Transformer</A> processes a 168 <A href="#pattern-Transformer">Source</A> according to the 169 instructions found in the <A href="#pattern-Templates">Templates</A>, and produces a 170 <A href="#pattern-Result">Result</A>.</p> 171 172 <p>The process of transformation from a tree, either in the form of an 173 object model, or in the form of parse events, into a stream, is known as 174 <code>serialization</code>. We believe this is the most suitable term for 175 this process, despite the overlap with Java object serialization.</p> 176 177 <H3>TRaX Patterns</H3> 178 <ul> 179 <p> 180 <b><a name="pattern-Processor">Processor</a></b> 181 <br> 182 <br> 183 <i>Intent: </i>Generic concept for the 184 set of objects that implement the TrAX interfaces.<br> 185 <i>Responsibilities: </i>Create compiled transformation instructions, transform 186 sources, and manage transformation parameters and 187 properties.<br> 188 <i>Thread safety: </i>Only the Templates object can be 189 used concurrently in multiple threads. The rest of the processor does not do 190 synchronized blocking, and so may not be used to perform multiple concurrent 191 operations. Different Processors can be used concurrently by different 192 threads.</p> 193 <p> 194 <b><a name="pattern-TransformerFactory">TransformerFactory</a></b> 195 <br> 196 <br> 197 <i>Intent: </i>Serve as a vendor-neutral Processor interface for 198 <A href="http://www.w3.org/TR/xslt">XSLT</A> and similar 199 processors.<br> 200 <i>Responsibilities: </i>Serve as a factory for a concrete 201 implementation of an TransformerFactory, serve as a direct factory for 202 Transformer objects, serve as a factory for Templates objects, and manage 203 processor specific features.<br> 204 <i>Thread safety: </i>A 205 TransformerFactory may not perform multiple concurrent 206 operations.</p> 207 <p> 208 <b><a name="pattern-Templates">Templates</a></b> 209 <br> 210 <br> 211 <i>Intent: </i>The 212 runtime representation of the transformation instructions.<br> 213 <i>Responsibilities: </i>A data bag for transformation instructions; act as a factory 214 for Transformers.<br> 215 <i>Thread safety: </i>Thread-safe for concurrent 216 usage over multiple threads once construction is complete.</p> 217 <p> 218 <b><a name="pattern-Transformer">Transformer</a></b> 219 <br> 220 <br> 221 <i>Intent: </i>Act as a per-thread 222 execution context for transformations, act as an interface for performing the 223 transformation.<br> 224 <i>Responsibilities: </i>Perform the 225 transformation.<br> 226 <i>Thread safety: </i>Only one instance per thread 227 is safe.<br> 228 <i>Notes: </i>The Transformer is bound to the Templates 229 object that created it.</p> 230 <p> 231 <b><a name="pattern-Source">Source</a></b> 232 <br> 233 <br> 234 <i>Intent: </i>Serve as a 235 single vendor-neutral object for multiple types of input.<br> 236 <i>Responsibilities: </i>Act as simple data holder for System IDs, DOM nodes, streams, 237 etc.<br> 238 <i>Thread safety: </i>Thread-safe concurrently over multiple 239 threads for read-only operations; must be synchronized for edit 240 operations.</p> 241 <p> 242 <b><a name="pattern-Result">Result</a></b> 243 <br> 244 <br> 245 <i>Potential alternate name: </i>ResultTarget<br> 246 <i>Intent: </i>Serve 247 as a single object for multiple types of output, so there can be simple process 248 method signatures.<br> 249 <i>Responsibilities: </i>Act as simple data holder for 250 output stream, DOM node, ContentHandler, etc.<br> 251 <i>Thread safety: </i>Thread-safe concurrently over multiple threads for read-only, 252 must be synchronized for edit.</p> 253 </ul> 254 255 256 </body> 257 </html> 258
