| <?xml version="1.0" standalone="no"?> |
| <!DOCTYPE s1 SYSTEM "../../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 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 <jar_name></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>> <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>> <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>> <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>> <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>> <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>> <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> |