http://xml.apache.org/http://www.apache.org/http://www.w3.org/

What's New
DTM
XSLTC Translets

Overview
Getting Started

FAQs

Sample Apps
Command Line

Usage Patterns

TrAX
API (Javadoc)

Extensions
Extensions Library

Release Notes

Xalan 2 Design
XSLTC Design

Bugs
Testing

Credits
XSLTC Credits

See also: XSLTC Design

Introduction
 

XSLT provides a compiler and a runtime processor. Use the compiler to compile an XSL stylesheet into a translet, a set of Java classes. Use the runtime processor to apply the translet to an XML document and perform a transformation.

NoteTo compile translets, you must be running the JDK or JRE 1.2 or higher. You can run translets with the JDK or JRE 1.1.8 or higher.

Setting the system classpath for XSLTC
 

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

Classes or JAR  To compile a translet  To run a translet  To use the XSLTC API 
the translet    required  required 
xsltc.jar  required  required  required 
runtime.jar  required    required 
BCEL.jar  required    required 
Jlex.jar      required 
java_cup.jar      required 

The JAR files listed above are in the Xalan-Java bin directory. The translet is the set of class files or the JAR file that you generate with the compiler; see Compiling translets.

If you are using JDK or JRE 1.1.8, also include classes.zip on the classpath. If you are using JDK or JRE 1.2, include tools.jar on the classpath.

NoteFor the time being, the Xalan processor and XSLT do not yet use the same DOM, SAX, and parser infastructures. Accordingly, you may find it necessary to reset the system classpath each time you switch between the Xalan processor and XSLTC. For information on setting the classpath for the Xalan processor, see Setting the system classpath for Xalan.

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.

The XSLT Compiler can be run on any platform including UNIX, Windows, NT, or Mac that supports Java 1.2.x or later. The generated translets can be run on any platform that supports a Java Runtime Environment, including a Palm Pilot with J2ME CLDC (Java 2 Micro Edition, Connected Limited Device Configuration).

To run the compiler from the command line or a script, set the classpath and run the XSLTC class with the appropriate flags and arguments (described below).

Synopsis
 

java org.apache.xalan.xsltc.compiler.XSLTC
    [-o <output>] [-d <directory>] [-j <jarfile>]
    [-p <package name>] [-u] <stylesheet>...


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.		

-u  <stylesheet>
  Specifies the stylesheet with a URI such as 
  'http://myserver/stylesheet1.xsl'.

   <stylesheet>
   (No flag) The pathname of the stylesheet file.

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.compiler.XSLTC
     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.compiler.XSLTC
     -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.compiler.XSLTC
     -o newhamlet hamlet.xsl

Example 3 producs a set of class files such as newhamlet.class, newhamlet$0.class, etc., rather than hamlet.class, hamles$0.class, etc.

Example 4: Compiling multiple stylesheets.

java org.apache.xalan.xsltc.compiler.XSLTC
     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.compiler.XSLTC
     -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 Sun XSLT runtime processor is a Java-based tool for transforming XML document files using a translet (compiled stylesheet).

The XSLT 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 translet from the command line or a script, set the classpath (be sure to include the translet) and run the translset with the appropriate flags and arguments (described below).

Synopsis
 

java <translet>
     {-u <document_url> | <document>} <class>
     [<name1>=<value1> ...]


Flags and arguments
 

The following flags and arguments are supported:

-u
   Specifies the XML input <document> with a URI,
   such as 'http://myserver/hamlet.xml'.		

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

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.runtime.DefaultRun
     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.compiler.XSLTC to compile an XSL stylesheet (hamlet.xsl).

Example 2: Passing stylesheet parameters to the translet.

java org.apache.xalan.xsltc.runtime.DefaultRun
     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.runtime.DefaultRun
     -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
 

G. Todd Miller has begun integrating the translet with the TrAX/JAXP 1.1 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.1 API to run Xalan-Java, the javax.xml.transformer.TransformerFactory system property is set to org.apache.xalan.processor.TransformerFactoryImpl. As it currently stands, this Xalan implementation of TransformerFactory always uses the Xalan Transformer to perform transformations. To use translets to perform transformations, set this system property to org.apache.xalan.xsltc.runtime.TransformerFactoryImpl. For information on setting this and related system properties designating XML parsere and XSL transformer, see Plugging in a Transformer and XML parser.

To Use the JAXP 1.1 API to perform transformations with translets do the following:

  1. Set the javax.xml.transformer.TransformerFactory system property as indicated above.

  2. Instantiate a TransformerFactory.

  3. Assuming you want to perform a series of transformations with the same translet, use the TransformerFactory and a StreamSource XSL stylesheet to generate a Templates object (the translet). If you are performing a single transformation, use the TransformerFactory and the StreamSource object to instantiate a Transformer.

  4. Perform the transformation, using a StreamSource object for the XML input and a StreamResult object to hold the transformation output.
Examples
 

Example 1: Using a translet/Templates object for multiple 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.runtime.TransformerFactoryImpl";
Properties props = System.getProperties();
props.put(key, value);
System.setProperties(props);
...
String xslInURI;
// Instantiate the TransformerFactory, and use it along with a SteamSource
// 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;
...
// For each transformation, instantiate a new Transformer, and perform
// the transformation from a StreamSource to a StreamResult;
Transformer transformer = translet.newTransformer();
transformer.transform(new StreamSource(xmlInURI),
                      new StreamResult(new FileOutputStream(htmlOutURI)));
...

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.runtime.TransformerFactoryImpl";
Properties props = System.getProperties();
props.put(key, value);
System.setProperties(props);
...
String xslInURI;
String xmlInURI;
String htmlOutURI;
// Instantiate the TransformerFactory, and use it along with a SteamSource
// 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)));

For a working sample that illustrates this usage pattern, see JAXPTransletMultipleTransformations.



XSLTC usage constraints
 

See Conformance issues and Known problems.



Copyright © 2001 The Apache Software Foundation. All Rights Reserved.