You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@locus.apache.org on 2000/09/29 17:46:33 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan overview.xml samples.xml usagepatterns.xml whatsnew.xml
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>