| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| <html> |
| <head> |
| <title>ASF: Command line options for XSLTC</title> |
| <meta http-equiv="content-type" content="text/html; charset=UTF-8" /> |
| <meta http-equiv="Content-Style-Type" content="text/css" /> |
| <link rel="stylesheet" type="text/css" href="resources/apache-xalan.css" /> |
| </head> |
| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| --> |
| <body> |
| <div id="title"> |
| <table class="HdrTitle"> |
| <tbody> |
| <tr> |
| <th rowspan="2"> |
| <a href="../index.html"> |
| <img alt="Trademark Logo" src="resources/XalanJ-Logo-tm.png" width="190" height="90" /> |
| </a> |
| </th> |
| <th text-align="center" width="75%"> |
| <a href="index.html">Xalan XSL Transformer User's Guide</a> |
| </th> |
| </tr> |
| <tr> |
| <td valign="middle">Command line options for XSLTC</td> |
| </tr> |
| </tbody> |
| </table> |
| <table class="HdrButtons" align="center" border="1"> |
| <tbody> |
| <tr> |
| <td> |
| <a href="http://www.apache.org">Apache Foundation</a> |
| </td> |
| <td> |
| <a href="http://xalan.apache.org">Xalan Project</a> |
| </td> |
| <td> |
| <a href="http://xerces.apache.org">Xerces Project</a> |
| </td> |
| <td> |
| <a href="http://www.w3.org/TR">Web Consortium</a> |
| </td> |
| <td> |
| <a href="http://www.oasis-open.org/standards">Oasis Open</a> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div id="navLeft"> |
| <ul> |
| <li> |
| <a href="resources.html">Resources</a> |
| <br /> |
| </li> |
| <li> |
| <a href="http://xalan.apache.org/index.html">Home</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="index.html">Xalan-J 2.7.2</a> |
| </li> |
| <li> |
| <a href="charter.html">Charter</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="whatsnew.html">What's New</a> |
| </li> |
| <li> |
| <a href="readme.html">Release Notes</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="overview.html">Overview</a> |
| </li> |
| <li> |
| <a href="downloads.html">Download/Build</a> |
| </li> |
| <li> |
| <a href="getstarted.html">Getting Started</a> |
| </li> |
| <li> |
| <a href="xsltc_usage.html">Using XSLTC</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="faq.html">FAQs</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="samples.html">Sample Apps</a> |
| </li> |
| <li> |
| <a href="commandline.html">Command Line</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="features.html">Features</a> |
| </li> |
| <li> |
| <a href="trax.html">Transform API</a> |
| </li> |
| <li> |
| <a href="xpath_apis.html">XPath API</a> |
| </li> |
| <li> |
| <a href="usagepatterns.html">Usage Patterns</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="apidocs/index.html">Xalan-J API</a> |
| </li> |
| <li> |
| <a href="public_apis.html">Public APIs</a> |
| </li> |
| <li> |
| <a href="dtm.html">DTM</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="extensions.html">Extensions</a> |
| </li> |
| <li> |
| <a href="extensionslib.html">Extensions Library</a> |
| </li> |
| <li> |
| <a href="extensions_xsltc.html">XSLTC Exts</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="design/design2_0_0.html">Xalan 2 Design</a> |
| </li> |
| <li> |
| <a href="xsltc/index.html">XSLTC Design</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="builds.html">Building a release</a> |
| </li> |
| <li> |
| <a href="http://xml.apache.org/xalan-j/test/overview.html">Testing</a> |
| </li> |
| <li> |
| <a href="bugreporting.html">Bug Reporting</a> |
| </li></ul><hr /><ul> |
| <li> |
| <a href="contact_us.html">Contact us</a> |
| </li> |
| </ul> |
| </div> |
| <div id="content"> |
| <h2>Command line options for XSLTC</h2> |
| <ul> |
| <li> |
| <a href="#options">Options</a> |
| </li> |
| <li> |
| <a href="#examples">Examples</a> |
| </li> |
| <li> |
| <a href="#faq">Simple FAQs</a> |
| </li> |
| <li> |
| <a href="#trax">Using options from the JAXP transform APIs</a> |
| </li> |
| </ul> |
| |
| <a name="options"></a> |
| <p align="right" size="2"> |
| <a href="#content">(top)</a> |
| </p> |
| <h3>Options</h3> |
| <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.</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 Xalan-Java Interpretive, 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> |
| <table class="note"> |
| <tr> |
| <td class="noteImg"> |
| <img src="resources/note.gif" alt="note" /> |
| </td> |
| <td class="noteTxt">The translet name is the same as the name of the Java class that |
| implements the translet. If the name specified by the <code>-XO</code> option |
| or derived from the URL for the stylesheet contains characters that are not |
| permitted in a Java class name, any such character will be replaced with an |
| underscore. For example, if the translet name specified by the <code>-XO</code> |
| option is <code>my-stylesheet</code>, or if the URL of the stylesheet is |
| <code>http://example.org/my-stylesheet.xsl</code>, the translet will actually |
| be named<code>my_stylesheet</code>. |
| </td> |
| </tr> |
| </table> |
| |
| |
| <a name="examples"></a> |
| <p align="right" size="2"> |
| <a href="#content">(top)</a> |
| </p> |
| <h3>Examples</h3> |
| |
| <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> |
| |
| |
| <a name="faq"></a> |
| <p align="right" size="2"> |
| <a href="#content">(top)</a> |
| </p> |
| <h3>Simple FAQs</h3> |
| |
| <p> |
| <b>Q:</b> 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> |
| <b>A:</b> 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> |
| <b>Q:</b> I want to use a translet for transformation, and I don't have the stylesheet.</p> |
| <p> |
| <b>A:</b> 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> |
| <b>Q:</b> I only want to compile the stylesheet. I don't want to do a transformation.</p> |
| <p> |
| <b>A:</b> JAXP 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> |
| |
| |
| <a name="trax"></a> |
| <p align="right" size="2"> |
| <a href="#content">(top)</a> |
| </p> |
| <h3>Using options from the JAXP transform APIs</h3> |
| <p>You can use some of the attributes in the <code>TransformerFactoryImpl</code> class of XSLTC to |
| customize the translet behaviors from JAXP.</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 border="1"> |
| <tr> |
| <td class="content" rowspan="1" colspan="1"> |
| <b>Attributes</b> |
| </td> |
| <td class="content" rowspan="1" colspan="1"> |
| <b>Process command line options</b> |
| </td> |
| <td class="content" rowspan="1" colspan="1"> |
| <b>Default values</b> |
| </td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">translet-name</td> |
| <td class="content" rowspan="1" colspan="1">-XO</td> |
| <td class="content" rowspan="1" colspan="1">GregorSamsa</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">destination-directory</td> |
| <td class="content" rowspan="1" colspan="1">-XD</td> |
| <td class="content" rowspan="1" colspan="1">null</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">package-name</td> |
| <td class="content" rowspan="1" colspan="1">-XP</td> |
| <td class="content" rowspan="1" colspan="1">null</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">jar-name</td> |
| <td class="content" rowspan="1" colspan="1">-XJ</td> |
| <td class="content" rowspan="1" colspan="1">null</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">generate-translet</td> |
| <td class="content" rowspan="1" colspan="1" /> |
| <td class="content" rowspan="1" colspan="1">false</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">auto-translet</td> |
| <td class="content" rowspan="1" colspan="1">-XT</td> |
| <td class="content" rowspan="1" colspan="1">false</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">use-classpath</td> |
| <td class="content" rowspan="1" colspan="1" /> |
| <td class="content" rowspan="1" colspan="1">false</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">enable-inlining</td> |
| <td class="content" rowspan="1" colspan="1">-XN</td> |
| <td class="content" rowspan="1" colspan="1">false</td> |
| </tr> |
| <tr> |
| <td class="content" rowspan="1" colspan="1">debug</td> |
| <td class="content" rowspan="1" colspan="1">-XX</td> |
| <td class="content" rowspan="1" colspan="1">false</td> |
| </tr> |
| </table> |
| |
| <p>You can set the attributes using the JAXP 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 JAXP is |
| equivalent to using the <code>-XO</code> option without the optional translet name from the Process command line.</p> |
| |
| <p>If the <code>use-classpath</code> attribute is set to <code>true</code>, the translet will be loaded |
| from the <code>CLASSPATH</code>. This attribute is typically used in a case when the translets are packaged in a |
| prebuilt jar file which is included in the <code>CLASSPATH</code>. You can set the <code>translet-name</code> attribute |
| to indicate which translet to use. If this attribute is not set, the name of the translet is taken from |
| the base name of the stylesheet. The <code>jar-name</code> attribute is not used in this situation.</p> |
| |
| <p>The following example shows you how to do the same thing from JAXP for the question 2 in the FAQ.</p> |
| |
| <blockquote class="source"> |
| <pre> |
| // 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()); |
| </pre> |
| </blockquote> |
| |
| <p align="right" size="2"> |
| <a href="#content">(top)</a> |
| </p> |
| </div> |
| <div id="footer">Copyright © 1999-2014 The Apache Software Foundation<br />Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation<div class="small">Web Page created on - Thu 2014-05-15</div> |
| </div> |
| </body> |
| </html> |
