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/11/21 18:41:03 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan getstarted.xml index.xml resources.xml usagepatterns.xml whatsnew.xml
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"/>