<?xml version="1.0" encoding="ISO-8859-1" 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=ISO-8859-1" /> | |
<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="../index.html">Home</a> | |
</li></ul><hr /><ul> | |
<li> | |
<a href="index.html">Xalan-J 2.7.1</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-2012 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 - Sun 03/18/2012</div> | |
</div> | |
</body> | |
</html> |