xdocs/sources/xalan/commandline_xsltc.xml

<?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="Command line options for XSLTC">
<ul>
<li><link anchor="options">Options</link></li>
<li><link anchor="examples">Examples</link></li>
<li><link anchor="faq">Simple FAQs</link></li>
<li><link anchor="trax">Using the new options from TrAX</link></li>
</ul>
   
<anchor name="options"/>
<s2 title="Options">
<p>The <code>org.apache.xalan.xslt.Process</code> command line now supports XSLTC for transformation. You can use 
the new <code>-XSLTC</code> option to enable the XSLTC support. The xsltc.jar file must be on your CLASSPATH 
in order to use the <code>-XSLTC</code> option.</p>
<p>The following existing options can be used with -XSLTC:</p>
<p><code>-IN, -XSL, -OUT, -V, -EDUMP, -XML, -TEXT, -HTML, -PARAM, <br/>
-MEDIA, -FLAVOR, -DIAG, -URIRESOLVER, -ENTITYRESOLVER,<br/>
-CONTENTHANDLER</code></p>

<p>The following existing options do not work with <code>-XSLTC</code>. If any of them is used with <code>-XSLTC</code>, 
a message is printed and the option is ignored.</p>
<p><code>-QC, -TT, -TG, -TS, -TTC, -TCLASS, -L, -INCREMENTAL, <br/>
-NOOPTIMIMIZE, -RL</code></p>

<p>We also have a new set of options for <code>-XSLTC</code>. They are all two letter options. The first 
letter is X and the second letter is the same as the corresponding option in the XSLTC command line 
<code>org.apache.xalan.xsltc.cmdline.Compile</code>.</p>

<p>These new options can only be used with <code>-XSLTC</code>. If any of them is used with the Xalan 
interpreter, a message is printed and the option is ignored.</p>

<p>Here is the list of the new options:</p>
<ul>
  <li><code>-XO [optional translet_name]</code><br/>
  Assign the name to the generated translet. If the translet_name is omitted, the translet is 
  generated using the default name (same as the xsl).</li>
  <li><code>-XD destination_directory</code><br/>
  Specify a destination directory for translet. The generated translet classes will be put 
  under the specified destination directory.</li>
  <li><code>-XJ jar_name</code><br/>
  Package translet classes into a jar file of name &lt;jar_name&gt;</li>
  <li><code>-XP package_name</code><br/>
  Specify a package name prefix for all generated translet classes</li>
  <li><code>-XN</code><br/>
  Enable XSL template inlining into one big method</li>
  <li><code>-XX</code><br/>
  Turn on additional debugging message output</li>
  <li><code>-XT</code><br/>
  Use translet to transform if possible</li>
</ul>
</s2>

<anchor name="examples"/>
<s2 title="Examples">

<p>You can just add the <code>-XSLTC</code> option to your existing option list so that it will do the same 
thing as before, but using XSLTC.</p>

<p>Here is a simple example on how to use XSLTC:</p>
<p>&gt; <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc</code></p>
<p>XSLTC compiles the stylesheet on the fly and uses the bytecode in memory to transform the input xml. 
No translet class is generated in this simple usage pattern.</p>
<p>If you want to generate translet classes from the stylesheet, you can use the <code>-XO</code> option:</p>
<p>&gt; <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc -xo</code></p>

<p>This example still uses the stylesheet for transformation, but it also generates the 
translet class "test.class".</p>

<p>You can use the <code>-XJ, -XP</code> or <code>-XD</code> options to further customize the translet generation behavior. Translets 
will be generated if any of the options <code>-XO, -XJ</code> or <code>-XT</code> is used.</p>
<p>&gt; <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc -xo newTranslet -xd temp -xp org.apache.test -xj translets.jar</code></p>

<p>The above command line uses the xsl for transformation. It also generates translet classes in
the name of <code>newTranslet</code>, using a package prefix of <code>org.apache.test</code>, and packages the translets
into the jar file <code>translets.jar</code> under the <code>temp</code> directory.</p>

<p>All of the examples above use the stylesheet to do the transformation. If the translets are 
already generated, you can use the <code>-XT</code> option to specify that you want to use the existing translets for transformation. 
The <code>-XT</code> option has a makefile like feature in that it will compare the timestamps of the translet 
and the stylesheet. If the translet is newer, it is used for the transformation, otherwise the stylesheet is 
used and the translet is regenerated.</p>

<p>The translet is loaded from the specified destination directory or the current directory, using
the specified translet name or the xsl base name, depending on whether the <code>-XD</code> or 
<code>-XO</code> option is used. The options <code>-XO, -XD, -XP</code> and <code>-XJ</code>
can be used with the <code>-XT</code> option to tell XSLTC how to find the translet classes. The translets
are directly read in as bytecode. You do not need to add the translet directory or the jar file to your
classpath.</p>
<p>Example:</p>
<p>&gt; <code>java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc -xt -xj translets.jar -xd temp</code></p>

<p>This command line will search for the translet <code>test.class</code> inside the jar file <code>temp/translets.jar</code>. If it is 
found and newer than test.xsl, it is used for the transformation; otherwise the xsl is used and the
translet is generated and packaged in the same jar.</p>

<p>Here is how the makefile feature for the <code>-XT</code> option works:</p>
<ol>
  <li>If the xsl does not exist, use the translet</li>
  <li>If the translet does not exist, use the xsl and generate a new translet</li>
  <li>If both exist and the translet is newer, use the translet for transformation</li>
  <li>If both exist and the xsl is newer, use the xsl for transformation and regenerate the translet</li>
</ol>
</s2>

<anchor name="faq"/>
<s2 title="Simple FAQs">

<p><em>Q:</em> If I use the <code>-XT</code> option, how can I tell if it is using the translet or the stylesheet for transformation?</p>
<p><em>A:</em> Use the <code>-XX</code> option. When XSLTC uses the translet for transformation, you will see a debug 
message like "Tranform using translet ..." or "Tranform using translet ... from jar file ...".</p>

<p><em>Q:</em> I want to use a translet for transformation, and I don't have the stylesheet.</p>
<p><em>A:</em> Suppose the translet class is <code>c:\translets\myTranslet.class</code>, you can use the following command line:</p>
<p>&gt; <code>java org.apache.xalan.xslt.Process -in test.xml -xsltc -xt -xo myTranslet -xd c:\translets</code></p>
<p>If you use <code>-XT</code> option, the <code>-XSL</code> option can be omitted. You have to specify the translet name 
using the <code>-XO</code> option because there is no default translet name in this situation.</p>

<p><em>Q:</em> I only want to compile the stylesheet. I don't want to do a transformation.</p>
<p><em>A:</em> TrAX has no notion of compiling a stylesheet. However, you can achieve the same effect by 
running a dummy transformation and tell XSLTC to save the translet class. Example:</p>
<p>&gt; <code>java org.apache.xalan.xslt.Process -xsl test.xsl -xsltc <br/>-xo</code></p>
<p>This command runs a transformation on an empty input and generates the translet <code>test.class</code>.</p>
</s2>

<anchor name="trax"/>
<s2 title="Using the new options from TrAX">

<p>If you use the TrAX interface for XSLTC, you could not tell it to use translets before. It always compiled 
the xsl on the fly and used the bytecode in memory for transformation.  Now you can use some of 
the new attributes in XSLTC's <code>TransformerFactoryImpl</code> class to customize the translet behaviors from TrAX.</p>

<p>Here is the list of attributes in <code>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</code> and their 
corresponding Process command line options:</p>

<table>
  <tr>
    <td><em>Attributes</em></td>
    <td><em>Process command line options</em></td>
    <td><em>Default values</em></td>
  </tr>
  <tr>
    <td>translet-name</td>
    <td>-XO</td>
    <td>GregorSamsa</td>
  </tr>
  <tr>
    <td>destination-directory</td>
    <td>-XD</td>
    <td>null</td>
  </tr>
  <tr>
    <td>package-name</td>
    <td>-XP</td>
    <td>null</td>
  </tr>
  <tr>
    <td>jar-name</td>
    <td>-XJ</td>
    <td>null</td>
  </tr>
  <tr>
    <td>generate-translet</td>
    <td></td>
    <td>false</td>
  </tr>
  <tr>
    <td>auto-translet</td>
    <td>-XT</td>
    <td>false</td>
  </tr>
  <tr>
    <td>enable-inlining</td>
    <td>-XN</td>
    <td>false</td>
  </tr>
  <tr>
    <td>debug</td>
    <td>-XX</td>
    <td>false</td>
  </tr>
</table>

<p>You can set the attributes using the TrAX interface <code>TransformerFactory.setAttribute(String name, Object value)</code>. 
The four attributes <code>translet-name, destination-directory, package-name and jar-name</code> are transient. 
They only apply to the next <code>newTemplates()</code> or <code>newTransformer()</code> call. Their values are reset to 
the default after the call.</p>

<p>The <code>generate-translet</code> attribute does not have a corresponding command line option. This attribute is
implied when the <code>-XO</code> or <code>-XJ</code> option is used. The purpose is to make the command line
usage syntax a little bit simpler. Setting the <code>generate-attribute</code> attribute to true from TrAX is 
equivalent to using the <code>-XO</code> option without the optional translet name from the Process command line.</p>

<p>The following example shows you how to do the same thing from TrAX for the question 2 in the FAQ.</p>

<source>
// set the system property javax.xml.transform.TransformerFactory in order to use XSLTC
String key = "javax.xml.transform.TransformerFactory";
String value = "org.apache.xalan.xsltc.trax.TransformerFactoryImpl";
Properties props = System.getProperties();
props.put(key, value);
System.setProperties(props);

TransformerFactory tfactory = null;
try {
  tfactory = TransformerFactory.newInstance();
}
catch (TransformerFactoryConfigurationError pfe) { pfe.printStackTrace(); }

// set the translet name
tfactory.setAttribute("translet-name", "myTranslet");

// set the destination directory
tfactory.setAttribute("destination-directory", "c:\\translets");

// use the translet for transformation if possible
tfactory.setAttribute("auto-translet", "true");

// You can create a Templates object from an empty Source if the translet is specified.
Templates templates = tfactory.newTemplates(new StreamSource());
</source>
</s2>
</s1>