[ANNOUNCE] XSLTC support on the Process command line

[mk...@ca.ibm.com]

Hi,

The org.apache.xalan.xslt.Process command line now supports XSLTC for
transformation. You use the new "-XSLTC" option to enable the XSLTC
support. The xsltc.jar file must be on your CLASSPATH in order to use
XSLTC.

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 will 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 character
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
the Xalan interpreter, a message is printed and the option is ignored.

Here is the list of the new options:
-XO [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
Enables template inlining

-XX
Turns on additional debugging message output

-XT
Use translet to transform if possible
---------------------------------------------------------------------------------------------------

Explanation of the new XSLTC specific options:

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.

A command line like the following will use XSLTC to do the transformation.
XSLTC will compile the stylesheet on the fly and use the in-memory bytecode
to transform the input xml. No translet class is generated in this default
usage pattern.
> java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc

If you want to generate translet class from the xsl, you can use the
following command line:
> java org.apache.xalan.xslt.Process -in test.xml -xsl test.xsl -xsltc -xo

The above example will still use the xsl for transformation, but it will
also generate the translet class "test.class".

You can use -XJ, -XP and -XD 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 puts the
translet classes into the jar file "translets.jar". The jar file is put
under the temp directory. The generated translet classes have a package
name prefix of "org.apache.test". And the translet class name is
"newTranslet".

All of the examples above use the xsl file to do the transformation. If the
translets are already generated and you want to use them to do the
transformation, you can use the -XT option. The -XT option has a makefile
like feature in that it will compare the timestamps of the translet and the
xsl. If the translet is newer, it is used for the transformation, otherwise
the xsl is used and the translet is re-generated.

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

This command line will search for a file "test.class" under the current
directory. If it is found and it is newer than test.xsl, we will use it to
do the transformation.

The other options (-XO, -XD, -XP, -XJ) can be used with the -XT option to
tell XSLTC where to find the translet classes.

Here is the subtle details on the -XT option:
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 do I know if it is actually using the
translet or the xsl?
A: Use the -XX option. If 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
a command line like this:
> 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 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 -xo
This command runs a transformation on an empty input and generates the
translet "test.class".


Using the new options from JAXP:

If you use JAXP with XSLTC, you could not tell it to use translets before.
It always compiled the xsl on the fly and used the in-memory bytecode for
transformation.  Now you can use some of the new attributes in XSLTC's
TransformerFactoryImpl to customize the translet behavior 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
translet-name          -XO
destination-directory  -XD
package-name           -XP
jar-name               -XJ
generate-translet
auto-translet          -XT
enable-inlining        -XN
debug                  -XX

You can set the attributes using the TRAX interface
TransformerFactory.setAttribute(). 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.

Here is an example on how to do the same thing from JAXP for the FAQ
question 2.

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



Morris Kwan
XSLT Development
IBM Toronto Lab
Tel: (905)413-3729
Email: mkwan@ca.ibm.com