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

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 `Controller` 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. These are available as constants in the `Controller` class: RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER

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.

Next