dleslie 00/09/29 08:46:31
Modified: java/xdocs/sources/xalan overview.xml samples.xml
usagepatterns.xml whatsnew.xml
Log:
Work in progress for Xalan-J 2 alpha release.
Revision Changes Path
1.2 +3 -2 xml-xalan/java/xdocs/sources/xalan/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/overview.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- overview.xml 2000/09/15 19:03:20 1.1
+++ overview.xml 2000/09/29 15:46:21 1.2
@@ -72,14 +72,15 @@
Transformation vocabulary and XPath, a language for addressing parts of
XML documents. For links to background materials,
discussion groups, frequently asked questions, and tutorials on XSLT,
see <link anchor="uptospeed">Getting up
to speed with XSLT</link>.</p>
- <note>XSL also includes a vocabulary for formatting documents, which is
still under design and is not part of &xslt4j;.
+ <note>XSL also includes a vocabulary for formatting documents, which is
not part of &xslt4j;.
For more information, see <jump href="http://www.w3.org/TR/xsl/";>W3C XSL
Working Draft</jump> and the <jump
href="http://xml.apache.org/fop";>Apache XML FOP (Formatting Objects
Project)</jump>.</note>
<p>You use the XSLT language to compose XSL stylesheets. An XSL
stylesheet contains instructions for
transforming XML documents from one document type into another document
type (XML, HTML, or other). In structural
terms, an XSL stylesheet specifies the transformation of one tree of
nodes (the XML input) into another tree of nodes
(the output or transformation result).</p>
- <note>The XSL stylesheet may generate and refer to cascading style
sheets (CSS) as part of its output.</note>
+ <note>The XSL stylesheet may generate and refer to cascading style
sheets (<jump
+ href="http://www.w3.org/Style/CSS/";>CSS</jump>) as part of its
output.</note>
<p>In the following example, the foo.xsl stylesheet is used to transform
foo.xml into foo.out:</p>
<p>foo.xml:</p>
<source><?xml version="1.0"?>
1.7 +16 -3 xml-xalan/java/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/samples.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- samples.xml 2000/09/25 21:16:30 1.6
+++ samples.xml 2000/09/29 15:46:21 1.7
@@ -63,6 +63,7 @@
<li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
<li><link anchor="sax2sax">SAX2SAX</link></li>
<li><link anchor="pipe">Pipe</link></li>
+<li><link anchor="usexmlfilters">UseXMLFilters</link></li>
<li><link anchor="applyxpath">ApplyXPath</link></li>
<li><link anchor="appletxmltohtml">AppletXMLtoHTML</link></li>
<li><link anchor="servlet">Servlet</link></li>
@@ -114,14 +115,26 @@
</s2><anchor name="sax2sax"/>
<s2 title="SAX2SAX">
<p>What it does: Explicitly set the SAX XMLReader and SAX ContentHandler
for processing the stylesheet, processing the XML input, and producing the
output.</p>
- <p>Run this sample from the Sax2sax subdirectory with</p>
+ <p>Run this sample from the SAX2SAX subdirectory with</p>
<p><code>java SAX2SAX</code></p>
</s2><anchor name="pipe"/>
<s2 title="Pipe">
- <p>What it does: Chains together a series of 3 transformations by piping
SAX events from one Transformer to
- another. Each Transformer operates as a SAX2 XMLFilter/XMLReader.</p>
+ <p>What it does: Pipes the output from one transformation to a second
transformation, then from the second
+ transformation to the third transformation. Transformer1 is the
ContentHandler for the XMLReader (which parses the
+ input document). Transformer2 provides the ContentHandler for
Transformer1, and Transformer3 for Transformer2.</p>
+ <note>Pipe and UseXMLFilters illustrate two strategies for using the
output of one transformation as the input for
+ another transformation. The Pipe sample incorporates a "push" model --
Transformer1 "pushes" its output to
+ Transformer2, and so on -- whereas in the UseXMLFilters sample,
Transformer3 "pulls" its input from Transformer2,
+ and so on.</note>
<p>Run this sample from the Pipe subdirectory with</p>
<p><code>java Pipe</code></p>
+ </s2><anchor name="usexmlfilters"/>
+ <s2 title="UseXMLFilters"/>
+ <p>What it does: Chains together the same transformations as the
preceding Pipe sample. Using each Transformer
+ object as an extension of the SAX XMLFilter interface, sets the
XMLReader as the parent of Transformer1,
+ Transformer1 as the parent of Transformer2, and Transformer2 as the
parent of of Transformer3.</p>
+ <p>Run this sample from the UseXMLFilters subdirectory with</p>
+ <p><code>java UseXMLFilters</code></p>
</s2><anchor name="applyxpath"/>
<s2 title="ApplyXPath">
<p>What it does: ApplyXPath uses the <jump
href="apidocs/org/apache/xpath/XPathAPI.html">XPathAPI</jump> convenience
methods to
1.4 +17 -10 xml-xalan/java/xdocs/sources/xalan/usagepatterns.xml
Index: usagepatterns.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/usagepatterns.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- usagepatterns.xml 2000/09/20 14:01:21 1.3
+++ usagepatterns.xml 2000/09/29 15:46:21 1.4
@@ -61,6 +61,7 @@
<li><link anchor="basic">Basic steps</link></li>
<li><link anchor="params">Setting stylesheet parameters</link></li>
<li><link anchor="sax">Explicitly working with SAX</link></li>
+<li><link anchor="outasin">Using transformation output as input for another
transformation</link></li>
<li><link anchor="dom">Processing and producing DOM trees</link></li>
<li><link anchor="xpath">Working with XPath expressions</link></li>
<li><link anchor="applet">Using the &xslt4j; applet wrapper</link></li>
@@ -102,17 +103,16 @@
<s2 title="2. Process the stylesheet, producing a Templates object">
<p>The Templates object is an immutable runtime representation of the
structure and content of a stylesheet (which may include
and import multiple stylesheet sources).</p>
-<p>A given Templates object may be used repeatedly and by multiple
concurrent threads for the transformation of XML input. Each Templates object
also incorporates XSLTSchema, which encapsulates the underlying XSLT stylesheet
schema.</p>
+<p>A given Templates object may be used repeatedly and by multiple
concurrent threads for the transformation of XML input.</p>
<p>You may provide the stylesheet as a SAX input source (from a file or
stream) or as a DOM tree.</p>
<p>Use the Processor process() method with a SAX input source (as in the
example above), or the processFromNode() method with a DOM tree to generate a
Templates object.</p>
<p>To perform this operation with a SAX input source, the processor uses a
trax.TemplatesBuilder (extending the SAX ContentHandler interface) and a SAX
XMLReader.</p>
<p>The XMLReader parses the input, sending parse events to the
TemplatesBuilder, which responds by building the Templates object.</p>
-<note>Templates and TemplatesBuilder are TRaX interfaces, and XMLReader is a
SAX interface. &xslt4j; uses org.apache.xalan.templates.StylesheetRoot to
implement Templates, and org.apache.xalan.processor.StylesheetHandler to
implement TemplatesBuilder. XMLReader is a SAX interface. The &xslt4j;
StylesheetProcessor uses org.xml.sax.XMLReaderFactory to instantiate an
XMLReader as designated by the org.xml.sax.driver system property. If you are
using &xml4j;, this system property should be set to
org.apache.xerces.parsers.SAXParser</note>
-<p>If you use the processFromNode() method with a DOM representation of the
stylesheet, the processor uses org.apache.xalan.utils.TreeWalker to traverse
the DOM, sending SAX events to the TemplatesBuilder.</p>
+<p>If you use the processFromNode() method with a DOM representation of the
stylesheet, the processor traverses the DOM, sending SAX events to the
TemplatesBuilder.</p>
</s2><anchor name="transformer"/>
<s2 title="3. Instantiate a Transformer">
<p>To transform an XML document, you need an implementation of the
trax.Transformer interface.</p>
-<p>&xslt4j; implements the Transformer interface with
org.apache.xalan.transformer.TransformerImpl.</p>
+<note>&xslt4j; implements the Transformer interface with
org.apache.xalan.transformer.TransformerImpl.</note>
<p>You can use a Templates object for multiple transformations (even
performed concurrently), but you should use the Templates object to instantiate
a separate Transformer for each transformation you perform. The Templates
object contains the stylesheet structure and data and XSLT schema, which are
immutable, whereas the Transformer tracks state information as it performs the
transformation.</p>
</s2><anchor name="transformation"/>
<s2 title="4. Perform a transformation">
@@ -120,10 +120,11 @@
<p>Just as with the stylesheet, you can supply the XML input in the form of
a SAX input source (from a URL or stream) or a DOM tree.</p>
<p>Use the Transformer transform() method with a SAX input source (as in the
example above), or the transformNode() method with a DOM tree to perform the
transformation.</p>
<p>TRaX provides the holder for the output: trax.Result. You can set up a
Result object to send the transformation result to a file or stream or to build
a DOM tree.</p>
-<p>The Transformer uses the SAX XMLParser to parse the XML input and sends
parse events to an input SAX ContentHandler,
org.apache.xalan.stree.SourceTreeHandler, which in turn uses
org.apache.xalan.utils.DOMBuilder to assemble the input into a DOM tree. Of
course this operation is unnecessary if the XML input is submitted as a DOM.</p>
-<p>For each node in the XML source, the Transformer uses the Templates
object and underlying XSLT schema to determine which template to apply: one of
the templates in the Templates object, a default template rule as specified in
the XSLT spec, or none.</p>
-<p>The Transformer works with org.apache.xalan.transformer.ResultTreeHandler
to forward the SAX events produced by this process to the appropriate output
ContentHandler, a serializer if the Result object has been set up to write to a
stream or file, a DOMBuilder utility if the output is to be a DOM tree.</p>
-<p>To the degree possible, the parsing of the XML source and application of
the Templates object to that source are performed concurrently in separate
threads. When necessary, the Transformer waits for the parse events that must
be in place before a given template may be applied.</p>
+<p>The Transformer uses the XMLParser to parse the XML input and sends parse
events to a SAX ContentHandler, which assembles the input into a DOM tree. Of
course this operation is unnecessary if the XML input is submitted as a DOM.</p>
+<p>For each node in the XML source, the Transformer uses the Templates
object to determine which template to apply: one of the templates in the
Templates object, a default template rule as specified in the XSLT spec, or
none.</p>
+<p>The Transformer forwards the SAX events produced by this process to the
appropriate output ContentHandler, a serializer if the Result object has been
set up to write to a stream or file, a DOMBuilder utility if the output is to
be a DOM tree.</p>
+<note>A serializer is a utility that translates a series of SAX events or a
DOM tree into a stream, performing any character escaping required by the
output method (the XML ourput method, for example normally requires < and
& to be escaped).</note>
+<p>To the degree possible, the parsing of the XML source and application of
the Templates object to that source are performed concurrently in separate
threads. For more information, see xxxx.</p>
</s2><anchor name="params"/>
<s2 title="Setting stylesheet parameters">
<p>An XSLT stylesheet may include parameters that are set at run time each
time a transformation takes place. To set a stylesheet parameter, use the
trax.Transformer <jump
href="apidocs/trax/Transformer.html#setParameter(java.lang.String,java.lang.String,java.lang.Object)">setParameter(String
name, String namespace, Object value)</jump> method. If the parameter QName
only includes a local name (as is often the case), the namespace argument is
null. For a working example, see UseStylesheetParam.java in the
java/samples/UseStylesheetParam subdirectory.</p>
@@ -182,6 +183,13 @@
// Parse the XML input document. The input and output ContentHandlers work in
// separate threads to optimize performance.
reader.parse("foo.xml");</source>
+</s2><anchor name="outasin"/>
+<s2 title="Using transformation output as input for another transformation">
+<p>You can chain together a series of two or more transformations such that
the output of one transformation provides input for the another transformation.
&xslt4j; supports two basic strategies for chaining a series of
transformations:</p>
+<ul>
+ <li><br/>A Transformer uses a SAX ContentHandler to process input, and
another ContentHandler to process output. Along these lines, you can use the
Transformer getInputContentHandler() method to make one Transformer the
ContentHandler for the XMLParse that reads the input, then use the same method
make a second Transformer the ContentHandler for the output of the first
Transformer, and so on. For more detail and an example, see the <link
idref="samples" anchor="pipe">Pipe<link> sample.<br/><br/></li>
+ <li>A Transformer extends the SAX XMLFilter interface. Using the
setParent() method this interface supplies, you can set an XMLReader as the
parent of the Transformer for the first transformation, then set this
Transformer as the parent for the Transformer performing the second
transformation, and so on. You launch the series by instructing the last
Transformer to parse the input. For more detail and an example, see the <link
idref="samples" anchor="usexmlfilters">UseXMLFilters<link> sample.</li>
+</ul>
</s2><anchor name="dom"/>
<s2 title="Processing and producing DOM trees">
<p>In some cases, the input and/or desired output for a transformation may
be a DOM tree object, rather than a file or stream.</p>
@@ -199,11 +207,10 @@
org.w3c.dom.Document resultDoc = docBuilder.newDocument();
trax.Result result = new trax.Result(resultDoc);
</source>
-<note>If you are using the Xerces implementation of the <ref>Java API for
XML Parsing</ref> (in xerces.jar), the default value for the
javax.xml.parsers.DocumentBuilderFactory system property is
org.apache.xerces.jaxp.DocumentBuilderFactoryImpl. The Xerces implementations
of DocumentBuilder and DOM Document are
org.apache.xerces.jaxp.DocumentBuilderImpl and
org.apache.xerces.dom.DocumentImpl.</note>
</s2><anchor name="xpath"/>
<s2 title="Working with XPath expressions">
<p>XSLT stylesheets use XPath expressions to select nodes, specify
conditions, and generate text for the result tree. XPath provides an API that
you can call directly. For example, you may want to select nodes
programmatically and do your own processing without a stylesheet.</p>
-<p>XPath is an independent entity, with clients other than XSLT processors
(such as XPointer). Accordingly, &xslt4j2; has packaged XPath as a separate
module (org.apache.xpath and its subpackages), although this module does use
some utility classes packaged in org.apache.xalan.utils. The
org.apache.xpath.XPathAPI class contains convenience methods that you can use
to return single DOM Nodes, NodeIterators, and XObjects. Apart from their own
functionality, these methods also provide a path into the lower-level XPath API
that you may find useful.</p>
+<p>XPath is an independent entity, with clients other than XSLT processors
(such as XPointer). Accordingly, &xslt4j2; has packaged XPath as a separate
module (org.apache.xpath and its subpackages), although concurrently this
module does use some utility classes packaged in org.apache.xalan.utils. The
org.apache.xpath.XPathAPI class contains convenience methods that you can use
to return single DOM Nodes, NodeIterators, and XObjects. Apart from their own
functionality, these methods also provide a path into the lower-level XPath API
that you may find useful.</p>
<p>For an example that uses the XPathAPI convenience methods to execute
XPath expressions against XML source files, see <link idref="samples"
anchor="applyxpath">ApplyXPath</link>.</p>
</s2><anchor name="applet"/>
<s2 title="Using the &xslt4j; applet wrapper">
1.8 +16 -6 xml-xalan/java/xdocs/sources/xalan/whatsnew.xml
Index: whatsnew.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/whatsnew.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- whatsnew.xml 2000/09/19 12:52:37 1.7
+++ whatsnew.xml 2000/09/29 15:46:21 1.8
@@ -64,25 +64,35 @@
<s2 title="New Design">
<p>&xslt4j2; represents a fundamental redesign of Xalan. The goal of this
redesign is an easier-to-use, more understandable, and more modular API that
that lends itself to "streaming," the production of transformation output while
the input is still being parsed, and that encourages wider participation in its
ongoing development by the open-source XML developer community.</p>
<p>As a result of this redesign, the changes are global in nature. The API
and the basic usage patterns are different. For the details, see <link
idref="usagepatterns">Basic Usage Patterns</link>.</p>
-<p>To start with, &xslt4j2; implements the <resource-ref idref="trax"/>
interfaces. A number of open-source XML tool developers have collaborated on
TRaX, a conceptual framework and a standard API for performing an open-ended
range of XML transformations. We strongly encourage you to use the TRaX
framework and interfaces when you peform XML transformations.</p>
+<p>To start with, &xslt4j2; implements the <resource-ref idref="trax"/>
interfaces. A number of open-source XML tool developers have collaborated on
TRaX, a conceptual framework and a standard API for performing a variety of XML
transformations. We strongly encourage you to use the TRaX framework and
interfaces when you perform XML transformations.</p>
<p>The basic organization of TRaX is quite simple: use a Processor to
process transformation instructions (the stylesheet), producing a Templates
object. Use the Templates object to instantiate a Transformer, with which you
can apply the Templates object to XML input, producing a result tree. For more
detail, see <link idref="usagepatterns" anchor="basic">Basic steps</link>.</p>
<p>&xslt4j2; builds on <resource-ref idref="sax2"/>, <resource-ref
idref="dom2"/>, and the <resource-ref idref="jaxp"/>. For example, &xslt4j2;
incorporates the SAX parsing event model in its support for the incremental
production of transformation output.</p>
<p>In conjunction with TRaX, &xslt4j; gathers basic operational settings
from system properties. System properties, for example, identify the stylesheet
processor and SAX parser to use, and the serializers that are available for
various output methods. The default settings point to the Xalan
StylesheetProcessor, the Xerces SAXParser, and the serializers shipped with
Xerces.</p>
</s2><anchor name="packages"/>
<s2 title="Package layout">
- <p>As the new package structure highlights, the processing of stylesheets
and production of stylesheet templates, the application of stylesheet templates
to source trees and production of output trees, the evaluation of XPath
expressions and XSLT matching patterns, and subsidiary operations and utilities
are more clearly segmented than in &xslt4j; version 1.</p>
-<p>&xslt4j2; is made up of four major and several minor modules. The four
major modules are:</p>
+ <p>The class package structure maps closely to major conceptual modules.
For example, you use the processor
+ package to process stylesheets and produce stylesheet templates (the
templates package). Then you use the
+ transformer package to apply the templates to a source tree and produce an
output tree. Responsibility for
+ evaluating XPath expressions and XSLT matching patterns is centralized in
the XPath packages, and a variety of
+ utilities used by multiple packages are in the utils package.</p>
+ <p>&xslt4j2; is made up of four major and several minor modules. The four
major modules are:</p>
<gloss>
<label><jump
href="apidocs/org/apache/xalan/processor/package-summary.html">org.apache.xalan.processor</jump></label>
- <item>Processes the stylesheet and produces the Templates
object. This module provides the primary entry point into &xslt4j;.</item>
+ <item>Processes the stylesheet and produces the Templates
object. This module is responsible for
+ implementing the <jump
href="apidocs/trax/Processor.html">trax.Processor</jump> abstract class, which
+ provides the primary entry point into &xslt4j;.</item>
</gloss>
<gloss>
<label><jump
href="apidocs/org/apache/xalan/templates/package-summary.html">org.apache.xalan.templates</jump></label>
- <item>Defines the structure and content of a stylesheet tree
(which may include multiple imported and included stylesheets).</item>
+ <item>Defines the structure and content of a stylesheet tree
(which may include multiple imported and
+ included stylesheets). This module is responsible for implementing the
<jump
+ href="apidocs/trax/Templates.html">trax.Templates</jump>
interface.</item>
</gloss>
<gloss>
<label><jump
href="apidocs/org/apache/xalan/transformer/package-summary.html">org.apache.xalan.transformer</jump></label>
- <item>Applies the Templates object to the XML source and
produces the result tree.</item>
+ <item>Applies the Templates object to the XML source and
produces the result tree. This module is
+ responsible for implementing the <jump
href="apidocs/trax/Transformer.html">trax.Transformer</jump>
+ interface.</item>
</gloss>
<gloss>
<label><jump
href="apidocs/org/apache/xpath/package-summary.html">org.apache.xpath</jump></label>
