This page describes how to use SAXON XSLT Stylesheets, either from the command line, or from the Java API.
| Contents | |
| Using Stylesheets | Reference |
|
Using the XSL interpreter from the command line Embedding the interpreter in an application |
See also: XSL Elements XSL Expressions XSL Patterns SAXON Extensibility SAXON XSL Conformance |
The Java class com.icl.saxon.StyleSheet 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 com.icl.saxon.StyleSheet [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.
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. |
| -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. |
| -t | Display version and timing information to the standard error output |
| -u | Indicates that the names of the source document and the style document are URLs; otherwise they are taken as filenames |
| -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 I don't know whether it works 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" ?>
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.
This is a two-stage process. First you need to create a PreparedStyleSheet. Then you can run this as often as you like; for each run you must create a new StyleSheetInstance from the PreparedStyleSheet.
The PreparedStyleSheet object represents a compiled stylesheet in memory. The main methods on PreparedStyleSheet are:
| prepare() | The stylesheet is supplied as a SAX InputSource object. This method causes the stylesheet to be parsed, validated, and readied for execution. Once prepared, it can be used repeatedly to process a sequence of source documents. If you use a SAXON ExtendedInputSource as your InputSource, this allows you (a) to specify the parser of your choice, and (b) to take the input from a DOM Document rather than from an XML source file. |
| makeStyleSheetInstance() | The PreparedStyleSheet can now be used repeatedly to process a sequence of source documents. Each time you use the stylesheet, you must make a new StyleSheetInstance object. |
The StyleSheetInstance object contains the context for a single execution of a stylesheet. The main methods on StyleSheetInstance are:
| setParams() | Set the value of global parameters declared in the stylesheet. These are passed in a ParameterSet object as a set of name-value pairs. If the same stylesheet is used several times to process different source documents, different parameters may be used for each one. The name of each parameter must be an unqualified name (no namespace URI can be supplied). The value may be any subclass of com.icl.saxon.expr.Value: specifically, StringValue, NumericValue, BooleanValue, NodeSetValue (unlikely), FragmentValue (also unlikely), or ObjectValue. The class ObjectValue is a wrapper around a Java object, which is accessible in the stylesheet only by using extension functions. |
| setOutputDetails() | Set the details of the initial output destination. Any output details set within the stylesheet itself (using xsl:output or saxon:output) will override these settings. The information is supplied using an OutputDetails object which holds similar attributes to the xsl:output element. On exit, the OutputDetails object may be interrogated to determine the media type (MIME type) of the output file. |
| renderSource() | Transform a source document using the current stylesheet. The source document is supplied in the form of a SAX InputSource object. If you use a SAXON ExtendedInputSource as your InputSource, this allows you (a) to specify the parser of your choice, and (b) to take the input from a DOM Document rather than from an XML source file. The ExtendedInputSource object also has a setEstimatedLength() method which you can use optionally to help efficient memory allocation; the value should ideally be the number of characters of PCDATA content in the document. |
| renderDocument() | Transform a source document using the current stylesheet. The source document is supplied in the form of a DocumentInfo object, which you can construct by creating a Builder and calling its build() method. This allows you to build the source document tree once, and use it several times perhaps with different stylesheets and with different parameters. Note however that the action of stripping whitespace nodes from the tree is irreversible, so the xsl:strip-space and xsl:preserve-space directives on any run after the first might not have the expected effect. |
| getSourceContentHandler() | This method returns a SAX2 ContentHandler, to which you can feed the source document in a sequence of SAX calls such as startDocument(), startElement(), characters(), endElement(), and endDocument(). (This replaces getSourceDocumentHandler() which provided a SAX1 interface in previous releases.) Once you have supplied the complete document, call renderSuppliedDocument() to process it. |
If the source document has an xml:stylesheet processing instruction which you want to use to identify the required stylesheet, you can instead follow the sequence below:
Michael H. Kay
13 April 2000