Each of the subdirectories in the Xalan-Java samples directory contains the source files for one or more sample applications. The class files for all the samples are in xalansamples.jar, so to run the samples, you should place xalansamples.jar on the system class path.

With most of the samples, you can use the following procedure:

1. Be sure xalan.jar, xalansamples.jar, and xerces.jar are on the system class path. For the extension examples, bsf.jar, bsfengines.jar, and (for the JavaScript extensions) js.jar must also be on the class path.
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. Run the sample from the command line (as indicated below)
5. Examine the application source files. You may also want to modify the source files. Remember that if you modify a java file, you must recompile the class and place it on the class path before you can run the modified application.

The basic command line for running most of the samples is

java classname args

where classname is the classname and args are the arguments, if any. As described in the following sections, some samples take no arguments. The samples in UseStylesheetParam and ApplyXPath take additional arguments. The samples in extensions use the Xalan-Java command-line utility, so they take arguments for the XML source file and the XSL stylesheet.

What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and prints the output to System.out.

You can run it from the SimpleTransform subdirectory with

java SimpleTransform

What it does: The TransformToDom class uses the foo.xsl stylesheet to transform foo.xml, produces an output DOM, and traverses the DOM, printing the traversal to System.out. In contrast to SimpleTransform, TransformToDom illustrates the procedure for creating an output DOM that is available for further processing. The XSLTProcessor is set up to use XercesLiaison and the Xerces DOM parser rather than the default DTM liaison and parser.

You can run it from the TransformToDom subdirectory with

java TransformToDom

What it does: The UseStyleSheetParam class uses foo.xsl and a stylesheet parameter to transform foo.xml, and prints the output to System.out. The stylesheet parameter appears as a text node in the output.

Run this sample from the UseStylesheetParam subdirectory with

java UseStylesheetParam param

where param is the stylesheet parameter (a string of your choice).

What it does: The ApplyXPath class uses the XPathAPI to execute an XPath expression against an XML document and returns the nodes (if any) it finds. XPathAPI contains some convenience methods for using XPath expressions to return single Nodes, NodeLists, and XObjects. In the future, we plan to incorporate user feedback and move these methods into the core API.

You can use this sample as an aid when you want to find out what a given XPath expression returns from a given XML file. Keep in mind that the context node (base point of evaluation) for the XPath expression is the document root.

Run this sample from the ApplyXPath subdirectory with

java ApplyXPath XMLFile XPathExpression

where XMLFile is an XML source file and XPathExpression is an XPath expression to apply to that file. The ApplyXPath subdirectory contains an XML file named foo.xml, so you can try command lines like

java ApplyXPath foo.xml /

and

java ApplyXPath foo.xml /doc/name/@first

If you are interested in the API for executing XPath expressions, we suggest you take a look at the methods in XPathAPI, and send us feedback on what best meets your needs.

What it does: The Pipe class uses the output of the first transformation as input to a second transformation.

The first transformation produces a sequence of SAX events which the second transformation processes with its own stylesheet. The consumer of SAX output can respond to these events as they occur, rather than waiting for the entire result tree to be constructed (as the DOM consumer must do).

Run this sample from the Pipe subdirectory with

java Pipe

For other examples using the SAX document handler, see the next section and Generating and responding to SAX events.

What it does: The PureSAX class uses SAX DocumentHandlers and the Xerces SAX parser to produce a stylesheet tree, an XML input tree, and the transformation result tree. The SAX parser uses the XSLT processor to set a lexical handler, which enables the parser to include "lexical" events in the XML source, such as the occurrence of comment nodes.

Run this sample from the PureSax subdirectory with

java PureSAX

The extensions subdirectory contains four samples with Xalan-Java extensions. Two of the samples use extensions implemented in JavaScript, and two of the samples use extensions implemented in Java. All of the samples are documented in Extensions.

To run these examples, you must place bsf.jar and bsfengines.jar (distributed with Xalan-Java), and js.jar (version 1.4 release 3, available from http://www.mozilla.org/rhino) on the class path. You do not need js.jar on the class path for the samples that use Java extensions.

Use java.org.apache.xalan.xslt.Process, the Xalan-Java command-line utility, to run these samples from the command line. The command line must include an -in flag with the XML source and an -xsl flag with the XSL stylesheet. If you want the output to be printed to a file, rather than to the screen, add an -out flag with the output file name.

Run these samples from the extensions directory as follows (each of the following is a single command line):

java org.apache.xalan.xslt.Process -in 1basicJscript.xml
  -xsl 1basicJscript.xsl

java org.apache.xalan.xslt.Process -in 2java-namespace.xml
  -xsl 2java-namespace.xsl

java org.apache.xalan.xslt.Process -in 3numlistJava.xml
  -xsl 3numlistJava.xsl

java org.apache.xalan.xslt.Process -in 4numlistJscript.xml
  -xsl 4numlistJscript.xsl

The applet uses a stylesheet to transform an XML document into HTML. It displays the XML document, the stylesheet, and the HTML output.

How to run it: See sample applet readme.

For a brief introduction to using applets to perform transformations, see Using the Xalan-Java applet wrapper

What it does: The client (which you must set up) specifies an XML document and a stylesheet. The servlet performs the transformation and returns the output to the client. You can use media.properties to specify which stylesheet is to be used depending on the client browser/device.

How to run it:

1. Configure your application server (Websphere or JServ, for example) so it can find the classes (in xalansamples.jar) as well as the stylesheets and properties file in the servlet subdirectory.
2. Set up an HTML client to call DefaultApplyXSL with arguments as illustrated below.

Examples:

http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL= /style.xsl

...applies the style.xsl stylesheet to the data.xml data. Both files are
served from the Web server's HTTP XSLTInputSource root.

http://localhost/servlet/DefaultApplyXSL?URL=/data.xml&xslURL= /style.xsl&debug=true

...ensures that XML and XSL processor messages are returned in the event of problems applying style.xsl to data.xml

http://localhost/servlet/DefaultApplyXSL/data.xml?xslURL=/style.xsl

...applies the style.xsl stylesheet to the data.xml data, just like the first example. This is an alternative way of specifying the XML XSLTInputSource by utilizing the HTTP request's path information.

http://localhost/servlet/DefaultApplyXSL/data.xml

...examines data.xml for an associated XSL stylesheet. If multiple XSLs are associated with the data, the stylesheet whose media attribute maps to your browser type will be chosen. If no mapping is successful, the primary associated stylesheet is used.

http://localhost/servlet/data.xml

...provides the same function as the previous example, but this example assumes that /servlet/data.xml has been mapped to be executed by this servlet. The servlet engine may be configured to map all or some *.xml files to this servlet through the use of servlet aliases or filters.

http://localhost/servlet/data.xml?catalog=http://www.xml.org/dtds/oag.xml

...supplements any servlet-configured XCatalog with a catalog of supply chain DTDs residing at the XML.ORG DTD repository.

For more information, see the comments in DefaultApplyXSL.java.