[prev in list] [next in list] [prev in thread] [next in thread]
List: xalan-cvs
Subject: cvs commit: xml-xalan/java/xdocs/sources/xalan overview.xml samples.xml usagepatterns.xml whatsnew.x
From: dleslie () locus ! apache ! org
Date: 2000-09-29 15:46:33
[Download RAW message or body]
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> \
---------------------------------------------------------------------
To unsubscribe, e-mail: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic