<?xml version="1.0" encoding="UTF-8"?>


<!DOCTYPE html
 PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>
 <title>Transformation API For XML</title>

 <meta name="CVS"
 content="$Id: overview.html,v 1.2 2005/06/10 03:50:39 jeffsuttor Exp $" />
 <meta name="AUTHOR"
 content="Jeff.Suttor@Sun.com" />
</head>
<body> 
 
<h2>Transformation API For XML</h2> 
 
 
<h3>Introduction</h3> 
 
This overview describes the set of APIs contained in
	 javax.xml.transform. For the sake of brevity, these interfaces are referred to
	 as TrAX (Transformations for XML). 
 
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, <A href="http://www.w3.org/TR/xslt">XSLT</A>
	 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. 
 
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. 
 
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. 
 
	 
<h3>General Terminology</h3> 
	 
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. 
	 
<ul>
<li>

Tree
 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.
</li>
<li>

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

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

Transformation
 The processor of consuming a stream or tree to produce
			 another stream or tree.
</li>
<li>

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

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

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

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

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

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

Templates
 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.
</li>
<li>

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

DOM
 Document Object Model, specifically referring to the
			 <A href="#http://www.w3.org/TR/DOM-Level-2%20">Document Object Model
			 (DOM) Level 2 Specification</A>.
</li>
<li>
	
		SAX 
		Simple API for XML, specifically referring to the <a href="http://sax.sourceforge.net/">SAX 2.0.2 release</a>.
	
</li>
</ul> 
 
 
 
<h3>Model</h3> 
 
The section defines the abstract model for TrAX, apart from the details
	 of the interfaces. 
 
A TRaX <A href="#pattern-TransformerFactory">TransformerFactory</A> is an object
	 that processes transformation instructions, and produces
	 <A href="#pattern-Templates">Templates</A> (in the technical
	 terminology). A <A href="#pattern-Templates">Templates</A>
	 object provides a <A href="#pattern-Transformer">Transformer</A>, which transforms one or
	 more <A href="#pattern-Source">Source</A>s into one or more
	 <A href="#pattern-Result">Result</A>s. 
 
To use the TRaX interface, you create a
	 <A href="#pattern-TransformerFactory">TransformerFactory</A>,
	 which may directly provide a <A href="#pattern-Transformers">Transformers</A>, or which can provide
	 <A href="#pattern-Templates">Templates</A> from a variety of
	 <A href="#pattern-Source">Source</A>s. The
	 <A href="#pattern-Templates">Templates</A> object is a processed
	 or compiled representation of the transformation instructions, and provides a
	 <A href="#pattern-Transformer">Transformer</A>. The
	 <A href="#pattern-Transformer">Transformer</A> processes a
	 <A href="#pattern-Transformer">Source</A> according to the
	 instructions found in the <A href="#pattern-Templates">Templates</A>, and produces a
	 <A href="#pattern-Result">Result</A>. 
 
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
	 <code>serialization</code>. We believe this is the most suitable term for
	 this process, despite the overlap with Java object serialization.
 
<H3>TRaX Patterns</H3>
<ul>

<a name="pattern-Processor">Processor</a>
 
 
Intent: Generic concept for the
 set of objects that implement the TrAX interfaces. 
Responsibilities: Create compiled transformation instructions, transform
 sources, and manage transformation parameters and
 properties. 
Thread safety: 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. Different Processors can be used concurrently by different
 threads.

<a name="pattern-TransformerFactory">TransformerFactory</a>
 
 
Intent: Serve as a vendor-neutral Processor interface for
 <A href="http://www.w3.org/TR/xslt">XSLT</A> and similar
 processors. 
Responsibilities: 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. 
Thread safety: A
 TransformerFactory may not perform mulitple concurrent
 operations.

<a name="pattern-Templates">Templates</a>
 
 
Intent: The
 runtime representation of the transformation instructions. 
Responsibilities: A data bag for transformation instructions; act as a factory
 for Transformers. 
Thread safety: Threadsafe for concurrent
 usage over multiple threads once construction is complete.

<a name="pattern-Transformer">Transformer</a>
 
 
Intent: Act as a per-thread
 execution context for transformations, act as an interface for performing the
 transformation. 
Responsibilities: Perform the
 transformation. 
Thread safety: Only one instance per thread
 is safe. 
Notes: The Transformer is bound to the Templates
 object that created it.

<a name="pattern-Source">Source</a>
 
 
Intent: Serve as a
 single vendor-neutral object for multiple types of input. 
Responsibilities: Act as simple data holder for System IDs, DOM nodes, streams,
 etc. 
Thread safety: Threadsafe concurrently over multiple
 threads for read-only operations; must be synchronized for edit
 operations.

<a name="pattern-Result">Result</a>
 
 
Potential alternate name: ResultTarget 
Intent: Serve
 as a single object for multiple types of output, so there can be simple process
 method signatures. 
Responsibilities: Act as simple data holder for
 output stream, DOM node, ContentHandler, etc. 
Thread safety: Threadsafe concurrently over multiple threads for read-only,
 must be synchronized for edit.
</ul> 
 

</body>
</html>

Collaborative Calculation and Data Science

colby

sagemath

Product

Resources

Company