logolineright
bottomhttp://xml.apache.org/http://www.apache.org/http://www.w3.org/
join
What's New
Release Notes
separator
Overview
Downloads
Getting Started
Using XSLTC
separator
FAQs
separator
Sample Apps
Command Line
separator
Features
Transform API
XPath API
Usage Patterns
separator
Xalan-J API
Public APIs
DTM
separator
Extensions
Extensions Library
XSLTC Exts
separator
Xalan 2 Design
XSLTC Design
separator
Source Repository
Xalan-Java Builds
Testing
User Mail Archive
Dev Mail Archive
Bug Reporting
close
Options
 

The org.apache.xalan.xslt.Process command line now supports XSLTC for transformation. You can use the new -XSLTC option to enable the XSLTC support.

The following existing options can be used with -XSLTC:

-IN, -XSL, -OUT, -V, -EDUMP, -XML, -TEXT, -HTML, -PARAM,
-MEDIA, -FLAVOR, -DIAG, -URIRESOLVER, -ENTITYRESOLVER,
-CONTENTHANDLER

The following existing options do not work with -XSLTC. If any of them is used with -XSLTC, a message is printed and the option is ignored.

-QC, -TT, -TG, -TS, -TTC, -TCLASS, -L, -INCREMENTAL,
-NOOPTIMIMIZE, -RL

We also have a new set of options for -XSLTC. 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 org.apache.xalan.xsltc.cmdline.Compile.

These new options can only be used with -XSLTC. If any of them is used with Xalan-Java Interpretive, a message is printed and the option is ignored.

Here is the list of the new options:

  • -XO [optional translet_name]
    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).
  • -XD destination_directory
    Specify a destination directory for translet. The generated translet classes will be put under the specified destination directory.
  • -XJ jar_name
    Package translet classes into a jar file of name <jar_name>
  • -XP package_name
    Specify a package name prefix for all generated translet classes
  • -XN
    Enable XSL template inlining into one big method
  • -XX
    Turn on additional debugging message output
  • -XT
    Use translet to transform if possible
NoteThe translet name is the same as the name of the Java class that implements the translet. If the name specified by the -XO 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 -XO option is my-stylesheet, or if the URL of the stylesheet is http://example.org/my-stylesheet.xsl, the translet will actually be namedmy_stylesheet.

Examples
 

You can just add the -XSLTC option to your existing option list so that it will do the same thing as before, but using XSLTC.

Here is a simple example on how to use XSLTC:

> java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc

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.

If you want to generate translet classes from the stylesheet, you can use the -XO option:

> java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc -xo

This example still uses the stylesheet for transformation, but it also generates the translet class "test.class".

You can use the -XJ, -XP or -XD options to further customize the translet generation behavior. Translets will be generated if any of the options -XO, -XJ or -XT is used.

> java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc -xo newTranslet -xd temp -xp org.apache.test -xj translets.jar

The above command line uses the xsl for transformation. It also generates translet classes in the name of newTranslet, using a package prefix of org.apache.test, and packages the translets into the jar file translets.jar under the temp directory.

All of the examples above use the stylesheet to do the transformation. If the translets are already generated, you can use the -XT option to specify that you want to use the existing translets for transformation. The -XT 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.

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 -XD or -XO option is used. The options -XO, -XD, -XP and -XJ can be used with the -XT 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.

Example:

> java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc -xt -xj translets.jar -xd temp

This command line will search for the translet test.class inside the jar file temp/translets.jar. 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.

Here is how the makefile feature for the -XT option works:

  1. If the xsl does not exist, use the translet
  2. If the translet does not exist, use the xsl and generate a new translet
  3. If both exist and the translet is newer, use the translet for transformation
  4. If both exist and the xsl is newer, use the xsl for transformation and regenerate the translet

Simple FAQs
 

Q: If I use the -XT option, how can I tell if it is using the translet or the stylesheet for transformation?

A: Use the -XX 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 ...".

Q: I want to use a translet for transformation, and I don't have the stylesheet.

A: Suppose the translet class is c:\translets\myTranslet.class, you can use the following command line:

> java org.apache.xalan.xslt.Process -in test.xml -xsltc -xt -xo myTranslet -xd c:\translets

If you use -XT option, the -XSL option can be omitted. You have to specify the translet name using the -XO option because there is no default translet name in this situation.

Q: I only want to compile the stylesheet. I don't want to do a transformation.

A: 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:

> java org.apache.xalan.xslt.Process -xsl test.xsl -xsltc
-xo

This command runs a transformation on an empty input and generates the translet test.class.


Using options from the JAXP transform APIs
 

You can use some of the attributes in the TransformerFactoryImpl class of XSLTC to customize the translet behaviors from JAXP.

Here is the list of attributes in org.apache.xalan.xsltc.trax.TransformerFactoryImpl and their corresponding Process command line options:

Attributes  Process command line options  Default values 
translet-name  -XO  GregorSamsa 
destination-directory  -XD  null 
package-name  -XP  null 
jar-name  -XJ  null 
generate-translet    false 
auto-translet  -XT  false 
use-classpath    false 
enable-inlining  -XN  false 
debug  -XX  false 

You can set the attributes using the JAXP interface TransformerFactory.setAttribute(String name, Object value). The four attributes translet-name, destination-directory, package-name and jar-name are transient. They only apply to the next newTemplates() or newTransformer() call. Their values are reset to the default after the call.

The generate-translet attribute does not have a corresponding command line option. This attribute is implied when the -XO or -XJ option is used. The purpose is to make the command line usage syntax a little bit simpler. Setting the generate-attribute attribute to true from JAXP is equivalent to using the -XO option without the optional translet name from the Process command line.

If the use-classpath attribute is set to true, the translet will be loaded from the CLASSPATH. This attribute is typically used in a case when the translets are packaged in a prebuilt jar file which is included in the CLASSPATH. You can set the translet-name 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 jar-name attribute is not used in this situation.

The following example shows you how to do the same thing from JAXP for the question 2 in the FAQ.

// 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());


dot
Copyright © 2005 The Apache Software Foundation. All Rights Reserved.