Trademark Logo Xalan XSL Transformer User's Guide
Getting Started
Apache Foundation Xalan Project Xerces Project Web Consortium Oasis Open

Getting Started

note Unless otherwise specified, the usage discussed in this section refers to the Xalan-Java Interpretive processor. See Getting Started with XSLTC for information on using the Xalan-Java Compiling processor.


Setting up the system classpath

At the very minimum, you must include xalan.jar, serializer.jar, xml-apis.jar, and xercesImpl.jar -- or another conformant XML parser -- see Plugging in a Transformer and XML parser) on the system classpath. To run the Xalan-Java Interpretive processor sample applications, include xalansamples.jar (all samples other than the servlet) and xalanservlet.jar. All these JAR files are distributed with Xalan-Java. To run Javascript extensions, include bsf.jar, which can be obtained from the Apache Jakarta BSF project. For extensions implemented in other scripting language, see extensions language requirements to identify any additional JAR files you must place on the classpath and where you can get them.

If you are using XSLTC, see Getting Starting with XSLTC.

If you are using JDK or JRE 1.3.x or 1.4.x, include tools.jar on the classpath. If you are using JDK or JRE 1.1.8 (supported for runtime only), then include on the classpath.


Trying out the samples

The Xalan-Java distribution includes a number of basic sample applications. These samples are easy to run, and you can review the source files -- all of which are brief -- to see just how they work.

To run the samples, do the following:

  1. Set up your classpath (see above), including xalansamples.jar and (for the servlet) xalanservlet.jar.
  2. Be sure the java executable is on your path.
  3. Go to the samples subdirectory containing the sample (use the DOS shell if you are running Windows).
  4. Use the java executable to run the sample from the command line.
  5. Examine the application source and result files.

For example, go to the SimpleTransform subdirectory and issue the following command:

java SimpleTransform

The sample writes the transformation result to a file (birds.out). To see how the example works, examine the source files: birds.xml, birds.xsl, and

The extensions examples require additional JAR files on the classpath, and the procedure for running the sample applet and sample servlet is different. For more information about all the samples, see Xalan-Java Samples.


Performing your own transformations from the command line

org.apache.xalan.xslt.Process provides a basic utility for performing transformations from the command line. You can use this utility, for example, to run several of the extensions samples. The command line for most standard transformations is as follows:

java org.apache.xalan.xslt.Process -in xmlSource
    -xsl stylesheet -out outputfile

where xmlSource is the XML source file name, stylesheet is the XSL stylesheet file name, and outputfile is the output file name.

If you want the output to be displayed on the screen, simply omit the -out flag and argument.

You can use this utility to try out XSL stylesheets you have written, to make sure they do what you expect with the XML source files they are designed to transform. The utility provides useful messages if the source file or stylesheet is not well formed. For more information, see Command-Line Utility.


Setting up your own Java applications

You can start by using your own XML source files and XSL stylesheets with the sample applications, which illustrate a number of the basic usage patterns.

Here is the basic procedure to keep in mind when you set up a transformation:

  1. Use the TransformerFactory static newInstance() method to instantiate a TransformerFactory.

  2. Use the TransformerFactory newTransformer(Source stylesheet) method to process the transformation instructions in an XSLT stylesheet Source (producing under the covers a Templates object) and generate a Transformer.

  3. Use the Transformer transform(Source xmlSource, Result transformResult) method to apply the transformation instructions (the Templates object) to the XML Source and produce the transformation Result.

For more information about this procedure and its variations, see Basic Usage Patterns.