# Invoking XSLT from Java

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.

Saxon incorporates support for the JAXP transformation API (previously 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.

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.
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.

Expand | Next