xdocs/sources/xalan/getstarted.xml - xalan-j - Git at Google

 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
 <!--
  * The Apache Software License, Version 1.1
  *
  *
  * Copyright (c) 1999-2003 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="Getting Started">
 <ul>
   <li><link anchor="classpath">Setting up the system classpath</link></li>
   <li><link anchor="samples">Trying out the samples</link></li>
   <li><link anchor="commandline">Performing your own transformations from the command line</link></li>
   <li><link anchor="java-apps">Setting up your own XSLT applications</link></li>
 </ul>
 <note>Unless otherwise specified, the usage discussed in this section refers to
 the &xslt4j; Interpretive processor. See <link idref="xsltc_usage">Getting Started with XSLTC
 </link> for information on using the &xslt4j; Compiling processor.</note><br></br>
 <anchor name="classpath"/>
 <s2 title="Setting up the system classpath">
   <p>At the very minimum, you must include xalan.jar, xml-apis.jar, and &xml4j-jar; -- or another
      conformant XML parser -- see <link idref="usagepatterns" anchor="plug">Plugging in a Transformer
      and XML parser</link>) on the system classpath. To run the XSLT Interpretive processor sample
      applications, include xalansamples.jar (all samples other than the servlet) and xalanservlet.jar.
      To run Javascript extensions, include bsf.jar. All these JAR files are distributed with &xslt4j;. For
      extensions implemented in other scripting language, see <link idref="extensions"
      anchor="supported-lang"> extensions language requirements</link> to identify any additional JAR
      files you must place on the classpath and where you can get them.</p>

   <p>If you are using <link idref="xsltc_usage">XSLTC</link>, see <link idref="xsltc_usage">
      Getting Starting with XSLTC</link>.</p>

   <p>If you are using JDK or JRE 1.2.2, 1.3.x or 1.4.x, include tools.jar on the classpath.  If you
      are using JDK or JRE 1.1.8 (supported for runtime only), then include classes.zip on the
      classpath.</p>
 </s2>

 <anchor name="samples"/>
 <s2 title="Trying out the samples">
   <p>The &xslt4j; distribution includes a number of basic sample applications. These samples are easy
      to run, and you can review the source files -- all of which are brief -- to see just how they
      work.</p>
   <p>To run the samples, do the following:</p>
   <ol>
     <li>Set up your classpath (see above), including xalansamples.jar and (for the servlet)
         xalanservlet.jar.</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>Use the java executable to run the sample from the command line.</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>
   <p>The sample writes the transformation result  to a file (birds.out). To see how the example works,
      examine the source files: birds.xml, birds.xsl, and SimpleTransform.java.</p>
   <p>The extensions examples require additional JAR files on the classpath, and the procedure for
      running the sample applet and sample servlet is different. For more information about all the
      samples, see <link idref="samples">&xslt4j; Samples</link>.</p>
 </s2>

 <anchor name="commandline"/>
 <s2 title="Performing your own transformations from the command line">
   <p>java.org.apache.xalan.xslt.Process provides a basic utility for performing transformations from
      the command line. You use this utility, for example, to run several of the extensions samples.
      The command line for most standard transformations is as follows:</p>
   <p><code>java org.apache.xalan.xslt.Process -in <ref>xmlSource</ref></code><br/>
      <code>&nbsp;&nbsp;&nbsp;&nbsp;-xsl <ref>stylesheet</ref> -out <ref>outputfile</ref></code></p>
   <p>where <ref>xmlSource</ref> is the XML source file name, <ref>stylesheet</ref> is the XSL
      stylesheet file name, and <ref>outputfile</ref> is the output file name.</p>
   <p>If you want the output to be displayed on the screen, simply omit the -out flag and argument.</p>
   <p>You can use this utility to try out XSL stylesheets you have written, to make sure they do what
      you expect with the XML source files they are designed to transform. The utility provides useful
      messages if the source file or stylesheet is not well formed. For more information, see
      <link idref="commandline">Command-Line Utility</link>.</p>
 </s2>

 <anchor name="java-apps"/>
 <s2 title="Setting up your own Java applications">
   <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 the <jump href="apidocs/javax/xml/transform/TransformerFactory.html">TransformerFactory</jump> static newInstance() method to instantiate a TransformerFactory.<br/><br/></li>
     <li>Use the TransformerFactory newTransformer(Source stylesheet) method to process the
         transformation instructions in an XSLT stylesheet Source (producing under the covers a
         <jump href="apidocs/javax/xml/transform/Templates.html">Templates</jump> 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 Templates object) to the XML Source and produce the
         transformation Result.<br/><br/></li>
   </ol>
   <p>For more information about this procedure and its variations, see <link idref="usagepatterns">Basic
      Usage Patterns</link>.</p>
 </s2>
 </s1>
	<?xml version="1.0" standalone="no"?>
	<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
	<!--
	* The Apache Software License, Version 1.1
	*
	*
	* Copyright (c) 1999-2003 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="Getting Started">
	<ul>
	<li><link anchor="classpath">Setting up the system classpath</link></li>
	<li><link anchor="samples">Trying out the samples</link></li>
	<li><link anchor="commandline">Performing your own transformations from the command line</link></li>
	<li><link anchor="java-apps">Setting up your own XSLT applications</link></li>
	</ul>
	<note>Unless otherwise specified, the usage discussed in this section refers to
	the &xslt4j; Interpretive processor. See <link idref="xsltc_usage">Getting Started with XSLTC
	</link> for information on using the &xslt4j; Compiling processor.</note><br></br>
	<anchor name="classpath"/>
	<s2 title="Setting up the system classpath">
	<p>At the very minimum, you must include xalan.jar, xml-apis.jar, and &xml4j-jar; -- or another
	conformant XML parser -- see <link idref="usagepatterns" anchor="plug">Plugging in a Transformer
	and XML parser</link>) on the system classpath. To run the XSLT Interpretive processor sample
	applications, include xalansamples.jar (all samples other than the servlet) and xalanservlet.jar.
	To run Javascript extensions, include bsf.jar. All these JAR files are distributed with &xslt4j;. For
	extensions implemented in other scripting language, see <link idref="extensions"
	anchor="supported-lang"> extensions language requirements</link> to identify any additional JAR
	files you must place on the classpath and where you can get them.</p>

	<p>If you are using <link idref="xsltc_usage">XSLTC</link>, see <link idref="xsltc_usage">
	Getting Starting with XSLTC</link>.</p>

	<p>If you are using JDK or JRE 1.2.2, 1.3.x or 1.4.x, include tools.jar on the classpath. If you
	are using JDK or JRE 1.1.8 (supported for runtime only), then include classes.zip on the
	classpath.</p>
	</s2>

	<anchor name="samples"/>
	<s2 title="Trying out the samples">
	<p>The &xslt4j; distribution includes a number of basic sample applications. These samples are easy
	to run, and you can review the source files -- all of which are brief -- to see just how they
	work.</p>
	<p>To run the samples, do the following:</p>
	<ol>
	<li>Set up your classpath (see above), including xalansamples.jar and (for the servlet)
	xalanservlet.jar.</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>Use the java executable to run the sample from the command line.</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>
	<p>The sample writes the transformation result to a file (birds.out). To see how the example works,
	examine the source files: birds.xml, birds.xsl, and SimpleTransform.java.</p>
	<p>The extensions examples require additional JAR files on the classpath, and the procedure for
	running the sample applet and sample servlet is different. For more information about all the
	samples, see <link idref="samples">&xslt4j; Samples</link>.</p>
	</s2>

	<anchor name="commandline"/>
	<s2 title="Performing your own transformations from the command line">
	<p>java.org.apache.xalan.xslt.Process provides a basic utility for performing transformations from
	the command line. You use this utility, for example, to run several of the extensions samples.
	The command line for most standard transformations is as follows:</p>
	<p><code>java org.apache.xalan.xslt.Process -in <ref>xmlSource</ref></code><br/>
	<code>    -xsl <ref>stylesheet</ref> -out <ref>outputfile</ref></code></p>
	<p>where <ref>xmlSource</ref> is the XML source file name, <ref>stylesheet</ref> is the XSL
	stylesheet file name, and <ref>outputfile</ref> is the output file name.</p>
	<p>If you want the output to be displayed on the screen, simply omit the -out flag and argument.</p>
	<p>You can use this utility to try out XSL stylesheets you have written, to make sure they do what
	you expect with the XML source files they are designed to transform. The utility provides useful
	messages if the source file or stylesheet is not well formed. For more information, see
	<link idref="commandline">Command-Line Utility</link>.</p>
	</s2>

	<anchor name="java-apps"/>
	<s2 title="Setting up your own Java applications">
	<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 the <jump href="apidocs/javax/xml/transform/TransformerFactory.html">TransformerFactory</jump> static newInstance() method to instantiate a TransformerFactory.<br/><br/></li>
	<li>Use the TransformerFactory newTransformer(Source stylesheet) method to process the
	transformation instructions in an XSLT stylesheet Source (producing under the covers a
	<jump href="apidocs/javax/xml/transform/Templates.html">Templates</jump> 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 Templates object) to the XML Source and produce the
	transformation Result.<br/><br/></li>
	</ol>
	<p>For more information about this procedure and its variations, see <link idref="usagepatterns">Basic
	Usage Patterns</link>.</p>
	</s2>
	</s1>