<?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: Getting Started with 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">Getting Started with 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>Using XSLTC<br /> | |
</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>Getting Started with XSLTC</h2> | |
<ul> | |
<li> | |
<a href="#intro">Introduction</a> | |
</li> | |
<li> | |
<a href="#classpath">Setting the system classpath for XSLTC</a> | |
</li> | |
<li> | |
<a href="#compile">Compiling translets from the command line</a> | |
</li> | |
<li> | |
<a href="#run">Running translets from the command line</a> | |
</li> | |
<li> | |
<a href="#api">Calling XSLTC with the JAXP API</a> | |
</li> | |
<li> | |
<a href="#xsltcsmart">Smart Transformer Switch</a> | |
</li> | |
<li> | |
<a href="#native_api">Calling XSLTC with the native API</a> | |
</li> | |
<li> | |
<a href="#constraints">Usage constraints</a> | |
</li> | |
<li> | |
<a href="samples.html#translets">Sample translets</a> | |
</li> | |
<li> | |
<a href="extensions_xsltc.html">Extensions for XSLTC</a> | |
</li> | |
</ul> | |
<p>See also: <a href="xsltc/index.html">XSLTC Design</a> | |
</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">Unless otherwise specified, the usage discussed in this section refers to | |
the Xalan-Java Compiling processor, XSLTC. See <a href="usagepatterns.html">Basic Usage | |
Patterns</a> for information on using the Xalan-Java Interpretive processor.</td> | |
</tr> | |
</table> | |
<br /> | |
<a name="intro"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Introduction</h3> | |
<p>XSLTC provides a compiler and a runtime processor. | |
Use the compiler to compile an XSL stylesheet into a translet (i.e., a set of | |
Java classes). Use the runtime processor to apply the translet to an XML | |
document and perform a transformation.</p> | |
<a name="classpath"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Setting the system classpath for XSLTC</h3> | |
<p>The xalan.jar contains support for both Xalan-Java processors. You | |
can use the JAXP <code>javax.xml.transform.TransformerFactory</code> property | |
(see <a href="#api">"Calling XSLTC with the JAXP API"</a> below) to | |
select which processor to use: the Interpretive or the Compiling processor.</p> | |
<p>To use XSLTC, simply put xalan.jar, serializer.jar, xml-apis.jar, and xercesImpl.jar on | |
your classpath.</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">To compile and run translets, you must use JDK (or JRE) 1.3.1 or higher.</td> | |
</tr> | |
</table> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">Although the XSLTC developers make every effort to avoid changes that | |
affect binary compatibility, we cannot guarantee that a translet will work with | |
any version of the run-time processor other than the one that corresponds to | |
the version of the XSLTC compiler that was used to create the translet.</td> | |
</tr> | |
</table> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Bundled System Classpath</h4> | |
<p> | |
To use this newer approach, simply put xalan.jar, serializer.jar, xml-apis.jar and | |
xercesImpl.jar in your classpath. There is no need to include xsltc.jar, BCEL.jar, JLex.jar, | |
regexp.jar, java_cup.jar or runtime.jar as required in previous releases. | |
</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">In order to compile and run translets you must have a JAXP 1.3 compliant XML | |
parser installed. Our distribution includes <a href="http://xerces.apache.org/xerces2-j/index.html">Xerces-Java @parser.version.VERSION@.@parser.version.RELEASE@.@parser.version.MINOR@</a>. | |
Include xercesImpl.jar and xml-apis.jar in your class path.</td> | |
</tr> | |
</table> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Unbundled System Classpath</h4> | |
<p>The binary distribution contains XSLTC and all its support classes bundled | |
into xalan.jar. To use the unbundled approach, rebuild | |
the xsltc.jar file using the xsltc.unbundledjar target. The support jars that | |
you'll need to add to your classpath are available in the Xalan Java lib | |
directory.</p> | |
<p>To compile translets, run translets, and use the XSLTC API, using | |
the unbundled jar approach, put the following on the system classpath:</p> | |
<table border="1"> | |
<tr> | |
<th class="content" rowspan="1" colspan="1">Classes or JAR</th> | |
<th class="content" rowspan="1" colspan="1">To compile a translet</th> | |
<th class="content" rowspan="1" colspan="1">To run a translet</th> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">the translet</td> | |
<td class="content" rowspan="1" colspan="1" /> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">xsltc.jar</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">runtime.jar</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">BCEL.jar</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
<td class="content" rowspan="1" colspan="1" /> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">JLex.jar</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
<td class="content" rowspan="1" colspan="1" /> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">java_cup.jar</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
<td class="content" rowspan="1" colspan="1" /> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">regexp.jar</td> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
<td class="content" rowspan="1" colspan="1" /> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">xml-dtm.jar</td> | |
<td class="content" rowspan="1" colspan="1" /> | |
<td class="content" rowspan="1" colspan="1">required</td> | |
</tr> | |
</table> | |
<p>The translet is the set of class files or the JAR file that you generate with | |
the compiler; see <a href="#compile">Compiling translets</a>.</p> | |
<a name="compile"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Compiling translets from the command line</h3> | |
<ul> | |
<li> | |
<a href="#comp-synopsis">Synopsis</a> | |
</li> | |
<li> | |
<a href="#comp-args">Flags and arguments</a> | |
</li> | |
<li> | |
<a href="#comp-examples">Examples</a> | |
</li> | |
</ul> | |
<p>The XSLT Compiler is a Java-based tool for compiling XSLT | |
stylesheets into lightweight and portable Java byte codes | |
called translets.</p> | |
<p>To run the compiler from the command line or from a script, | |
<a href="#classpath">set the classpath</a> and | |
run the class <code>org.apache.xalan.xsltc.cmdline.Compile</code>. The | |
synopsis of the options and arguments accepted by this class is shown below. | |
</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">You can also use the | |
<a href="commandline.html">Xalan-Java command-line utility</a>, to | |
compile or run XSLTC translets.</td> | |
</tr> | |
</table> | |
<a name="comp-synopsis"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Synopsis</h4> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Compile</code> | |
<br /> | |
<code> [-o <output>] [-d <directory>] [-j <jarfile>]</code> | |
<br /> | |
<code> [-p <package name>] [-n] [-x] [-v] [-u] [-h]<br /> | |
{<stylesheet> | -i }</code> | |
</p> | |
<a name="comp-args"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Flags and arguments</h4> | |
<p>The following flags and arguments are supported:</p> | |
<blockquote class="source"> | |
<pre>-o <output> | |
Specifies the name of the generated translet class. | |
If you omit this argument, the translet class is | |
named <stylesheet>. Translets are written as | |
.class files. | |
-d <directory> | |
Specifies the destination directory. If you omit | |
this argument, the translet class files are placed | |
in the current working directory. | |
-j <jarfile> | |
Outputs the generated translet class files into a | |
jar file named <jarfile>.jar. When this option is | |
used, only the jar file is output. | |
-p <package name> | |
Specifies a package name for the generated translet | |
classes. | |
-n Enables template inlining (default behavior better on average). | |
-x Turns on additional debugging messages. | |
-s Disables calling System.exit | |
-u <stylesheet> | |
Specifies the stylesheet with a URI such as | |
'http://myserver/stylesheet1.xsl'. | |
<stylesheet> | |
(No flag) The pathname of the stylesheet file. | |
-i Force stylesheet to be read from stdin | |
-v Prints version of compiler | |
-h Prints usage statement</pre> | |
</blockquote> | |
<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>-o</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>-o</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="comp-examples"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Examples</h4> | |
<p>The following examples assume that you have already set the | |
classpath to include the translet and the required JAR | |
files (see <a href="#classpath">setting the system classpath</a>).</p> | |
<p> | |
<b>Example 1:</b> Creating a translet from the hamlet.xsl | |
stylesheet.</p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Compile</code> | |
<br /> | |
<code> hamlet.xsl</code> | |
</p> | |
<p>Example 1 produces a set of class files such as hamlet.class, hamlet$0.class, hamlet$1.class.</p> | |
<p> | |
<b>Example 2:</b> Outputting to a JAR file.</p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Compile</code> | |
<br /> | |
<code> -j hamlet.jar hamlet.xsl</code> | |
</p> | |
<p>Example 2 produces hamlet.jar, which contains the translet class | |
files.</p> | |
<p> | |
<b>Example 3:</b> Specifying the translet class name. </p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Compile</code> | |
<br /> | |
<code> -o newhamlet hamlet.xsl</code> | |
</p> | |
<p>Example 3 produces a set of class files such as newhamlet.class, | |
newhamlet$0.class, etc., rather than hamlet.class, hamlet$0.class, | |
etc.</p> | |
<p> | |
<b>Example 4:</b> Compiling multiple stylesheets.</p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Compile</code> | |
<br /> | |
<code> hamlet1.xsl hamlet2.xsl hamlet3.xsl</code> | |
</p> | |
<p>Example 4 produces three translets and set of class files derived from the three stylesheets.</p> | |
<p> | |
<b>Example 5:</b> Package Specification.</p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Compile</code> | |
<br /> | |
<code> -p com.mycompany.translets hamlet.xsl</code> | |
</p> | |
<p>Example 5 produces a set of class files such as com/mycompany/translets/hamlet.class, | |
com/mycompany/translets/hamlet$0.class', etc.</p> | |
<a name="run"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Running translets from the command line</h3> | |
<ul> | |
<li> | |
<a href="#run-synopsis">Synopsis</a> | |
</li> | |
<li> | |
<a href="#run-args">Flags and arguments</a> | |
</li> | |
<li> | |
<a href="#run-examples">Examples</a> | |
</li> | |
</ul> | |
<p>The XSLTC runtime processor is a Java-based tool for | |
transforming XML document files using a translet (compiled | |
stylesheet). </p> | |
<p>The XSLTC processor can be run on any platform including UNIX, | |
Windows, NT, Mac that supports Java, including a Palm Pilot | |
with J2ME CLDC (Java 2 Micro Edition, Connected Limited Device | |
Configuration).</p> | |
<p>To run a translet from the command line or a script, | |
<a href="#classpath">set the classpath</a> (be sure to include | |
the translet) and run the translet with the appropriate flags and arguments | |
(described below).</p> | |
<table class="note"> | |
<tr> | |
<td class="noteImg"> | |
<img src="resources/note.gif" alt="note" /> | |
</td> | |
<td class="noteTxt">You can also use the | |
<a href="commandline.html">Xalan-Java Command-line Utility</a>, to | |
compile or run XSLTC translets.</td> | |
</tr> | |
</table> | |
<a name="run-synopsis"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Synopsis</h4> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Transform</code> | |
<br /> | |
<code> [-j <jarfile>] [-x] {-u <document_url> | <document>} <class></code> | |
<br /> | |
<code> [<name1>=<value1> ...]</code> | |
</p> | |
<a name="run-args"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Flags and arguments</h4> | |
<p>The following flags and arguments are supported:</p> | |
<blockquote class="source"> | |
<pre> | |
-j Specifies <jarfile> from which to load translet. | |
-x Turns on debugging messages. | |
-s Disables calling System.exit | |
-u Specifies the XML input <document> with a URI, | |
such as 'http://myserver/hamlet.xml'. | |
Arguments without flags: | |
<document> | |
Filename of the XML input document. | |
<document_url> | |
URI of the XML input document (see the -u flag above). | |
<class> | |
The translet that performs the transformation. The translet | |
may take a set of stylesheet parameters specified as | |
name-value pairs. The format for a name-value pair is | |
<name>=<value>.</pre> | |
</blockquote> | |
<a name="run-examples"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Examples</h4> | |
<p>The following examples assume that you have already set the classpath to include the translet and the required JAR | |
files (see <a href="#classpath">setting the system classpath</a>).</p> | |
<p>A possible variation: You have set the classpath to include the required JAR files, but when you run the translet, | |
you use the java -cp flag to add the current working directory (containing the translet class files you have just generated) | |
to the classpath.</p> | |
<p> | |
<b> | |
<i>Windows:</i> | |
</b> | |
<code> java -cp .;%CLASSPATH% ...</code> | |
<br /> | |
<b> | |
<i>UNIX: </i> | |
</b> | |
<code> java -cp .:$CLASSPATH ...</code> | |
</p> | |
<p> | |
<b>Example 1:</b> Processing an XML document.</p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Transform</code> | |
<br /> | |
<code> hamlet.xml hamlet</code> | |
</p> | |
<p>Example 1 uses the specified translet (hamlet) to transform the specified XML input document (hamlet.xml). | |
The XML input document is in the current working directory. The translet was created by using | |
org.apache.xalan.xslt.cmdline.Compile to compile an XSL stylesheet (hamlet.xsl). </p> | |
<p> | |
<b>Example 2:</b> Passing stylesheet parameters to the translet.</p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Transform</code> | |
<br /> | |
<code> hamlet.xml hamlet</code> | |
<br /> | |
<code> speaker=HAMLET 'scene=SCENE IV'</code> | |
</p> | |
<p>Example 2 passes "HAMLET" to the stylesheet for the stylesheet parameter named speaker, and "SCENE IV" for the | |
stylesheet parameter named scene. The second name-value pair was placed in single quotes to | |
specify a value containing a space.</p> | |
<p> | |
<b>Example 3:</b> Processing an XML input document specified with a URI.</p> | |
<p> | |
<code>java org.apache.xalan.xsltc.cmdline.Transform</code> | |
<br /> | |
<code> -u http://zarya.east/test.xml hamlet</code> | |
</p> | |
<p>Example 3 applies the translet (hamlet) to the XML input document (http://zarya.east/test.xml hamlet). Inclusion of | |
the flag (-u) is optional.</p> | |
<a name="api"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Calling XSLTC with the JAXP API</h3> | |
<ul> | |
<li> | |
<a href="#api-attributes">XSLTC TransformerFactory attributes</a> | |
</li> | |
<li> | |
<a href="#api-examples">Examples</a> | |
</li> | |
</ul> | |
<p>XSLTC translets are integrated with the JAXP 1.3 API. Accordingly, it is now possible to set a | |
system property and use a TransformerFactory to generate a Transformer that performs a transformation by compiling | |
and running a translet.</p> | |
<p>When you use the JAXP 1.3 API to run Xalan-Java, the | |
<code>javax.xml.transform.TransformerFactory</code> system property is set to | |
<code>org.apache.xalan.processor.TransformerFactoryImpl</code>. As it currently | |
stands, this Xalan-Java implementation of TransformerFactory always uses the Xalan-Java | |
Interpretive processor to perform transformations. To use translets to perform | |
transformations, set this system property to | |
<code>org.apache.xalan.xsltc.trax.TransformerFactoryImpl</code>. For | |
information on setting this and related system properties designating XML | |
parsers and XSL transformers, see | |
<a href="usagepatterns.html#plug">Plugging in a Transformer and XML | |
parser</a>.</p> | |
<p>To use the JAXP 1.3 API to perform transformations with translets do the | |
following:</p> | |
<ol> | |
<li>Set the <code>javax.xml.transform.TransformerFactory</code> system | |
property as indicated above.<br /> | |
<br /> | |
</li> | |
<li>Instantiate a <code>TransformerFactory</code>.<br /> | |
<br /> | |
</li> | |
<li>Instantiate a <code>Transformer</code> object either directly from | |
the <code>TransformerFactory</code> or through a <code>Templates</code> | |
object. A <code>Transformer</code> is a processed instance of a | |
stylesheet (a translet) that can be used to perform a | |
transformation. See below for more information on when you should use | |
a <code>Templates</code> object.<br /> | |
<br /> | |
</li> | |
<li>Perform the transformation, using a StreamSource object for the XML | |
input and a StreamResult object to hold the transformation output.</li> | |
</ol> | |
<p>Both a <code>Templates</code> object and a <code>Tranformer</code> object are | |
processed representations of a stylesheet, but you cannot use a | |
<code>Templates</code> object to perform transformations. Instead, | |
you can use a <code>Templates</code> object to create new | |
<code>Transformer</code> instances, without having to reprocess the | |
stylesheet each time. You can use a <code>TransformerFactory</code> to | |
generate a <code>Templates</code> object or a <code>Transformer</code> | |
object directly. You can use a <code>Transformer</code> more than once, | |
but you cannot use it concurrently on more than one thread. If you need | |
to use the same stylesheet to perform transformations on more than one | |
thread at the same time, use a <code>Templates</code> object and create | |
as many <code>Transformer</code> objects as you require.</p> | |
<p>XSLTC also defines a set of attributes that you can set on the | |
<code>TransformerFactory</code> in order to save and subsequently use those | |
translets by way of the JAXP Transform API - without having to recompile the | |
stylesheet each time.</p> | |
<a name="api-attributes"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>XSLTC TransformerFactory attributes</h4> | |
The JAXP Transform API defines a <code> | |
<a href="apidocs/javax/xml/transform/TransformerFactory.html#setAttribute(java.lang.String, java.lang.Object)">TransformerFactory.setAttribute</a> | |
</code> method that you can use to set implementation-defined attributes. | |
<table border="1"> | |
<tr> | |
<th class="content" rowspan="1" colspan="1">Attribute</th> | |
<th class="content" rowspan="1" colspan="1">Purpose</th> | |
<th class="content" rowspan="1" colspan="1">Type of value</th> | |
<th class="content" rowspan="1" colspan="1">Default value</th> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">translet-name</td> | |
<td class="content" rowspan="1" colspan="1">Specifies the name of the translet</td> | |
<td class="content" rowspan="1" colspan="1">String</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">Specifies where to save translet class files</td> | |
<td class="content" rowspan="1" colspan="1">String</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">Specifies which package translet class files will be in</td> | |
<td class="content" rowspan="1" colspan="1">String</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">Specifies the name of a jar file in which translets should be saved</td> | |
<td class="content" rowspan="1" colspan="1">String</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">Specifies whether translet class files should be generated</td> | |
<td class="content" rowspan="1" colspan="1">Boolean</td> | |
<td class="content" rowspan="1" colspan="1">Boolean.FALSE</td> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">auto-translet</td> | |
<td class="content" rowspan="1" colspan="1">Specifies that time-stamp of translet file, if any, should be compared with that of stylesheet to decide whether to recompile the stylesheet</td> | |
<td class="content" rowspan="1" colspan="1">Boolean</td> | |
<td class="content" rowspan="1" colspan="1">Boolean.FALSE</td> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">use-classpath</td> | |
<td class="content" rowspan="1" colspan="1">Specifies that precompiled translet classes should be looked up from the classpath when a new transformer or templates is created</td> | |
<td class="content" rowspan="1" colspan="1">Boolean</td> | |
<td class="content" rowspan="1" colspan="1">Boolean.FALSE</td> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">enable-inlining</td> | |
<td class="content" rowspan="1" colspan="1">Specifies whether methods that represent templates should be inlined. See <a href="#constraints">Usage constraints</a> | |
</td> | |
<td class="content" rowspan="1" colspan="1">Boolean</td> | |
<td class="content" rowspan="1" colspan="1">Boolean.FALSE</td> | |
</tr> | |
<tr> | |
<td class="content" rowspan="1" colspan="1">debug</td> | |
<td class="content" rowspan="1" colspan="1">Enables debugging messages</td> | |
<td class="content" rowspan="1" colspan="1">Boolean</td> | |
<td class="content" rowspan="1" colspan="1">Boolean.FALSE</td> | |
</tr> | |
</table> | |
<p>The <code>translet-name</code>, <code>destination-directory</code>, | |
<code>package-name</code> and <code>jar-name</code> attributes are transient. | |
They only apply to the next invocation of either the <code>newTemplates</code> | |
or the <code>newTransformer</code> method on that | |
<code>TransformerFactory</code>.</p> | |
<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 value specified for the | |
<code>translet-name</code> attribute 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 was | |
<code>my-stylesheet</code>, the translet will actually be named | |
<code>my_stylesheet</code>.</td> | |
</tr> | |
</table> | |
<a name="api-examples"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h4>Examples</h4> | |
<p> | |
<b>Example 1:</b> Using a translet/Templates object for multiple | |
concurrent transformations</p> | |
<blockquote class="source"> | |
<pre>import java.util.Properties; | |
import javax.xml.transform.Transformer; | |
import java.io.FileOutputStream; | |
import javax.xml.transform.TransformerFactory; | |
import javax.xml.transform.Templates; | |
import javax.xml.transform.stream.StreamSource; | |
import javax.xml.transform.stream.StreamResult; | |
... | |
// Set the TransformerFactory system property. | |
// Note: For more flexibility, load properties from a properties file. | |
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); | |
... | |
String xslInURI; | |
// Instantiate the TransformerFactory, and use it with a StreamSource | |
// XSL stylesheet to create a translet as a Templates object. | |
TransformerFactory tFactory = TransformerFactory.newInstance(); | |
Templates translet = tFactory.newTemplates(new StreamSource(xslInURI)); | |
... | |
String xmlInURI; | |
String htmlOutURI; | |
String xmlInURI2; | |
String htmlOutURI2; | |
... | |
// For each thread, instantiate a new Transformer, and perform the | |
// transformations on that thread from a StreamSource to a StreamResult; | |
Transformer transformer = translet.newTransformer(); | |
transformer.transform(new StreamSource(xmlInURI), | |
new StreamResult(new FileOutputStream(htmlOutURI))); | |
transformer.transform(new StreamSource(xmlInURI2), | |
new StreamResult(new FileOutputStream(htmlOutURI2))); | |
...</pre> | |
</blockquote> | |
<p>For a working sample that illustrates this usage pattern, see <a href="samples.html#xsltc1">JAXPTransletOneTransformation</a>.</p> | |
<p> | |
<b>Example 2:</b> Compiling a translet/Templates object for a single transformation</p> | |
<blockquote class="source"> | |
<pre>import java.util.Properties; | |
import javax.xml.transform.TransformerFactory; | |
import java.io.FileOutputStream; | |
import javax.xml.transform.Transformer; | |
import javax.xml.transform.stream.StreamSource; | |
import javax.xml.transform.stream.StreamResult; | |
... | |
// Set the TransformerFactory system property. | |
// Note: For more flexibility, load properties from a properties file. | |
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); | |
... | |
String xslInURI; | |
String xmlInURI; | |
String xmlInURI2; | |
String htmlOutURI; | |
String htmlOutURI2; | |
// Instantiate the TransformerFactory, and use it along with a StreamSource | |
// XSL stylesheet to create a Transformer. | |
TransformerFactory tFactory = TransformerFactory.newInstance(); | |
Transformer transformer = | |
tFactory.newTransformer(new StreamSource(xslInURI)); | |
// Perform the transformation from a StreamSource to a StreamResult; | |
transformer.transform(new StreamSource(xmlInURI), | |
new StreamResult(new FileOutputStream(htmlOutURI))); | |
// Re-use the same transformer for a second transformation | |
transformer.transform(new StreamSource(xmlInURI2), | |
new StreamResult(new FileOutputStream(htmlOutURI2)));</pre> | |
</blockquote> | |
<p>For a working sample that illustrates this usage pattern, see <a href="samples.html#xsltc2">JAXPTransletMultipleTransformations</a>.</p> | |
<a name="xsltcsmart"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Smart Transformer Switch</h3> | |
<p>As part of the JAXP API, a "Smart Transformer Switch" enables automatic switching | |
between Xalan-Java Interpretive and XSLTC processors within your application. It uses Xalan-Java Interpretive | |
processor to create your <code>Transformer</code> objects, and uses XSLTC to create your | |
<code>Templates</code> objects.</p> | |
<p>To use the switch, you set the JAXP system property, | |
<code>javax.xml.transform.TransformerFactory</code>, to | |
<code>org.apache.xalan.xsltc.trax.SmartTransformerFactoryImpl</code>. | |
For one-time transformations or transformations that require extensions | |
supported by Xalan-Java Interpretive, and not XSLTC, you would use the | |
<code>SmartTransformerFactoryImpl</code> to create <code>Transformer</code> | |
objects. For a repeated transformation where performance is critical, you would | |
create a <code>Templates</code> object from which you would create your | |
<code>Transformer</code> objects.</p> | |
<a name="native_api"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Calling XSLTC with the native API</h3> | |
<p>The XSLTC Native API is no longer supported. Instead, you should always | |
use XSLTC with the JAXP Transform API.</p> | |
<a name="constraints"></a> | |
<p align="right" size="2"> | |
<a href="#content">(top)</a> | |
</p> | |
<h3>Usage constraints</h3> | |
<ul> | |
<li>The default for template inlining has been changed. Previously, | |
by default, inlining (putting all the templates into one big method) was on and | |
the <code>"-n"</code> option to the compile command line disabled inlining. | |
With inlining on, XSLTC can generate methods that are too long (<b>> 64K length</b>) | |
to run, or contain jump offsets that are too large for the JVM to handle. | |
Now the default is not to inline templates. Instead, compilation creates separate | |
methods for each template. Inlining was thought to improve performance, | |
but with recent hotspot technology in the Java 1.4.x JVM, performance is better with | |
inlining off. From the command line, you would use <code>"-n"</code> | |
to turn on inlining, or with JAXP set the "enable-inlining" attribute to the TransformerFactory. | |
For example, | |
<blockquote class="source"> | |
<pre>TransformerFactory tfac = new TransformerFactory(); | |
tfac.setAttribute("enable-inlining", Boolean.TRUE);</pre> | |
</blockquote> | |
<br /> | |
</li> | |
<li>XSLTC tries to determine the order in which global variables are initialized | |
by tracking the dependencies between them. In some cases, the value of a variable | |
may depend on a template, e.g., if <code>xsl:call-template</code> is used to initialized | |
a variable whose type is RTF. If this happens, a | |
<code>NullPointerException</code> may be thrown at run-time | |
when the translet attempts to access a variable that has not been properly | |
initialized. In most cases, this problem can be avoided by reordering the | |
variable declarations.<br /> | |
</li> | |
</ul> | |
<p>To check on the open bugs in the current Apache xml-xalan/java repository, | |
follow the instructions below:</p> | |
<ol> | |
<li>Go to <a href="http://issues.apache.org/jira">http://issues.apache.org/jira</a>.</li> | |
<li>Select project <b>XalanJ2</b>.</li> | |
<li>Select <b>XSLTC</b> from the Components list.</li> | |
</ol> | |
<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 - Fri 07/13/2012</div> | |
</div> | |
</body> | |
</html> |