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/08/28 23:01:48 UTC
cvs commit: xml-xalan/java/xdocs/sources/xalan commandline.xml samples.xml whatsnew.xml
dleslie 00/08/28 14:01:47
Modified: java/xdocs/sources xalan-jlocal.xml
java/xdocs/sources/xalan whatsnew.xml
Added: java/xdocs/sources/xalan commandline.xml samples.xml
Log:
partial 1st drafts
Revision Changes Path
1.2 +5 -1 xml-xalan/java/xdocs/sources/xalan-jlocal.xml
Index: xalan-jlocal.xml
===================================================================
RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan-jlocal.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- xalan-jlocal.xml 2000/08/28 18:16:14 1.1
+++ xalan-jlocal.xml 2000/08/28 21:01:37 1.2
@@ -68,11 +68,15 @@
label="Sample Apps"
source="xalan/samples.xml"/>
+ <document id="commandline"
+ label="Command Line"
+ source="xalan/commandline.xml"/>
+
<separator/>
<external href="apidocs/index.html" label="API (Javadoc)"/>
<separator/>
- <external href="http://xml.apache.org/bugs/" label="Bug reporting"/>
+<external href="http://xml.apache.org/xalan/design/design2_0_0.html" label="Xalan 2 Design"/>
</book>
1.2 +12 -10 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- whatsnew.xml 2000/08/28 18:15:35 1.1
+++ whatsnew.xml 2000/08/28 21:01:44 1.2
@@ -58,16 +58,18 @@
-->
<s1 title="What's new in &xslt4j2;">
<ul>
-<li><link anchor="design">New Design</link></li>
-<li><link anchor="basic">Basic 4 steps</link></li>
-<li><link anchor="processor">1. Instantiate stylesheet Processor</link></li>
-<li><link anchor="process">2. Process stylesheet</link></li>
-<li><link anchor="transformer">3. Instantiate Transformer</link></li>
-<li><link anchor="transformation">4. Perform transformation</link></li>
-<li><link anchor="modules">Modularity</link></li>
-<li><link anchor="sax">SAX</link></li>
-<li><link anchor="params">Setting stylesheet parameters</link></li>
-<li><link anchor="dom">DOM</link></li>
+ <li><link anchor="design">New Design</link></li>
+ <li><link anchor="basic">Basic 4 steps</link></li>
+ <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>
+ </ol>
+ <li><link anchor="modules">Modularity</link></li>
+ <li><link anchor="sax">SAX</link></li>
+ <li><link anchor="params">Setting stylesheet parameters</link></li>
+ <li><link anchor="dom">DOM</link></li>
</ul><anchor name="design"/>
<s2 title="New Design">
<p>&xslt4j2; represents a fundamental redesign of Xalan. It differs from &xslt4j; 1 in the following basic ways:</p>
1.1 xml-xalan/java/xdocs/sources/xalan/commandline.xml
Index: commandline.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<s1 title="Command-Line Utility">
<s2 title="Using the Command-Line Utility">
<p>To perform a transformation, you can call &xslt4j; from the command line (or script),
an applet, an application, or a servlet (see <link idref="usagepatterns">Usage Patterns</link>).</p>
<p>The org.apache.xalan.xslt.Process main() method provides a command-line interface
for performing XSL transformation. To perform a transformation from the command line or a script,
do the following:</p>
<ol>
<li><link idref="getstarted" anchor="download">Download &xslt4j;</link>.<br/><br/></li>
<li><link idref="getstarted"
anchor="classpath">Set the java class path</link> to include xalan.jar and xerces.jar<br/><br/></li>
<li>Call java and the Process class with the appropriate flags and
arguments (described below). The following command line, for example, includes the -IN, -XSL,
and -OUT flags with their accompanying arguments -- the XML source document, the XSL
stylesheet, and the output file:<br/><br/>
<code>java org.apache.xalan.xslt.Process -IN foo.xml -XSL foo.xsl -OUT foo.out</code>
</li></ol>
<p>The command line utility can take the following flags and arguments (the flags are case insensitive):</p>
<source>-IN inputXMLURL
-XSL XSLTransformationURL
-OUT outputFileName
-LXCIN compiledStylesheetFileNameIn
-LXCOUT compiledStylesheetFileNameOut
-PARSER fully qualified class name of parser liaison
-V (Version info)
-QC (Quiet Pattern Conflicts Warnings)
-Q (Quiet Mode)
-LF (Use linefeeds only on output -- default is CR/LF)
-CR (Use carriage returns only on output -- default is CR/LF)
-INDENT (Number of spaces to indent each level in output tree --default is 0)
-TT (Trace the templates as they are being called)
-TG (Trace each result tree generation event)
-TS (Trace each selection event)
-TTC (Trace the template children as they are being processed)
-VALIDATE (Validate the XML and XSL input -- validation is off by default)
-EDUMP [optional]FileName (Do stackdump on error)
-XML (Use XML formatter and add XML header)
-TEXT (Use simple Text formatter)
-HTML (Use HTML formatter)
-PARAM name expression (Set a stylesheet parameter)</source>
<p>Use -IN to specify the XML source document.</p>
<p>Use -XSL to specify the XSL stylesheet file.</p>
<p>Use -LXCIN to specify a compiled XSL stylesheet file.</p>
<p>Use -LXCOUT to compile an XSL stylesheet for future use as -LXCIN input.</p>
<note>You can only use -LXCIN with a compiled stylesheet that you have already created with the -LXOUT switch. For an
example, see <link anchor="compiledstylesheet">Using a compiled stylesheet</link></note>
<p>Include -PARSER if you supply your own parser liaison class, which is required if you do not use DTM or the
Xerces parser.</p>
<p>Use -TEXT 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
not well formed XML.</p>
<p>To set stylesheet parameters from the command line, use <br/>
<code>TestXSLT -PARAM <ref>name expression</ref></code><br/>
To set the parameter to a string value, enclose the string in single quotes (') to
make it an expression.</p>
<p><anchor name="compiledstylesheet"/><em>Using a compiled stylesheet</em></p>
<p>If you are using a stylesheet repeatedly, you can improve performance by compiling the stylesheet the first time
you use it and using the compiled stylesheet for subsequent transformations.</p>
<p>For example, the following command line performs a transformation and compiles the stylesheet:"<br/><br/>
<code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -lxcout foo.style</code><br/><br/>
The following command line uses the compiled stylesheet for the next transformation:<br/><br/>
<code>java org.apache.xalan.xslt.Process -in foo2.xml -lxcin foo.style</code></p>
</s2>
</s1>
1.1 xml-xalan/java/xdocs/sources/xalan/samples.xml
Index: samples.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!--
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xalan" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, Lotus
* Development Corporation., http://www.lotus.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="&xslt4j2; Samples">
<ul>
<li><link anchor="simpletransform">SimpleTransform</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="pipe">Pipe</link></li>
<li><link anchor="appletxmltohtml">AppletXMLtoHTML</link></li>
<li><link anchor="servlet">Servlet</link></li>
<li><link anchor="extensions">Extensions</link></li>
</ul>
<s2 title="Samples to help you get started">
<p>Each of the subdirectories in the &xslt4j; java/samples directory contains the source files for one or more
sample applications. The class files for the samples are in xalansamples.jar (everything except the servlet) and xalanservlet.jar, so to run the samples, you should place these JAR files on the system class path.</p>
<p>With most of the samples, you can use the following procedure:</p>
<ol>
<li>Be sure xalan.jar, xalansamples.jar (xalanservlet.jar for the servlet), and xerces.jar are on the system class
path. For the extension examples, bsf.jar, bsfengines.jar, and (for the JavaScript extensions) js.jar must also be on the class
path.</li>
<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>Run the sample from the command line (as indicated below)</li>
<li>Examine the application source files. You may also want to modify the source files. Remember that if you
modify a java file, you must recompile the class and place it on the class path before you can run the
modified application.</li>
</ol>
<p>The basic command line for running most of the samples is </p>
<p><code>java <ref>classname args</ref></code></p>
<p>where <ref>classname</ref> is the classname and <ref>args</ref> are the arguments, if any. As described in
the following sections, some samples take no arguments. The samples in UseStylesheetParam and xxx take
additional arguments. The samples in extensions use the &xslt4j; <link idref="commandline">command-line
utility</link>, so they take arguments for the XML source file and the XSL stylesheet.</p>
</s2><anchor name="simpletransform"/>
<s2 title="SimpleTransform">
<p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and prints the
output to System.out.</p>
<p>You can run it from the SimpleTransform subdirectory with</p>
<p><code>java SimpleTransform</code></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,
and prints the output to System.out. The stylesheet parameter appears as a text node in the output.</p>
<p>Run this sample from the UseStylesheetParam subdirectory with</p>
<p><code>java UseStylesheetParam <ref>param</ref></code></p>
<p>where <ref>param</ref> is the stylesheet parameter (a string of your choice).</p>
</s2><anchor name="sax2sax"/>
<s2 title="SAX2SAX">
<p>What it does: Explicitly set the SAX XMLReader and SAX ContentHandler for processing the stylesheet, processing the XML input, and producing the output.</p>
<p>Run this sample from the Pipe subdirectory with</p>
<p><code>java SAX2SAX</code></p>
</s2><anchor name="pipe"/>
<s2 title="Pipe">
<p>What it does: Chains together a series of 3 transformations by piping SAX events from one Transformer to
another. Each Transformer operates as a SAX2 XMLFilter/XMLReader.</p>
<p>Run this sample from the Pipe subdirectory with</p>
<p><code>java Pipe</code></p>
</s2><anchor name="appletxmltohtml"/>
<s2 title="AppletXMLtoHTML">
<p>The applet uses a stylesheet to transform an XML document into HTML. It displays the XML document, the
stylesheet, and the HTML output.</p>
<p>How to run it: See <jump href="../samples/appletXMLtoHTML/readme.html">sample applet readme</jump>.</p>
</s2><anchor name="servlet"/>
<s2 title="Servlet">
<p>What it does: The client (which you must set up) specifies an XML document and a stylesheet. The servlet
performs the transformation and returns the output to the client. You can use media.properties to specify
which stylesheet is to be used depending on the client browser/device.</p>
<p>How to run it:</p>
<ol>
<li>Configure your application server (Websphere or JServ, for example) so it can find the classes (in
xalanservlet.jar) as well as the stylesheets and properties file in the servlet subdirectory.</li>
<li>Set up an HTML client to call DefaultApplyXSL with arguments as illustrated below.</li>
</ol>
</s2><anchor name="extensions"/>
<s2 title="Extensions">
<ul>
<li><link anchor="ext1">SimpleRedirect</link></li>
<li><link anchor="ext2">2-basicJscript</link></li>
<li><link anchor="ext3">3-java-namespace</link></li>
<li><link anchor="ext4">4-numlistJava</link></li>
<li><link anchor="ext5">5-numlistJScript</link></li>
</ul>
<p>The extensions subdirectory contains 5 samples with &xslt4j; extensions. Two of the samples use
extensions implemented in JavaScript, and thre of the samples use extensions implemented in Java.</p>
<p>To run these examples, you must place bsf.jar and bsfengines.jar (distributed with &xslt4j;), and js.jar
(version 1.4 release 3, available from
<jump href="http://www.mozilla.org/rhino">http://www.mozilla.org/rhino</jump>) on the class path.
You do not need js.jar on the class path for the samples that use Java extensions. </p>
<p>Use java.org.apache.xalan.xslt.Process, the &xslt4j; command-line utility, to run most of these samples from
the <link idref="commandline">command line</link>. The command line must include an -in flag with the
XML source and an -xsl flag with the XSL stylesheet. If you want the output to be written to a file, rather
than to the screen, add an -out flag with the output file name.</p>
<p>Run these samples from the extensions directory as follows (each of the following is a single command
line):</p>
<anchor name="ext1"/>
<s3 title="SimpleRedirect">
<p>What it does: Uses the Redirect extension elements shipped with &xslt4j; to direct output to two output
files.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java SimpleRedirect</code></p>
</s3><anchor name="ext2"/>
<s3 title="2-basicJscript">
<p>What it does: Uses an extension element and extension function implemented in Javascript.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in 2-basicJscript.xml</code>
<br/> <code>-xsl 2-jbasicJscript.xsl</code></p>
</s3><anchor name="ext3"/>
<s3 title="3-java-namespace">
<p>What it does: Uses extension functions to format dates. This sample illustrates use of the predefined java
extension namespace to provide ready access to extensions implemented in Java.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in 3-java-namespace.xml</code>
<br/> <code>3-java-namespace.xsl</code></p>
</s3><anchor name="ext4"/>
<s3 title="4-numlistJava">
<p>What it does: Uses a Java extension to transform a set of name elements into an alphabetical and numbered
list.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code>java org.apache.xalan.xslt.Process -in 4-numlistJava.xml</code>
<br/> <code>-xsl 4-numlistJava.xsl</code></p>
</s3><anchor name="ext5"/>
<s3 title="5-numlistJscript">
<p>What it does: Uses a Javascript extension to transform a set of name elements into an alphabetical and
numbered list. This sample performs the same operations as the preceding Java extension.</p>
<p>Run this sample from the extensions subdirectory with</p>
<p><code> java org.apache.xalan.xslt.Process -in 5-numlistJscript.xml </code>
<br/> <code>-xsl 5-numlistJscript.xsl</code></p>
</s3>
</s2>
</s1>