Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## 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:
  - Define a vendor-neutral and language-neutral interface for tree transformations that will allow an application to use any implementation.
  - Support SAX 1, SAX 2, DOM Level 1, and the `org.xml.serialize.Serializer` interfaces.
  - Provide a good model for concurent and optimized transformations.
  - Provide a reasonable model for incremental processing.
  - Provide a reasonable model for passing data from the calling application to the transformation.

### 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:

- newTransformer() creates a Transformer object associated with the Templates object
- getOutputFormat() returns an org.xml.serialize.OutputFormat object that you may modify and hand in to the Transformer object

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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Copyright © 2000 Apache XML Project. All Rights Reserved.