



































|
See also:
XSLTC Design
 |
Unless otherwise
specified, the usage discussed in this section refers to the
Xalan-Java Compiling processor, XSLTC. See Basic Usage Patterns for information
on using the Xalan-Java Interpretive processor. |
|
|
The
Xalan-Java Compiled processor 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.
 |
To compile and run
translets, you must have a JDK or a JRE 1.2 or
higher. |
|
|
|
To use this newer approach, simply put xsltc.jar in your
classpath. No need to mention the others (BCEL.jar, JLex.jar,
regexp.jar, java_cup.jar, runtime.jar).
 |
In order to compile
and run translets you must have a JAXP 1.2 compliant XML parser
installed. Our distribution includes Xerces (just
include xercesImpl.jar and xml-apis.jar in your class
path). |
|
 |
 |
 |
 |
Compiling translets from the command
line |
 |
 |
 |
 |
|
|
The XSLT
Compiler is a Java-based tool for compiling XSLT stylesheets into
lightweight and portable Java byte codes called
translets.
To run the
compiler from the command line or from a script, set the classpath and run the
class org.apache.xalan.xsltc.cmdline.Compile .
The synopsis of the options and arguments accepted by this class is
shown below.
|
|
java
org.apache.xalan.xsltc.cmdline.Compile
[-o
<output>] [-d <directory>] [-j
<jarfile>]
[-p
<package name>] [-n] [-x] [-v] [-u] [-h]
{<stylesheet> | -i
}
|
|
|
The following examples assume that you have already set
the classpath to include the translet and the required JAR files
(see setting the system
classpath).
Example 1: Creating a translet from the hamlet.xsl
stylesheet.
java
org.apache.xalan.xsltc.cmdline.Compile
hamlet.xsl
Example 1 produces a set of class files such as
hamlet.class, hamlet$0.class, hamlet$1.class.
Example 2: Outputting to a JAR file.
java
org.apache.xalan.xsltc.cmdline.Compile
-j
hamlet.jar hamlet.xsl
Example 2 produces hamlet.jar, which contains the
translet class files.
Example 3: Specifying the translet class
name.
java
org.apache.xalan.xsltc.cmdline.Compile
-o
newhamlet hamlet.xsl
Example 3 produces a set of class files such as
newhamlet.class, newhamlet$0.class, etc., rather than hamlet.class,
hamlet$0.class, etc.
Example 4: Compiling multiple
stylesheets.
java
org.apache.xalan.xsltc.cmdline.Compile
hamlet1.xsl hamlet2.xsl hamlet3.xsl
Example 4 produces three translets and set of class files
derived from the three stylesheets.
Example 5: Package Specification.
java
org.apache.xalan.xsltc.cmdline.Compile
-p
com.mycompany.translets hamlet.xsl
Example 5 produces a set of class files such as
com/mycompany/translets/hamlet.class,
com/mycompany/translets/hamlet$0.class', etc.
|
|
 |
 |
 |
 |
Running translets from the command
line |
 |
 |
 |
 |
|
|
The XSLTC
runtime processor is a Java-based tool for transforming XML
document files using a translet (compiled stylesheet).
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).
To run a
translet from the command line or a script, set the classpath (be sure to
include the translet) and run the translet with the appropriate
flags and arguments (described below).
|
|
java
org.apache.xalan.xsltc.cmdline.Transform
[-j
<jarfile>] [-x] [-s] {-u <document_url> |
<document>} <class>
[<name1>=<value1> ...]
|
|
|
The following examples assume that you have already set
the classpath to include the translet and the required JAR files
(see setting the system
classpath).
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.
Windows:java -cp .;%CLASSPATH%
...
UNIX: java -cp .:$CLASSPATH
...
Example 1: Processing an XML document.
java
org.apache.xalan.xsltc.cmdline.Transform
hamlet.xml hamlet
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).
Example 2: Passing stylesheet parameters to the
translet.
java
org.apache.xalan.xsltc.cmdline.Transform
hamlet.xml hamlet
speaker=HAMLET 'scene=SCENE IV'
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.
Example 3: Processing an XML input document
specified with a URI.
java
org.apache.xalan.xsltc.cmdline.Transform
-u
http://zarya.east/test.xml hamlet
Example 3 applies the translet (hamlet) to the XML input
document (http://zarya.east/test.xml hamlet). Inclusion of the flag
(-u) is optional.
|
|
 |
 |
 |
 |
Calling XSLTC with the TrAX/JAXP
API |
 |
 |
 |
 |
|
|
XSLTC
translets are integrated with the TrAX/JAXP 1.2 API. See
The Translet API & TrAX. 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.
When you
use the JAXP 1.2 API to run Xalan-Java, the javax.xml.transform.TransformerFactory
system property is set to org.apache.xalan.processor.TransformerFactoryImpl .
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 org.apache.xalan.xsltc.trax.TransformerFactoryImpl .
For information on setting this and related system properties
designating XML parsers and XSL transformers, see Plugging in a Transformer and XML
parser.
To use the
JAXP 1.2 API to perform transformations with translets do the
following:
- Set the
javax.xml.transform.TransformerFactory
system property as indicated above.
- Instantiate a
TransformerFactory .
- Instantiate a
Transformer object either
directly from the TransformerFactory or
through a Templates object. A
Transformer 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 Templates object.
- Perform
the transformation, using a StreamSource object for the XML input
and a StreamResult object to hold the transformation
output.
Both a
Templates
object and a Tranformer object are
processed representations of a stylesheet, but you cannot use a
Templates
object to perform transformations. Instead, you can use a
Templates
object to create new Transformer instances,
without having to reprocess the stylesheet each time. You can use a
TransformerFactory to
generate a Templates object or a
Transformer
object directly. You can use a Transformer 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 Templates object and
create as many Transformer objects as you
require.
XSLTC also
defines a set of attributes that you can set on the TransformerFactory in
order to save and subsequently use those translets by way of the
JAXP Transform API - without having to recompile the stylesheet
each time.
|
|
Example 1: Using a translet/Templates object for
multiple concurrent transformations
 |
 |
 |
 |
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)));
...
|
 |
 |
 |
 |
For a working sample that illustrates this usage pattern,
see JAXPTransletOneTransformation.
Example 2: Compiling a translet/Templates object
for a single transformation
 |
 |
 |
 |
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)));
|
 |
 |
 |
 |
For a working sample that illustrates this usage pattern,
see JAXPTransletMultipleTransformations.
|
|
|
|
As part of
the TrAX API, a "Smart Transformer Switch" enables automatic
switching between the Interpretive and the Compiling processors
within your application. It uses the Interpretive processor to
create your Transformer objects, and
uses XSLTC to create your Templates
objects.
To use the
switch, you set the TrAX system property, javax.xml.transform.TransformerFactory ,
to org.apache.xalan.xsltc.trax.SmartTransformerFactoryImpl .
For one-time transformations or transformations that require
extensions supported by the Interpretive processor, and not XSLTC,
you would use the SmartTransformerFactoryImpl
to create Transformer objects. For a
repeated transformation where performance is critical, you would
create a Templates object from
which you would create your Transformer
objects.
|
|
|
- The strip
space element does not work with copy-of. For example, with
<xsl:strip-space
elements="*"/> , if you do an identity transform by
matching on the root node (/) and then do a copy-of select="." , the
whitespace-only nodes are not stripped out. xsl:strip-space works when
you do not do a copy-of.
- The
default for template inlining has been changed. Previously, by
default, inlining (putting all the templates into one big method)
was on and the
"-n" option to the compile
command line disabled inlining. With inlining on, XSLTC can
generate methods that are too long (> 64K length) 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 "-n" to turn on inlining,
or with TrAX set the "enable-inlining" attribute to the
TransformerFactory. For example,
 |
 |
 |
 |
TransformerFactory tfac = new TransformerFactory();
tfac.setAttribute("enable-inlining", Boolean.TRUE);
|
 |
 |
 |
 |
- 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
xsl:call-template is used
to initialized a variable whose type is RTF. If this happens, a
NullPointerException 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.
To check
on the open bugs in the current Apache xml-xalan/java repository,
follow the instructions below:
- Go to http://nagoya.apache.org/bugzilla.
- Select
Query Existing Bug Reports.
- Choose:
Program: XalanJ2
Component: org.apache.xalan.xsltc (and)
Xalan-Xsltc
- Submit
the query.
|
|
|