Xalan XSL Transformer User's Guide
	Getting Started with XSLTC

Apache Foundation

Xalan Project

Xerces Project

Web Consortium

Oasis Open

• Resources
  
• Home

---

• Xalan-J 2.7.3
• Charter

---

• What's New
• Release Notes

---

• Overview
• Download/Build
• Getting Started
• Using XSLTC
  

---

• FAQs

---

• Sample Apps
• Command Line

---

• Features
• Transform API
• XPath API
• Usage Patterns

---

• Xalan-J API
• Public APIs
• DTM

---

• Extensions
• Extensions Library
• XSLTC Exts

---

• Xalan 2 Design
• XSLTC Design

---

• Building a release
• Testing
• Bug Reporting

---

• Contact us

Getting Started with XSLTC

• Introduction
• Setting the system classpath for XSLTC
• Compiling translets from the command line
• Running translets from the command line
• Calling XSLTC with the JAXP API
• Smart Transformer Switch
• Calling XSLTC with the native API
• Usage constraints
• Sample translets
• Extensions for XSLTC

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.

‌

(top)

Introduction

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.

‌

(top)

Setting the system classpath for XSLTC

The xalan.jar file contains support for both Xalan-Java processors. You can use the JAXP javax.xml.transform.TransformerFactory property (see "Calling XSLTC with the JAXP API" below) to select which processor to use: the Interpretive or the Compiling processor.

To use XSLTC, simply put xalan.jar, serializer.jar, xml-apis.jar, and xercesImpl.jar on the system classpath.

To compile and run translets, you must use JDK (or JRE) 1.8 or higher.

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.

(top)

Bundled System Classpath

To use this approach, simply put xalan.jar, serializer.jar, xml-apis.jar and xercesImpl.jar on your system classpath.

In order to compile and run translets you must have a JAXP 1.3 compliant XML parser installed. Our distribution includes Xerces-Java 2.12.2. Include xercesImpl.jar and xml-apis.jar on your system classpath.

(top)

Unbundled System Classpath

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 and tools directories.

To compile translets, run translets, and use the XSLTC API, using the unbundled jar approach, put the following on the system classpath:

Classes or JAR	To compile a translet	To run a translet
the translet		required
xsltc.jar	required	required
runtime.jar	required
bcel-6.7.0.jar	required

The translet is the set of class files or the JAR file that you generate with the compiler; see Compiling translets.

‌

(top)

Compiling translets from the command line

• Synopsis
• Flags and arguments
• Examples

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.

You can also use the Xalan-Java command-line utility, to compile or run XSLTC translets.

‌

(top)

Synopsis

java org.apache.xalan.xsltc.cmdline.Compile
    [-o <output>] [-d <directory>] [-j <jarfile>]
    [-p <package name>] [-n] [-x] [-v] [-u] [-h]
    {<stylesheet> | -i }

‌

(top)

Flags and arguments

The following flags and arguments are supported:

-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

The translet name is the same as the name of the Java class that implements the translet. If the name specified by the -o 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 -o option is my-stylesheet, or if the URL of the stylesheet is http://example.org/my-stylesheet.xsl, the translet will actually be named my_stylesheet.

‌

(top)

Examples

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.

‌

(top)

Running translets from the command line

• Synopsis
• Flags and arguments
• Examples

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).

You can also use the Xalan-Java Command-line Utility, to compile or run XSLTC translets.

‌

(top)

Synopsis

java org.apache.xalan.xsltc.cmdline.Transform
     [-j <jarfile>] [-x] {-u <document_url> | <document>} <class>
     [<name1>=<value1> ...]

‌

(top)

Flags and arguments

The following flags and arguments are supported:

-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>.

‌

(top)

Examples

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.

‌

(top)

Calling XSLTC with the JAXP API

• XSLTC TransformerFactory attributes
• Examples

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.

When you use the JAXP 1.3 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.3 API to perform transformations with translets do the following:

1. Set the javax.xml.transform.TransformerFactory system property as indicated above.
   
   
2. Instantiate a TransformerFactory.
   
   
3. 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.
   
   
4. 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.

‌

(top)

XSLTC TransformerFactory attributes

The JAXP Transform API defines a TransformerFactory.setAttribute method that you can use to set implementation-defined attributes.

Attribute	Purpose	Type of value	Default value
translet-name	Specifies the name of the translet	String	"GregorSamsa"
destination-directory	Specifies where to save translet class files	String	null
package-name	Specifies which package translet class files will be in	String	null
jar-name	Specifies the name of a jar file in which translets should be saved	String	null
generate-translet	Specifies whether translet class files should be generated	Boolean	Boolean.FALSE
auto-translet	Specifies that time-stamp of translet file, if any, should be compared with that of stylesheet to decide whether to recompile the stylesheet	Boolean	Boolean.FALSE
use-classpath	Specifies that precompiled translet classes should be looked up from the classpath when a new transformer or templates is created	Boolean	Boolean.FALSE
enable-inlining	Specifies whether methods that represent templates should be inlined. See Usage constraints	Boolean	Boolean.FALSE
debug	Enables debugging messages	Boolean	Boolean.FALSE

The translet-name, destination-directory, package-name and jar-name attributes are transient. They only apply to the next invocation of either the newTemplates or the newTransformer method on that TransformerFactory.

The translet name is the same as the name of the Java class that implements the translet. If the value specified for the translet-name 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 my-stylesheet, the translet will actually be named my_stylesheet.

‌

(top)

Examples

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.

‌

(top)

Smart Transformer Switch

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 Transformer objects, and uses XSLTC to create your Templates objects.

To use the switch, you set the JAXP system property, javax.xml.transform.TransformerFactory, to org.apache.xalan.xsltc.trax.SmartTransformerFactoryImpl. For one-time transformations or transformations that require extensions supported by Xalan-Java Interpretive, 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.

‌

(top)

Calling XSLTC with the native API

The XSLTC native API is no longer supported. Instead, you should always use XSLTC with the JAXP Transform API.

‌

(top)

Usage constraints

• 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 the hotspot technology within Java VMs, performance is better with inlining off. From the command line, you would use "-n" to turn on inlining, or with JAXP 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 xalan-java repository, follow the instructions below:

1. Go to http://issues.apache.org/jira.
2. Select project XalanJ2.
3. Select XSLTC from the Components list.

(top)

Copyright © 1999-2023 The Apache Software Foundation
Apache, Xalan, and the Feather logo are trademarks of The Apache Software Foundation