Project

Profile

Help

How to connect?
Download (42.7 KB) Statistics
| Branch: | Revision:

he / src / userdoc / configuration.xml @ 7728ae0b

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="configuration" title="Saxon Configuration">
3
   <h1>Saxon Configuration</h1>
4

    
5

    
6
   <p>There are many parameters and options that can be set to control the way in which Saxon
7
      options can be set. This section of the documentation brings this information together in one place.</p>
8

    
9
   <nav>
10
      <ul/>
11
   </nav>
12

    
13
   <section id="config-interfaces" title="Configuration interfaces">
14
      <h1>Configuration interfaces</h1>
15

    
16

    
17
      <p>At the heart of Saxon is the object <a class="javalink" href="net.sf.saxon.Configuration">net.sf.saxon.Configuration</a>. This contains all the current
18
         settings of configuration options. All Saxon tasks, such as compiling and running queries and transformations, or building and validating source
19
         documents, happen under the control of a <code>Configuration</code>. Many resources are owned by the <code>Configuration</code>, meaning that related
20
         tasks must run under the same <code>Configuration</code>. Most notably, the <code>Configuration</code> holds a <a class="javalink"
21
            href="net.sf.saxon.om.NamePool">NamePool</a>, which is a table allocating integer codes to the qualified names that appear in stylesheets, queries,
22
         schemas, and source documents, and during the execution of a stylesheet or query all the resources used (for example, the stylesheet, all its input
23
         documents, and any schemas it uses) must all use the same <code>NamePool</code> to ensure that they all use the same integer codes for the same
24
         qualified names. However, two Saxon tasks that are unrelated can run under different <code>Configuration</code> objects.</p>
25

    
26
      <p>There are subclasses of <code>Configuration</code> containing resources associated with the capabilities of the different Saxon editions: specifically,
27
            <a class="javalink" href="com.saxonica.config.ProfessionalConfiguration">com.saxonica.config.ProfessionalConfiguration</a> and <a class="javalink"
28
            href="com.saxonica.config.EnterpriseConfiguration">com.saxonica.config.EnterpriseConfiguration</a>. In many cases the <code>Configuration</code> is
29
         used as a factory class to deliver services associated with the different capability levels, for example the method <code>getOptimizer()</code> returns
30
         the query optimizer appropriate to the loaded Saxon edition.</p>
31

    
32
      <p>Many configuration options have direct setter and getter methods on the <code>Configuration</code> object, for example
33
            <code>setAllowExternalFunctions()</code> and <code>isAllowExternalFunctions()</code>. Some other options have setters and getters on objects
34
         reachable from the <code>Configuration</code>, for example defaults for XSLT processing can be controlled using methods such as
35
            <code>getDefaultXsltCompilerInfo().setXsltVersion()</code>, while defaults for XQuery processing can be controlled using methods such as
36
            <code>getDefaultStaticQueryContext().setLanguageVersion()</code>.</p>
37
      
38
      <p>The most general mechanism for getting and setting configuration properties, however, is provided by the methods
39
         <code>getConfigurationProperty(Feature)</code> and <code>setConfigurationProperty(Feature,
40
            value)</code>. In these methods the property to be read or written is identified by a
41
         <a class="javalink" href="net.sf.saxon.lib.Feature">net.sf.saxon.lib.Feature</a> object,
42
         typically one of the objects defined as static constants, for example
43
         <code>Feature.ALLOW_EXTERNAL_FUNCTIONS</code>. The Feature object is also parameterized by
44
         the type of value required, for example <code>Feature.ALLOW_EXTERNAL_FUNCTIONS</code> is a
45
         <code>Feature&lt;Boolean&gt;</code>. Internally, the <code>Feature</code> object defines
46
         both a unique integer code for the feature, and a unique string in the form of a URI (for
47
         example, <code>"http://saxon.sf.net/feature/allowExternalFunctions"</code>). In some
48
         interfaces, for example the JAXP <code>TransformerFactory</code>, configuration options are identified
49
         by strings, and the required strings can be accessed using the <code>name</code> property of the
50
         <code>Feature</code>, for example <code>net.sf.saxon.lib.Feature.ALLOW_EXTERNAL_FUNCTIONS.name</code>.
51
         For backwards compatibility reasons, these strings are also available as constants in the class
52
         <a class="javalink" href="net.sf.saxon.lib.FeatureKeys">net.sf.saxon.lib.FeatureKeys</a>.</p>
53
      
54
      <p>On command line interfaces such as <code>net.sf.saxon.Transform</code>, configuration
55
         options can be supplied using the form <code>--name:value</code>. Here <code>name</code> is
56
         the part of the URI after the final "/", for example <code>allowExternalFunctions</code>,
57
         and the <code>value</code> must be supplied as a string. In such cases, and in other cases
58
         where values must be supplied as strings (for example the
59
         <code>xslt/factory/attribute</code> element in Ant), Saxon accepts the strings "true", "1",
60
         "yes", "on", or "false", "0", "no", "off", to represent booleans.</p>
61

    
62
      <p>For backwards compatibility, the <code>Configuration</code> class continues to support the methods 
63
            <code>getConfigurationProperty(name)</code> and <code>setConfigurationProperty(name, value)</code>. In these methods the name of the configuration
64
         property is always a string in the form of a URI (for example, <code>"http://saxon.sf.net/feature/initialTemplate"</code>), and the strings available
65
         are all defined by constants in the class <a class="javalink" href="net.sf.saxon.lib.FeatureKeys">net.sf.saxon.lib.FeatureKeys</a> (for example,
66
            <code>FeatureKeys.INITIAL_TEMPLATE</code>). The value is of various types depending on the property. In the vast majority of cases, the property can
67
         be supplied as a string, or it has an alternative, equivalent property that can be supplied as a string. For properties that are essentially boolean in
68
         nature the value can be supplied either as one of the Java constants <code>Boolean.TRUE</code> or <code>Boolean.FALSE</code>, or as one of the strings
69
         "true", "1", "yes", "on", or "false", "0", "no", "off". These choices are designed to suit the conventions of different APIs in which the configuration
70
         options are exposed.</p>
71

    
72
      <p>In many APIs for controlling Saxon activities, the <code>Configuration</code> object is not exposed directly, but is hidden below some similar object
73
         acting as the root object for that particular API. Many of these objects provide a direct way to set the configuration options. These are discussed in
74
         the following sections.</p>
75

    
76
      <nav>
77
         <ul/>
78
      </nav>
79

    
80
      <section id="jaxp-configuration" title="JAXP Factory Interfaces">
81
         <h1>JAXP Factory Interfaces</h1>
82

    
83

    
84
         <p>Saxon implements a number of JAXP interfaces, notably the APIs for transformation, XPath processing, and validation.</p>
85
         
86
         <h2>XSLT</h2>
87
         
88
         <p>For transformation, the root object of the API is the JAXP <code>TransformerFactory</code>. Saxon provides several implementations of this interface:</p>
89
         
90
         <ul>
91
            <li>For any Saxon edition: <a class="javalink" href="net.sf.saxon.TransformerFactoryImpl">net.sf.saxon.TransformerFactoryImpl</a>. This creates
92
            the "highest possible" configuration based on what software is in use (without taking into account what license file is deployed). An application
93
            creating an instance of this class can therefore use Saxon-PE or Saxon-EE facilities if they are available.</li>
94
            
95
            <li>For Saxon-HE: <a class="javalink" href="net.sf.saxon.BasicTransformerFactory">net.sf.saxon.BasicTransformerFactory</a>. This strictly
96
            disables all Saxon-PE and Saxon-EE features.</li>
97
            <li>For Saxon-PE: <a class="javalink" href="com.saxonica.config.ProfessionalTransformerFactory">com.saxonica.config.ProfessionalTransformerFactory</a></li>
98
            <li>For Saxon-EE: <a class="javalink" href="com.saxonica.config.EnterpriseTransformerFactory">com.saxonica.config.EnterpriseTransformerFactory</a></li>
99
            <li>For streaming with Saxon-EE: <a class="javalink" href="com.saxonica.config.StreamingTransformerFactory">com.saxonica.config.StreamingTransformerFactory</a>.
100
            This <code>TransformerFactory</code> does not fully comply with the JAXP specifications, because (in the interests of enabling streaming) it does not set
101
            the global context item to the root node of the source document; if any global variables in the stylesheet refer to the context item, this will
102
            cause a streaming failure.</li>
103
         </ul>
104
         
105
         <p>The JAXP static method <code>TransformerFactory.newInstance()</code> searches the classpath for a JAR file containing a manifest that identifies
106
            it as a JAXP transformation engine. If it finds Saxon-HE on the classpath, it will instantiate <code>net.sf.saxon.TransformerFactoryImpl</code>;
107
            if it finds Saxon-PE, then <code>ProfessionalTransformerFactory</code>; if Saxon-EE, then <code>EnterpriseTransformerFactory</code>.</p>
108
         
109
         <aside>The JAXP classpath search is time-consuming, and creates the danger that the application will fail if the classpath is configured incorrectly.
110
         Saxonica recommends instantiating the desired <code>TransformerFactory</code> directly, using its own constructor, or by naming the class as the
111
            first argument of the <code>TransformerFactory.newInstance()</code> method. Better still, use the s9api interface.</aside>
112
               
113
         <p>The <code>TransformerFactory</code> interface provides methods <code>getAttribute(name)</code> and <code>setAttribute(name, value)</code> which correspond directly
114
            to the methods <code>getConfigurationProperty(name)</code> and <code>setConfigurationProperty(name, value)</code> on the underlying <a
115
               class="javalink" href="net.sf.saxon.Configuration">Configuration</a> object. By casting from the JAXP interface to the Saxon implementation class
116
            it is also possible to call the <code>getConfiguration</code> method which exposes the <code>Configuration</code> object directly.</p>
117

    
118
         <p>The Saxon-PE and Saxon-EE implementations of the <code>TransformerFactory</code> also allow the configuration property <a class="bodylink code"
119
               href="/configuration/config-features">Feature.CONFIGURATION_FILE.name</a> to be set. The value is a filename containing the name of a
120
            configuration file, which must have the format described in <a class="bodylink" href="/configuration/configuration-file">Configuration file</a>.
121
            This causes any previously-initialized configuration to be discarded, and replaced with a new <code>Configuration</code> object built from the
122
            settings in the specified configuration file.</p>
123

    
124
         <h2>XPath</h2>
125
         
126
         <p>Saxon implements the JAXP XPath interface <code>javax.xml.xpath.XPathFactory</code>; the implementation class is <a class="javalink"
127
               href="net.sf.saxon.xpath.XPathFactoryImpl">net.sf.saxon.xpath.XPathFactoryImpl</a>.</p>
128
         
129
         <p>However, the Saxon JAR files do not contain the manifest information that causes Saxon to be picked up as an XPath implementation by the factory method
130
         <code>XPathFactory.newInstance()</code>; it must be instantiated directly. This is because an application calling this method is probably expecting to
131
         find an XPath 1.0 engine, and is very likely to fail in some way if an XPath 3.1 engine is returned.</p>
132
         
133
         <p>The JAXP <code>XPathFactory</code> interface is designed very much around (a) the XPath 1.0 type system, and (b) the DOM as the expected tree model. In addition,
134
            it only works with Saxon if the <a class="javalink" href="net.sf.saxon.Configuration">Configuration</a> that underpins the <code>XPathFactory</code> is the same as the <code>Configuration</code>
135
            used to build the source document. Use of this interface with Saxon is therefore not very satisfactory, and the s9api interface is strongly preferred.</p>
136

    
137
         <p>The JAXP <code>XPathFactory</code> interface has a general-purpose configuration mechanism in the form of the two methods <code>setFeature()</code>
138
            and <code>getFeature()</code>. These can be used to set/get all boolean-valued configuration options in the underlying Saxon <a class="javalink"
139
               href="net.sf.saxon.Configuration">Configuration</a>, as well as the options defined in the JAXP interface itself. To set configuration options
140
            that are not boolean-valued, it is necessary to navigate to the underlying <code>Configuration</code> object and use its native interfaces. Saxon's
141
            implementation class for the <code>XPathFactory</code> is <code>net.sf.saxon.xpath.XPathFactoryImpl</code>, regardless which Saxon edition is in use.</p>
142

    
143
         <h2>XSD (Schema processing)</h2>
144

    
145
         <p>Saxon-EE also implements the JAXP <code>SchemaFactory</code> in class <a class="javalink" href="com.saxonica.ee.jaxp.SchemaFactoryImpl"
146
               >com.saxonica.ee.jaxp.SchemaFactoryImpl</a>. The interface offers methods <code>getProperty(name)</code> and <code>setProperty(name,
147
               value)</code> which map to the underlying methods in the Saxon <code>Configuration</code>; again, it is also possible to cast to the Saxon
148
            implementation class and call configuration-setting methods directly.</p>
149

    
150
      </section>
151
      <section id="s9api-config" title="Configuration using s9api">
152
         <h1>Configuration using s9api</h1>
153

    
154

    
155
         <p>In Saxon's s9api interface the root API object is the <a class="javalink" href="net.sf.saxon.s9api.Processor">net.sf.saxon.s9api.Processor</a>
156
            object. This again is a wrapper around a <a class="javalink" href="net.sf.saxon.Configuration">Configuration</a>. All the configuration properties
157
            are exposed via the <code>Processor</code> methods <code>getConfigurationProperty(Feature)</code> and <code>setConfigurationProperty(Feature,
158
               value)</code> which map directly to the same methods on the underlying <code>Configuration</code>.</p>
159

    
160
         <p>The s9api <code>Processor</code> object also has a constructor <code>new Processor(source)</code> which allows the underlying
161
               <code>Configuration</code> to be built from a supplied configuration file. The argument is a <code>org.xml.sax.Source</code> object, for example
162
            a <code>StreamSource</code>, which identifies the configuration file, which must have the format described in <a class="bodylink"
163
               href="/configuration/configuration-file">Configuration file</a>.</p>
164

    
165
         <p>In many cases with s9api it is more appropriate to set options at a finer level of granularity than the <code>Processor</code>. For example, options
166
            that affect XSLT stylesheet compilation can be set on the <a class="javalink" href="net.sf.saxon.s9api.XsltCompiler">XsltCompiler</a> object, and
167
            options that affect XQuery compilation on the <a class="javalink" href="net.sf.saxon.s9api.XQueryCompiler">XQueryCompiler</a>. Some more specialized
168
            configuration options are not exposed directly by these two classes, but can be tailored by accessing the underlying support objects: <a
169
               class="javalink" href="net.sf.saxon.trans.CompilerInfo">CompilerInfo</a> in the case of XSLT, and <a class="javalink"
170
               href="net.sf.saxon.query.StaticQueryContext">StaticQueryContext</a> in the case of XQuery.</p>
171
        
172
        <aside>When s9api was introduced, the name stood for "Saxon 9 Application Programming Interface.
173
          It's a nice snappy name, so we've retained it unchanged for Saxon 10.</aside>
174
      </section>
175

    
176
      <section id="config-dotnet" title="Configuration using the .NET API">
177
         <h1>Configuration using the .NET API</h1>
178

    
179

    
180

    
181
         <p>In Saxon's Saxon.Api interface on .NET, the root API object is the <a class="javalink" href="Saxon.Api.Processor">Saxon.Api.Processor</a> object.
182
            This again is a wrapper around a <a class="javalink" href="net.sf.saxon.Configuration">Configuration</a>. All the configuration properties are
183
            exposed via the <code>Processor</code> methods <code>getProperty(name)</code> and <code>setProperty(name, value)</code> which map directly to the
184
            methods <code>getConfigurationProperty(name)</code> and <code>setConfigurationProperty(name, value)</code> on the underlying
185
               <code>Configuration</code>.</p>
186

    
187
         <p>The Saxon.Api <code>Processor</code> object also has a constructor <code>new Processor(stream)</code> which allows the underlying
188
               <code>Configuration</code> to be built from a supplied configuration file, which must have the format described in <a class="bodylink"
189
               href="/configuration/configuration-file">Configuration file</a>. Configuration files are available only in Saxon-PE and Saxon-EE.</p>
190

    
191
         <p>In many cases with the Saxon.Api interface it is more appropriate to set options at a finer level of granularity than the <code>Processor</code>.
192
            For example, options that affect XSLT stylesheet compilation can be set on the <a class="javalink" href="Saxon.Api.XsltCompiler">XsltCompiler</a>
193
            object, and options that affect XQuery compilation on the <a class="javalink" href="Saxon.Api.XQueryCompiler">XQueryCompiler</a>.</p>
194
      </section>
195

    
196
      <section id="config-commandline" title="Configuration from the command line">
197
         <h1>Configuration from the command line</h1>
198

    
199
         <p>The main command-line interfaces to Saxon are <a class="javalink" href="net.sf.saxon.Transform">net.sf.saxon.Transform</a> for running a
200
            transformation, <a class="javalink" href="net.sf.saxon.Query">net.sf.saxon.Query</a> for running XQuery, and <a class="javalink"
201
               href="com.saxonica.Validate">com.saxonica.Validate</a> for validating a document against a schema. These commands allow many
202
            configuration options to be specified by command line options: for example if XML Schema 1.1 support is wanted, all three
203
            commands allow this to be requested using the option <code>-xsdversion:1.1</code> (the
204
            default from Saxon 9.8). Many of these options correspond directly to the configuration
205
            properties available on the <a class="javalink" href="net.sf.saxon.Configuration">Configuration</a> object.</p>
206
         
207
         <p>For full details, including lists of the available command line options for each of
208
            these interfaces, see the following:</p>
209
         <ul><li><a class="bodylink" href="/using-xsl/commandline">Running XSLT from the Command Line</a></li>
210
            <li><a class="bodylink" href="/using-xquery/commandline">Running XQuery from the Command Line</a></li>
211
            <li><a class="bodylink" href="/schema-processing/commandline">Running Validation from the Command Line</a></li>
212
         </ul>
213

    
214
         <p>For more specialized options, there is also a fallback mechanism. Each configuration property has a URI, which is always of the form
215
               <code>http://saxon.sf.net/feature/SOME_NAME</code>. Provided the property allows a string value (as most do), the property can be set from the
216
            command line using the syntax <code>--SOME_NAME:value</code>. For example the property identified by <a class="bodylink code"
217
               href="/configuration/config-features">Feature.LICENSE_FILE_LOCATION</a> has the URI
218
               <code>http://saxon.sf.net/feature/licenseFileLocation</code>, and it can therefore be set on the command line using an option such as
219
               <code>--licenseFileLocation:c:/saxon/license.lic</code>. </p>
220

    
221
         <aside>For boolean-valued configuration properties, Saxon accepts any of the values "yes", "on", "true", or "1" to switch the option on, or "no",
222
            "off", "false", or "0" to switch it off.</aside>
223
      </section>
224
      <section id="config-xqj" title="Configuration using XQJ">
225
         <h1>Configuration using XQJ</h1>
226

    
227
         <p>The root object in the XQJ (XQuery for Java) API is <code>javax.xml.query.XQDataSource</code>, and the Saxon implementation class is <a
228
               class="javalink" href="com.saxonica.xqj.SaxonXQDataSource">com.saxonica.xqj.SaxonXQDataSource</a>. The <code>XQDataSource</code> provides methods
229
               <code>getProperty(name)</code> and <code>setProperty(name, value)</code>. In these
230
            calls, the name is the URI-valued string associated with one of the <a
231
               class="javalink" href="net.sf.saxon.lib.Feature">net.sf.saxon.lib.Feature</a>
232
            constants.</p>
233

    
234
         <p>There is a glitch however. The XQJ specifications mandate that the properties available through this interface should also have
235
            explicit getters and setters: for example if a property named "lineNumbering" is available, then there should be a pair of methods
236
               <code>setLineNumbering()</code> and <code>getLineNumbering()</code>. This does not square well with the use of URIs for property names. Secondly,
237
            XQJ requires that the property values should be strings. Saxon therefore:</p>
238

    
239
         <ol>
240
            <li>
241
               <p>exposes a subset of commonly-used configuration properties using shortened names such as <code>dtdValidation</code> and
242
                     <code>retainLineNumbers</code></p>
243
            </li>
244
            <li>
245
               <p>provides getters and setters for these properties, as required by the XQJ specification</p>
246
            </li>
247
            <li>
248
               <p>lists the names of the above properties (only) in the result of the method <code>getSupportedPropertyNames()</code></p>
249
            </li>
250
            <li>
251
               <p>makes all other configuration properties available using URIs as the name, without providing getters and setters, and without listing the
252
                  names in the result of <code>getSupportedPropertyNames()</code>, provided that the value can be represented as a string. Boolean values can be
253
                  represented using any of the strings ("yes", "on", "true", or "1"), or ("no", "off", "false", or "0").</p>
254
            </li>
255
         </ol>
256

    
257
      </section>
258
      <section id="config-ant" title="Configuration when running Ant">
259
         <h1>Configuration when running Ant</h1>
260

    
261
         <p>It is possible to run XSLT transformations from Ant using the <code>xslt</code> task, selecting Saxon as the XSLT processor by setting the
262
               <code>factory</code> child element to the Saxon implementation class of <code>javax.xml.transform.TransformerFactory</code>; that is one of <a
263
               class="javalink" href="net.sf.saxon.TransformerFactoryImpl">net.sf.saxon.TransformerFactoryImpl</a>, <a class="javalink"
264
               href="com.saxonica.config.ProfessionalTransformerFactory">com.saxonica.config.ProfessionalTransformerFactory</a>, or <a class="javalink"
265
               href="com.saxonica.config.EnterpriseTransformerFactory">com.saxonica.config.EnterpriseTransformerFactory</a> depending on the Saxon edition in
266
            use.</p>
267

    
268
         <p>Additional configuration options can be specified using the <code>attribute</code> child of the <code>factory</code> element, for example the
269
            following task was used as part of the pipeline for publishing this documentation:</p>
270

    
271
         <samp><![CDATA[  <xslt in="${userdoc.dir}/src/function-data.xml"
272
        style="${userdoc.dir}/style/preprocess-functions.xsl"
273
        out="${userdoc.dir}/src/functions.xml"
274
        classpath="e:/saxon/eej/saxon-ee-10.0.jar;e:/saxon/eej/saxon-licenses">
275
        <factory name="com.saxonica.config.EnterpriseTransformerFactory">
276
            <attribute name="http://saxon.sf.net/feature/xsltSchemaAware" value="true"/>
277
            <attribute name="http://saxon.sf.net/feature/schema-validation-mode" value="strict"/>
278
            <attribute name="http://saxon.sf.net/feature/xsd-version" value="1.1"/>
279
        </factory>
280
  </xslt>]]></samp>
281
         <p>Many of the options available as configuration parameters (for example <a class="bodylink code" href="/configuration/config-features"
282
               >Feature.XSLT_INITIAL_TEMPLATE</a>) were provided explicitly with Ant in mind. The provision of these parameters makes the customized version
283
            of the Ant XSLT task provided with some earlier Saxon versions redundant, and the customized task is no longer supported.</p>
284
         
285
         <aside><p>One configuration property that is particularly useful when running Ant is 
286
            <code>http://saxon.sf.net/feature/ignoreSAXSourceParser</code>. Normally, Saxon attempts
287
         to set its own <code>EntityResolver</code> on the XML parser used for parsing source documents,
288
         because this allows commonly used DTDs and external entities to be fetched from Saxon's internal
289
         copies rather than from the web. However, when the application invoking Saxon supplies its own
290
         pre-configured XML parser, Saxon normally respects this and does not change the settings supplied.
291
         Ant, when it invokes Saxon, supplies an XML parser, so by default Saxon will not set its own
292
         <code>EntityResolver</code>. Setting the <code>ignoreSAXSourceParser</code> configuration option
293
         in an <code>attribute</code> child of the <code>factory</code> element overrides this. This can
294
         give dramatic performance improvements when using Ant to transform documents that contain references
295
         to these common W3C DTDs and entity files.</p></aside>
296
      </section>
297
   </section>
298
   <section id="configuration-file" title="Saxon configuration file">
299
      <h1>Saxon Configuration File</h1>
300

    
301
      <p>Configuration parameters for Saxon can be defined in a configuration file. This file is optional. It can be applied by using the option
302
            <code>-config:filename</code> on the <code>Transform</code>, <code>Query</code>, or <code>Validate</code> command line, or using the factory method
303
            <code>Configuration.readConfiguration()</code>.</p>
304
      <aside>A schema <code>config.xsd</code> for the configuration file, as well as example configuration files, are provided in the
305
            <code>samples/config</code> directory of the <code>saxon-resources</code> download.</aside>
306
      <p>In both the s9api interface on Java, and the Saxon.Api interface on .NET, there is a constructor on the <code>Processor</code> class that takes a
307
         configuration file as input.</p>
308
      <p>Here is an example configuration file. It is designed to show as many options as possible; in practice, no option needs to be included if it is to take
309
         its default value, and it is probably good practice to only include those parameters that you need to specify explicitly. Some of the example values
310
         used in this sample will not work unless you have files with the relevant names at particular locations, or unless you have classes with particular
311
         names available on your classpath; if such entries cause problems, you can always delete them.</p>
312
      <samp><![CDATA[<configuration xmlns="http://saxon.sf.net/ns/configuration"
313
               edition="EE"
314
               licenseFileLocation="saxon-license.lic"
315
               label="Some label">
316
  <global
317
    allowedProtocols="all"
318
    allowExternalFunctions="true"
319
    allowMultiThreading="true"
320
    allowOldJavaUriFormat="false"
321
    allowSyntaxExtensions="true"
322
    collectionFinder="net.sf.saxon.resource.StandardCollectionFinder"
323
    compileWithTracing="false"
324
    defaultCollation="http://www.w3.org/2005/xpath-functions/collation/codepoint"
325
    defaultCollection="file:///e:/temp"
326
    defaultRegexEngine="S"
327
    dtdValidation="false"
328
    dtdValidationRecoverable="true"
329
    eagerEvaluation="true"
330
    entityResolver="net.sf.saxon.lib.StandardEntityResolver"
331
    environmentVariableResolver=""
332
    errorListener="net.sf.saxon.lib.StandardErrorListener"
333
    expandAttributeDefaults="true"
334
    generateByteCode="true"
335
    ignoreSAXSourceParser="false"
336
    lazyConstructionMode="false"
337
    lineNumbering="true"
338
    markDefaultedAttributes="true"
339
    maxCompiledClasses="10000"
340
    monitorHotSpotByteCode="true"
341
    optimizationLevel="10"
342
    parser=""
343
    preEvaluateDoc="false"
344
    preferJaxpParser="true"
345
    recognizeUriQueryParameters="true"
346
    regexBacktrackingLimit="10000000"
347
    retainNodeForDiagnostics="false"
348
    schemaValidation="strict"
349
    serializerFactory=""
350
    sourceResolver=""
351
    stableCollectionUri="false"
352
    stableUnparsedText="false"
353
    standardErrorOutputFile="file:///e:/errorOutput.log"
354
    streamability="standard"
355
    streamingFallback="true"
356
    stripSpace="all"
357
    styleParser=""
358
    suppressEvaluationExpiryWarning="false"
359
    suppressXPathWarnings="false"
360
    suppressXsltNamespaceCheck="false"
361
    thresholdForFunctionInlining="100"
362
    thresholdForHotspotByteCode="100"
363
    timing="false"
364
    traceExternalFunctions="true"
365
    traceListener="net.sf.saxon.trace.XSLTTraceListener"
366
    traceOptimizerDecisions="false"
367
    treeModel="tinyTreeCondensed"
368
    unparsedTextURIResolver="net.sf.saxon.lib.StandardUnparsedTextResolver"
369
    uriResolver="net.sf.saxon.lib.StandardURIResolver"
370
    usePiDisableOutputEscaping="false"
371
    useTypedValueCache="true"
372
    validationComments="false"
373
    validationWarnings="true"
374
    versionOfXml="1.0"
375
    xInclude="false"
376
    xpathVersionForXsd="20"
377
    xpathVersionForXslt="31"
378
  />
379

    
380
  <xslt
381
    disableXslEvaluate="false"
382
    enableAssertions="false"
383
    initialMode=""
384
    initialTemplate=""
385
    messageEmitter=""
386
    outputUriResolver=""
387
    recoveryPolicy="recoverWithWarnings"
388
    resultDocumentThreads="10"
389
    schemaAware="false"
390
    staticErrorListener=""
391
    staticUriResolver=""
392
    styleParser="">
393
    <extensionElement namespace="http://saxon.sf.net/sql" 
394
      factory="net.sf.saxon.option.sql.SQLElementFactory"/>
395
  </xslt>
396
  
397
  <xsltPackages>
398
    <package name="http://package.one/" version="1.0" sourceLocation="packageOne.xsl" 
399
      exportLocation="packageOne.sef"/>
400
    <package name="http://package.one/" version="2.0-beta" sourceLocation="2.0beta/packageOne.xsl" 
401
      exportLocation="2.0beta/packageOne.sef"/>
402
    <package name="http://package.two/" version="8.6.3" sourceLocation="packageTwo.xsl">
403
       <withParam name="debug" select="true()"/>
404
       <withParam name="maxTransactions" select="300"/>
405
    </package>
406
  </xsltPackages>  
407

    
408
  <xquery
409
    allowUpdate="true"
410
    constructionMode="preserve"
411
    defaultElementNamespace=""
412
    defaultFunctionNamespace="http://www.w3.org/2005/xpath-functions"
413
    emptyLeast="true"
414
    inheritNamespaces="true"
415
    moduleUriResolver="net.sf.saxon.lib.StandardModuleURIResolver"
416
    multipleModuleImports="true"
417
    preserveBoundarySpace="false"
418
    preserveNamespaces="true"
419
    requiredContextItemType="document-node()"
420
    schemaAware="false"
421
    staticErrorListener=""
422
    />
423
    
424
  <xsd
425
    allowUnresolvedSchemaComponents="false"
426
    assertionsCanSeeComments="false"
427
    implicitSchemaImports="false"
428
    multipleSchemaImports="false"
429
    occurrenceLimits="100,250"
430
    schemaUriResolver="com.saxonica.config.ee.StandardSchemaResolver"
431
    thresholdForCompilingTypes="100"
432
    useXsiSchemaLocation="false"
433
    version="1.1"
434
  />
435
  
436
  <serialization
437
    method="xml"
438
    indent="yes"
439
    saxon:indent-spaces="8"
440
    xmlns:saxon="http://saxon.sf.net/"/>
441
    
442
  <localizations defaultLanguage="en" defaultCountry="US">
443
    <localization lang="da" class="net.sf.saxon.option.local.Numberer_da"/>
444
    <localization lang="de" class="net.sf.saxon.option.local.Numberer_de"/>
445
  </localizations>
446
  
447
  <resources>
448
    <externalObjectModel>net.sf.saxon.option.xom.XOMObjectModel</externalObjectModel>
449
    <extensionFunction>s9apitest.TestIntegrationFunctions$SqrtFunction</extensionFunction>
450
    <fileExtension extension="xq" mediaType="text/plain"/>
451
    <schemaDocument>file:///c:/MyJava/samples/data/books.xsd</schemaDocument>
452
    <schemaComponentModel/>
453
  </resources>
454
  
455
  <collations>
456
    <collation uri="http://www.w3.org/2005/xpath-functions/collation/codepoint" 
457
               class="net.sf.saxon.expr.sort.CodepointCollator"/>
458
    <collation uri="http://www.microsoft.com/collation/caseblind" 
459
               class="net.sf.saxon.expr.sort.CodepointCollator"/>
460
    <collation uri="http://example.com/french" lang="fr" ignore-case="yes"/>
461
  </collations>  
462
</configuration>
463
]]></samp>
464
      <p>The <code>configuration</code> element takes three possible attributes:</p>
465
      <ul>
466
         <li>
467
            <p>
468
               <code>edition</code>, whose value indicates the Saxon edition in use: HE (home edition), PE (professional edition), or EE (enterprise edition).
469
               The default value is HE. If PE or EE is specified, then the appropriate license file must be installed.</p>
470
         </li>
471
         <li>
472
            <p>
473
               <code>licenseFileLocation</code>, a URI identifying the location of the license file. This may be an absolute URI, or it may be relative to the base
474
            URI of the configuration file; it must use the <code>file</code> URI scheme. If the attribute is absent, then Saxon will search for a license file
475
            using the installed software location and the classpath in the usual way. For example, if the license file is in the same directory as the configuration
476
            file, specify <code>licenseFileLocation="saxon-license.lic"</code>.</p>
477
         </li>
478
         <li>
479
            <p><code>label</code>, being a label string that may be used to identify the configuration. Within the implementation the value of this label may be
480
               retrieved using <a class="javalink" href="net.sf.saxon.Configuration#getLabel">net.sf.saxon.Configuration.getLabel()</a><link/>. The default is
481
                  <code>null</code>.</p>
482
         </li>
483
      </ul>
484
      <p>The children of the <code>configuration</code> element may appear in any order.</p>
485
      <p>The contents of the different sections of the configuration file are described in the following subsections. </p>
486
      <nav>
487
         <ul/>
488
      </nav>
489
      <section id="config-global" title="The &lt;global&gt; element">
490
         <h1>The &lt;global&gt; element</h1>
491
         <p>The <code>global</code> input element of the configuration file contains properties defining global configuration options.</p>
492
         <xi:include href="featureKeys/ConfigFileDoc-global.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
493
      </section>
494
      <section id="config-xslt" title="The &lt;xslt&gt; element">
495
         <h1>The &lt;xslt&gt; element</h1>
496
         <p>The <code>xslt</code> element of the configuration file contains properties specific to XSLT. Remember that these are defaults; they can always be
497
            overridden for specific queries or transformations. An attribute whose value is set to a zero-length string is ignored: the effect is the same as
498
            omitting the attribute.</p>
499
         <xi:include href="featureKeys/ConfigFileDoc-xslt.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
500
         
501
         <p>The <code>xslt</code> element may also contain one or more <code>extensionElement</code> children defining namespaces used for extension instructions.
502
            Each <code>extensionElement</code> element must have the following attributes:</p>
503
         <xi:include href="featureKeys/ConfigFileDoc-extensionElement.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
504
      </section>
505
      <section id="config-xsltPackages" title="The &lt;xsltPackages&gt; element">
506
         <h1>The &lt;xsltPackages&gt; element</h1>
507
         <p>The <code>xsltPackages</code> element contains zero or more <code>package</code> elements, each of which defines an XSLT 3.0 package, or a version 
508
            of a package. The packages may be listed in any order.</p>
509
         <p>Each <code>package</code> element may have the following attributes:</p>
510
         <xi:include href="featureKeys/ConfigFileDoc-package.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
511
         
512
         <p>The <code>package</code> element may also have zero or more <code>withParam</code> children supplying values of static stylesheet parameters
513
            to be used during package compilation. If it is necessary to have different
514
            sets of parameter bindings for a package in the same configuration, this should be achieved by use of different versions, for example "1.0-streamable"
515
            versus "1.0-nonstreamable". </p>
516
         <p>Each <code>withParam</code> element must have the following attributes:</p>
517
         <xi:include href="featureKeys/ConfigFileDoc-withParam.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
518
         
519
         <p>The list of packages in the configuration file is used:</p>
520
         <ul>
521
            <li>When running XSLT from the command line, to resolve any packages used in <code>xsl:use-package</code> declarations.</li>
522
            <li>When compiling an XSLT package using the s9api <code>XsltCompiler</code>, to resolve any packages used in <code>xsl:use-package</code> declarations,
523
               unless they have already been compiled and imported explicitly using the same <code>XsltCompiler</code>.</li>
524
         </ul>
525
         
526
      </section>
527
      
528
      <section id="config-xquery" title="The &lt;xquery&gt; element">
529
         <h1>The &lt;xquery&gt; element</h1>
530
         <p>The <code>xquery</code> element of the configuration file contains properties specific to XQuery. Remember that these are defaults, they can always
531
            be overridden for specific queries. An attribute whose value is set to a zero-length string is ignored, the effect is the same as omitting the
532
            attribute.</p>
533
         <xi:include href="featureKeys/ConfigFileDoc-xquery.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
534
      </section>
535
      <section id="config-xsd" title="The &lt;xsd&gt; element">
536
         <h1>The &lt;xsd&gt; element</h1>
537
         <p>The <code>xsd</code> element of the configuration file contains properties defining how schema documents are compiled by Saxon. </p>
538
         <xi:include href="featureKeys/ConfigFileDoc-xsd.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
539
      </section>
540
      <section id="config-serialization" title="The &lt;serialization&gt; element">
541
         <h1>The &lt;serialization&gt; element</h1>
542
         <p>The <code>serialization</code> input element of the configuration file contains default serialization properties. These are
543
         used as defaults for serialization properties that are not present in an <a class="bodylink
544
            code" href="/xsl-elements/output">xsl:output</a> declaration in an XSLT stylesheet. They
545
         currently have no effect on serialization of secondary result documents, or on serialization of XQuery results. The values are used
546
         only at stylesheet compile time. When a stylesheet is loaded from a Stylesheet Export File, the serialization properties of the run-time
547
         configuration have no effect.</p>
548
         <xi:include href="featureKeys/ConfigFileDoc-serialization.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
549
      </section>
550
      <section id="config-resources" title="The &lt;resources&gt; element">
551
         <h1>The &lt;resources&gt; element</h1>
552
         <p>The <code>resources</code> element in the configuration file defines a number of resources that can be preloaded into the configuration. It contains
553
            child elements as detailed below, in any order; most of them can appear more than once.</p>
554
         <xi:include href="featureKeys/ConfigFileDoc-resources.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
555
         <p>The <code>resources</code> element may also contain zero or more <code>fileExtension</code> elements as detailed below.
556
         These are used to define a mapping from file extensions to media types.</p>
557
         <p>Each <code>fileExtension</code> element must have the following attributes, to define one pair in the mapping:</p>
558
         <xi:include href="featureKeys/ConfigFileDoc-fileExtension.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
559
      </section>
560
      <section id="config-collations" title="The &lt;collations&gt; element">
561
         <h1>The &lt;collations&gt; element</h1>
562
         <p>The <code>collations</code> element in the configuration file defines a number of collations that can be preloaded into the configuration. It
563
            contains zero or more child <code>collation</code> elements as detailed below.</p>
564
         <p>Each <code>collation</code> element may have the following attributes:</p>
565
         <xi:include href="featureKeys/ConfigFileDoc-collation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
566
      </section>
567
      <section id="config-localizations" title="The &lt;localizations&gt; element">
568
         <h1>The &lt;localizations&gt; element</h1>
569
         <p>The <code>localizations</code> element in the configuration file defines classes used to localize the output of the <a class="bodylink code"
570
               href="/xsl-elements/number">xsl:number</a> instruction in XSLT, and the functions <a class="bodylink code" href="/functions/fn/format-date"
571
               >format-date()</a>, <a class="bodylink code" href="/functions/fn/format-time">format-time()</a>, and <a class="bodylink code"
572
               href="/functions/fn/format-dateTime">format-dateTime()</a>.</p>
573
         <p>It has two attributes, <code>defaultLanguage</code> and <code>defaultCountry</code> which provide default values for the <code>lang</code>
574
            attribute/argument and the <code>country</code> argument respectively. If no values are supplied, the defaults are taken from the default Locale in
575
            the Java VM (which in turn will typically depend on operating system settings).</p>
576
         <p>The element contains zero or more child <code>localization</code> elements as detailed below.</p>
577
         <p>Each <code>localization</code> element may have the following attributes:</p>
578
         <xi:include href="featureKeys/ConfigFileDoc-localization.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
579
         <p>Note that numberers for various European languages (da, de, fr, dr-BE, it, nl, nl-BE, sv) are supplied in package
580
               <code>net.sf.saxon.option.local</code>. In Saxon-PE and Saxon-EE these are compiled into the standard JAR file, but they are not configured by
581
            default. In Saxon-HE they are not built-in to the product, but can be integrated from the supplied source code in the same way as user-written
582
            localizations.</p>
583
      </section>
584
   </section>
585
   <section id="config-features" title="Configuration Features">
586
      <h1>Configuration Features</h1>
587

    
588

    
589
      <p>This page provides a complete list of the configuration features available.</p>
590

    
591
      <p>The properties are identified by a symbolic name and a URI value defined in the Java module <a class="javalink" href="net.sf.saxon.lib.Feature"
592
         >Feature</a>. The table below describes the effect for each property.</p>
593

    
594
      <xi:include href="featureKeys/FeatureKeysDoc.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
595

    
596

    
597
   </section>
598
</article>
(5-5/21)