dleslie 00/11/21 09:41:03
Modified: java/xdocs/sources/xalan getstarted.xml index.xml
resources.xml usagepatterns.xml whatsnew.xml
Log:
work in progress
Revision Changes Path
1.7 +9 -6 xml-xalan/java/xdocs/sources/xalan/getstarted.xml
Index: getstarted.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/getstarted.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- getstarted.xml 2000/10/18 18:04:00 1.6
+++ getstarted.xml 2000/11/21 17:40:57 1.7
@@ -35,7 +35,7 @@
<li>Be sure the java executable is on your path.</li>
<li>Go to the samples subdirectory containing the sample (use the DOS shell
if you are running Windows).</li>
<li>Use the java executable to run the sample from the command line.</li>
-<li>Examine the application source files.</li>
+<li>Examine the application source and result files.</li>
</ol>
<p>For example, go to the SimpleTransform subdirectory and issue the
following command:</p>
<p><code>java SimpleTransform</code></p>
@@ -54,11 +54,14 @@
<p>You can start by using your own XML source files and XSL stylesheets with
the sample applications, which illustrate a number of the <link
idref="usagepatterns">basic usage patterns</link>.</p>
<p>Here is the basic TRaX procedure to keep in mind when you set up a
transformation:</p>
<ol>
-<li>Use org.apache.trax.Processor.newInstance("xslt") to instantiate a
stylesheet processor -- a TRaX <jump
href="apidocs/org/apache/trax/Processor.html">Processor</jump> object
implemented by the Xalan <jump
href="apidocs/org/apache/xalan/processor/StylesheetProcessor.html">StylesheetProcessor</jump>.<br/><br/></li>
-<li>Use the Processor process() or processFromNode() method to process the
stylesheet (a SAX InputSource or DOM Node) and generate a Templates object -- a
TRaX <jump href="apidocs/org/apache/trax/Templates.html">Templates</jump>
object implemented by the Xalan <jump
href="apidocs/org/apache/xalan/processor/StylesheetRoot.html">StylesheetRoot</jump><br/><br/></li>
-<li>Use the Templates newTransformer() method to instantiate a Transformer
-- a TRaX
-<jump href="apidocs/org/apache/trax/Transformer.html">Transformer</jump>
object implemented by the Xalan <jump
href="apidocs/org/apache/xalan/transformer/TransformerImpl.html">TransformerImpl</jump>.<br/><br/></li>
-<li>Use one of the Transformer transform() or transformNode() methods to
apply the Templates object to an XML document (a SAX InputSource or DOM Node)
and perform the transformation, placing the output in a TRaX <jump
href="apidocs/org/apache/trax/Result.html">Result</jump> object.</li>
+<li>Use the TransformerFactory static newInstance() method to instantiate a
<jump
href="apidocs/javax/xml/transform/TransformerFactory.html"></jump>.<br/><br/></li>
+<li>Use the TransformerFactory newTransformer(Source stylesheet) method to
process the transformation instructions in an XSLT stylesheet (producing under
the covers a <jump
href="apidocs/javax/xml/transform/Templates.html"></jump>Templates object) and
generate a <jump
href="apidocs/javax/xml/transform/Transformer.html">Transformer</jump>.<br/><br/></li>
+<li>Use the Transformer transform(Source xmlSource, Result transformResult)
method to apply the transformation instructions (the Template object) to the
XML Source and produce the transformation Result.<br/><br/></li>
+</ol>
+<p>A couple of alternatives:</p>
+<ol>
+<li>If you want to apply the same transformation instructions to a number of
XML sources, use the TransformerFactory newTemplates(Source stylesheet) method
to process the stylesheet and explicitly produce a Templates object, which you
can then use repeatedly and even in concurrently running threads to generate a
Transformer and perform a transformation.<br/><br/></li>
+<li>If you are processing SAX input, cast the TransformerFactory object you
instantiate to <jump
href="apidocs/javax/xml/transform/sax/SAXTransformerer.html">SAXTransformerFactory</jump>,
which provides access to SAX ContentHandlers for producing Templates objects
and Transformers.</li>
</ol>
<p>For more information about this procedure and its variations, see <link
idref="usagepatterns">Basic Usage Patterns</link>.</p>
</s2>
1.4 +2 -3 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- index.xml 2000/10/16 21:56:58 1.3
+++ index.xml 2000/11/21 17:40:57 1.4
@@ -73,9 +73,8 @@
<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 the first release of &xslt4j2;. It is an alpha
Developer's release. 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 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>
</s2>
<s2 title="How do I get it?">
<p>Download and unzip either of the following:</p>
1.4 +2 -0 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- resources.xml 2000/10/19 20:14:50 1.3
+++ resources.xml 2000/11/21 17:40:58 1.4
@@ -54,6 +54,8 @@
<resource id="trax"
title="TRaX (Transformations for XML)"
location="apidocs/org/apache/trax/package-summary.html#package_description"/>
+
+
<resource id="dom"
title="DOM"
location="http://www.w3.org/DOM"/>
1.15 +23 -21 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.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- usagepatterns.xml 2000/11/02 13:26:56 1.14
+++ usagepatterns.xml 2000/11/21 17:40:58 1.15
@@ -75,36 +75,37 @@
<anchor name="basic"/>
<s2 title="Basic steps">
<ol>
- <li><link anchor="processor">Instantiate stylesheet Processor</link></li>
- <li><link anchor="process">Process stylesheet</link></li>
- <li><link anchor="transformer">Instantiate Transformer</link></li>
- <li><link anchor="transformation">Perform transformation</link></li>
+ <li><link anchor="transformerfactory">Instantiate a
TransformerFactory</link></li>
+ <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>
- <source>// 1. Instantiate a stylesheet Processor.
-org.apache.trax.Processor processor =
- org.apache.trax.Processor.newInstance("xslt");
+ <source>// 1. Instantiate a TransformerFactory.
+javax.xml.transform.TransformerFactory tFactory =
+ javax.xml.transformerTransformerFactory.newInstance();
-// 2. Process the stylesheet, producing a Templates object.
-org.apache.trax.Templates templates = processor.process
- (new org.xml.sax.InputSource("foo.xsl"));
+// 2. Use the TransformerFactory to process the stylesheet Source and
+// generate a Transformer.
+javax.xml.transform.Transformer transformer = tFactory.newTransformer
+ (new javax.xml.transform.stream.StreamSource("foo.xsl");
-// 3. Use the Templates object to instantiate a Transformer.
-org.apache.trax.Transformer transformer = templates.newTransformer();
-
// 4. Use the Transformer to apply the Templates object to an XML
-// source and send the output to a Result object.
+// Source and send the output to a Result object.
transformer.transform
- ( new org.xml.sax.InputSource("foo.xml"),
- new org.apache.trax.Result(new java.io.FileOutputStream("foo.out"))
);</source>
+ (new javax.xml.transform.stream.StreamSource("foo.xml"),
+ new javax.xml.transform.stream.StreamResult( new
+
java.io.FileOutputStream("foo.out")));</source>
<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 stylesheet Processor">
- <p>The org.apache.trax.Processor static newInstance() method with "xslt"
as its argument instantiates the processor designated by the
org.apache.trax.processor.xslt system property.</p>
- <p>If this system property has not already been set (from the command line
or in your application), org.apache.trax.Processor sets it from
org/apache/trax/trax.properties (in xalan.jar).</p>
- <p>For &xslt4j;, this system property should be set to
org.apache.xalan.processor.StylesheetProcessor.</p>
+ <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. Process the stylesheet, producing a Templates object">
+ <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>
@@ -113,6 +114,7 @@
<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>
</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>
1.13 +2 -2 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.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- whatsnew.xml 2000/10/17 12:54:58 1.12
+++ whatsnew.xml 2000/11/21 17:40:59 1.13
@@ -64,8 +64,8 @@
<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. 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 Processor to
process transformation instructions (the stylesheet), producing a Templates
object. Use the Templates object to instantiate a Transformer, with which you
can apply the Templates object to XML input, producing a result tree. For more
detail, see <link idref="usagepatterns" anchor="basic">Basic steps</link>.</p>
+<p>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"/>
