Saxon home page

Using Stylesheets


This page describes how to use Saxon XSLT Stylesheets, either from the command line, or from the Java API, or as an Applet in the browser.

Contents
Using Stylesheets Reference
Using Saxon from the Command Line
Embedding Saxon in an Application
Running Saxon in an Applet
See also:
XSL Elements
XPath Expressions
XSL Patterns
Saxon Extensibility
Saxon XSLT and XPath Conformance

Using Saxon from the Command Line

The Java class net.sf.saxon.Transform has a main program that may be used to apply a given style sheet to a given source XML document. The form of command is:

java  net.sf.saxon.Transform   [options]   source-document   stylesheet   [ params…]

The options must come first, then the two file names, then the params. The stylesheet is omitted if the -a option is present.

If you are using JDK 1.2 or later, you can use the simpler form of command:

java  -jar dir/saxon7.jar   [options]   source-document   stylesheet   [ params…]

The options are as follows (in any order):

-a Use the xml-stylesheet processing instruction in the source document to identify the stylesheet to be used. The stylesheet argument should be omitted.
-ds | -dt Selects the implementation of the internal tree model. -dt selects the "tinytree" model (the default). -ds selects the traditional tree model. See Choosing a tree model below.
-l Switches line numbering on for the source document. Line numbers are accessible through the extension function saxon:line-number(), or from a trace listener.
-m classname Use the specified Emitter to process the output from xsl:message. The class must implement the net.sf.saxon.output.Emitter class. This interface is similar to a SAX ContentHandler, it takes a stream of events to generate output. In general the content of a message is an XML fragment. By default the standard XML emitter is used, configured to write to the standard error stream, and to include no XML declaration. Each message is output as a new document.
-noext Suppress calls on extension functions, other than system-supplied Saxon and EXSLT extension functions. This option is useful when loading an untrusted stylesheet, perhaps from a remote site using an http:// URL; it ensures that the stylesheet cannot call Java methods and thereby gain privileged access to resources on your machine.
-o filename Send output to named file. In the absence of this option, output goes to standard output. If the source argument identifies a directory, this option is mandatory and must also identify a directory; on completion it will contain one output file for each file in the source directory.
-r classname Use the specified URIResolver to process all URIs. The URIResolver is a user-defined class, that extends the net.sf.saxon.URIResolver class, whose function is to take a URI supplied as a string, and return a SAX InputSource. It is invoked to process URIs used in the document() function, in the xsl:include and xsl:import elements, and (if -u is also specified) to process the URIs of the source file and stylesheet file provided on the command line.
-t Display version and timing information to the standard error output
-T Display stylesheet tracing information to the standard error output. Also switches line numbering on for the source document.
-TL classname Run the stylesheet using the specified TraceListener. The classname names a user-defined class, which must implement net.sf.saxon.trace.TraceListener
-u Indicates that the names of the source document and the style document are URLs; otherwise they are taken as filenames, unless they start with "http:" or "file:", in which case they are taken as URLs
-w0, w1, or w2 Indicates the policy for handling recoverable errors in the stylesheet: w0 means recover silently, w1 means recover after writing a warning message to the system error output, w2 means signal the error and do not attempt recovery. (Note, this does not currently apply to all errors that the XSLT recommendation describes as recoverable). The default is w1.
-x classname Use specified SAX parser for source file and any files loaded using the document() function. The parser must be the fully-qualified class name of a Java class that implements the org.xml.sax.Parser or org.xml.sax.XMLReader interface
-y classname Use specified SAX parser for stylesheet file, including any loaded using xsl:include or xsl:import. The parser must be the fully-qualified class name of a Java class that implements the org.xml.sax.Parser or org.xml.sax.XMLReader interface
-?Display command syntax
source-document Identifies the source file or directory. Mandatory. If this is a directory, all the files in the directory will be processed individually. In this case the -o option is mandatory, and must also identify a directory, to contain the corresponding output files. A directory must be specified as a filename, not as a URL.
stylesheet Identifies the stylesheet. Mandatory unless the -a option is used.

A param takes the form name=value, name being the name of the parameter, and value the value of the parameter. These parameters are accessible within the stylesheet as normal variables, using the $name syntax, provided they are declared using a top-level xsl:param element. If there is no such declaration, the supplied parameter value is silently ignored.

Under Windows it is possible to supply a value containing spaces by enclosing it in double quotes, for example name="John Smith". This is a feature of the operating system shell, not something Saxon does, so it may not work the same way under every operating system.

If the -a option is used, the name of the stylesheet is omitted. The source document must contain a <?xml-stylesheet?> processing instruction before the first element start tag; this processing instruction must have a pseudo-attribute href that identifies the relative or absolute URL of the stylsheet document, and a pseudo-attribute type whose value is "text/xml", "application/xml", or "text/xsl". For example:

<?xml-stylesheet type="text/xsl" href="../style3.xsl" ?>

It is also possible to refer to a stylesheet embedded within the source document, provided it has an id attribute and the id attribute is declared in the DTD as being of type ID. For example:

<?xml-stylesheet type="text/xsl" href="#style1" ?> <!DOCTYPE BOOKLIST SYSTEM "books.dtd" <!ATTLIST xsl:transform id ID #IMPLIED> > <BOOKLIST> ... <xsl:transform id="style1" version="1.0" xmlns:xsl="..."> ... </xsl:transform> </BOOKLIST>

Choosing a tree model

Saxon provides two implementations of the internal tree data structure (or tree model). The tree model can be chosen by an option on the command line (-dt for the tiny tree, -ds for the standard tree) or from the Java API. The default is to use the tiny tree model. The choice should make no difference to the results of a transformation (except the order of attributes and namespace declarations) but only affects performance.

Generally speaking, the tiny tree model is faster to build but slower to navigate. It therefore performs better when you visit each node on the tree once or less. The standard tree model may perform better (sometimes very much better) when each node is visited many times, especially when you use the preceding or preceding-sibling axis.

The tiny tree model gives most benefit when you are processing a large document. It uses a lot less memory, so it can prevent thrashing when the size of document is such that the standard tree doesn't fit in real memory.


Embedding Saxon in an Application

Rather than using the interpreter from the command line, you may want to include it in your own application, perhaps one that enables it to be used within an applet or servlet. If you run the interpreter repeatedly, this will always be much faster than running it each time from a command line.

Saxon incorporates support for the JAXP 1.1 API, also known as TrAX. This is compatible with the API for invoking other XSLT processors such as Xalan and jd-xslt.

This API is described in the javadoc documentation included with the Saxon download. Look for the javax.xml.transform package.

More information and examples relating to the TrAX API can be found in the TraxExamples.java example application found in the samples directory.


Running Saxon from an Applet

It is possible to run Saxon from an applet in the browser. This means that the transformation will run on the client machine, which saves resources on the server. It also means that it is possible for the user to navigate around the downloaded XML document, performing repeated transformations to see different pages of data, without ever returning to the server: this too reduces load on the server, as well as giving the user an improved response time once the XML data and the supporting Saxon software (saxon7.jar is 644Kb) have been downloaded.

Because Saxon now requires JDK 1.2 or later, you must first ensure that the Sun Java plug-in is installed as the default Java VM for your browser

To support transformations running in an applet, Saxon includes a support routine net.sf.saxon.XSLTProcessorApplet.class which can be used to drive the transformation. This rountine is in fact borrowed from the class of the same name included in the Xalan-Java 2.0.0 product. It drives the transformation using TrAX interfaces, which means that the code works equally well with either product.

To use this routine, you first need to include an applet in your HTML page. This might take the form:

<applet name="xslControl" code="net.sf.saxon.XSLTProcessorApplet.class" archive="saxon7.jar" height="0" width"0"> <param name="documentURL" value="source.xml"/> <param name="styleURL" value="style.xsl"/> </applet>

For production use it is better to use the HTML <OBJECT> element. This can be used to ensure that the right Java VM is used with the applet, preventing failures that will confuse the end user.

To run a transformation, all you have to do is to call the getHTMLText() method provided by the applet, for example

<body onLoad="target.innerHTML=document.xslControl.getHTMLText()"> <div id="target"></div> </body>

You can specify the source document and stylesheet dynamically using the methods xslControl.setDocumentURL(string) or xslControl.setStyleURL(string). If you don't specify a stylesheet, Saxon will try to locate one using the <?xml-stylesheet?> processing instruction in the source document.

You can set parameters for the transformation (a single parameter only, unfortunately) by calling xslControl.setStylesheetParam("name", "value").

There are some sample applications using Saxon as an applet in the samples/applet folder. Make sure that the saxon7.jar file is in an accessible location before you try to use them.

Michael H. Kay
20 December 2001