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/12/04 18:23:51 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan BUGS DONE commandline.xml index.xml overview.xml readme.xml resources.xml samples.xml usagepatterns.xml whatsnew.xml
dleslie 00/12/04 09:23:47
Modified: java/xdocs/sources entities.ent
java/xdocs/sources/trax trax.xml
java/xdocs/sources/xalan BUGS DONE commandline.xml index.xml
overview.xml readme.xml resources.xml samples.xml
usagepatterns.xml whatsnew.xml
Log:
Work in progresss for xalan-j 2.0.d02
Revision Changes Path
1.5 +1 -1 xml-xalan/java/xdocs/sources/entities.ent
Index: entities.ent
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/entities.ent,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- entities.ent 2000/10/20 12:54:08 1.4
+++ entities.ent 2000/12/04 17:23:36 1.5
@@ -5,7 +5,7 @@
<!ENTITY xslt4j-dist "xalan-j_2_0_D02">
<!ENTITY xslt4j-current "&xslt4j; version 2.0.D02">
<!ENTITY xml4j "Xerces-Java">
-<!ENTITY xml4j-used "&xml4j; version 1.2">
+<!ENTITY xml4j-used "&xml4j; version 1.2.2">
<!ENTITY xslt4c "Xalan-C++">
<!ENTITY xml4c "Xerces-C++">
<!ENTITY download "The &xslt4j-current; download from xml.apache.org includes xerces.jar from &xml4j-used;.">
1.2 +14 -9 xml-xalan/java/xdocs/sources/trax/trax.xml
Index: trax.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/trax/trax.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- trax.xml 2000/11/15 22:35:32 1.1
+++ trax.xml 2000/12/04 17:23:37 1.2
@@ -1,7 +1,8 @@
<?xml version="1.0"?>
<!DOCTYPE spec SYSTEM "../../style/dtd/spec.dtd">
<spec>
- <title>Transformation API For XML (TrAX)</title><frontmatter>
+ <title>Transformation API For XML (TrAX)</title>
+ <frontmatter>
<pubdate>November 12, 2000</pubdate>
<copyright>Copyright 2000 Java Community Process (Sun Microsystems,
Inc.)</copyright>
@@ -11,11 +12,12 @@
<address>
<email>sboag@lotus.com</email>
</address>
- </author></frontmatter> <introduction>
+ </author></frontmatter>
+ <introduction>
<title>Introduction</title>
<para>This overview describes the set of APIs contained in
- <ulink url="package-summary.html">javax.xml.transform</ulink>. For the sake of brevity, these interfaces are referred to
- as TrAX (Transformations for XML). </para>
+ <ulink url="package-summary.html">javax.xml.transform</ulink>, <ulink url="package-summary.html">javax.xml.transform.stream</ulink>, <ulink url="package-summary.html">javax.xml.transform.dom</ulink>, and <ulink url="package-summary.html">javax.xml.transform.sax</ulink>. For the sake of brevity, these interfaces are referred to
+ as TrAX (Transformation API for XML). </para>
<para>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,
@@ -124,7 +126,8 @@
release</termref>.</listitem>
</varlistentry>
</variablelist>
- </sect2></introduction><requirements>
+ </sect2></introduction>
+ <requirements>
<title>Requirements</title>
<para>The following requirements have been determined from broad experience
with XML projects from the various members participating on the JCP.</para>
@@ -180,7 +183,8 @@
structure.</listitem>
<listitem id="requirement-error-reporting">TrAX must have a mechanism for
reporting errors and warnings to the calling application.</listitem>
- </orderedlist> </requirements> <model>
+ </orderedlist> </requirements>
+ <model>
<title>Model</title>
<para>The section defines the abstract model for TrAX, apart from the details
of the interfaces.</para>
@@ -256,11 +260,12 @@
must be synchronized for edit.</thread-safety> </pattern> </patterns></model>
<sect1 id="package">
<title>javax.xml.transform</title>
- <para>This package defines the generic <ulink url="trax.html">TrAX</ulink> APIs for processing transformation
- instructions, and performing a transformation from source to result. These
+ <para>This package defines the generic APIs for processing transformation instructions,
+ and performing a transformation from source to result. For an overview, see
+ <ulink url="trax.html">Transformation API for XML (TrAX)</ulink>. The TrAX
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
- transformation. It achieves this by defining
+ transformation. TrAX achieves this by defining
<plink>javax.xml.transform.Source</plink> and
<plink>javax.xml.transform.Result</plink> interfaces.</para>
<para>To define concrete classes for the user, TrAX defines specializations
1.6 +1 -1 xml-xalan/java/xdocs/sources/xalan/BUGS
Index: BUGS
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/BUGS,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- BUGS 2000/10/17 18:00:48 1.5
+++ BUGS 2000/12/04 17:23:40 1.6
@@ -29,7 +29,7 @@
<li>The unparsed-entity-uri() function fails.<br/><br/></li>
<li>The @namespace:* pattern is not assigned the appropriate priority for conflict resolution.</li>
</ul>
-<p>The Apache XML Bug Tracking System is currently not working. If you find a bug, please report it (with "Xalan-J 2 bug" in the subject line) to the <human-resource-ref idref="xalandev"/>.</p>
+<p>The Apache XML Bug Tracking System is currently not working. If you find a bug, please report it (with "Xalan-J 2 bug" in the subject line) to the <human-resource-ref idref="xalandev"/>. We strongly encourage you write patches for problems you find and submit them to <human-resource-ref idref="xalandev"/>. We review the patches we receive to make sure they do not break something else, and (assuming they do not) include them in our next release. In the interest of fixing bugs, adding enhancements, and addressing outstanding design issues, we sincerely want (and need!) your active participation in the ongoing development of Xalan.</p>
</s3>
1.2 +2 -1 xml-xalan/java/xdocs/sources/xalan/DONE
Index: DONE
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/DONE,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DONE 2000/09/15 19:03:20 1.1
+++ DONE 2000/12/04 17:23:41 1.2
@@ -1,3 +1,4 @@
<s3 title="Changes since &xslt4j; version 2.0.D01">
-<p></p>
+<p>The Transformation API for XML (TrAX) that &xslt4j2; implements has undergone substantial revisions since the release of &xslt4j; 2.0.D01. TrAX has joined the Java API for XML Parsing (JAXP) as part of the Sun® <resource-ref idref="jsr063"/>. Accordingly, the TrAX package names have changed. The conceptual organization has also changed somewhat: The primary transformation interfaces are defined in javax.xml.transform, with concrete classes for managing stream input/output, SAX parsers and ContentHandler, and DOM parsers and DOM trees in javax.xml.transform.stream, javax.xml.transform.sax, and javax.xml.transform.dom. For more information, see <resource-ref idref="trax"/>, and review <link idref="usagepatterns">Usage Patterns</link>.</p>
+<p>Other changes:</p>
</s3>
1.7 +4 -4 xml-xalan/java/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/commandline.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- commandline.xml 2000/10/17 12:54:57 1.6
+++ commandline.xml 2000/12/04 17:23:41 1.7
@@ -99,11 +99,11 @@
-HTML (Use HTML formatter)
-PARAM name value (Set a stylesheet parameter)
-DIAG put out timing diagnostics</source>
- <p>Use -IN to specify the XML source document.</p>
- <p>Use -XSL to specify the XSL stylesheet file.</p>
- <p>Use -TEXT if you want the output to include only element values (not element tags with element names and
+ <p>Use <code>-IN</code> to specify the XML source document.</p>
+ <p>Use <code>-XSL</code> to specify the XSL stylesheet file.</p>
+ <p>Use <code>-TEXT</code> if you want the output to include only element values (not element tags with element names and
attributes).</p>
- <p>Use -HTML to write 4.0 transitional HTML (some elements, such as <br>, are
+ <p>Use <code>-HTML</code> to write 4.0 transitional HTML (some elements, such as <br>, are
not well formed XML).</p>
<p>To set stylesheet parameters from the command line, use <br/>
<code>java org.apache.xalan.xslt.Process -PARAM <ref>name value</ref></code></p>
1.5 +7 -11 xml-xalan/java/xdocs/sources/xalan/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/index.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- index.xml 2000/11/21 17:40:57 1.4
+++ index.xml 2000/12/04 17:23:42 1.5
@@ -63,18 +63,14 @@
in an applet or a servlet, or as a module in other program.</p>
</s2>
<s2 title="I've heard of &xslt4j;, but what is version 2?">
- <p>&xslt4j; version 2 recasts Xalan as an implementation of the <resource-ref idref="trax"/> interfaces. TRaX provides a
- modular framework and a standard API for performing an open-ended range of XML transformations.</p>
- <p>In conjunction with TRaX, &xslt4j2; relies on system properties to configure its operational settings, such as
- which stylesheet processor, which SAX parser, and which serializers to use. The default settings point to the Xalan
- StylesheetProcessor, the serializers shipped with Xalan, and the Xerces SAXParser.</p>
+ <p>&xslt4j; version 2 recasts Xalan as an implementation of the <resource-ref idref="trax"/> interfaces, part of the Java API for XML Processing. TRaX provides a
+ modular framework and a standard API for performing XML transformations, and it utilizies system properties to determine which Transformer and which XML parser to use.</p>
<p>&xslt4j; version 2 also builds on <resource-ref idref="sax2"/>, <resource-ref idref="dom2"/>, and the
<resource-ref idref="jaxp"/>.</p>
<p>For more information, see <link idref="whatsnew">What's new in &xslt4j2;</link>.</p>
</s2>
<s2 title="How about this release?">
- <p>&xslt4j-current; is a beta Developer's release of &xslt4j2;. For information about known
- limitations and problems, see the <link idref="readme">Release notes</link>. Please send your comments, bug reports, and feedback to the <human-resource-ref idref="xalandev"/></p>
+ <p>&xslt4j-current; is an alpha Developer's release of &xslt4j2;. The primary change between &xslt4j-current; and &xslt4j; 2.0.D01 is the integration of the TrAX interfaces into <resource-ref idref="jaxp"/>. For the details, and for information about known limitations and problems with this alpha release, see the <link idref="readme">Release notes</link>. Please send your comments, bug reports, and feedback to the <human-resource-ref idref="xalandev"/></p>
</s2>
<s2 title="How do I get it?">
<p>Download and unzip either of the following:</p>
@@ -87,11 +83,11 @@
<s2 title="Where do I get Xerces?">
<p>The Xalan download includes xerces.jar from &xml4j-used;. This is all you need to run Xalan with the Xerces XML parser.
You can, however, download the complete Xerces distribution from the <resource-ref idref="xml4j-distdir"/>.</p>
- <note>If you plan to use a different XML parser, see <link idref="usagepatterns" anchor="xmlreader">Setting the
- XMLReader</link>.</note>
+ <note>If you plan to use a different XML parser, see <link idref="usagepatterns" anchor="plug">Plugging in a Transformer and
+ XML parser</link>.</note>
</s2>
<s2 title="What else do I need?">
- <p>You need the Java Development Kit or Java Runtime 1.1.8 or 1.2.2, which you can obtain from <jump
+ <p>You need the Java Development Kit or Java Runtime 1.1.8, 1.2.2, or 1.3, which you can obtain from <jump
href="http://www.ibm.com/java/jdk">ibm.com/java/jdk/</jump> or <jump href="http://www.java.sun.com">java.sun.com</jump>.</p>
</s2>
<s2 title="For more information...">
@@ -99,4 +95,4 @@
Started</link>. All of the Xalan documentation on this website is included in the Xalan download, as are a number of samples
to help you start using &xslt4j2; to transform XML documents.</p>
</s2>
-</s1>
\ No newline at end of file
+</s1>
\ No newline at end of file
1.6 +10 -10 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.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- overview.xml 2000/11/01 20:12:31 1.5
+++ overview.xml 2000/12/04 17:23:42 1.6
@@ -94,19 +94,19 @@
</xsl:stylesheet></source>
<p>foo.out:</p>
<source><out>Hello</out></source>
-<p>By default, &xslt4j; uses the &xml4j; SAXParser, and it may be configured (<link idref="usagepatterns" anchor="xmlreader">with system properties</link>) to work with other parsers. The input may be submitted in the form of a SAX InputStream (from a URI, a character or byte stream, or another transformation) or a DOM Node.</p>
+<p>By default, &xslt4j; uses &xml4j;, and it may be configured with system properties to work with other XML parsers (see <link idref="usagepatterns" anchor="plug">Plugging in a Transformer and XML parser</link>). The input may be submitted in the form of a SAX InputStream (from a URI, a character or byte stream, or another transformation) or a DOM Node.</p>
<p>&xslt4j; performs the transformations specified in the XSL stylesheet and packages a sequence of SAX events that may be serialized to an output stream or writer, used to build a DOM tree, or forwarded as input to another transformation.</p>
</s2><anchor name="features"/>
<s2 title="&xslt4j; Features">
<ul>
- <li>Implements the <resource-ref idref="xslt"/> and the <resource-ref idref="xpath"/>.<br/><br/></li>
- <li>Builds on <resource-ref idref="trax"/>, <resource-ref idref="sax2"/>, <resource-ref idref="dom2"/>,
- and the <resource-ref idref="jaxp"/>.<br/><br/></li>
- <li>May be configured to work with any XMLReader, such as the
- <jump href="http://xml.apache.org/xerces-j/index.html">&xml4j; SAXParser</jump>, that implements the
- Java API for XML Parsing (see <link idref="usagepatterns" anchor="xmlreader">Setting the
- XMLReader</link>).<br/><br/></li>
- <li>Can process SAX or DOM input, and output to SAX or DOM.<br/><br/></li>
+ <li>Implements the relevant W3C specifications: <resource-ref idref="xslt"/> and <resource-ref idref="xpath"/>.<br/><br/></li>
+ <li>Implements <resource-ref idref="trax"/>, now part of <resource-ref idref="jaxp"/>, and builds on
+ <resource-ref idref="sax2"/> and <resource-ref idref="dom2"/>.<br/><br/></li>
+ <li>May be configured to work with any XML parser, such
+ <jump href="http://xml.apache.org/xerces-j/index.html">&xml4j;</jump>, that implements <resource-ref
+ idref="jaxp"/> (see <link idref="usagepatterns" anchor="xmlreader">Plugging in an XML
+ parser</link>).<br/><br/></li>
+ <li>Can process Stream, SAX or DOM input, and output to a Stream, SAX or DOM.<br/><br/></li>
<li>Transformations may be chained (the output of one transformation may be the input for
another).<br/><br/></li>
<li>May be run from the <link idref="commandline">command line</link> for convenient file-to-file
@@ -114,7 +114,7 @@
<li>Includes an <link idref="getstarted" anchor="applet">applet wrapper</link>.<br/><br/></li>
<li>May be used in a <link idref="samples" anchor="servlet">servlet</link> to transform XML documents into
HTML and serve the results to clients.<br/><br/></li>
- <li>Supports the creation of <link idref="extensions">Java and scripting language extensions</link> and
+ <li>Supports the creation of <link idref="extensions">Java and scripting language extensions</link>. and
provides a growing library of extension elements and functions.</li>
</ul>
</s2><anchor name="towork"/>
1.8 +3 -5 xml-xalan/java/xdocs/sources/xalan/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/readme.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- readme.xml 2000/10/19 11:57:13 1.7
+++ readme.xml 2000/12/04 17:23:42 1.8
@@ -62,7 +62,6 @@
-->
<s1 title="Release Notes">
<p>&xslt4j-current; alpha release</p>
-<p>It is our pleasure to thank two new contributors, Gary Peskin and Costin Manolache, for the fantastic help they have provided in producing this first release of Xalan-Java 2, and for the new ideas and creative work we are sure they will continue to provide in the ongoing &xslt4j; saga.</p>
<ul>
<li><link anchor="status">Status</link></li>
<li><link anchor="build">Build Notes</link></li>
@@ -71,14 +70,14 @@
</ul>
<s2 title="Status">
<ul>
- <!--li><link anchor="done">Changes since version 2.0.D01</link></li-->
+ <li><link anchor="done">Changes since version 2.0.D01</link></li>
<li><link anchor="bugs">Open bugs and bug reporting</link></li>
<li><link anchor="status">Version of Xerces to use</link></li>
<li><link anchor="notes">Other release notes</link></li>
<li><link anchor="to-do">To-do tasks for future &xslt4j; releases</link></li>
</ul>
- <!--anchor name="done"/>
- &done-j; -->
+ <anchor name="done"/>
+ &done-j;
<anchor name="bugs"/>
&bugs-j;
<anchor name="status"/>
@@ -219,6 +218,5 @@
</s2><!--anchor name="history"/>
<s2 title="Cumulative history of software changes">
<note>We started tracking the changes in earlier releases beginning with &xslt4j; version 1.1.</note>
-
</s2-->
</s1>
1.6 +9 -9 xml-xalan/java/xdocs/sources/xalan/resources.xml
Index: resources.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/resources.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- resources.xml 2000/12/01 22:25:11 1.5
+++ resources.xml 2000/12/04 17:23:43 1.6
@@ -49,13 +49,8 @@
<resource id="xpath"
title="XML Path Language (XPath) Version 1.0"
- location="http://www.w3.org/TR/xpath"/>
-
- <resource id="trax"
- title="TRaX (Transformations for XML)"
- location="apidocs/org/apache/trax/trax.html"/>
+ location="http://www.w3.org/TR/xpath"/>
-
<resource id="dom"
title="DOM"
location="http://www.w3.org/DOM"/>
@@ -71,10 +66,15 @@
location="http://www.megginson.com/SAX/Java/index.html"/>
<resource id="jaxp"
title="Java API for XML Parsing"
- location="http://java.sun.com/xml/docs/api/index.html"/>
+ location="http://java.sun.com/xml/docs/api/index.html"/>
+ <resource id="jsr063"
+ title="Java Specification Request 63"
+ location="http://java.sun.com/aboutJava/communityprocess/review/jsr063"/>
+ <resource id="trax"
+ title="TRaX (Transformation API for XML)"
+ location="apidocs/javax/xml/transform/trax.html"/>
-
<human-resource id="xalandev"
name="Xalan Development Mailing List"
mailto="xalan-dev@xml.apache.org"/>
-</resources>
\ No newline at end of file
+</resources>
\ No newline at end of file
1.14 +9 -9 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.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- samples.xml 2000/10/20 12:52:34 1.13
+++ samples.xml 2000/12/04 17:23:43 1.14
@@ -60,9 +60,9 @@
<ul>
<li><link anchor="simpletransform">SimpleTransform</link></li>
<li><link anchor="usestylesheetpi">UseStylesheetPI</link></li>
-<li><link anchor="transformtodom">TransformToDom</link></li>
<li><link anchor="usestylesheetparam">UseStylesheetParam</link></li>
<li><link anchor="sax2sax">SAX2SAX</link></li>
+<li><link anchor="domtodom">DomToDom</link></li>
<li><link anchor="pipe">Pipe</link></li>
<li><link anchor="usexmlfilters">UseXMLFilters</link></li>
<li><link anchor="applyxpath">ApplyXPath</link></li>
@@ -108,14 +108,6 @@
<p>You can run it from the UseStylesheetPI subdirectory with</p>
<p><code>java UseStylesheetPI</code></p>
<p>For more information, see <link idref="usagepatterns" anchor="embed">Working with embedded stylesheets</link>.</p>
- </s2><anchor name="transformtodom"/>
- <s2 title="TransformToDom">
- <p>What it does: The TransformToDom class uses the foo.xsl stylesheet to transform foo.xml, produces an output
- DOM, and traverses the DOM, printing the traversal to System.out. In contrast to SimpleTransform,
- TransformToDom illustrates the procedure for creating an output DOM that is available for further
- processing.</p>
- <p>You can run it from the TransformToDom subdirectory with</p>
- <p><code>java TransformToDom</code></p>
</s2><anchor name="usestylesheetparam"/>
<s2 title="UseStylesheetParam">
<p>What it does: The UseStyleSheetParam class uses foo.xsl and a stylesheet parameter to transform foo.xml,
@@ -128,6 +120,14 @@
<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><code>java SAX2SAX</code></p>
+ </s2><anchor name="domtodom"/>
+ <s2 title="DomToDom">
+ <p>What it does: the DomToDom class uses the foo.xsl stylesheet to transform a DOM document derived from foo.xml, produces an output
+ DOM, and traverses the DOM, printing the traversal to System.out. In contrast to SimpleTransform,
+ DomToDom illustrates the procedure for processing an input DOM and creating an output DOM that is available for
+ further processing.</p>
+ <p>You can run it from the DomToDom subdirectory with</p>
+ <p><code>java DomToDom</code></p>
</s2><anchor name="pipe"/>
<s2 title="Pipe">
<p>What it does: Pipes the output from one transformation to a second transformation, then from the second
1.16 +147 -146 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.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- usagepatterns.xml 2000/11/21 17:40:58 1.15
+++ usagepatterns.xml 2000/12/04 17:23:43 1.16
@@ -59,7 +59,7 @@
<s1 title="Basic usage patterns">
<ul>
<li><link anchor="basic">Basic steps</link></li>
-<li><link anchor="xmlreader">Setting the XMLReader</link></li>
+<li><link anchor="plug">Plugging in the Transformer and XML parser</link></li>
<li><link anchor="embed">Working with embedded stylesheets</link></li>
<li><link anchor="params">Setting stylesheet parameters</link></li>
<li><link anchor="sax">Explicitly working with SAX</link></li>
@@ -79,7 +79,7 @@
<li><link anchor="transformer">Process the stylesheet and generate a Transformer</link></li>
<li><link anchor="transformation">Perform the transformation</link></li>
</ol>
- <p>The following example highlights the four basic steps involved in performing a transformation.</p>
+ <p>The following example illustrates the three basic steps involved in performing a transformation.</p>
<source>// 1. Instantiate a TransformerFactory.
javax.xml.transform.TransformerFactory tFactory =
javax.xml.transformerTransformerFactory.newInstance();
@@ -89,8 +89,8 @@
javax.xml.transform.Transformer transformer = tFactory.newTransformer
(new javax.xml.transform.stream.StreamSource("foo.xsl");
-// 4. Use the Transformer to apply the Templates object to an XML
-// Source and send the output to a Result object.
+// 3. Use the Transformer to transform an XML Source and send the
+// output to a Result object.
transformer.transform
(new javax.xml.transform.stream.StreamSource("foo.xml"),
new javax.xml.transform.stream.StreamResult( new
@@ -98,165 +98,159 @@
<note>For a working example of this model at its simplest, see SimpleTransform.java in the java/samples/SimpleTransform subdirectory.</note>
</s2><anchor name="processor"/>
<s2 title="1. Instantiate a TransformerFactory">
- <p>TransformerFactory is an abstract class with a static newInstance() method that instantiates the concrete subclass designated by the javax.xml.transform.TransformerFactory system property.</p>
- <p>The default setting for this system property is org.apache.xalan.processor.TransformerFactoryImpl.</p>
-</s2><anchor name="process"/>
- <s2 title="2. Use the TransformerFactory to process the stylesheet Source and produce a Transformer">
- <p>You may provide the stylesheet Source in the form of a stream of XML markup (StreamSource) or a DOM Node (DOMSource). To specify a StreamSource, you may use a system ID or file name (using URI syntax), an InputStream, or a Reader.</p>
-<p>The Transformer newTransformer(Source) method processes the stylesheet into a Templates object and generates a Transformer that you can use to perform a transformation.</p>
-
-<p></p>
- <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.</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 org.apache.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>
-<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>
-<note>You may also provide the Source in the form of SAX ContentHandler events from a SAX InputSource or SAX XMLReader (SAXSource), in which case you should use a <jump href="apidocs/javax/xml/transform/xax/SAXTransformerFactory.html">SAXTransformerFactory</jump>. For more information, see xxxxxx.</note>
+ <p><jump href="apidocs/javax/xml/transform/TransformerFactory#html">TransformerFactory</jump> is an abstract class with a static newInstance() method that instantiates the concrete subclass designated by the javax.xml.transform.TransformerFactory system property.</p>
+ <p>The default setting for this system property is <jump href="apidocs/org/apache/xalan/processor/TransformerFactoryImpl.html">org.apache.xalan.processor.TransformerFactoryImpl</jump>.</p>
</s2><anchor name="transformer"/>
-<s2 title="3. Instantiate a Transformer">
-<p>To transform an XML document, you need an implementation of the org.apache.trax.Transformer interface.</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 title="2. Use the TransformerFactory to process the stylesheet Source and produce a Transformer">
+<p>The TransformerFactory <jump href="apidocs/javax/xml/transform/TransformerFactory.html#newTransformer(javax.xml.transform.Source)">newTransformer(Source xslSource)</jump> method processes the stylesheet Source into a Templates object and returns a Transformer that you can use to perform a transformation (apply the Templates object to an XML Source).</p>
+<p>You may provide the stylesheet Source in the form of a stream of XML markup (<jump href="apidocs/javax/xml/transform/stream/StreamSource.html">StreamSource</jump>), a DOM Node (<jump href="apidocs/javax/xml/transform/dom/DOMSource.html">DOMSource</jump>), or a series of SAX ContentHandler events (<jump href="apidocs/javax/xml/transform/sax/SAXSource.html">SAXSource</jump>). To specify a StreamSource, you may use a system ID or file name (using URI syntax), a java.io.InputStream, or a java.io.Reader. The use of DOMSource and SAXSource are illustrated in subsequent sections.</p>
+<note>If you plan to use the stylesheet Source to transform multiple XML Sources, you should use the TransformerFactory <jump href="apidocs/javax/xml/import/TransformerFactory.html#newTemplates(javax.xml.transform.Source)">newTemplates(Source xslSource)</jump> method to explicitly generate a Templates object, which you can then use repeatedly to generate a Transformer for performing an individual transformation. See <link anchor="multithreading">Multithreading</link>.</note>
</s2><anchor name="transformation"/>
-<s2 title="4. Perform a transformation">
-<p>Supply the XML input, a target or "holder" for the transformation output, and instruct the Transformer to perform the transformation.</p>
-<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: org.apache.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 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 output 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. This enables the Transformer to begin supplying the client with transformation output before the parsing has been completed. When necessary, the Transformer waits for the XMLReader to provide the input it needs to continue.</p>
-</s2><anchor name="xmlreader"/>
-<s2 title="Setting the XMLReader">
-<p>Unless you are submitting your stylesheet and your XML input in the form of DOM trees, &xslt4j; uses an XMLReader to parse the stylesheet and the XML input. This XMLReader must implement the <resource-ref idref="jaxp"/>. To designate an XMLReader, do one of the following:</p>
-<ul>
- <li>Set the org.xml.sax.driver system property.<br/><br/>
- You can set system properties from the command line or within your application. You can also edit the setting in org/apache/xalan/res/XSLTInfo.properties (in xalan.jar). If the org.xml.sax.driver system property is not set, &xslt4j; uses this file to set it.<br/><br/></li>
- <li>Call the org.apache.trax.Processor.setXMLReader() method.<br/><br/>
- If you call this method before you call org.apache.trax.Processor.process() to generate a Templates object, &xslt4j; uses the XMLReader you designate to process the stylesheet and the XML input, and ignores the org.xml.sax.driver property setting (for the current transformation).<br/><br/></li>
-</ul>
-<p>Be sure the XMLReader is on the classpath. The &xml4j; XMLReader -- org.apache.xerces.parsers.SAXParser -- is in xerces.jar.</p>
-<note>Other system properties: The default serializer system property settings are in org/apache/serialize/serializer.properties. The default XSLT stylesheet system property setting is in org/apache/trax/trax.properties. These properties files are in xalan.jar.</note>
+<s2 title="3. Use the Transformer to perform a transformation">
+<p>Use the Transformer <jump href="apidocs/javax/xml/import/Transformer.html#transform(javax.xml.transform.Source, javax.xml.transform.Result">transform(Source xmlSource, Result transformResult)</jump> method to transform the XML Source and place the transformation output in a Result object.</p>
+<p>Just as with the stylesheet, you can supply the XML Source in the form of a <jump href="apidocs/javax/xml/transform/stream/StreamSource.html">StreamSource</jump>, <jump href="apidocs/javax/xml/transform/dom/DOMSource.html">DOMSource</jump>, or <jump href="apidocs/javax/xml/transform/sax/SAXSource.html">SAXSource</jump>. Likewise, the Result may be a <jump href="apidocs/javax/xml/transform/stream/StreamResult.html">StreamResult</jump>, <jump href="apidocs/javax/xml/transform/dom/DOMResult.html">DOMResult</jump>, or <jump href="apidocs/javax/xml/transform/sax/SAXResult.html">SAXResult</jump>.</p>
+<p>For each node in the XML source, the Transformer uses the transformation instructions in 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>
+</s2><anchor name="plug"/>
+<s2 title="Plugging in the Transformer and XML parser">
+<p>The <jump href="apidocs/javax/xml/transform/package-summary.html">javax.xml.transform</jump> and <jump href="apidocs/javax/xml/parsers/package-summary.html">javax.xml.parsers</jump> interfaces enable you to isolate your application from the implementation details of a given Transformer, SAX parser, or DOM parser. Like javax.xml.transform.TransformerFactory, javax.xml.parsers.SAXParserFactory and javax.xml.parsers.DocumentBuilderFactory are abstract classes with a static newInstance() method that instantiates a concrete "Factory" which in turn wraps an implementation. Each of these newInstance() methods, uses a system property setting to determine the implementation to instantiate.</p>
+<p>&xslt4j; is distributed with the following system property settings for the Xalan XSLT Transformer and the Xerces DOM and SAX parsers:</p>
+<gloss>
+ <label>System property</label>
+ <item>Default value</item>
+ <label><code>vax.xml.transform.TransformerFactory</code></label>
+ <item><code>org.apache.xalan.proccessor.TransformerFactoryImpl</code></item>
+ <label><code>javax.xml.parsers.DocumentBuilderFactory</code></label>
+ <item><code>org.apache.xerces.jaxp.DocumentBuilderFactoryImpl</code></item>
+ <label><code>javax.xml.parsers.SAXParserFactory</code></label>
+ <item><code>org.apache.xerces.jaxp.SAXParserFactoryImpl</code></item>
+ </gloss>
+<p>For information about the mechanism used to determine system property values, see "Section 3: Pluggability Layer" in the <ref>Java API for XML Processing</ref> at <jump href="http://java.sun.com/aboutJava/communityprocess/review/jsr063/index.html">JSR-000063 JavaTM API for XML Processing 1.1</jump>.</p>
</s2><anchor name="embed"/>
<s2 title="Working with embedded stylesheets">
-<p>An XML source document may include an <jump href="http://www.w3.org/TR/xml-stylesheet/">xml-stylesheet processing instruction</jump> which identifies the stylesheet to be used to process the document. As indicated by the processing instruction <ref>href</ref> attribute, the stylesheet itself may be embedded in the XML document or located elsewhere.</p>
+<p>An XML Source may include an <jump href="http://www.w3.org/TR/xml-stylesheet/">xml-stylesheet processing instruction</jump> which identifies the stylesheet to be used to process the document. As indicated by the processing instruction <ref>href</ref> attribute, the stylesheet itself may be embedded in the XML document or located elsewhere.</p>
<p>Suppose you have an XML document (foo.xml) with the following xml-stylesheet processing instruction:</p>
<p><code><?xml-stylesheet type="text/xml" href="foo.xsl"?></code></p>
-<p>The following fragment, uses this instruction to locate the stylesheet (foo.xsl in the same directory) and create a Templates object. Note the use of the Processor getAssociatedStylesheets() and processMultipleStylesheets() methods in steps 2a and 2b.</p>
-<note>An XML document may include more than one xml-stylesheet processing instruction, hence the support for working with multiple stylesheets. If more than one stylesheet is returned, the other stylesheets are imported into the first stylesheet [awaiting clarification from the W3C].</note>
-<source>// 1. Instantiate the stylesheet processor.
-org.apache.trax.Processor processor =
- org.apache.trax.Processor.newInstance("xslt");
-
-// 2a. Get the stylesheet(s) from the XML source (the source may contain
-// more than one xml-stylesheet processing instruction).
+<p>The following fragment, uses this instruction to locate the stylesheet (foo.xsl in the same directory as foo.xml) and create a Templates object. Note the use of the TransformerFactory getAssociatedStylesheet() in step 2a.</p>
+<note>An XML document may include more than one xml-stylesheet processing instruction, hence the support for working with multiple stylesheets. If more than one stylesheet is returned, the other stylesheets are imported into the first stylesheet.</note>
+<source>// 1. Instantiate the TransformerFactory.
+javax.xml.transform.TransformerFactory tFactory =
+ javax.xml.transform.TransformerFactory.newInstance();
+// 2a. Get the stylesheet from the XML source.
String media = null , title = null, charset = null;
-org.xml.sax.InputSource[] stylesheet = processor.getAssociatedStylesheets
- ( new InputSource("file:///xalan/samples/UseStylesheetPI/foo.xml"),
- media, title, charset );
-// 2b. Process the stylesheet(s), producing a Templates object.
-org.apache.trax.Templates templates = processor.processMultiple(stylesheet);
+javax.xml.transform.Source stylesheet = tFactory.getAssociatedStylesheet
+ (new StreamSource("foo.xml"),media, title, charset);
-// 3. Use the Templates object to instantiate a Transformer.
-org.apache.trax.Transformer transformer = templates.newTransformer();
+// 2b. Process the stylesheet and generate a Transformer.
+Transformer transformer = tFactory.newTransformer(stylesheet);
-// 4. Use the Transformer to apply the Templates object to an XML
-// source and send the output to a Result object.
+// 3. Use the Transformer to perform the transformation and send the
+// the output to a Result object.
transformer.transform
- (new org.xml.sax.InputSource("foo.xml"),
- new org.apache.trax.Result(new java.io.FileWriter("foo.out")));</source>
+ (new javax.xml.transform.stream.StreamSource("foo.xml"),
+ new StreamResult (new java.io.FileOutputStream("foo.out")));</source>
<p>For a sample that uses this technique, see <link idref="samples" anchor="usestylesheetpi">UseStylesheetPI</link>.</p>
<p>You can also instruct the <link idref="commandline">command-line utility</link> to use stylesheet processing
instructions:</p>
<ol>
- <li>Include the -IN flag with an XML source that contains a stylesheet processing instruction.<br/><br/></li>
- <li>Do not include the -XSL flag.</li>
+ <li>Include the <code>-in</code> flag with an XML source that contains a stylesheet processing instruction.<br/><br/></li>
+ <li>Do not include the <code>-xsl</code> flag.</li>
</ol>
</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 org.apache.trax.Transformer <jump href="apidocs/org/apache/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>
-<p>You can also set a parameter with the command-line utility by including the -param flag. For example:</p>
+<p>An XSLT stylesheet may include parameters that are set at run time each time a transformation is performed. To set a stylesheet parameter, use the Transformer <jump href="apidocs/org/apache/trax/Transformer.html#setParameter(java.lang.String,java.lang.Object)">setParameter(String name, Object value)</jump> method. For a working example, see UseStylesheetParam.java in the samples/UseStylesheetParam subdirectory.</p>
+<p>You can also set a parameter with the command-line utility by including the <code>-param</code> flag. For example:</p>
<p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -param param1 foobar</code></p>
<p>where <code>param</code> is the parameter name and <code>foobar</code> is the parameter value. The parameter namespace is null.</p>
</s2><anchor name="sax"/>
<s2 title="Explicitly working with SAX">
<p>&xslt4j; uses the SAX event model to process stylesheets, to parse XML input documents, and to produce output. For each of these operations, an XMLReader reads input, firing parse events, and a ContentHandler listens to the XMLReader and performs parse event methods.</p>
-<p>When you use the basic procedure described above for performing transformations, &xslt4j; takes care of many of the SAX details under the covers. You are free to make these details explicit, which simply means that you can intervene in the procedure to accommodate any custom conditions in which your application operates.</p>
-<p>Suppose, for example, you are using a custom XMLReader (perhaps doing more than just parsing static XML documents) to generate &xslt4j; SAX parse events. You can instruct the Transformer to provide the ContentHandler for this XMLReader. You might even have a custom reader for producing/processing stylesheets, in which case you simply set the org.apache.trax.TemplatesBuilder (implemented by the org.apache.xalan.processor.StylesheetHandler) as the ContentHandler for this reader.</p>
+<p>When you use the basic procedure described above for performing transformations, &xslt4j; takes care of many of the SAX details under the covers. You are free to make these details explicit, which simply means that you can intervene in the procedure to accommodate the precise environment in which your application operates.</p>
+<p>Suppose, for example, you are using a custom XMLReader, perhaps doing more than just parsing static XML documents) to generate &xslt4j; SAX parse events. You might even have a custom reader for producing/processing stylesheets. You can cast the TransformerFactory to a SAXTransformerFactory, which provides access to a TransformerHandler, which you can set as the ContentHandler for this reader.</p>
<p>The following example explicitly sets up the XMLReader and ContentHandlers, and replicates the <link anchor="basic">basic steps</link> described above.</p>
- <source>// 1. Instantiate stylesheet processor.
-org.apache.trax.Processor processor =
- org.apache.trax.Processor.newInstance("xslt");
-
-// 2. Process the stylesheet. producing a Templates object.
-// Get the XMLReader.
-org.xml.sax.XMLReader reader =
- org.xml.sax.helpers.XMLReaderFactory.createXMLReader();
-// Set the ContentHandler.
-org.apache.trax.TemplatesBuilder templatesBuilder =
- processor.getTemplatesBuilder();
-reader.setContentHandler(templatesBuilder);
-// Set the ContentHandler to also function as a LexicalHandler, which
-// includes "lexical" (e.g., comments and CDATA) events. The Xalan
-// TemplatesBuilder -- org.apache.xalan.processor.StylesheetHandler -- is
-// also a LexicalHandler).
-if(templatesBuilder instanceof org.xml.sax.ext.LexicalHandler)
- reader.setProperty("http://xml.org/sax/properties/lexical-handler",
- templatesBuilder);
-// Parse the stylesheet.
-reader.parse("foo.xsl");
-//Get the Templates object from the ContentHandler.
-org.apache.trax.Templates templates = templatesBuilder.getTemplates();
-
-// 3. Use the Templates object to instantiate a Transformer.
-org.apache.trax.Transformer transformer = templates.newTransformer();
-
-// 4. Perform the transformation.
-// Set up the ContentHandler (a serializer) for the output.
-java.io.FileOutputStream fos = new java.io.FileOutputStream("foo.out");
-org.apache.trax.Result result = new org.apache.trax.Result(fos);
-org.apache.serialize.Serializer serializer =
- org.apache.serialize.SerializerFactory.getSerializer("xml");
-transformer.setContentHandler(serializer.asContentHandler());
-// Set up the ContentHandler for the input.
-org.xml.sax.ContentHandler chandler = transformer.getInputContentHandler();
-reader.setContentHandler(chandler);
-if(chandler instanceof org.xml.sax.ext.LexicalHandler)
- reader.setProperty("http://xml.org/sax/properties/lexical-handler",chandler);
-else
- reader.setProperty("http://xml.org/sax/properties/lexical-handler", null);
-// Parse the XML input document. The input and output ContentHandlers work in
-// separate threads to optimize performance.
-reader.parse("foo.xml");</source>
+ <source>// Instantiate a TransformerFactory.
+javax.xml.transform.TransformerFactory tFactory =
+ javax.xml.transform.TransformerFactory.newInstance();
+// Verify that the TransformerFactory implementation you are using
+// supports SAX input and output (&xslt4j; does!).
+if (tFactory.getFeature(javax.xml.transform.sax.SAXSource.FEATURE) &&
+ tFactory.getFeature(javax.xml.transform.sax.SAXResult.FEATURE))
+ {
+ // Cast the TransformerFactory to SAXTransformerFactory.
+ javax.xml.transform.sax.SAXTransformerFactory saxTFactory =
+ ((javax.xml.transform.SAXTransformerFactory) tFactory);
+ // Create a Templates ContentHandler to handle parsing of the
+ // stylesheet.
+ javax.xml.transform.sax.TemplatesHandler templatesHandler =
+ saxTFactory.newTemplatesHandler();
+
+ // Create an XMLReader and set its ContentHandler.
+ org.xml.sax.XMLReader reader =
+ org.xml.sax.helpers.XMLReaderFactory.createXMLReader();
+ reader.setContentHandler(templatesHandler);
+
+ // Parse the stylesheet.
+ reader.parse("foo.xsl");
+
+ // Get the Templates object (generated during the parsing of the stylesheet)
+ // from the TemplatesHandler.
+ javax.xml.transform.Templates templates =
+ templatesHandler.getTemplates();
+ // Create a Transformer ContentHandler to handle parsing of
+ // the XML Source.
+ javax.xml.transform.sax.TransformerHandler transformerHandler
+ = saxTFactory.newTransformerHandler(templates);
+ // Reset the XMLReader's ContentHandler to the TransformerHandler.
+ reader.setContentHandler(transformerHandler);
+
+ // Set the ContentHandler to also function as a LexicalHandler, which
+ // can process "lexical" events (such as comments and CDATA).
+ reader.setProperty("http://xml.org/sax/properties/lexical-handler",
+ transformerHandler);
+
+ // Set up a Serializer to serialize the Result to a file.
+ org.apache.xalan.serialize.Serializer serializer =
+ org.apache.xalan.serialize.SerializerFactory.getSerializer("xml");
+ serializer.setOutputStream(new java.io.FileOutputStream("foo.out"));
+ // The Serializer functions as a SAX ContentHandler.
+ javax.xml.transform.Result result =
+ new javax.xml.transform.sax.SAXResult(serializer.asContentHandler());
+ transformerHandler.setResult(result);
+
+ // Parse the XML input document.
+ 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>
+
+<p>You can chain together a series of transformations such that the output of each transformation provides input for the next transformation. &xslt4j; supports two basic strategies for chaining a series of transformations:</p>
<ul>
- <li>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 XMLReader that parses 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>
+ <li>Use the SAXTransformerFactory to process the stylesheet and create a TransformerHandler for each transformation. Then you can set
+the first TransformerHandler as the ContentHandler for the XMLReader that parses the input, make the second TransformerHandler the ContentHandler for the output of the first TransformerHandler, and so on. For more detail and an example, see the <link idref="samples" anchor="pipe">Pipe</link> sample.<br/><br/></li>
+ <li>Use the SAXTransformerFactory to process the stylesheet and create a SAX XMLFilter for each transformation. Set an XMLReader as the parent of the first XMLFilter, the first XMLFilter as the parent of the second XMLFilter, and so on. You launch the series of transformations by instructing the last XMLFilter to parse the XML Source for the first transformation. 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>
-<p>To process DOM input, use one of the org.apache.trax.Transformer <jump href="apidocs/org/apache/trax/Transformer.html#transformNode(org.w3c.dom.Node, org.apache.trax.Result)">transformNode()</jump> methods.</p>
- <p>To produce a transformation result in the form of a DOM tree, use the <jump href="http://java.sun.com/xml/docs/api/index.html">Java API for XML Parsing</jump> as indicated below to instantiate an empty DOM Document to hold the result tree.</p>
- <ol>
- <li>The javax.xml.parsers.DocumentBuilderFactory abstract class contains a static newInstance() method for instantiating a factory designated by the javax.xml.parsers.DocumentBuilderFactory system property.<br/><br/></li>
- <li>In turn, the factory provides a newDocumentBuilder() method with which you instantiate a DocumentBuilder.<br/><br/></li>
- <li>Use the DocumentBuilder to instantiate an empty DOM Document.<br/><br/></li>
- <li>Use this DOM Document node to construct the org.apache.trax.Result object for the transformation result tree.</li>
- </ol>
-<source>javax.xml.parsers.DocumentBuilderFactory dfactory =
- javax.xml.parsers.DocumentBuilderFactory.newInstance();
-javax.xml.parsers.DocumentBuilder docBuilder = dfactory.newDocumentBuilder();
-org.w3c.dom.Document resultDoc = docBuilder.newDocument();
-org.apache.trax.Result result = new org.apache.trax.Result(resultDoc);
-</source>
+ <p>In some cases, the input and/or desired output for a transformation may be a DOM tree object. The javax.xml.transform.DOM package provides <jump href="apidocs/javax/xml/transform/dom/DOMSource.html">DOMSource</jump> and a <jump href="apidocs/javax/xml/transform/dom/DOMResult.html">DOMResult</jump>, either or both of which you can use when you perform a transformation.</p>
+<p>In some cases, your application provides input in the form of a DOM tree, which accelerates the transformation process, since the input has in effect already been processed. To produce DOM input from a stream, you can use a <jump href="apidocs/javax/xml/parsers/DocumentBuilderFactory.html">DocumentBuilderFactory</jump> to produce a <jump href="apidocs/javax/xml/parsers/DocumentBuilder.html">DocumentBuilder</jump> with which you can parse the XML input into a DOM Document, as illustrated below.</p>
+<source>// Instantiate a DocumentBuilderFactory.
+javax.xml.parsers.DocumentBuilderFactory dfactory =
+ javax.xml.parsers.DocumentBuilderFactory.newInstance();
+// Use the DocumentBuilderFactory to provide access to a DocumentBuilder.
+javax.xml.parsers.DocumentBuilder dBuilder = dfactory.newDocumentBuilder();
+// Use the DocumentBuilder to parse the XML input.
+org.w3c.dom.Document inDoc = dBuilder.Parse("foo.xml");</source>
+<p>To produce DOM output, simply use a Transformer to transform to a DOMResult object.</p>
+<source>// Generate a Transformer.
+javax.xml.transform.Transformer transformer = tFactory.newTransformer
+ (new javax.xml.transform.Stream.StreamSource("foo.xsl"));
+// Create an empy DOMResult object for the output.
+javax.xml.transform.dom.DOMResult domResult =
+ new javax.xml.transform.dom.DOMResult();
+// Perform the transformation.
+transformer.transform(new javax.xml.transform.dom.DOMSource(inDoc)
+ domResult;
+// Now you can get the output Node from the DOMResult
+org.w3c.dom.Node node = domResult.getNode();</source>
+<p>The <link idref="samples" anchor="domtodom">TransformFromDOMtoDOM</link> illustrates both procedures, and serializes the DOMResult to System.out.</p>
</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>
@@ -284,13 +278,19 @@
</s2><anchor name="servlet"/>
<s2 title="Using &xslt4j; in a servlet">
-<p>You can set up a servlet to use &xslt4j; to respond to requests for XML documents by transforming those documents into HTML and serving them to clients. For a sample of how this might be done, see <link idref="samples" anchor="servlet">sample servlet</link>.</p>
+<p>You can set up a servlet to use &xslt4j; to respond to requests for XML documents by transforming those documents into HTML and serving them to clients. For a sample of how this can be done, see <link idref="samples" anchor="servlet">sample servlet</link>.</p>
</s2><anchor name="extensions"/>
<s2 title="Creating and using extensions">
<p>For those cases where you want to be able to call procedural code from within a stylesheet, the &xslt4j; Extensions facility supports the creation of extension elements and extension functions. See <link idref="extensions">Extensions</link> and <link idref="samples" anchor="extensions">Extensions samples</link>.</p>
</s2><anchor name="multithreading"/>
<s2 title="Multithreading">
-<p>A given Templates object may be used concurrently and repeatedly in multiple transformations. You must, however, use a separate Transformer object to perform each transformation. The Transformer object tracks state information and is lightweight. Each time you perform a transformation, use the Templates object newTransformer() method to instantiate a Transformer.</p>
+<p>A given Templates object may be used repeatedly and even in multiple threads running concurrently for the transformation of XML input, but you should use the Templates object to instantiate a separate Transformer for each transformation you perform. The Templates object is an immutable runtime representation of the structure and content of a stylesheet (which may include and import multiple stylesheet sources). A Transformer, on the other hand, is a lightweight object that tracks state information during the transformation, and should only be used to perform a single transformation.</p>
+
+<p>If you want to perform multiple transformations (sequentialy or concurrently) with the same stylesheet instructions, do the following:</p>
+<ol>
+ <li>Use the TransformerFactory <jump href="apidocs/javax/xml/transform/TransformerFactory.html#newTemplates(javax.xml.transform.Source)">newTemplates(Source xslSource)</jump> method to create a Templates object.<br/><br/></li>
+<li>For each transformation, use the Templates object <jump href="apidocs/javax/xml/transform/Templates.html#newTransformer()">newTransformer()</jump> method to create a Transformer, and use that Transformer's <jump href="apidocs/javax/xml/transform/Transformer.html#transform(javax.xml.transform.Source, javax.xml.transform.Result)">transform(Source xmlSource, Result transformResult)</jump> method to perform the transformation.</li>
+</ol>
</s2><anchor name="debugging"/>
<s2 title="Debugger Interface">
<p>&xslt4j; contains a debugger interface in the org.apache.xalan.xslt.trace package:</p>
@@ -311,7 +311,7 @@
selection of a stylesheet node.</li>
</ul>
<p>The <link idref="commandline">command-line utility</link> uses the debugger interface when you include one or more of the
- following switches: -TT, -TG, -TS, -TTC.</p>
+ following switches: <code>-TT</code>, <code>-TG</code>, <code>-TS</code>, <code>-TTC</code>.</p>
<p>Example:</p>
<source>import org.apache.xalan.transformer.TransformerImpl;
import org.apache.xalan.trace.TraceManager;
@@ -331,14 +331,14 @@
// Print information whenever a template is invoked.
ptl.m_traceTemplates = true;
-// Set up the transformation
-org.apache.trax.Processor processor =
- org.apache.trax.Processor.newInstance("xslt");
-org.apache.trax.Templates templates = processor.process
- (new org.xml.sax.InputSource("foo.xsl"));
-org.apache.trax.Transformer transformer = templates.newTransformer();
+// Set up the transformation
+javax.xml.transform.TransformerFactory tFactory =
+ javax.xml.trnasform.TransformerFactory.newInstance();
+javax.xml.transform.Transformer transformer =
+ tFactory.newTransformer(new javax.xml.transform.stream.StreamSource
+ ("foo.xsl"));
-// Cast the Transformer object as TransformerImpl.
+// Cast the Transformer object to TransformerImpl.
if (transformer instanceof TransformerImpl) {
TransformerImpl transformerImpl = (TransformerImpl)transformer;
@@ -350,8 +350,9 @@
// Perform the transformation --printing information to
// the events log during the process.
transformer.transform
- ( new org.xml.sax.InputSource("foo.xml"),
- new org.apache.trax.Result(new java.io.FileWriter("foo.out")) );
+ ( new javax.xml.transform.stream.StreamSource("foo.xml"),
+ new javax.xml.transform.stream.StreamResult
+ (new java.io.FileWriter("foo.out")) );
}
// Close the PrintWriter and FileWriter.
pw.close();
1.14 +8 -99 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.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- whatsnew.xml 2000/11/21 17:40:59 1.13
+++ whatsnew.xml 2000/12/04 17:23:44 1.14
@@ -57,104 +57,13 @@
* <http://www.apache.org/>.
-->
<s1 title="What's new in &xslt4j2;">
-<ul>
- <li><link anchor="design">New Design</link></li>
- <li><link anchor="packages">Package layout</link></li>
-</ul><anchor name="design"/>
+
<s2 title="New Design">
- <p>With respect to &xslt4j; 1.x, &xslt4j2; represents a fundamental redesign of Xalan. The primary objective of this redesign is an easier-to-use, more understandable, and more modular API that that encourages wider participation in its ongoing development by the open-source XML developer community, and that lends itself to "streaming," the production of transformation output while the input is still being parsed.</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 XML transformations. In November 2000, was incorporated into the Sun Java Specification Request 63, the Java API for XMP Procesing Version 1.1. We strongly encourage you to use the TRaX framework and interfaces when you use &xslt4j2; to perform XML transformations.</p>
-<p>The basic organization of TRaX is quite simple: use a TransformerFactory to process transformation instructions and generate a Transformer, with which you can apply the processed transformation instructions (a Templates object) to your XML source, producing a transformation result. 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 Java system property settings. System properties, for example, identify the stylesheet processor and XMLReader to use, and the serializers that are available for various output methods. You can set these system properties on the command line, in your applications, or by editing the properties files that &xslt4j; uses for system properties that you do not set. The default settings in these files (as shipped) point to the Xalan StylesheetProcessor, the serializers shipped with Xalan, and the Xerces SAXParser.</p>
-</s2><anchor name="packages"/>
- <s2 title="Package layout">
- <p>The new class package structure is flatter and maps closely to the TRaX framework. 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.</p>
- <p>Responsibility for evaluating XPath expressions and XSLT matching patterns is centralized in the XPath packages,
- serializers for outputting transformation result trees as a stream are in the serializers package, and a variety of
- utilities used by multiple packages are in the utils package.</p>
- <p>&xslt4j2; is made up of four primary and several secondary packages. The four primary packages 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 package is responsible for
- implementing the <jump href="apidocs/org/apache/trax/Processor.html">org.apache.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). This package is responsible for implementing the <jump
- href="apidocs/org/apache/trax/Templates.html">org.apache.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. This package is
- responsible for implementing the <jump href="apidocs/org/apache/trax/Transformer.html">org.apache.trax.Transformer</jump>
- interface.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/xpath/package-summary.html">org.apache.xpath</jump> packages</label>
- <item>Evaluates XPath expressions and XSLT match patterns.</item>
- </gloss>
- <p>Other packages include:</p>
- <gloss>
- <label><jump href="apidocs/org/apache/xalan/xslt/package-summary.html">org.apache.xalan.xslt</jump></label>
- <item>Xalan <link idref="commandline">command-line utility</link> for performing transformations.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/xalan/stree/package-summary.html">org.apache.xalan.stree</jump></label>
- <item>Implementation of DOM source tree optimized for node retrieval and XSLT processing.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/xalan/utils/package-summary.html">org.apache.xalan.utils</jump></label>
- <item>Xalan utilities used by the other packages.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/xalan/res/package-summary.html">org.apache.xalan.res</jump></label>
- <item>&xslt4j; resource files (such as error messages).</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/xalan/client/package-summary.html">org.apache.xalan.client</jump></label>
- <item>Provides an applet interface for performing XSLT transformations.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/xalan/trace/package-summary.html">org.apache.xalan.trace</jump></label>
- <item>Enables XSLT debuggers and similar tools to add trace listeners to transformation operations.</item>
- </gloss>
- <gloss>
- <label><jump
- href="apidocs/org/apache/xalan/extensions/package-summary.html">org.apache.xalan.extensions</jump></label>
- <item>Support for extension elements and extension functions, which allow you to call Java code and scripts from
- within a stylesheet.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/xalan/lib/package-summary.html">org.apache.xalan.lib</jump>
- packages</label>
- <item>The &xslt4j; library of extension elements and extension functions.</item>
- </gloss>
- <p>Other packages that are included in the xml-xalan source tree and xalan.jar:</p>
- <gloss>
- <label><jump href="apidocs/org/javax/xml/parsers/package-summary.html">javax.xml.parsers</jump></label>
- <item>The xml.apache.org implementation of <resource-ref idref="jaxp"/>.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/apache/serialize/package-summary.html">org.apache.serialize</jump> and <jump href="apidocs/org/apache/xml/serialize/transition/package-summary.html">org.apache.xml.serialize.transition</jump> packages</label>
- <item>Output transformation result trees as a stream.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/xml/sax/package-summary.html">org.xml.sax</jump> packages</label>
- <item>SAX 2 interfaces.</item>
- </gloss>
- <gloss>
- <label><jump href="apidocs/org/w3c/dom/package-summary.html">org.w3.dom</jump> packages</label>
- <item>DOM level 2 interfaces.</item>
- </gloss>
- <note>As actions are taken by the relevant standards organizations, the TrAX and serializer packages are subject to change in future releases.</note>
+ <p>&xslt4j2; represents a fundamental redesign of Xalan. The primary objective of this redesign is an easier-to-use, more understandable, and more modular API that that encourages wider participation in its ongoing development by the open-source XML developer community, and that lends itself to "streaming," the production of transformation output while the input is still being parsed.</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. &xslt4j2; also implements the standard TrAX API (see below) that enables you to code your XML applications without reference to the internal details of a given implementation.</p>
+<p>Given the scope of the redesign, the changes with respect to <jump href="http://xml.apache.org/xalan/index.html">&xslt4j; 1.x</jump> are global in nature. For an introduction to &xslt4j2; usage patterns, see <link idref="usagepatterns">Basic Usage Patterns</link>.</p>
+<p>&xslt4j2; implements the <resource-ref idref="trax"/> interfaces. The product of extensive open-source collaboration by members of the XML developer community, TrAX provides a conceptual framework and a standard API for performing XML transformations. During its evolution, the TrAX API has undergone several revisions. We believe this API has now reached or is very close to final form. In November 2000, TrAX was incorporated into <resource-ref idref="jsr063"/>, the Java API for XML Processing Version 1.1, which has been published for public review. We strongly encourage you to utilize the TrAX framework when you use &xslt4j2; to perform XML transformations.</p>
+<p>The basic organization of TrAX is quite simple: use a TransformerFactory to process transformation instructions and generate a Transformer, with which you can apply the processed transformation instructions to your XML Source, producing a transformation Result. For more detail, see <link idref="usagepatterns" anchor="basic">Basic steps</link>.</p>
+<p>As part of the Java API for XML Processing, TraX provides a stable framework for plugging Transformers (like &xslt4j;) and XML parsers (like &xml4j;) into your applications without tying yourself to the internal details of those implementations. See <link idref="usagepatterns" anchor="plug">Plugging in TrAX, SAX, and DOM implementations</link>.</p>
</s2>
-</s1>
+</s1>
\ No newline at end of file