To use Xalan, you need the following:

• The JDK or JRE 1.1.8 or 1.2.2
• xalan.jar
• xerces.jar

You can get the JDK or JRE from ibm.com/java/jdk/ or java.sun.com.

Download xalan-j_1_2_D01.zip or xalan-j_1_2_D01.tar.gz. Both of these files contain Xalan-Java version 1.2.D01 (with xalan.jar) and xerces.jar from Xerces-Java version 1.1.2. You can use a zip or tar utility to expand these files into a full build.

If you plan to run XSLT extensions, you need bsf.jar and bsfengines.jar, both of which are included in the Xalan-Java distribution. If you plan to run XSLT extensions implemented in JavaScript or another scripting language, you will need one or more additional files as indicated in extensions language requirements.

At the very minimum, you must include xalan.jar and xerces.jar on the system class path. To run the sample applications, include xalansamples.jar. To run extensions, include bsf.jar and bsfengines.jar. All these JAR files are distributed with Xalan-Java. For extensions implemented in JavaScript or another scripting language, see extensions language requirements to identify any additional JAR files you must place on the class path and where you can get them.

If you are using JDK or JRE 1.1.8, also include classes.zip on the class path.

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 class path (see above), including xalansamples.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 files.

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

java SimpleTransform

The sample displays the transformation result on the screen. To see how the example works, examine the source files: foo.xml, foo.xsl, and SimpleTransform.java.

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

java.org.apache.xalan.xslt.Process provides a basic utility for performing transformations from the command line. You use this utility, for example, to run 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. If you include a DOCTYPE statement in your XML source files and include the -validate flag on the command line, the utility will also let you know whether the XML document is valid (conforms to that DOCTYPE). For more information, see Command-Line Utility.

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.

If you modify a java source file, be sure to compile the class and place it on the system class path. Here are some basic points to keep in mind as you are setting up transformations:

• Use the XSLTProcessorFactory static getProcessor() method to set up an XSLTProcessor interface object.
  
  
• Set up XSLTInputSource class objects for the XML input and XSL stylesheet. You can use a file name or URL, character streams, byte streams, or SAX input stream to instantiate an XSLTInputSource object.
  
  If the XML document contains a stylesheet Processing Instruction (PI), you do not need to create a separate XSLTInputSource object for an XSL stylesheet.
  
  
• For improved performance with a series of transformations, use the XSLTProcessor processStylesheet() method to compile the XSL stylesheet (the result is a StylesheetRoot class), and then use the StylesheetRoot process() method to perform the transformations.
  
  Compiling the stylesheet is also useful when you need to get information from the stylesheet before the transformation occurs, for instance, when you need to find out the output encoding in order to construct the right kind of Writer. You must also compile the stylesheet if you are using the XSLTProcessor as a SAX document handler (see Generating and responding to SAX events).
  
  
• Set up an XSLTResultTarget class for the transformation output. You can use a file name or URL, character stream, byte stream, or SAX document handler to instantiate an XSLTResultTarget object.
  
  
• Use the XSLTProcessor process() method to perform the transformation, or the StylesheetRoot process() method to perform a series of transformations with the same stylesheet.
  
  XSLTProcessor is thread-safe for one instance per thread. If you are using the same instance of XSLTProcessor to perform more than one transformation, call the reset method between transformations. StylesheetRoot is multithread-safe, and a single instance may be used across threads. Accordingly, you can call a StylesheetRoot object process() method repeatedly without resetting the StyleSheetRoot.

For more information on setting up applications, see Basic Usage Patterns.