Saxon Documentation

Full Contents

About Saxon

Changes in this Release

Licensing

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

Using JAXP for Transformations

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.

Where the required value of a property is a Boolean, the supplied value may be either a java.lang.Boolean, or a String holding the values "true" or "false". The returned value of the property, however, will be a Boolean.

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 (`xsl:result-document`), all of which carry similar security risks. It is also a good idea when executing untrusted stylesheets to use a URIResolver that monitors the use of the doc(), document(), and collection() functions to read external documents.
COLLATION_URI_RESOLVER	An instance of a user-written class implementing Saxon's `CollationURIResolver` interface. This is used to process any collation URIs found in the stylesheet, returning an object of class `StringCollator` that implements the requested collation.
COLLATION_URI_RESOLVER_CLASS	The name of a user-written class implementing Saxon's `CollationURIResolver` interface. The class is instantiated and the resulting instance is used as the value of the COLLATION_URI_RESOLVER property.
COLLECTION_URI_RESOLVER	An instance of a user-written class implementing Saxon's `CollectionURIResolver` interface. This is used to process any URIs used in calls to the `collection()` function. The `CollectionURIResolver` may either return a sequence of URIs (which are then resolved in the same way as URIs passed to the `doc()` function), or it may return a sequence of (typically document) nodes.
COLLECTION_URI_RESOLVER_CLASS	The name of a user-written class implementing Saxon's `CollectionURIResolver` interface. The class is instantiated and the resulting instance is used as the value of the COLLECTION_URI_RESOLVER property.
COMPILE_WITH_TRACING	A Boolean. If run-time tracing of stylesheet execution is required, then the code must be compiled with tracing enabled. Default is false. (Switching tracing on at run-time is done by providing a `TraceListener` to the `Controller` object, which is Saxon's implementation of the JAXP `Transformer`.)
DTD_VALIDATION	A Boolean. If true, the XML parser is requested to perform validation of source documents against their DTD. Default is false.
EXPAND_ATTRIBUTE_DEFAULTS	A Boolean. If true, default attribute values found in a schema or DTD are expanded (both on input and on output documents, if validation is requested). Default is true. It is always possible to switch this off for schema validation, but not all XML parsers allow it to be switched off in the case of DTD validation.
LINE_NUMBERING	A Boolean. Default is false. If true, line and column number information is retained for all source documents. This is accessible using the `saxon:line-number()` and `saxon:column-number()` extension functions. Note that the information is only as good as the XML parser supplies. SAX parsers generally report the position of an element node using the line and column number of the ">" character that forms the last character of the start tag.
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.
MODULE_URI_RESOLVER	Affects XQuery only. An instance of a user-written class implementing Saxon's `ModuleURIResolver` interface. This is used to process any URIs used in `import module` directives in XQuery.
MODULE_URI_RESOLVER_CLASS	Affects XQuery only. The name of a user-written class implementing Saxon's `ModuleURIResolver` interface. This is used to process any URIs used in `import module` directives in XQuery.
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.
OPTIMIZATION_LEVEL	A string whose value is an integer in the range 0 (no optimization) to 10 (full optimization); currently all values other than 0 result in full optimization but this is likely to change in future. The default is full optimization; this feature allows optimization to be suppressed in cases where reducing compile time is important, or where optimization gets in the way of debugging, or causes extension functions with side-effects to behave unpredictably. (Note however, that even with no optimization, lazy evaluation may still cause the evaluation order to be not as expected.)
OUTPUT_URI_RESOLVER	An instance of the class `OutputURIResolver`; this object will be used to resolve URIs of secondary result documents specified in the `href` attribute of the `xsl:result-document` instruction
OUTPUT_URI_RESOLVER_CLASS	The name of a class that implements `OutputURIResolver`; Saxon will instantiate this class and use the resulting `OutputURIResolver` to resolve URIs of secondary result documents specified in the `href` attribute of the `xsl:result-document` instruction
PRE_EVALUATE_DOC_FUNCTION	A Boolean. If true, calls on the `doc()` and `document()` functions, if their arguments are known at compile time, will be evaluated at compile time, and the resulting document will be stored as part of the Saxon `Configuration` and shared by all queries and transformations running within that Configuration. Useful for reference documents that have stable content and are used by many different queries and transformations. Default is false, which means each query or transformation will reload the document from disc.
RECOGNIZE_URI_QUERY_PARAMETERS	A Boolean: true if the the standard URI resolver is to recognize query parameters included in the URI (for example, `?val=strict`). Such parameters can then be used in URIs passed to the `doc()` or `document()` functions. For details of the query parameters available, see Source Documents
RECOVERY_POLICY	An Integer, 0, 1, or 2. Indicates the policy for handling dynamic errors that the XSLT specification defines as recoverable. 0 means recover silently; 1 means recover after signalling a warning to the ErrorListener; 2 means treat the error as fatal. An example of a recoverable error is when two template rules match the same node. These are available as constants in the `Configuration` class: RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER
RECOVERY_POLICY_NAME	A string "recoverSilently", "recoverWithWarnings", or "doNotRecover". Indicates the policy for handling dynamic errors that the XSLT specification defines as recoverable. "recoverSilently" means recover silently; "recoverWithWarnings" means recover after signalling a warning to the ErrorListener; "doNotRecover" means treat the error as fatal. An example of a recoverable error is when two template rules match the same node.
SCHEMA_URI_RESOLVER	An instance of the class `SchemaURIResolver`; this object will be used to resolve URIs of schema documents referenced in `xsl:import-schema` declarations in XSLT, `import schema` in XQuery, references from one schema document to another using `xs:include` or `xs:import`, and references from an instance document to a schema using `xsi:schemaLocation`.
SCHEMA_URI_RESOLVER_CLASS	The name of a class that implements the interface `SchemaURIResolver`; this class will be instantiated and the resulting instance will be used as the value of the `SCHEMA_URI_RESOLVER` property.
SCHEMA_VALIDATION	An Integer. One of the symbolic constants Validation.STRIP, Validation.PRESERVE, Validation.LAX, Validation.STRICT. Indicates whether and how schema validation should be applied to source documents.
SCHEMA_VALIDATION_MODE	A string. One of the values "strict", "lax", "preserve", or "skip". Indicates whether and how schema validation should be applied to source documents.
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)
STRIP_WHITESPACE	A string. One of the values "all", "none", or "ignorable". Indicates whether all whitespace, no whitespace, or whitespace in elements defined in a DTD or schema as having element-only content should be stripped from source documents. Default is "ignorable". This whitespace stripping is additional to any stripping done as a result of the `xsl:strip-space` declaration in the stylesheet.
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)
TIMING	A Boolean: true if basic timing information is to be output to the standard error output stream.
TRACE_EXTERNAL_FUNCTIONS	A Boolean. If true, Saxon will output (to the standard error output) progress information about its attempts to locate and disambiguate references to external Java extension functions. Useful for diagnistics if you are having trouble with user-written extension functions.
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.
TRACE_LISTENER_CLASS	The name of a class that implements net.sf.saxon.trace.TraceListener. A new instance of this class will be created for each query or transformation run under the control of this Configuration. This TraceListener will be notified of significant events occurring during the transformation, for tracing or debugging purposes.
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.
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.
XINCLUDE	A Boolean. Indicates whether source documents should have any XInclude directives expanded. Default is false. This relies on support in the underlying XML parser.
XML_VERSION	An integer. Indicates the version of XML that is used for validating names and determining which characters are allowed. Values are 10 for XML 1.0, and 11 for XML 1.1. Default is currently 1.0, but may change.

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.