You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sb...@locus.apache.org on 2000/11/01 17:37:46 UTC
cvs commit: xml-xalan/java/src/javax/xml/trax/stream StreamResult.java StreamSource.java
sboag 00/11/01 08:37:44
Added: java/src/javax/xml/trax Features.java Result.java
Source.java SourceLocator.java Templates.java
Transformer.java TransformerException.java
TransformerFactory.java
TransformerFactoryException.java URIResolver.java
package.html trax.properties
java/src/javax/xml/trax/dom DOMLocator.java DOMResult.java
DOMSource.java
java/src/javax/xml/trax/sax SAXResult.java SAXSource.java
SAXTransformerFactory.java SerializerHandler.java
TransformerHandler.java
java/src/javax/xml/trax/stream StreamResult.java
StreamSource.java
Log:
James Davidson, Rajiv Mordani, and myself got together last week at ApacheCon London to work on the TrAX proposal. You can find the results of this work at http://xml.apache.org/trax/trax_10_30_00.zip (sorry about the apache address, it's all I have outside our firewall).
The highlights of the changes are:
1) Processor has been renamed to TransformerFactory, in order to match the javax.xml.parsers pattern.
2) Input and Result are defined with abstract interfaces (Source and Result) that are empty. You must use a concrete implementation of these interfaces.
3) Three subpackages are defined: sax, dom, and stream. These implement the specifics for the given Source and Result types. In addition, the sax package has a SAXTransformerFactory, SerializerHandler, and TransformerHandler.
4) The serializer package is gone (sorry, Assaf). Instead, TransformerFactory now implements a newTransformer method that takes no arguments. This method is defined to return a Transformer that does an identity copy from Source to Result. With this, you can do everything the serializer interface did, and more.
5) The one thing I don't like much, is that TransformerFactory.newInstance no longer takes a string as an argument (which signified the type of TransformerFactory you want). James used the same argument about this as he used about the DOM builder. But, there are complicating factors, and it's better to be more simple now, and add this in later, if it is really needed.
6) The Features class contains URLs for all the supported types of features, i.e. DOM, SAX, etc.
7) Namespaced names (or Universal Names) are specified to be passed as {url}local-name. While this is ugly, it's the only way to cleanly use existing Java classes like Properties that use the String class, and is easy enough to parse. These are used both for output properties, and for variables.
I am pretty happy with this API at this point, though I'm sure it needs some polishing on details. It lines up cleanly with the existing JSR63 transform stuff (a lot of the wording won't have to be changed), allows anybody to define a transformation from any object to any object (for instance, it will be easy to define a JDOM transformer), supports different transformer models, is very powerful, yet is relatively simple for the job to be done. I *think* Mike Kay will be pleased also, but he'll have to speak for himself.
A good place to start is the examples file.
Work to be done:
1) Documentation, both JavaDoc and the JSR doc (which James will do).
2) Rajiv needs to do some work on the TransformerFactory to bring it fully into line with javax.xml.parsers.
3) Respond to comments and requests for revisions.
Revision Changes Path
1.1 xml-xalan/java/src/javax/xml/trax/Features.java
Index: Features.java
===================================================================
package javax.xml.trax;
/**
* This class defines feature URLs that are supported by
* the TrAX subpackages, such as sax, dom, etc. Using these
* values allows the transformer to do an identity comparison
* instead of a lexical comparison, which can greatly improve
* the performance of TransformerFactory#getFeature.
*/
public class Features
{
/**
* If TransformerFactory#getFeature returns true with this value
* passed as a parameter, the transformer supports the interfaces
* found in the javax.xml.trax.sax package.
*/
public static final String SAX="http://xml.org/trax/features/sax";
/**
* If TransformerFactory#getFeature returns true with this value
* passed as a parameter, the transformer supports the interfaces
* found in the javax.xml.trax.dom package.
*/
public static final String DOM="http://xml.org/trax/features/dom";
/**
* If TransformerFactory#getFeature returns true with this value
* passed as a parameter, the transformer supports the interfaces
* found in the javax.xml.trax.stream package.
*/
public static final String STREAM="http://xml.org/trax/features/stream";
}
1.1 xml-xalan/java/src/javax/xml/trax/Result.java
Index: Result.java
===================================================================
package javax.xml.trax;
import java.lang.String;
import java.io.OutputStream;
import java.io.Writer;
/**
* An object that implements this interface contains the information
* needed to build a result tree for a transformation.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface Result
{
}
1.1 xml-xalan/java/src/javax/xml/trax/Source.java
Index: Source.java
===================================================================
package javax.xml.trax;
import java.lang.String;
import java.io.InputStream;
import java.io.Reader;
/**
* An object that implements this interface contains the information
* needed to build a source tree for a transformation.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface Source
{
}
1.1 xml-xalan/java/src/javax/xml/trax/SourceLocator.java
Index: SourceLocator.java
===================================================================
package javax.xml.trax;
/**
* This interface is primarily for the purposes of reporting where
* an error occured in the source or transformation instructions.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface SourceLocator
{
/**
* Return the public identifier for the current document event.
*
* <p>The return value is the public identifier of the document
* entity or of the external parsed entity in which the markup
* triggering the event appears.</p>
*
* @return A string containing the public identifier, or
* null if none is available.
* @see #getSystemId
*/
public String getPublicId();
/**
* Return the system identifier for the current document event.
*
* <p>The return value is the system identifier of the document
* entity or of the external parsed entity in which the markup
* triggering the event appears.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before passing it to the application.</p>
*
* @return A string containing the system identifier, or null
* if none is available.
* @see #getPublicId
*/
public String getSystemId();
/**
* Return the line number where the current document event ends.
*
* <p><strong>Warning:</strong> The return value from the method
* is intended only as an approximation for the sake of error
* reporting; it is not intended to provide sufficient information
* to edit the character content of the original XML document.</p>
*
* <p>The return value is an approximation of the line number
* in the document entity or external parsed entity where the
* markup triggering the event appears.</p>
*
* @return The line number, or -1 if none is available.
* @see #getColumnNumber
*/
public int getLineNumber();
/**
* Return the column number where the current document event ends.
*
* <p><strong>Warning:</strong> The return value from the method
* is intended only as an approximation for the sake of error
* reporting; it is not intended to provide sufficient information
* to edit the character content of the original XML document.</p>
*
* <p>The return value is an approximation of the column number
* in the document entity or external parsed entity where the
* markup triggering the event appears.</p>
*
* @return The column number, or -1 if none is available.
* @see #getLineNumber
*/
public int getColumnNumber();
}
1.1 xml-xalan/java/src/javax/xml/trax/Templates.java
Index: Templates.java
===================================================================
package javax.xml.trax;
import java.util.Properties;
import javax.xml.trax.TransformerException;
/**
* The Templates object is the runtime representation of compiled
* transformation instructions.
*
* <p>Templates must be threadsafe for a given instance
* over multiple threads concurrently, and are generally meant to
* be used multiple times in a given session.</p>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface Templates
{
/**
* Create a new transformation context for this Templates object.
*
* @return A valid non-null instance of a Transformer.
*
* @throws TransformerException if a Transformer can not be created.
*/
Transformer newTransformer() throws TransformerException;
/**
* Get the static properties for xsl:output. The object returned will
* be a clone of the internal values, and thus it can be mutated
* without mutating the Templates object, and then handed in to
* the process method.
*
* <p>For XSLT, Attribute Value Templates attribute values will
* be returned unexpanded (since there is no context at this point).</p>
*
* @return A OutputProperties object that may be mutated.
*/
Properties getOutputProperties();
}
1.1 xml-xalan/java/src/javax/xml/trax/Transformer.java
Index: Transformer.java
===================================================================
package javax.xml.trax;
import java.util.Properties;
/**
* This object represents a Transformer, which can transform a
* source tree into a result tree.
*
* <p>An object of this class can not be used concurrently over
* multiple threads.</p>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public abstract class Transformer
{
/**
* Process the source tree to the output result.
* @param xmlSource The input for the source tree.
* @param outputTarget The output source target.
*
* @throws TransformerException
*/
public abstract void transform(Source xmlSource, Result outputTarget)
throws TransformerException;
/**
* Set the output properties for the transformation. These
* properties will override properties set in the templates
* with xsl:output.
*
* <p>If argument to this function is null, any properties
* previously set will be removed.</p>
*
* @param oformat A set of output properties that will be
* used to override any of the same properties in effect
* for the transformation.
*
* @see org.xml.serialize.OutputFormat
*/
public abstract void setOutputProperties(Properties oformat);
/**
* Set a parameter for the templates.
*
* @param name The name of the parameter,
* which may have a namespace URI.
* @param value The value object. This can be any valid Java object
* -- it's up to the processor to provide the proper
* coersion to the object, or simply pass it on for use
* in extensions.
*/
public abstract void setParameter(String name, Object value);
/**
* Set an object that will be used to resolve URIs used in
* document(), etc.
* @param resolver An object that implements the URIResolver interface,
* or null.
*/
public abstract void setURIResolver(URIResolver resolver);
/**
* Method setProperty
*
* @param name
* @param value
*
* @throws TransformerFactoryException
*/
public abstract void setProperty(String name, Object value)
throws TransformerFactoryException;
/**
* Method getProperty
*
* @param name
*
* @return
*
* @throws TransformerFactoryException
*/
public abstract Object getProperty(String name)
throws TransformerFactoryException;
}
1.1 xml-xalan/java/src/javax/xml/trax/TransformerException.java
Index: TransformerException.java
===================================================================
package javax.xml.trax;
import javax.xml.trax.SourceLocator;
/**
* This simply subclasses the TransformerException for the purposes
* of being able to be caught in a catch clause.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class TransformerException extends Exception
{
SourceLocator locator;
Exception containedException;
/**
* Create a new TransformerException.
*
* @param message The error or warning message.
*/
public TransformerException(String message)
{
super(message);
this.containedException = null;
this.locator = null;
}
/**
* Create a new TransformerException wrapping an existing exception.
*
* @param e The exception to be wrapped.
*/
public TransformerException(Exception e)
{
super("TRaX Transform Exception");
this.containedException = e;
this.locator = null;
}
/**
* Wrap an existing exception in a TransformerException.
*
* <p>This is used for throwing processor exceptions before
* the processing has started.</p>
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param e Any exception
*/
public TransformerException(String message, Exception e)
{
super("TRaX Transform Exception");
this.containedException = e;
this.locator = null;
}
/**
* Create a new TransformerException from a message and a Locator.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a DocumentHandler
* callback.</p>
*
* @param message The error or warning message.
* @param locator The locator object for the error or warning.
*/
public TransformerException(String message, SourceLocator locator)
{
super(message);
this.containedException = null;
this.locator = locator;
}
/**
* Wrap an existing exception in a TransformerException.
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param locator The locator object for the error or warning.
* @param e Any exception
*/
public TransformerException(String message, SourceLocator locator,
Exception e)
{
super(message);
this.containedException = e;
this.locator = locator;
}
}
1.1 xml-xalan/java/src/javax/xml/trax/TransformerFactory.java
Index: TransformerFactory.java
===================================================================
package javax.xml.trax;
import java.io.IOException;
import java.util.Properties;
import java.util.Enumeration;
/**
* A TransformerFactory instance creates Transformer and Template
* objects.
*
* A particular TransformerFactory 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
* "javax.xml.trax.xslt" obtained using java.lang.System.getProperty().
* Or, a given application may set a platform default factory name, which
* will be used if no system property is found.
* A derived class with the specified name shall implement a
* public no-args constructor used by the base abstract class to
* create a concrete instance of this class.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public abstract class TransformerFactory
{
/**
* The name of the default concrete class to be used.
*/
private static String platformDefaultFactoryName = null;
/**
* Set the name of the default concrete class to be used.
*/
private static String PLATFORMDEFAULTFACTORYPROP
= "javax.xml.trax.processor.xslt";
/**
* Set the name of the default concrete class to be used.
*
* @param classname Full classname of concrete implementation
* of the abstract TransformerFactory class.
*/
public static void setPlatformDefault(String classname)
{
platformDefaultFactoryName = classname;
}
/**
* Obtain a new instance of a TransformerFactory object.
*
* A particular TransformerFactory 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
* "javax.xml.trax.xslt" obtained using java.lang.System.getProperty().
* Or, a given application may set a platform default factory name, which
* will be used if no system property is found.
* A derived class with the specified name shall implement a
* public no-args constructor used by the base abstract class to
* create a concrete instance of this class.
*
* @return Concrete instance of an Processor object.
*
* @throws TransformerFactoryException if, for any reason, an
* instance can't be created.
*/
public static TransformerFactory newInstance()
throws TransformerFactoryException
{
TransformerFactory factory = null;
try
{
String factoryKey = PLATFORMDEFAULTFACTORYPROP;
String factoryName = System.getProperty(factoryKey);
if (null == factoryName)
{
factoryName = platformDefaultFactoryName;
}
if (null == factoryName)
{
throw new TransformerFactoryException("Can't find system property: "
+ factoryKey);
}
Class factoryClass = Class.forName(factoryName);
factory = (TransformerFactory) factoryClass.newInstance();
}
catch (java.lang.IllegalAccessException iae)
{
throw new TransformerFactoryException(
"Transformation Processor can not be accessed!", iae);
}
catch (java.lang.InstantiationException ie)
{
throw new TransformerFactoryException(
"Not able to create Transformation Processor!", ie);
}
catch (java.lang.ClassNotFoundException cnfe)
{
throw new TransformerFactoryException(
"Transformation Processor not found!", cnfe);
}
return factory;
}
/**
* Process the source into a Transformer object. Care must
* be given to know that this object can not be used concurrently
* in multiple threads.
*
* @param source An object that holds a URL, input stream, etc.
*
* @return A Transformer object capable of
* being used for transformation purposes in a single thread.
*
* @exception TransformerFactoryException May throw this during the parse when it
* is constructing the Templates object and fails.
*/
public abstract Transformer newTransformer(Source source)
throws TransformerFactoryException;
/**
* Create a new Transformer object that performs a copy
* of the source to the result.
*
* @param source An object that holds a URL, input stream, etc.
*
* @return A Transformer object capable of
* being used for transformation purposes in a single thread.
*
* @return
* @exception TransformerFactoryException May throw this during
* the parse when it is constructing the
* Templates object and it fails.
*/
public abstract Transformer newTransformer()
throws TransformerFactoryException;
/**
* Process the source into a Templates object, which is likely
* a compiled representation of the source. This Templates object
* may then be used concurrently across multiple threads. Creating
* a Templates object allows the TransformerFactory to do detailed
* performance optimization of transformation instructions, without
* penalizing runtime transformation.
*
* @param source An object that holds a URL, input stream, etc.
* @returns A Templates object capable of being used for transformation purposes.
*
* @return
* @exception TransformerFactoryException May throw this during the parse when it
* is constructing the Templates object and fails.
*/
public abstract Templates newTemplates(Source source)
throws TransformerFactoryException;
//======= CONFIGURATION METHODS =======
/**
* Look up the value of a feature.
*
* <p>The feature name is any fully-qualified URI.</p>
* @param name The feature name, which is a fully-qualified
* URI.
* @return The current state of the feature (true or false).
*/
public abstract boolean getFeature(String name);
/**
* Method setProperty
*
* @param name
* @param value
*
* @throws TransformerFactoryException
*/
public abstract void setProperty(String name, Object value)
throws TransformerFactoryException;
/**
* Method getProperty
*
* @param name
*
* @return
*
* @throws TransformerFactoryException
*/
public abstract Object getProperty(String name)
throws TransformerFactoryException;
/**
* Set an object that will be used to resolve URIs used in
* xsl:import, etc. This will be used as the default for the
* transformation.
* @param resolver An object that implements the URIResolver interface,
* or null.
*/
public abstract void setURIResolver(URIResolver resolver);
/**
* Set an object that will be used to resolve URIs used in
* xsl:import, etc. This will be used as the default for the
* transformation.
*
* @return
*/
public abstract URIResolver getURIResolver();
}
1.1 xml-xalan/java/src/javax/xml/trax/TransformerFactoryException.java
Index: TransformerFactoryException.java
===================================================================
package javax.xml.trax;
/**
* The TransformerFactoryException is a type of ProcessorException that
* is thrown when a configurable factory object can not
* be created.
*
* <h3>Open issues:</h3>
* <dl> * <dt><h4>No open issues are known for this class</h4></dt>
* <dd></dd>
* </dl>
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class TransformerFactoryException extends Exception
{
SourceLocator locator;
Exception containedException;
/**
* Create a new TransformerFactoryException.
*
* @param message The error or warning message.
*/
public TransformerFactoryException(String message)
{
super(message);
this.containedException = null;
this.locator = null;
}
/**
* Create a new TransformerFactoryException wrapping an existing exception.
*
* @param e The exception to be wrapped.
*/
public TransformerFactoryException(Exception e)
{
super("TRaX Transform Exception");
this.containedException = e;
this.locator = null;
}
/**
* Wrap an existing exception in a TransformerFactoryException.
*
* <p>This is used for throwing processor exceptions before
* the processing has started.</p>
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param e Any exception
*/
public TransformerFactoryException(String message, Exception e)
{
super("TRaX Transform Exception");
this.containedException = e;
this.locator = null;
}
/**
* Create a new TransformerFactoryException from a message and a Locator.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a DocumentHandler
* callback.</p>
*
* @param message The error or warning message.
* @param locator The locator object for the error or warning.
*/
public TransformerFactoryException(String message, SourceLocator locator)
{
super(message);
this.containedException = null;
this.locator = locator;
}
/**
* Wrap an existing exception in a TransformerFactoryException.
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param locator The locator object for the error or warning.
* @param e Any exception
*/
public TransformerFactoryException(String message, SourceLocator locator,
Exception e)
{
super(message);
this.containedException = e;
this.locator = locator;
}
}
1.1 xml-xalan/java/src/javax/xml/trax/URIResolver.java
Index: URIResolver.java
===================================================================
package javax.xml.trax;
/**
* <p>An interface that can be called by the processor to for turning the
* URIs used in document() and xsl:import etc into an Source object.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface URIResolver
{
/**
* This will be called by the processor when it encounters
* an xsl:include, xsl:import, or document() function.
*
* @param href An href attribute, which may be relative or absolute.
* @param base The base URI in effect when the href attribute was encountered.
*
* @return A non-null Source object.
*
* @throws TransformerException
*/
public Source resolve(String href, String base) throws TransformerException;
}
1.1 xml-xalan/java/src/javax/xml/trax/package.html
Index: package.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>
</title>
</head>
<body>
<h2>Transformations API For XML (TrAX)</h2>
<p>October 30, 2000</p>
<p>©Copyright 2000 Java Community Process (Sun Microsystems,
Inc.)</p>
<h3>Introduction</h3>
<p>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, XSLT Stylesheets, other types of script, or by
proprietary formats. The inputs, one or multiple, to a transformation, may be
an 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.</p>
<p>The great challenge of a transformation API is how to deal with
combinations of inputs and outputs, without becoming specialized for any of the
given types.</p>
<p>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 will fill the requirements of
general application across a great variety of uses. </p>
<h3>General Terminology</h3>
<p>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.</p>
<dl>
<dt>Transformation</dt>
<dd>The processor of consuming a stream or tree to produce
another stream or tree.</dd>
<dt>Serialization</dt>
<dd>The process of taking a tree and turning it into a stream. In
some sense, serialization is a specialization of transformation.</dd>
<dt>Transformer</dt>
<dd>A transformer is the thing that executes the transformation.
</dd>
<dt>Transformation instructions</dt>
<dd>Describes the transformation. A form of code or
script.</dd>
<dt>Processor</dt>
<dd>A general term for the thing that may both process the
transformation instructions, and perform the transformation.</dd>
</dl>
<h3>Requirements</h3>
<p>The following requirements have been determined from broad experience
with XML projects from the various members participating on the JCP.</p>
<ol>
<li>TrAX must provide a clean, simple interface for simple
uses.</li>
<li>TrAX must be powerful enough to be applied to a wide range of
uses, such as, e-commerce, content management, server content delivery, and
client applications.</li>
<li>A processor that implements a TrAX interface must be
optimizeable. Performance is a critical issue for most transformation use
cases.</li>
<li>As a specialization of the above requirement, a TrAX processor
must be able to support a compiled model, so that a single set of
transformation instructions can be compiled, optimized, and applied to a large
set of input sources.</li>
<li>TrAX must not be dependent an any given type of transformation
instructions. For instance, it must remain independent of XSLT.</li>
<li>TrAX must be able to allow processors to transform DOM
trees.</li>
<li>TrAX must be able to allow processors to produce DOM
trees.</li>
<li>TrAX must be able to allow processors to transform SAX
events.</li>
<li>TrAX must be able to allow processors to produce DOM
trees.</li>
<li>TrAX must be able to allow processors to transform streams of
XML.</li>
<li>TrAX must be able to allow processors to produce XML, HTML, and
other types of streams.</li>
<li>TrAX must be able to allow processors to implement the various
combinations of inputs and outputs within a single processor.</li>
<li>TrAX must be able to allow processors to implement only a limited
set of inputs. For instance, it should be possible to write a processor that
implements the TrAX interfaces that only processor DOM trees, not streams or
SAX events.</li>
<li>TrAX should allow a processor to implement transformations of
proprietary data structures. For instance, it should be possible to implement a
processor that provides TrAX interfaces that performs transformation of JDOM
trees.</li>
<li>TrAX must be able to allow the setting of serialization
properties, without constraint as to what the details of those properties
are.</li>
<li>TrAX must allow the setting of parameters to the transformation
instructions.</li>
<li>TrAX must be able to support the setting of parameters and
properties as XML Namespaced items (i.e. qualified names).</li>
<li>TrAX must be able to support URL resolution from within the
transformation, and have it return the needed data structure.</li>
</ol>
<h3>Model</h3>
<p>The section defines the abstract model for TrAX, apart from the details
of the interfaces.</p>
<p>A TRaX TransformerFactory is an object that
processes transformation instructions, and produces
Templates (in the technical termonology). The
Templates provide Transformers, which
transform one or more Sources into one or more
Results.</p>
<p>To use the TRaX interface, you create a
TransformerFactory, which may directly provide Transformers,
or which can provide Templates from a variety of
Sources. The Templates object is normally a compiled
representation of the transformation instructions, and provides a
Transformer. The Transformer processes an
InputSource according to the instructions found in the
Templates, and produces a Result.</p>
<p>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
Serialization. This term, although it overlaps with Java
object serialization, is the best description of this process.</p>
ProcessorGeneric concept for the
set of objects that implement the TrAX
interfaces.Create compiled transformation
instructions, transform resources, and manager parameters and properties of
those transformations.Only the Templates
object can be used concurrently in multiple threads. The rest of the processor
does not do synchronized blocking, and so can not be used
concurrently.
TransformerFactory Serve as a vendor
neutral Processor interface for XSLT processors and similar
processors. 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.
TransformerFactorys can not run concurrently.
Templates The run
time representation of the transformation instructions.
Acts as a data bag for transformation instructions, act as a
factory for Transformers. Threadsafe
concurrently over multiple threads once construction is
complete.
Transformer Act as a per-thread execution
context for transformations, act as an interface for performing the
transformation.Perfom the
transformation. Only safe one instance per
thread. The Transformer is bound to the Templates object
that created it.
Source Serve as a single vendor-neutral
object for multiple types of input. Act as simple
data holder for System IDs, DOM nodes, streams, etc.
Threadsafe concurrently over multiple threads for read-only,
must be synchronized for edit.
Result
ResultTarget Serve
as a single object for multiple types of output, so there can be simple process
method signatures. Act as simple data holder for
output stream, DOM node, ContentHandler, etc.
Threadsafe concurrently over multiple threads for read-only,
must be synchronized for edit.
<h3>Interfaces and Usage</h3>
<p>The detailed documentation of the APIs is left to JavaDoc for the
moment, until the interfaces are stable enough to document here.</p>
<p> TrAX defines a top-level series of interfaces in org.javax.xml.trax.
These interfaces have no dependencies on SAX or the DOM standard, and try to
make as few assumptions as possible about the details of the source and result
of a transform. It acheaves this by defining org.javax.xml.trax.Source and
org.javax.xml.trax.Result interfaces, which, at the current time, hold no
methods, though this may change over time.</p>
<p>In order to define concrete, useable classes for the user, TrAX
defines specialization of the interfaces found at the TrAX root level. These
interfaces are found in javax.xml.trax.sax, javax.xml.trax.dom,
javax.xml.trax.uri, and javax.xml.trax.stream.</p>
<h3>Creating Objects</h3>
<p>TrAX allows a concrete TransformerFactory object to be created from
static functions implemented by the TransformerFactory abstract class. A
particular TransformerFactory is "plugged" into the platform via the
ProcessorFactory in one of two ways: 1) as a platform default classname that
can be set via the TransformerFactory#setPlatformDefault method, and 2) through
external specification by a system property named "org.xml.trax.Processor.xslt"
obtained using java.lang.System.getProperty().</p>
<h3>Specification of Inputs and Outputs</h3>
<p>TrAX defines two interface objects called Source and Result. In
order to pass Source and Result objects to the TrAX interfaces, concrete
classes need to be used. TrAX defines four concrete representations of Source
and Result pairs: URISource and URIResult, StreamSource and StreamResult,
SAXSource and SAXResult, and DOMSource and DOMResult.</p>
<h3>Qualified Name representation</h3>
<p>One of the facts of dealing with XML objects is having to deal
withNamespaces.
Qualified Names appear in XML markup as prefixed names. But the prefixes
themselves do not hold identity, rather, it is the URIs that they contextually
map to that hold the identity. Therefore, when passing Qualified Names in among
Java programs, it is impossible to pass "xyz:foo" without have some sort of
object that maps "xyz" to a namespace. </p>
<p>One solution to this as been to create a QName object that holds
the namespace URI, as well as the prefix and local name. But this is not a
great solution when you want to use unique strings as keys in a dictionary
object, for instance. Not having a string representation also makes it very
hard to specify namespaced identity outside the context of a XML
document.</p>
<p>In order to pass namespaced values to transformations, for instance
as a set of properties to the Serializer, this specification defines that
parameter String object specified as "qname" be passed as two-part string, with
the first part being the URL, the delimiter being the '{' for the start of the
URI and '}' signifies the end, with the local name following. If the qname has
a null URL, then the String object will only contain the local name. An
application can safely check for a non-null URI by testing to see if the first
character of the name is a '{' character.</p>
<p>For example, if a URI and local name were obtained from an element
defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>,
then the TrAX QName would be "{http://xyz.foo.com/yada/baz.html}foo". Note that
the prefix is lost.</p>
<h3>Serialization</h3>
<p>
</p>
<p>If all that is desired is the simple identity transformation of a
source to a result, then the TransformerFactory provides a newTransformer
method that does not have any arguments. The method will create a Transformer
that will simply perform a copy of the source to the result. The most common
uses of this will be to create a DOM from SAX events, or creates an XML or HTML
stream from DOM or SAX events. The following example illustrates the
serialization of a DOM node to an XML stream.</p>
<code>
<pre> TransformerFactory tfactory = TransformerFactory.newInstance();
Transformer serializer = tfactory.newTransformer();
Properties oprops = new Properties();
oprops.put("method", "html");
oprops.put("indent-amount", "2");
serializer.setOutputProperties(oprops);
serializer.transform(new DOMSource(doc),
new StreamResult(System.out));</pre>
</code>
<h3>Resolution of URIs within a transformation</h3>
<p>TBD</p>
</body>
</html>
1.1 xml-xalan/java/src/javax/xml/trax/trax.properties
Index: trax.properties
===================================================================
#
# $Revision: 1.1 $ $Date: 2000/11/01 16:37:37 $
#
# Note: This properties file is provided for illustrative purposes
# only and is not part of the interface definition.
# This properties file is located in the implementation JAR
# and different implementations will specify different
# implementation classes and output methods.
#
#
# Lis the methods supported by this implementation
#
serialize.methods=xml,html,xhtml,text,wml:wml
#
# Use the Xalan serializer implementation for the default XSLT processor
#
javax.xml.trax.processor.xslt=org.apache.xalan.processor.StylesheetProcessor
1.1 xml-xalan/java/src/javax/xml/trax/dom/DOMLocator.java
Index: DOMLocator.java
===================================================================
package javax.xml.trax.dom;
import javax.xml.trax.SourceLocator;
import org.w3c.dom.Node;
/**
* Interface DOMLocator
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface DOMLocator extends SourceLocator
{
/**
* Method getOriginatingNode
*
* @return
*/
public Node getOriginatingNode();
}
1.1 xml-xalan/java/src/javax/xml/trax/dom/DOMResult.java
Index: DOMResult.java
===================================================================
package javax.xml.trax.dom;
import javax.xml.trax.*;
import java.lang.String;
import java.io.OutputStream;
import java.io.Writer;
import org.w3c.dom.Node;
/**
* Acts as an holder for a transformation result tree.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class DOMResult implements Result
{
/**
* Zero-argument default constructor.
*/
public DOMResult() {}
/**
* Create a new output target with a DOM node.
*
* @param n The DOM node that will contain the result tree.
*/
public DOMResult(Node n)
{
setNode(n);
}
/**
* Set the node that will contain the result DOM tree.
*
* @param node
*/
public void setNode(Node node)
{
this.node = node;
}
/**
* Get the node that will contain the result tree.
*
* @return
*/
public Node getNode()
{
return node;
}
/**
* Field node
*/
private Node node;
}
1.1 xml-xalan/java/src/javax/xml/trax/dom/DOMSource.java
Index: DOMSource.java
===================================================================
package javax.xml.trax.dom;
import javax.xml.trax.*;
import java.lang.String;
import java.io.OutputStream;
import java.io.Writer;
import org.w3c.dom.Node;
/**
* Acts as an holder for a transformation Source tree.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class DOMSource implements Source
{
/**
* Zero-argument default constructor.
*/
public DOMSource() {}
/**
* Create a new output target with a DOM node.
*
* @param n The DOM node that will contain the Source tree.
*/
public DOMSource(Node n)
{
setNode(n);
}
/**
* Set the node that will contain the Source DOM tree.
*
* @param node
*/
public void setNode(Node node)
{
this.node = node;
}
/**
* Get the node that will contain the Source tree.
*
* @return
*/
public Node getNode()
{
return node;
}
/**
* Field node
*/
private Node node;
}
1.1 xml-xalan/java/src/javax/xml/trax/sax/SAXResult.java
Index: SAXResult.java
===================================================================
package javax.xml.trax.sax;
import javax.xml.trax.*;
import java.lang.String;
import java.io.OutputStream;
import java.io.Writer;
import org.xml.sax.ContentHandler;
import org.xml.sax.ext.DeclHandler;
import org.xml.sax.ext.LexicalHandler;
/**
* Acts as an holder for a transformation result tree.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class SAXResult implements Result
{
/**
* Zero-argument default constructor.
*/
public SAXResult() {}
/**
* Create a new output target with a DOM node.
*
*
* @param handler
*/
public SAXResult(ContentHandler handler)
{
setHandler(handler);
}
/**
* Set the node that will contain the result DOM tree.
*
* @param handler
*/
public void setHandler(ContentHandler handler)
{
this.handler = handler;
}
/**
* Get the node that will contain the result tree.
*
* @return
*/
public ContentHandler getHandler()
{
return handler;
}
/**
* Set the SAX2 DeclHandler for the output.
*
* @param handler
*/
void setDeclHandler(DeclHandler handler)
{
this.declhandler = declhandler;
}
/**
* Get the SAX2 DeclHandler for the output.
* @return A DeclHandler, or null.
*/
DeclHandler getDeclHandler()
{
return declhandler;
}
/**
* Set the SAX2 LexicalHandler for the output.
*
* @param handler
*/
void setLexicalHandler(LexicalHandler handler)
{
this.lexhandler = lexhandler;
}
/**
* Get a SAX2 LexicalHandler for the output.
* @return A LexicalHandler, or null.
*/
LexicalHandler getLexicalHandler()
{
return lexhandler;
}
//////////////////////////////////////////////////////////////////////
// Internal state.
//////////////////////////////////////////////////////////////////////
/**
* Field handler
*/
private ContentHandler handler;
/**
* Field declhandler
*/
private DeclHandler declhandler;
/**
* Field lexhandler
*/
private LexicalHandler lexhandler;
}
1.1 xml-xalan/java/src/javax/xml/trax/sax/SAXSource.java
Index: SAXSource.java
===================================================================
package javax.xml.trax.sax;
import javax.xml.trax.*;
import java.lang.String;
import java.io.OutputStream;
import java.io.Writer;
import org.xml.sax.XMLReader;
import org.xml.sax.ext.DeclHandler;
import org.xml.sax.ext.LexicalHandler;
import org.xml.sax.InputSource;
/**
* Acts as an holder for SAX-style Source tree input.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class SAXSource implements Source
{
/**
* Zero-argument default constructor.
*/
public SAXSource()
{
}
/**
* Create a SAXSource, using an XMLReader and an InputSource.
* The Transformer or SAXTransformerFactory will set itself
* to be the reader's content handler, and then will call
* reader.parse(inputSource).
*/
public SAXSource(XMLReader reader, InputSource inputSource)
{
this.reader = reader;
this.inputSource = inputSource;
}
/**
* Create a SAXSource, using an InputSource.
* The Transformer or SAXTransformerFactory will create a
* reader via org.xml.sax.helpers.ParserFactory
* (if setXMLReader is not used), and will set itself
* to be the content handler of that reader, and then will call
* reader.parse(inputSource).
*/
public SAXSource(InputSource inputSource)
{
this.inputSource = inputSource;
}
/**
* Set the InputSource to be used for the source tree input.
*
* @param reader A valid XMLReader or XMLFilter reference.
*/
public void setXMLReader(XMLReader reader)
{
this.reader = reader;
}
/**
* Set the XMLReader to be used for the source tree input.
*
* @param inputSource A valid InputSource reference.
*/
public void setInputSource(InputSource inputSource)
{
this.inputSource = inputSource;
}
private XMLReader reader;
private InputSource inputSource;
}
1.1 xml-xalan/java/src/javax/xml/trax/sax/SAXTransformerFactory.java
Index: SAXTransformerFactory.java
===================================================================
package javax.xml.trax.sax;
import javax.xml.trax.*;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.XMLReader;
import org.xml.sax.ErrorHandler;
import org.xml.sax.EntityResolver;
import org.xml.sax.XMLFilter;
/**
* Interface SAXTransformerFactory
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public abstract class SAXTransformerFactory extends TransformerFactory
{
/**
* Get a TransformerHandler object that can process SAX
* ContentHandler events into a Result.
*
* @param src The source of the transformation instructions.
*
* @throws TransformerFactoryException
*/
public abstract TransformerHandler newTransformerHandler(Source src) throws TransformerFactoryException;
/**
* Create an XMLFilter that uses the given source as the
* transformation instructions.
*
* @param src The source of the transformation instructions.
*
* @return An XMLFilter object, or null if this feature is not supported.
*/
public abstract XMLFilter newXMLFilter(Source src);
/**
* Get InputSource specification(s) that are associated with the
* given document specified in the source param,
* via the xml-stylesheet processing instruction
* (see http://www.w3.org/TR/xml-stylesheet/), and that matches
* the given criteria. Note that it is possible to return several stylesheets
* that match the criteria, in which case they are applied as if they were
* a list of imports or cascades.
*
* @param source
* @param media The media attribute to be matched. May be null, in which
* case the prefered templates will be used (i.e. alternate = no).
* @param title The value of the title attribute to match. May be null.
* @param charset The value of the charset attribute to match. May be null.
* @returns An array of InputSources that can be passed to processMultiple method.
*
* @return A Source object suitable for passing to the TransformerFactory.
*
* @throws TransformerFactoryException
*/
public abstract Source getAssociatedStylesheet(
Source source, String media, String title, String charset)
throws TransformerFactoryException;
}
1.1 xml-xalan/java/src/javax/xml/trax/sax/SerializerHandler.java
Index: SerializerHandler.java
===================================================================
package javax.xml.trax.sax;
/**
* Interface that supplements {@link org.xml.sax.DocumentHandler} and
* {@link org.xml.sax.ContentHandler} with additional methods suitable
* for serialization.
*
* @version Alpha
* @author <a href="mailto:arkin@exoffice.com">Assaf Arkin</a>
*/
public interface SerializerHandler
{
/**
* Starts an un-escaping section. All characters printed within an
* un-escaping section are printed as is, without escaping special
* characters into entity references. Only XML and HTML serializers
* need to support this method.
* <p>
* The contents of the un-escaping section will be delivered through
* the regular <tt>characters</tt> event.
*/
public void startNonEscaping();
/**
* Ends an un-escaping section.
*
* @see #startNonEscaping
*/
public void endNonEscaping();
/**
* Starts a whitespace preserving section. All characters printed
* within a preserving section are printed without indentation and
* without consolidating multiple spaces. This is equivalent to
* the <tt>xml:space="preserve"</tt> attribute. Only XML
* and HTML serializers need to support this method.
* <p>
* The contents of the whitespace preserving section will be delivered
* through the regular <tt>characters</tt> event.
*/
public void startPreserving();
/**
* Ends a whitespace preserving section.
*
* @see #startPreserving
*/
public void endPreserving();
}
1.1 xml-xalan/java/src/javax/xml/trax/sax/TransformerHandler.java
Index: TransformerHandler.java
===================================================================
package javax.xml.trax.sax;
import javax.xml.trax.*;
import org.xml.sax.ContentHandler;
import org.xml.sax.ext.LexicalHandler;
/**
* This is a SAX ContentHandler that may be used to process SAX
* events into an Templates objects. This is an abstract class
* instead of an interface, so it can be a ContentHandler object,
* for passing into the JAXP SAXParser interface.
*/
public interface TransformerHandler
extends ContentHandler, LexicalHandler
{
/**
* When this object is used as a ContentHandler or DocumentHandler, it
* creates a Templates object, which the caller can get once
* the SAX events have been completed.
* @return The stylesheet object that was created during
* the SAX event process, or null if no stylesheet has
* been created.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*
* @throws TransformerException
*/
public Templates getTemplates() throws TransformerException;
public void setResult(Result result);
}
1.1 xml-xalan/java/src/javax/xml/trax/stream/StreamResult.java
Index: StreamResult.java
===================================================================
package javax.xml.trax.stream;
import javax.xml.trax.*;
import java.lang.String;
import java.io.OutputStream;
import java.io.Writer;
import org.xml.sax.ContentHandler;
import org.xml.sax.ext.DeclHandler;
import org.xml.sax.ext.LexicalHandler;
/**
* Acts as an holder for a transformation result tree.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class StreamResult implements Result
{
/**
* Zero-argument default constructor.
*/
public StreamResult() {}
/**
* Constructor StreamResult
*
* @param byteStream
*/
public StreamResult(OutputStream byteStream)
{
setByteStream(byteStream);
}
/**
* Constructor StreamResult
*
* @param characterStream
*/
public StreamResult(Writer characterStream)
{
setCharacterStream(characterStream);
}
/**
* Method setByteStream
*
* @param byteStream
*/
public void setByteStream(OutputStream byteStream)
{
this.byteStream = byteStream;
}
/**
* Method getByteStream
*
* @return
*/
public OutputStream getByteStream()
{
return byteStream;
}
/**
* Method setCharacterStream
*
* @param characterStream
*/
public void setCharacterStream(Writer characterStream)
{
this.characterStream = characterStream;
}
/**
* Method getCharacterStream
*
* @return
*/
public Writer getCharacterStream()
{
return characterStream;
}
/**
* Method setSystemId
*
* @param systemId
*/
public void setSystemId(String systemId)
{
this.systemId = systemId;
}
/**
* Method getSystemId
*
* @return
*/
public String getSystemId()
{
return systemId;
}
/**
* Field systemId
*/
private String systemId;
//////////////////////////////////////////////////////////////////////
// Internal state.
//////////////////////////////////////////////////////////////////////
/**
* Field byteStream
*/
private OutputStream byteStream;
/**
* Field characterStream
*/
private Writer characterStream;
}
1.1 xml-xalan/java/src/javax/xml/trax/stream/StreamSource.java
Index: StreamSource.java
===================================================================
package javax.xml.trax.stream;
import javax.xml.trax.Source;
import java.io.InputStream;
import java.io.Reader;
/**
* Acts as an holder for a transformation Source tree.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class StreamSource implements Source
{
/**
* Zero-argument default constructor.
*/
public StreamSource() {}
/**
* Constructor StreamSource
*
* @param byteStream
*/
public StreamSource(InputStream byteStream)
{
setByteStream(byteStream);
}
/**
* Constructor StreamSource
*
* @param characterStream
*/
public StreamSource(Reader characterStream)
{
setCharacterStream(characterStream);
}
/**
* Method setCharacterStream
*
* @param characterStream
*/
public StreamSource(String systemId)
{
this.systemId = systemId;
}
/**
* Method setByteStream
*
* @param byteStream
*/
public void setByteStream(InputStream byteStream)
{
this.byteStream = byteStream;
}
/**
* Method getByteStream
*
* @return
*/
public InputStream getByteStream()
{
return byteStream;
}
/**
* Method setCharacterStream
*
* @param characterStream
*/
public void setCharacterStream(Reader characterStream)
{
this.characterStream = characterStream;
}
/**
* Method getCharacterStream
*
* @return
*/
public Reader getCharacterStream()
{
return characterStream;
}
/**
* Method setPublicId
*
* @param publicId
*/
public void setPublicId(String publicId)
{
this.publicId = publicId;
}
/**
* Method getPublicId
*
* @return
*/
public String getPublicId()
{
return publicId;
}
/**
* Method setSystemId
*
* @param systemId
*/
public void setSystemId(String systemId)
{
this.systemId = systemId;
}
/**
* Method getSystemId
*
* @return
*/
public String getSystemId()
{
return systemId;
}
/**
* Field publicId
*/
private String publicId;
/**
* Field systemId
*/
private String systemId;
//////////////////////////////////////////////////////////////////////
// Internal state.
//////////////////////////////////////////////////////////////////////
/**
* Field byteStream
*/
private InputStream byteStream;
/**
* Field characterStream
*/
private Reader characterStream;
}