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>[EMAIL PROTECTED]</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="[email protected]"/>
-</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
