Package org.apache.trax

Defines a global interface for generating Templates and performing XML transformations.

See:
          Description

Interface Summary
Templates The Templates object is the runtime representation of compiled transformation instructions.
TemplatesBuilder This is a SAX ContentHandler that may be used to process SAX events into an Templates objects.
Transformer This object represents a Transformer, which is a SAX2 XMLFilter.
URIResolver This version of URIResolver reflects the proposal made by Michael Kay to revise the interface as defined in TRAX 0.6.
 

Class Summary
Examples Some examples to show how the Simple API for Transformations could be used.
Processor A particular transformation Processor is "plugged" into the platform via Processor in one of two ways: 1) as a platform default, and 2) through external specification by a system property named "org.xml.org.apache.trax.Processor.[type]" obtained using java.lang.System.getProperty().
Result Acts as an holder for a transformation result tree.
 

Exception Summary
ProcessorException This exception serves as a root exception of TRaX exception, and is thrown in raw form when an exceptional condition occurs in the Processor object.
ProcessorFactoryException The ProcessorFactoryException is a type of ProcessorException that is thrown when a configurable factory object can not be created.
TransformException This simply subclasses the TransformException for the purposes of being able to be caught in a catch clause.
 

Package org.apache.trax Description

Defines a global interface for generating Templates and performing XML transformations.

A Processor uses a SAX XMLReader and a TemplatesBuilder (a SAX ContentHandler) to process the transformation instructions and produce a Templates object. A Transformer applies the Templates object (with any input parameters and serializer OutputFormat properties) to the XML input and generates the content for a Result object.

Version:
Alpha, 0.5, March 20, 2000
Author:
Scott Boag
(with help from Keith Visco, Mike Kay, Oracle, Assaf Arkin, and many others)
Goals:

Usage Examples

See Examples Page

The TRaX Interfaces

To create a Processor, call the factory interface on the trax.Processor class. The actual Processor is plugged into the platform either as a platform default or as specified by the org.xml.trax.Processor.[type] system property (org.xml.trax.Processor.xslt, for example, indicates an XSLT processor).

The Processor and Transformer both provide SAX style getFeature/setFeature methods. For example, you can ask the Transformer whether it supports the "http://xml.org/trax/features/dom/input" feature before you attempt to process XML input submitted as a DOM tree.

The Processor's primary purpose is to process transformation instructions, such as an XSLT stylesheet, into a threadsafe Templates object. The Processor can get these instructions from a SAX InputSource, a DOM tree, or a list of InputSources specified by an xml-stylesheet instruction in the XML source.

The Templates object is a bag of instructions that tells the Transformer} how to transform a source tree. It is meant to be thread safe for concurrent use in multiple threads. Currently, the Templates object has just two methods:

The Transformer object represents a single transformation. You can only use the Transformer object in one thread at a time. You can pass parameters to the Transformer object, which will then be used during the transformation. You can also set the OutputFormat, which overrides the properties obtained from the owning Templates object. The primary Transformer method is transform(), which takes as input a SAX InputSource}. But there are a couple of other ways to cause a transformation to occur. You can use the transformNode() method to transform a DOM Node. You can also obtain SAX parse event handler interfaces, such as DocumentHandler, which can then be used as SAX event catchers. A Transformer is also a SAX XMLFilter, which resembles an XML reader/parser, except that it obtains its events from another XML reader rather than from a primary source like an XML document or database. For example, you can use the Transformer as a SAX XMLFilter to chain or pipe transformations. The Transformer also allows you to use a SAX XMLFilter polymorphicaly as a SAX XMLReader.

The output of a transformation is specified via a Result object. This is very much like a SAX InputSource, except that it allows you to specify OutputStreams, Writers, or DOM Nodes. To specify SAX output, simply use the SAX XMLReader methods (the Transformer is also a SAX XMLReader), and call the transform() method that takes only an InputSource (no Result object).

Design Patterns

For more detailed information on the patterns see the Design Patterns Document

For open design issues, see the class and method headers.



Copyright © 2000 Apache XML Project. All Rights Reserved.