<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
   <head>
      <this-is section="using-xsl" page="embedding" subpage="jaxp-transformation"/>
      <!--
           Generated at 2010-10-29T18:20:48.427+01:00--><title>Saxonica: XSLT and XQuery Processing: Using JAXP for Transformations</title>
      <meta name="coverage" content="Worldwide"/>
      <meta name="copyright" content="Copyright Saxonica Ltd"/>
      <meta name="title"
            content="Saxonica: XSLT and XQuery Processing: Using JAXP for Transformations"/>
      <meta name="robots" content="noindex,nofollow"/>
      <link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
   </head>
   <body class="main">
      <h1>Using JAXP for Transformations</h1>
      <p>More information and examples relating to the JAXP transformation API can be found in the
<b>TraxExamples.java</b> example application found in the samples directory.</p>
      <p>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 <a class="bodylink" href="../../extensibility/function-result.xml">Saxon Extensibility</a>. If the resulting value
is an atomic value, it is cast to the required type of the parameter as specified in the
<code>xsl:param</code> 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.</p>
      <p>The JAXP <code>TransformerFactory</code> interface provides a configuration method
<code>setAttribute()</code> for setting implementation-defined configuration parameters. The
parameters supported by Saxon have names defined by constants in the class
<code>net.sf.saxon.FeatureKeys</code>. The names of these properties and their meanings, 
are described in the table below.</p>
      <p>Where the required value of a property is a Boolean, the supplied value may be either a <code>java.lang.Boolean</code>,
or a String holding the values "true" or "false". The returned value of the property, however, will be a <code>Boolean</code>.</p>
      <table>
         <tr>
            <td content="para">
               <p>
                  <b>property</b>
               </p>
            </td>
            <td content="para">
               <p>
                  <b>meaning</b>
               </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>ALLOW_EXTERNAL_FUNCTIONS</p>
            </td>
            <td content="para">
               <p>A Boolean. True if the stylesheet allows external functions to be called.
Default is true. The setting <code>false</code> is recommended in an environment
where untrusted stylesheets may be executed. Setting this value to <code>false</code>
also disables user-defined extension elements, together with the writing of multiple
output files (<code>xsl:result-document</code>), 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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>COLLATION_URI_RESOLVER</p>
            </td>
            <td content="para">
               <p>An instance of a user-written class implementing Saxon's <code>CollationURIResolver</code> interface. 
This is used to process any collation URIs
found in the stylesheet, returning an object of class <code>StringCollator</code> that implements the requested
collation.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>COLLATION_URI_RESOLVER_CLASS</p>
            </td>
            <td content="para">
               <p>The name of a user-written class implementing Saxon's <code>CollationURIResolver</code> interface. 
The class is instantiated and the resulting instance is used as the value of the COLLATION_URI_RESOLVER property.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>COLLECTION_URI_RESOLVER</p>
            </td>
            <td content="para">
               <p>An instance of a user-written class implementing Saxon's <code>CollectionURIResolver</code> interface. 
This is used to process any  URIs used in calls to the <code>collection()</code> function. 
The <code>CollectionURIResolver</code> may either return a sequence of URIs (which are then resolved
in the same way as URIs passed to the <code>doc()</code> function), or it may return a sequence of
(typically document) nodes.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>COLLECTION_URI_RESOLVER_CLASS</p>
            </td>
            <td content="para">
               <p>The name of a user-written class implementing Saxon's <code>CollectionURIResolver</code> interface. 
The class is instantiated and the resulting instance is used as the value of the COLLECTION_URI_RESOLVER property.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>COMPILE_WITH_TRACING</p>
            </td>
            <td content="para">
               <p>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
<code>TraceListener</code> to the <code>Controller</code> object, which is Saxon's implementation
of the JAXP <code>Transformer</code>.)</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>DTD_VALIDATION</p>
            </td>
            <td content="para">
               <p>A Boolean. If true, the XML parser is requested to perform validation of source
documents against their DTD. Default is false.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>EXPAND_ATTRIBUTE_DEFAULTS</p>
            </td>
            <td content="para">
               <p>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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>LINE_NUMBERING</p>
            </td>
            <td content="para">
               <p>A Boolean. Default is false. If true, line and column number information is retained for all source documents.
This is accessible using the <code>saxon:line-number()</code> and <code>saxon:column-number()</code> 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 "&gt;" character that forms the last character of the start tag.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>MESSAGE_EMITTER_CLASS</p>
            </td>
            <td content="para">
               <p>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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>MODULE_URI_RESOLVER</p>
            </td>
            <td content="para">
               <p>Affects XQuery only. An instance of a user-written class implementing Saxon's <code>ModuleURIResolver</code> interface. 
This is used to process any  URIs used in <code>import module</code> directives in XQuery. </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>MODULE_URI_RESOLVER_CLASS</p>
            </td>
            <td content="para">
               <p>Affects XQuery only. The name of a user-written class implementing Saxon's <code>ModuleURIResolver</code> interface. 
This is used to process any URIs used in <code>import module</code> directives in XQuery. </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>NAME_POOL</p>
            </td>
            <td content="para">
               <p>A instance of class <code>net.sf.saxon.om.NamePool</code>. 
Indicates that the supplied NamePool should be used as the target (run-time) NamePool by all
stylesheets compiled (using <code>newTemplates()</code>) after this call on <code>setAttribute</code>.
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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>OPTIMIZATION_LEVEL</p>
            </td>
            <td content="para">
               <p>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.) </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>OUTPUT_URI_RESOLVER</p>
            </td>
            <td content="para">
               <p>An instance of the class <code>OutputURIResolver</code>; this object will be used to resolve URIs
of secondary result documents specified in the <code>href</code> attribute of the <code>xsl:result-document</code>
instruction</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>OUTPUT_URI_RESOLVER_CLASS</p>
            </td>
            <td content="para">
               <p>The name of a class that implements <code>OutputURIResolver</code>; Saxon will instantiate this 
class and use the resulting <code>OutputURIResolver</code> to resolve URIs
of secondary result documents specified in the <code>href</code> attribute of the <code>xsl:result-document</code>
instruction</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>PRE_EVALUATE_DOC_FUNCTION</p>
            </td>
            <td content="para">
               <p>A Boolean. If true, calls on the <code>doc()</code> and <code>document()</code> 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 <code>Configuration</code> 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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>RECOGNIZE_URI_QUERY_PARAMETERS</p>
            </td>
            <td content="para">
               <p>A Boolean: true if the the standard URI resolver is to recognize query parameters
included in the URI (for example, <code>?val=strict</code>). Such parameters can then be used in URIs
passed to the <code>doc()</code> or <code>document()</code> functions. For details of the query parameters
available, see <a class="bodylink" href="../../sourcedocs/intro.xml">Source Documents</a>
               </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>RECOVERY_POLICY</p>
            </td>
            <td content="para">
               <p>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 <code>Configuration</code>
class: RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>RECOVERY_POLICY_NAME</p>
            </td>
            <td content="para">
               <p>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. </p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>SCHEMA_URI_RESOLVER</p>
            </td>
            <td content="para">
               <p>An instance of the class <code>SchemaURIResolver</code>; this object will be used to resolve URIs
of schema documents referenced in <code>xsl:import-schema</code> declarations in XSLT, <code>import schema</code> in
XQuery, references from one schema document to another using <code>xs:include</code> or <code>xs:import</code>,
and references from an instance document to a schema using <code>xsi:schemaLocation</code>.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>SCHEMA_URI_RESOLVER_CLASS</p>
            </td>
            <td content="para">
               <p>The name of a class that implements the interface <code>SchemaURIResolver</code>; 
this class will be instantiated and the resulting instance will be used as the value of the 
<code>SCHEMA_URI_RESOLVER</code> property.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>SCHEMA_VALIDATION</p>
            </td>
            <td content="para">
               <p>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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>SCHEMA_VALIDATION_MODE</p>
            </td>
            <td content="para">
               <p>A string. One of the values "strict", "lax", "preserve", or "skip". 
Indicates whether and how schema validation should be applied to source documents.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>SOURCE_PARSER_CLASS</p>
            </td>
            <td content="para">
               <p>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)</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>STRIP_WHITESPACE</p>
            </td>
            <td content="para">
               <p>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 <code>xsl:strip-space</code>
declaration in the stylesheet.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>STYLE_PARSER_CLASS</p>
            </td>
            <td content="para">
               <p>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)</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>TIMING</p>
            </td>
            <td content="para">
               <p>A Boolean: true if basic timing information is to be output to the standard error output stream.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>TRACE_EXTERNAL_FUNCTIONS</p>
            </td>
            <td content="para">
               <p>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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>TRACE_LISTENER</p>
            </td>
            <td content="para">
               <p>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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>TRACE_LISTENER_CLASS</p>
            </td>
            <td content="para">
               <p>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.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>TREE_MODEL</p>
            </td>
            <td content="para">
               <p>An Integer: Builder.STANDARD_TREE or Builder.TINY_TREE. Selects an implementation of the
Saxon tree model. The default is Builder.TINY_TREE.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>VALIDATION_WARNINGS</p>
            </td>
            <td content="para">
               <p>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-EE only.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>VERSION_WARNING</p>
            </td>
            <td content="para">
               <p>A Boolean. Indicates whether a warning message should be notified (to the ErrorListener) if
running against a stylesheet that specifies <code>version="1.0"</code>. This warning is output by default (because
the W3C specification requires it), but it may be suppressed using this option.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>XINCLUDE</p>
            </td>
            <td content="para">
               <p>A Boolean. Indicates whether source documents should have any XInclude directives
expanded. Default is false. This relies on support in the underlying XML parser.</p>
            </td>
         </tr>
         <tr>
            <td content="para">
               <p>XML_VERSION</p>
            </td>
            <td content="para">
               <p>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.</p>
            </td>
         </tr>
      </table>
      <p>Saxon's implementation of the JAXP <code>Transformer</code> interface is the class <code>net.sf.saxon.Controller</code>.
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 <code>Transformer</code> to a <code>Controller</code>. The methods are described in the JavaDoc documentation
supplied with the product.</p>
      <p>When using the JAXP interface, you can set serialization properties using a <code>java.util.Properties</code>
object. The names of the core XSLT 1.0 properties, such as <code>method</code>, <code>encoding</code>,
and <code>indent</code>, are defined in the JAXP class <code>javax.xml.transform.OutputKeys</code>. 
Additional properties, including Saxon extensions and XSLT 2.0 extensions, have names defined by
constants in the class <code>net.sf.saxon.event.SaxonOutputKeys</code>. The values of the properties
are exactly as you would specify them in the <code>xsl:output</code> declaration.</p>
      <table width="100%">
         <tr>
            <td>
               <p align="right"><a class="nav" href="../performanceanalysis.xml">Next</a></p>
            </td>
         </tr>
      </table>
   </body>
</html>