Saxon Documentation

Full Contents

About Saxon

Changes in this Release

Conditions of Use

Using XSLT 2.0
	Using XSLT 2.0 Stylesheets
	Running XSLT from the Command Line
	Compiling a Stylesheet
	Running Saxon XSLT transformations from Ant
»	Invoking XSLT from an application
	Performance Analysis

Using XQuery

Handling Source Documents

XML Schema Processing

XPath API for Java

Saxon on .NET

Extensibility

Saxon Extensions

Sample Saxon Applications

The Saxon SQL Extension

XSLT Elements

XPath 2.0 Expression Syntax

Function Library

Standards Conformance

Invoking XSLT from an application

Rather than using the XSLT 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.

On the Java platform, Saxon incorporates support for the JAXP transformation API (originally known as TrAX). This is compatible with the API for invoking other XSLT processors such as Xalan and Oracle.

This API is described in the documentation provided with JDK 1.4. It is available online at http://java.sun.com/j2se/1.4/docs/api/ Look for the javax.xml.transform package.

There is also an API for Saxon on the .NET platform, designed to make Saxon available from .NET languages such as C#, VB.NET, and ASP.NET. See Saxon on .NET.

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

The types of object that can be supplied as stylesheet parameters are not defined in the JAXP specification: they are implementation-dependent. Saxon takes the Java object supplied, and converts it to an XPath value using the same rules as it applies for the return value from a Java extension function: for these rules, see Saxon Extensibility. If the resulting value is an atomic value, it is cast to the required type of the parameter as specified in the xsl:param declaration, using the XPath casting rules. If the value is non-atomic (for example, if it is a node, or a sequence of integers), then no conversion is attempted, instead, the value must match the required type as stated.

The JAXP TransformerFactory interface provides a configuration method setAttribute() for setting implementation-defined configuration parameters. The parameters supported by Saxon have names defined by constants in the class net.sf.saxon.FeatureKeys. The names of these properties and their meanings, are described in the table below.

property	meaning
ALLOW_EXTERNAL_FUNCTIONS	A Boolean: true if the stylesheet allows external functions to be called. Default is true. The setting `false` is recommended in an environment where untrusted stylesheets may be executed. Setting this value to `false` also disables user-defined extension elements, together with the writing of multiple output files, all of which carry similar security risks.
TRACE_EXTERNAL_FUNCTIONS	A Boolean: true if the tracing of calls to external Java methods is required. Default is false. This switch is useful when analyzing why Saxon fails to find a Java method to match an extension function call in the stylesheet, or why it chooses one method over another when several are available. The trace output is sent to System.err.
TIMING	A Boolean: true if basic timing information is to be output to the standard error output stream.
TREE_MODEL	An Integer: Builder.STANDARD_TREE or Builder.TINY_TREE. Selects an implementation of the Saxon tree model. The default is Builder.TINY_TREE.
TRACE_LISTENER	An instance of the class net.sf.saxon.trace.TraceListener. This object will be notified of significant events occurring during the transformation, for tracing or debugging purposes.
LINE_NUMBERING	A Boolean. Indicates whether line numbers are to be maintained for the source document. This will not be possible if the source document is supplied as a DOM. The line numbers are accessible through the tracing interface, and also via the saxon:line-number() extension function.
RECOVERY_POLICY	An Integer. Indicates how dynamic errors should be handled. One of the values (defined as constants in the Controller class) RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER).
MESSAGE_EMITTER_CLASS	The full name of a class that implements the net.sf.saxon.output.Emitter interface; the class will be used to format the output of the xsl:message instruction.
SOURCE_PARSER_CLASS	The full name of a class that implements the org.xml.sax.XMLReader interface; the class will be used to parse source documents (that is, the principal source document plus any secondary source documents read using the document() function)
STYLE_PARSER_CLASS	The full name of a class that implements the org.xml.sax.XMLReader interface; the class will be used to parse stylesheet documents (that is, the principal stylesheet module plus any secondary source documents read using xsl:include or xsl:import)
OUTPUT_URI_RESOLVER	An instance of the class net.sf.saxon.OutputURIResolver; this object will be used to resolve URIs of secondary result documents specified in the `href` attribute of the `xsl:result-document` instruction
VALIDATION	A Boolean. Indicates whether the XML parser should be asked to validate source documents against their DTD. This applies to the initial source document and any source documents read using the document() function, unless handled by a user-written URIResolver.
VALIDATION_WARNINGS	A Boolean. Indicates (if true) that errors occuring while validating a final result tree are to be treated as warnings rather than fatal errors. Although the XSLT specification states that validation errors are fatal, this switch can be useful during debugging because it enables the invalid output to be inspected. It will include comments showing where the validity errors were found. Applies to Saxon-SA only.
VERSION_WARNING	A Boolean. Indicates whether a warning message should be notified (to the ErrorListener) if running against a stylesheet that specifies `version="1.0"`. This warning is output by default (because the W3C specification requires it), but it may be suppressed using this option.
NAME_POOL	A instance of class `net.sf.saxon.om.NamePool`. Indicates that the supplied NamePool should be used as the target (run-time) NamePool by all stylesheets compiled (using `newTemplates()`) after this call on `setAttribute`. Normally a single system-allocated NamePool is used for all stylesheets compiled while the Java VM remains loaded; this attribute allows user control over the allocation of NamePools. Note that source trees used as input to a transformation must be built using the same NamePool that is used when the stylesheet is compiled: this will happen automatically if the input to a transformation is supplied as a SAXSource or StreamSource but it is under user control if you build the source tree yourself.

Saxon's implementation of the JAXP Transformer interface is the class net.sf.saxon.Controller. This provides a number of options beyond those available in the standard JAXP interface, for example the ability to set an output URI resolver for secondary output documents, and a method to set the initial mode before the transformation starts. You can access these methods by casting the Transformer to a Controller. The methods are described in the JavaDoc documentation supplied with the product.

When using the JAXP interface, you can set serialization properties using a java.util.Properties object. The names of the core XSLT 1.0 properties, such as method, encoding, and indent, are defined in the JAXP class javax.xml.transform.OutputKeys. Additional properties, including Saxon extensions and XSLT 2.0 extensions, have names defined by constants in the class net.sf.saxon.event.SaxonOutputKeys. The values of the properties are exactly as you would specify them in the xsl:output declaration.