dleslie 00/09/07 12:38:02
Modified: java/src/trax Processor.java Result.java Templates.java
TemplatesBuilder.java package.html
Log:
Editorial updates for javadoc
Revision Changes Path
1.4 +1 -1 xml-xalan/java/src/trax/Processor.java
Index: Processor.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/trax/Processor.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Processor.java 2000/08/07 21:36:09 1.3
+++ Processor.java 2000/09/07 19:37:57 1.4
@@ -24,7 +24,7 @@
* and 2) through external specification by a system property named
* "org.xml.trax.Processor.[type]" obtained using
* java.lang.System.getProperty(). The [type] part of the property
specifies
- * the language to be used, for instance, "trax.processor.xslt" would
+ * the processing language to be used, for instance, "trax.processor.xslt"
would
* specify an XSLT processor. This property (or platform default)
* names a class that is a concrete subclass of org.xml.trax.Processor.
* The subclass shall implement a public no-args constructor used by
1.3 +6 -6 xml-xalan/java/src/trax/Result.java
Index: Result.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/trax/Result.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- Result.java 2000/06/24 18:31:03 1.2
+++ Result.java 2000/09/07 19:37:57 1.3
@@ -10,7 +10,7 @@
import org.w3c.dom.Node;
/**
- * Acts as an holder for result tree specifications.
+ * Acts as an holder for a transformation result tree.
* <p>This class is modeled after the SAX InputSource class, except that it
* is for the Result target, and in addition to streams, and writers,
* it also can specify a DOM node to which nodes will be appended.</p>
@@ -47,7 +47,7 @@
/**
* Create a new output target with a character stream.
*
- * @param characterStream The character stream where the results will be
written.
+ * @param characterStream The character stream where the result will be
written.
*/
public Result (Writer characterStream)
{
@@ -55,9 +55,9 @@
}
/**
- * Create a new output target with a character stream.
+ * Create a new output target with a DOM node.
*
- * @param characterStream The character stream where the results will be
written.
+ * @param n The DOM node that will contain the result tree.
*/
public Result (Node n)
{
@@ -106,7 +106,7 @@
}
/**
- * Set the node that will contain the result nodes.
+ * Set the node that will contain the result DOM tree.
*/
public void setNode (Node node)
{
@@ -114,7 +114,7 @@
}
/**
- * Get the node that will contain the result nodes.
+ * Get the node that will contain the result tree.
*/
public Node getNode ()
{
1.2 +1 -1 xml-xalan/java/src/trax/Templates.java
Index: Templates.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/trax/Templates.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Templates.java 2000/06/20 16:30:17 1.1
+++ Templates.java 2000/09/07 19:37:58 1.2
@@ -10,7 +10,7 @@
* The Templates object is the runtime representation of compiled
* transformation instructions. Templatess must be threadsafe for a given
instance
* over multiple threads concurrently, and are generally meant to
- * be used many multiple times for a given session.
+ * be used multiple times in a given session.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>newTransformer</h4></dt>
1.2 +2 -2 xml-xalan/java/src/trax/TemplatesBuilder.java
Index: TemplatesBuilder.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/trax/TemplatesBuilder.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- TemplatesBuilder.java 2000/06/20 16:30:17 1.1
+++ TemplatesBuilder.java 2000/09/07 19:37:58 1.2
@@ -21,8 +21,8 @@
public interface TemplatesBuilder extends org.xml.sax.ContentHandler
{
/**
- * When this object is used as a ContentHandler or DocumentHandler, it
will
- * create a Templates object, which the caller can get once
+ * 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
1.3 +56 -62 xml-xalan/java/src/trax/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/trax/package.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- package.html 2000/07/06 02:26:34 1.2
+++ package.html 2000/09/07 19:37:58 1.3
@@ -1,81 +1,75 @@
-<!-- CVS $Revision: 1.2 $ $Date: 2000/07/06 02:26:34 $ -->
+<!-- CVS $Revision: 1.3 $ $Date: 2000/09/07 19:37:58 $ -->
<html>
<title>Transformations for XML (TRaX).</title>
<body>
- <p>Defines an interface for processing transformation instructions,
performing tree transformations via a transformer, and sending the
result to SAX handlers, and interfacing to a [EMAIL PROTECTED]
org.xml.serialize.Serializer} if needed.<p>
+ <p>Defines a global interface for generating Templates and performing
XML transformations.</p>
+
+ <p>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.<p>
<dl>
<dt><b>Version: </b></dt><dd>Alpha, 0.5, March 20, 2000</dd>
- <dt><b>Author: </b></dt><dd><a href="mailto:[EMAIL PROTECTED]">Scott
Boag</a>
<dd>(with help from Keith Visco, Mike Kay,
Oracle, Assaf Arkin, and many others).</dd>
+ <dt><b>Author: </b></dt><dd><a href="mailto:[EMAIL PROTECTED]">Scott
Boag</a>
+ <dd>(with help from Keith Visco, Mike Kay,
Oracle, Assaf Arkin, and many others)</dd>
<dt><b>Goals: </b></dt><dd>
<ul>
- <li>Define a vendor-neutral and language-neutral interface for
tree
transformations that will allow an application to use any
implementation.</li>
+ <li>Define a vendor-neutral and language-neutral interface for
tree
+ transformations that will allow an application to use any
implementation.</li>
<li>Support SAX 1, SAX 2, DOM Level 1, and the [EMAIL PROTECTED]
org.xml.serialize.Serializer} interfaces.</li>
<li>Provide a good model for concurent and optimized
transformations.</li>
<li>Provide a reasonable model for incremental processing.</li>
- <li>Provide a reasonable model for passing data from the calling
application
to the transformation.</li>
+ <li>Provide a reasonable model for passing data from the calling
application
+ to the transformation.</li>
</ul>
</dd>
- </dl><A
HREF="file://C:\x\xml-xalan\java\src\org\apache\xalan\client\package.html">file://C:\x\xml-xalan\java\src\org\apache\xalan\client\package.html</A>
+ </dl>
+
<h3>Usage Examples</h3>
- <p>See <a href="org/xml/trax/Examples.html#method_detail">Examples
Page</a></p>
+ <p>See <a href="Examples.html#method_detail">Examples Page</a></p>
- <h3>The TRaX Interfaces</h3>
- <p>A TRaX [EMAIL PROTECTED] org.xml.trax.Processor} is an object that
processes transformation
- instructions, or [EMAIL PROTECTED] org.xml.trax.Templates}. The
[EMAIL PROTECTED] org.xml.trax.Templates} provide
- [EMAIL PROTECTED] org.xml.trax.Transformer}s, which transforms a
source tree into a result tree.</p>
<p>To use the TRaX interface, you create an [EMAIL PROTECTED]
org.xml.trax.Processor}, which can
- provide [EMAIL PROTECTED] org.xml.trax.Templates}
from a variety of sources. The [EMAIL PROTECTED] org.xml.trax.Templates}
object
- provides a [EMAIL PROTECTED] org.xml.trax.Transformer}. The [EMAIL
PROTECTED] org.xml.trax.Transformer} processes the
- [EMAIL PROTECTED] org.xml.sax.InputSource} according to the
- [EMAIL PROTECTED] org.xml.trax.Templates}, parameters, and
- [EMAIL PROTECTED] org.xml.serialize.OutputFormat} properties.</p>
<p>To create a [EMAIL PROTECTED] org.xml.trax.Processor}, you call the
factory interface on
the [EMAIL PROTECTED] org.xml.trax.Processor} class. The [EMAIL
PROTECTED] org.xml.trax.Processor} is
- "plugged" into the platform in one of two
- ways: 1) as a platform default, and 2) through external specification
by a
- system property named "org.xml.trax.Processor.[type]"
obtained using java.lang.System.getProperty(). The [type] part of the
property specifies
- the language to be used, for instance, "org.xml.trax.Processor.xslt"
would
specify an XSLT processor.</p>
<p>Both the [EMAIL PROTECTED] org.xml.trax.Processor} and the [EMAIL
PROTECTED] org.xml.trax.Transformer}
- objects let you ask about particular features
that the processor supports. You can do this using SAX style
getFeature/setFeature
methods. For instance, some processors may not support DOM trees as a
method of
input. In this case, it is wise to first ask the [EMAIL PROTECTED]
org.xml.trax.Transformer}
- if it supports the "http://xml.org/trax/features/dom/input"; feature.
- Those methods that may be optional are clearly documented in the
method headers.</p>
-
- <p>The [EMAIL PROTECTED] org.xml.trax.Processor}'s primary purpose is to
process transformation
instructions, such as
- an XSLT stylesheet, into a threadsafe [EMAIL PROTECTED]
org.xml.trax.Templates} object.
The [EMAIL PROTECTED] org.xml.trax.Processor} can get these
- instructions from either a SAX [EMAIL PROTECTED]
org.xml.sax.InputSource}, or from a DOM tree.
- The [EMAIL PROTECTED] org.xml.trax.Processor}
can also return a list of [EMAIL PROTECTED] org.xml.sax.InputSource}s
from a XML document
- that are specified via
the xml-stylesheet instruction. These [EMAIL PROTECTED]
org.xml.sax.InputSource}s can
- then be handed in to a
process instruction to create a [EMAIL PROTECTED]
org.xml.trax.Templates} object.</p>
-
<p>The [EMAIL PROTECTED] org.xml.trax.Templates} object is a bag of
instructions
that tells the [EMAIL PROTECTED] org.xml.trax.Transformer} how to
- transform a source tree. It is meant to be thread safe for use in
multiple threads
- at the same time. At this time there are only two methods on the
[EMAIL PROTECTED] org.xml.trax.Templates}
- object. newTransformer() creates a [EMAIL PROTECTED]
org.xml.trax.Transformer} object that is
- associated with the [EMAIL PROTECTED] org.xml.trax.Templates} object.
getOutputFormat() allows
- you to get a [EMAIL PROTECTED] org.xml.serialize.OutputFormat} object
which you may then modify
- and hand in to the [EMAIL PROTECTED] org.xml.trax.Transformer}
object.</p>
-
- <p>The [EMAIL PROTECTED] org.xml.trax.Transformer} object represents a
single transform. You can only
- use the Transformer object in a single thread at a time. You can
pass parameters to the
- [EMAIL PROTECTED] org.xml.trax.Transformer} object, which will then
be used from within the
- transform. You can also set the OutputFormat, which will override
the properties
- obtained from the owning [EMAIL PROTECTED] org.xml.trax.Templates}
object. The primary method on
- the [EMAIL PROTECTED] org.xml.trax.Templates} object is
transform(...), which takes as input a
- SAX [EMAIL PROTECTED] org.xml.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 [EMAIL PROTECTED] org.xml.sax.DocumentHandler},
- which can then be used as SAX event catchers. A [EMAIL PROTECTED]
org.xml.trax.Transformer} is
- also a SAX [EMAIL PROTECTED] org.xml.sax.XMLFilter}. An XML filter
is like an XML reader/parser,
except that it obtains its events from another XML reader rather than a
primary source like
an XML document or database. Useing the [EMAIL PROTECTED]
org.xml.trax.Transformer} as a
- [EMAIL PROTECTED] org.xml.sax.XMLFilter} is one method to use to
chain or pipe transformations.
- It also allows you to use a [EMAIL PROTECTED] org.xml.sax.XMLFilter}
polymorphicaly as a
- [EMAIL PROTECTED] org.xml.sax.XMLReader}.</p>
-
- <p>The output of a transformation is specified via a [EMAIL PROTECTED]
org.xml.trax.Result} object.
- This is very much like a [EMAIL PROTECTED] org.xml.sax.InputSource},
except that it allows you
- to specify OutputStreams, Writers, or DOM Nodes. To specify SAX
output, simply use
- the [EMAIL PROTECTED] org.xml.sax.XMLReader} methods (since the
[EMAIL PROTECTED] org.xml.trax.Transformer}
- is also a [EMAIL PROTECTED] org.xml.sax.XMLReader}), and call the
transform() method that takes
- only an input source. </p>
<h3>Design Patterns</h3>
-
<p><img src="org/xml/trax/trax.gif"></p>
+ <h3>The TRaX Interfaces</h3>
+
+ <p>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).</p>
+
+ <p>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.</p>
+
+ <p>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.</p>
+
+ <p>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:</p>
+ <ul>
+ <li>newTransformer() creates a Transformer object associated with the
Templates object</li>
+ <li>getOutputFormat() returns an org.xml.serialize.OutputFormat object
that you may modify and hand in to the
+ Transformer object</li>
+ </ul>
+
+ <p>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.</p>
+
+ <p>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).</p>
+
+ <h3>Design Patterns</h3>
- <p>For more detailed information on the patterns see the <a
href="org\xml\trax\patterns.html">Design Patterns Document</a></p>
-
<p>For open design issues, see the class and method headers.</p>
+ <p>For more detailed information on the patterns see the <a
href="patterns.html">Design Patterns Document</a></p>
+ <p>For open design issues, see the class and method headers.</p>
</body>
</html>
