Project

Profile

Help

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

he / src / userdoc / using-xsl.xml @ d9cb5c62

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="using-xsl" title="Using XSLT">
3
   <h1>Using XSLT Stylesheets</h1>
4

    
5

    
6
   <p>This section describes how to use XSLT stylesheets with Saxon, either from the command line,
7
      or from the <dfn>Java API</dfn>, or from <dfn>Ant</dfn>:</p>
8

    
9
   <nav except="xslt30 compiling performanceanalysis">
10
      <ul/>
11
   </nav>
12

    
13
   <p>It also includes useful information on <a class="bodylink" href="compiling">Compiling a
14
         Stylesheet</a>, and <a class="bodylink" href="performanceanalysis">Performance
15
      Analysis</a>.</p>
16

    
17
   <p>Furthermore, a summary description of the current Saxon implementation of <a class="bodylink"
18
         href="xslt30">XSLT 3.0</a> is provided, with links to other relevant sections of the
19
      documentation.</p>
20

    
21
   <p>For full information about the conformance of Saxon to the XSLT 3.0
22
      specification, and about the handling of implementation-defined features of the
23
      specifications, see <a class="bodylink" href="/conformance">Conformance</a>.</p>
24

    
25
   <section id="commandline" title="Running XSLT from the Command Line">
26
      <h1>Running XSLT from the Command Line</h1>
27

    
28

    
29
      <p>A command is available to apply a given stylesheet to a given source XML document. For
30
         simple transformations on the Java platform, use the command:</p>
31
      <kbd>java net.sf.saxon.Transform -s:<i>source</i> -xsl:<i>stylesheet</i> -o:<i>output</i>
32
      </kbd>
33

    
34
      <p>where <i>source</i>, <i>stylesheet</i>, and <i>output</i> are the source XML file, the XSLT
35
         stylesheet, and the output file respectively.</p>
36

    
37
      <p>For the .NET platform, the command is simply:</p>
38
      <kbd>Transform -s:<i>source</i> -xsl:<i>stylesheet</i> -o:<i>output</i>
39
      </kbd>
40

    
41
      <p>For a schema-aware transformation, specify the option <code>-sa</code>, or (on the Java
42
         platform only) use the alternate entry point <code>com.saxonica.Transform</code>. For more
43
         details see <a class="bodylink" href="/schema-processing/satransformcmd">Schema-Aware
44
            Transformations</a>.</p>
45

    
46
      <p>For backwards compatibility with previous releases, the prefixes <code>-s:</code> and
47
            <code>-xsl:</code> can be omitted provided that the source document and the stylesheet
48
         are the last two options before any keyword=value parameters.</p>
49

    
50
      <p>More generally, the arguments consist of a number of options prefixed with "-", then
51
         optionally (for backwards compatibility) the source filename and/or stylesheet filename,
52
         then a number of parameters provided as keyword=value pairs. The options must come first,
53
         then the file names if present, then the parameters.</p>
54

    
55
      <p>For this to work, all the necessary Java components must be available on the
56
            <dfn>classpath</dfn>. See <a class="bodylink" href="/about/installationjava"
57
            >Installation</a> for details of how to set up the classpath.</p>
58

    
59
      <p>If you are are not using any additional Java libraries, you can use the simpler form of
60
         command (this example is for Saxon-HE 10.0):</p>
61
      <kbd>java  -jar <i>dir</i>/saxon-he-10.0.jar [options] [params]</kbd>
62

    
63
      <p>
64
         <i>Note, however, that this does not work if you need to load user-written extension
65
            functions or other classes (such as the ICU localization library) from the classpath. It
66
            will therefore not work if your stylesheet uses extension functions or other plug-in
67
            components such as parsers or URI resolvers.</i>
68
      </p>
69

    
70

    
71
      <h2 class="subtitle">Command line options</h2>
72

    
73
      <p>The options are as follows (in any order). Square brackets indicate an optional value.</p>
74
      <table>
75
         <tr>
76
            <td>
77
               <p>-a[:(on|off)]</p>
78
            </td>
79
            <td>
80
               <p>Use the xml-stylesheet processing instruction in the source document to identify
81
                  the stylesheet to be used. The stylesheet argument must not be present on the
82
                  command line. For more details see <a class="bodylink" href="aoption">Using the
83
                        <code>-a</code> option</a>.</p>
84
            </td>
85
         </tr>
86
         <tr>
87
            <td>
88
               <p>-catalog:filenames</p>
89
            </td>
90
            <td>
91
               <p><i>filenames</i> is either a file name or a list of file names separated by
92
                  semicolons; the files are OASIS XML catalogs used to define how public identifiers
93
                  and system identifiers (URIs) used in a source document, stylesheet, or schema are
94
                  to be redirected, typically to resources available locally. For more details see
95
                     <a class="bodylink" href="/sourcedocs/xml-catalogs">Using XML Catalogs</a>.
96
               </p>
97
            </td>
98
         </tr>
99
         <tr>
100
            <td>
101
               <p>-config:filename</p>
102
            </td>
103
            <td>
104
               <p>Indicates that configuration information should be taken from the supplied <a
105
                     class="bodylink" href="/configuration/configuration-file">configuration
106
                     file</a>. Any options supplied on the command line override options specified
107
                  in the configuration file. </p>
108
            </td>
109
         </tr>
110
         
111
         <tr>
112
            <td>
113
               <p>-dtd:(on|off|recover)</p>
114
            </td>
115
            <td>
116
               <p>Setting <code>-dtd:on</code> requests DTD-based validation of the source file and
117
                  of any files read using the <code>document()</code> function. Requires an XML
118
                  parser that supports validation. The setting <code>-dtd:off</code> (which is the
119
                  default) suppresses DTD validation. The setting <code>-dtd:recover</code> performs
120
                  DTD validation but treats the error as non-fatal if it fails. Note that any
121
                  external DTD is likely to be read even if not used for validation, because DTDs
122
                  can contain definitions of entities.</p>
123
            </td>
124
         </tr>
125

    
126
         <tr>
127
            <td>
128
               <p>-ea:(on|off)</p>
129
            </td>
130
            <td>
131
               <p>Setting <code>-ea:on</code> enables assertions both at compile time and at run
132
                  time. Assertions (defined using the XSLT 3.0 <code>xsl:assert</code> instruction) are disabled
133
                  by default at compile time, and enabled by default at run-time provided they were
134
                  enabled at compile time.</p>
135
            </td>
136
         </tr>
137
         <tr>
138
            <td>
139
               <p>-expand:(on|off)</p>
140
            </td>
141
            <td>
142
               <p>Normally, if validation using a DTD or schema is requested, any fixed or default
143
                  values defined in the DTD or schema will be expanded. Specifying
144
                     <code>-expand:off</code> suppresses this. (In the case of DTD-defined defaults,
145
                  this might not work with all XML parsers. It does work with the Xerces parser
146
                  (default for Java) and the Microsoft parser (default for .NET).)</p>
147
            </td>
148
         </tr>
149
         <tr>
150
            <td>
151
               <p>-explain[:filename]</p>
152
            </td>
153
            <td>
154
               <p>Display an execution plan and other diagnostic information for the stylesheet.
155
                  This is a representation of the expression tree after rewriting by the optimizer.
156
                  It combines the XSLT instructions and the XPath expressions into a single tree. If
157
                  no file name is specified the output is sent to the standard error stream. The
158
                  output is in XML format.</p>
159
            </td>
160
         </tr>
161
         <tr>
162
            <td>
163
               <p>-export:filename</p>
164
            </td>
165
            <td>
166
               <p>Export the compiled stylesheet, in a form suitable for subsequent execution. For
167
                  more details, see <a class="bodylink" href="../compiling">Compiling a
168
                     Stylesheet</a>.</p>
169
            </td>
170
         </tr>
171
         <tr>
172
            <td>
173
               <p>-ext:(on|off)</p>
174
            </td>
175
            <td>
176
               <p>If <code>ext:off</code> is specified, suppress calls on dynamically-loaded
177
                  external Java functions. This does not affect calls on integrated extension
178
                  functions, including Saxon and EXSLT extension functions. This option is useful
179
                  when loading an untrusted stylesheet, perhaps from a remote site using an
180
                     <code>http://</code> URL; it ensures that the stylesheet cannot call arbitrary
181
                  Java methods and thereby gain privileged access to resources on your machine. </p>
182
            </td>
183
         </tr>
184
         <tr>
185
            <td>
186
               <p>-im:modename</p>
187
            </td>
188
            <td>
189
               <p>Selects the initial mode for the transformation. If this is namespaced, it can be
190
                  written as <code>{uri}localname</code>. </p>
191
            </td>
192
         </tr>
193
         <tr>
194
            <td>
195
               <p>-init:initializer</p>
196
            </td>
197
            <td>
198
               <p>The value is the name of a user-supplied class that implements the interface <a
199
                     class="javalink" href="net.sf.saxon.lib.Initializer">Initializer</a>; this
200
                  initializer will be called during the initialization process, and may be used to
201
                  set any options required on the <code>Configuration</code> programmatically.</p>
202
            </td>
203
         </tr>
204
         <tr>
205
            <td>
206
               <p>-it[:template-name]</p>
207
            </td>
208
            <td>
209
               <p>Selects the initial named template to be executed. If this is namespaced, it can
210
                  be written as <code>{uri}localname</code>. If the template name is omitted, the
211
                  default is <code>xsl:initial-template</code>. When this option is used, you do not
212
                  need to supply a source file, but if you do, you must supply it using the
213
                     <code>-s</code> option.</p>
214
            </td>
215
         </tr>
216
         <tr>
217
            <td>
218
               <p>-jit:on|off</p>
219
            </td>
220
            <td>
221
               <p>Determines whether just-in-time compilation of template rules is in force. The default
222
                  is <code>on</code>, unless the <code>nogo</code> or <code>explain</code> option is set.
223
                  When JIT is enabled, the body of a template rule is not compiled until the rule first fires.
224
                  This gives faster compilation when a stylesheet has been written to handle a large XML vocabulary,
225
                  but the source document only uses a fraction of the vocabulary. The drawback is that static
226
                  errors in the stylesheet may go undetected.</p>
227
            </td>
228
         </tr>
229
         <tr>
230
            <td>
231
               <p>-l[:(on|off)]</p>
232
            </td>
233
            <td>
234
               <p>If <code>-l</code> or <code>-l:on</code> is specified, causes line and column
235
                  numbers to be maintained for source documents. These are accessible using the
236
                  extension functions <code>saxon:line-number()</code> and
237
                     <code>saxon:column-number()</code>. Line numbers are useful when the purpose of
238
                  the stylesheet is to find errors or anomalies in the source XML file. Without this
239
                  option, <dfn>line numbers</dfn> are available while source documents are being
240
                  parsed and validated, but they are not retained in the tree representation of the
241
                  document.</p>
242
            </td>
243
         </tr>
244
         <tr>
245
            <td>
246
               <p>-lib:filenames</p>
247
            </td>
248
            <td>
249
               <p>A list of filenames containing library packages. The filenames are separated by
250
               ";" on Windows systems, or ":" on Linux and Mac. Each filename must identify either (a) 
251
               a top-level module in a source XSLT package, or (b) a SEF file containing an exported library
252
               package. There is no constraint on the order of the packages.</p>
253
            </td>
254
         </tr>
255
         <tr>
256
            <td>
257
               <p>-license:(on|off)</p>
258
            </td>
259
            <td>
260
               <p>Relevant only when Saxon-PE or Saxon-EE software is loaded. By default, Saxon will
261
                  look for a license and report a warning if none is found, which escalates to a fatal
262
                  error if licenseable features (such as schema-awareness) are used. If <code>-license:off</code>
263
                  is specified, Saxon will not look for a license unless it is needed, and will fall back
264
                  silently if none is found (this means that the transformation might succeed, but
265
                  without taking advantage of Saxon-EE optimizations). The option <code>-license:off</code>
266
                  is useful to suppress warnings in the case where it is known that a compiled stylesheet
267
                  containing an embedded license key is being executed.</p>
268
            </td>
269
         </tr>
270
         <tr>
271
            <td>
272
               <p>-m:classname</p>
273
            </td>
274
            <td>
275
               <p>Use the specified <code>Receiver</code> to process the output from
276
                     <code>xsl:message</code>. The class must implement the <a class="javalink"
277
                     href="net.sf.saxon.event.Receiver">Receiver</a> interface, and
278
                 it must have a public zero-argument constructor. This
279
                  interface is similar to a SAX <code>ContentHandler</code>, it takes a stream of
280
                  events to generate output. In general the content of a message is an XML fragment.
281
                  By default the standard XML emitter is used, configured to write to the standard
282
                  error stream, and to include no XML declaration.</p> 
283
              <p>Each message is output as a new
284
                  document. The sequence of calls to this <code>Receiver</code> is as follows: there
285
                  is a single <code>open()</code> call at the start of the transformation, and a
286
                  single <code>close()</code> call at the end; and each evaluation of an
287
                     <code>xsl:message</code> instruction starts with a <code>startDocument()</code>
288
                  call and ends with <code>endDocument()</code>. The <code>startDocument()</code>
289
                  event has a <code>properties</code> argument indicating whether
290
                     <code>terminate="yes"</code> was specified, and the <code>locationId</code> on
291
                  calls such as <code>startElement()</code> and <code>characters()</code> can be
292
                  used to identify the location in the stylesheet where the message data originated
293
                  (this is achieved by passing the supplied <code>locationId</code> in a call to
294
                     <code>getPipelineConfiguration().getLocator().getSystemId(locationId)</code>,
295
                  or to <code>getLineNumber()</code> on the same object).</p> 
296
              <p>Select the class <code java="net.sf.saxon.serialize.MessageWarner">MessageWarner</code> to have <code>xsl:message</code>
297
                  output notified to the JAXP <code>ErrorListener</code>, as described in the JAXP
298
                  documentation.</p>
299
            </td>
300
         </tr>
301
         <tr>
302
            <td>
303
               <p>-nogo</p>
304
            </td>
305
            <td>
306
               <p>If set, the stylesheet is analysed for errors, and any requested
307
                     <code>-explain</code> or <code>-export</code> output is generated, but the
308
                  stylesheet is not executed.</p>
309
            </td>
310
         </tr>
311
         <tr>
312
            <td>
313
               <p>-now:yyyy-mm-ddThh:mm:ss+hh:mm</p>
314
            </td>
315
            <td>
316
               <p>Sets the value of <code>current-dateTime()</code> (and
317
                     <code>implicit-timezone()</code>) for the transformation. This is designed for
318
                  testing, to enable repeatable results to be obtained for comparison with reference
319
                  results, or to test that stylesheets can handle significant dates and times such
320
                  as end-of-year processing.</p>
321
            </td>
322
         </tr>
323
         <tr>
324
            <td>
325
               <p>-ns:(uri|##any|##html5)</p>
326
            </td>
327
            <td>
328
               <p>Defines the handling of unprefixed element names appearing as name tests in path expressions
329
                  and match patterns in the stylesheet.</p>
330
               <ul>
331
                  <li>
332
               Supplying a URI sets the default namespace for elements
333
                  and types (effectively a default value for <code>xpath-default-namespace</code> — note that an
334
                  explicit value for this attribute takes precedence).</li> 
335
                  <li>The value <code>##any</code> declares that unprefixed names are treated as a test on the local
336
                  name of the element only: they will match regardless of namespace.</li> 
337
                  <li>The value <code>##html5</code>
338
                  declares that an unprefixed element name will match either a name in the XHTML namespace, or a name
339
                  in no namespace. This option is intended primarily for use when generating stylesheets to run under
340
                  Saxon-JS in the browser, since the resulting behavior is close to that defined by the special rules in the HTML5
341
                  specification for XSLT and XPath running against an HTML5 DOM.</li></ul>
342
            </td>
343
         </tr>
344
         <tr>
345
            <td>
346
               <p>-o:filename</p>
347
            </td>
348
            <td>
349
               <p>Send output to named file.</p>
350
               <p>If the source (<code>-s</code>) argument identifies a directory, this option is
351
                  mandatory and must also identify a directory; on completion it will contain one
352
                  output file for each file in the source directory.</p>
353
               <p>In other cases, this option has two effects: it defines the file where the principal
354
                  output of the transformation will be written, and it defines the base URI used for resolving
355
                  the value of the <code>xsl:result-document/@href</code> attribute when secondary result documents
356
                  are written.</p>
357
               <p>In the absence of this option, (a) the principal output is written to the standard
358
                  output stream, and (b) secondary output file locations are resolved relative to the 
359
                  current working directory.</p> 
360
               <p>Output files are created if they do not
361
                  already exist; any necessary directories will also be created. If a file does
362
                  already exist, it is generally overwritten, though this will not necessarily happen if the transformation
363
                  fails.</p>
364
            </td>
365
         </tr>
366
         <tr>
367
            <td>
368
               <p>-opt:[-]flags</p>
369
            </td>
370
            <td>
371
               <p>Allows individual optimizations to be enabled or
372
                  disabled selectively. There is a set of single-letter flags identifying particular optimizations:</p>
373
               <ul>
374
                  <li>c: generate bytecode</li>
375
                  <li>d: detect void path expressions</li>
376
                  <li>e: cache regular expressions</li>
377
                  <li>f: inline functions</li>
378
                  <li>g: extract global variables</li>
379
                  <li>j: just-in-time compilation of template rules</li>
380
                  <li>k: create keys</li>
381
                  <li>l: loop lifting</li>
382
                  <li>m: miscellaneous</li>
383
                  <li>n: constant folding</li>
384
                  <li>r: template rule-sets</li>
385
                  <li>s: extract common subexpressions</li>
386
                  <li>t: tail call optimization</li>
387
                  <li>v: inline variables</li>
388
                  <li>w: create switch statements</li>
389
                  <li>x: index predicates</li>
390
               </ul>
391
               <p>A value such as <code>opt:gs</code> runs with only the selected optimizations; <code>opt:-gs</code> runs with the
392
                  selected optimizations disabled and all others enabled. The value <code>opt:0</code> suppresses all optimizations. The default is full
393
                  optimization; this feature allows optimization to be suppressed in cases where
394
                  reducing compile time is important, or where optimization gets in the way of
395
                  debugging, or causes extension functions with side-effects to behave
396
                  unpredictably. (Note however, that even with no optimization, lazy evaluation may
397
                  still cause the evaluation order to be not as expected.) </p>
398
               <aside>Disabling optimizations may in some cases prevent streamed evaluation. For example, some expressions
399
               only become streamable because the optimizer is able to work out that sorting nodes into document order is unnecessary.</aside>
400
               <aside>Most of these flags enable optimizations that cause extra work at compile time to improve run-time performance.
401
               The <code>j</code> option is an exception: enabling this option shifts work from compile time to run time.</aside>
402
            </td>
403
         </tr>
404
         <tr>
405
            <td>
406
               <p>-or:classname</p>
407
            </td>
408
            <td>
409
               <p>Use the specified <code>OutputURIResolver</code> to process output URIs appearing
410
                  in the <code>href</code> attribute of <code>xsl:result-document</code>. The
411
                     <code>OutputURIResolver</code> is a user-defined class that implements the <a
412
                     class="javalink" href="net.sf.saxon.lib.OutputURIResolver"
413
                     >net.sf.saxon.lib.OutputURIResolver</a> interface.</p>
414
            </td>
415
         </tr>
416
         <tr>
417
            <td>
418
               <p>-outval:(recover|fatal)</p>
419
            </td>
420
            <td>
421
               <p>Normally, if validation of result documents is requested, a validation error is
422
                  fatal. Setting the option <code>-outval:recover</code> causes such validation
423
                  failures to be treated as warnings. The validation message is written both to the
424
                  standard error stream, and (where possible) as a comment in the result document
425
                  itself.</p>
426
               <p>This option does not by itself cause result documents to be validated; that happens
427
                  only as a consequence of the <code>type</code> or <code>validation</code> attribute
428
                  on an <code>xsl:result-document</code> instruction. The only effect of the option is
429
                  to determine what happens when validation fails.</p>
430
               <p><i>Validating result documents can be very useful while debugging a stylesheet,
431
                  because it provides instant feedback when the output is incorrect. However, it can
432
                  sometimes be frustrating during development when you know that parts of the code have
433
                  not yet been written. The option <code>outval:recover</code> is designed to give you
434
                  the best of both worlds: it tells you that the output is wrong, but still enables you to
435
                  see the complete result document that your code is producing.</i></p>
436
            </td>
437
         </tr>
438
         <tr>
439
            <td>
440
               <p>-p[:(on|off)]</p>
441
            </td>
442
            <td>
443
               <p>Enable recognition of query parameters (such as <code>xinclude=yes</code>)
444
                 in the <code>StandardURIResolver</code>. This option is available in Saxon-PE and Saxon-EE only.
445
                  It cannot be used in conjunction with the <code>-r</code> option, and it
446
                  automatically switches on the <code>-u</code> and <code>-sa</code> options. The
447
                  effect is that Saxon-specific query parameters are recognized in a URI. One query
448
                  parameter that is recognized is <code>val</code>. This may take the values
449
                     <code>strict</code>, <code>lax</code>, or <code>strip</code>. For example,
450
                     <code>source.xml?val=strict</code> loads a document with strict schema
451
                  validation. </p>
452
            </td>
453
         </tr>
454
         <tr>
455
            <td>
456
               <p>-quit:(on|off)</p>
457
            </td>
458
            <td>
459
               <p>With the default setting, <code>on</code>, the command will quit the Java VM and
460
                  return an exit code if a failure occurs. This is useful when running from an
461
                  operating system shell. With the setting <code>quit:off</code> the command instead
462
                  throws a <code>RunTimeException</code>, which is more useful when the command is
463
                  invoked from another Java application such as Ant. </p>
464
            </td>
465
         </tr>
466
         <tr>
467
            <td>
468
               <p>-r:classname</p>
469
            </td>
470
            <td>
471
               <p>Use the specified <code>URIResolver</code> to process all URIs. The
472
                     <code>URIResolver</code> is a user-defined class, that implements the
473
                 <code>javax.xml.transform.URIResolver</code> interface, whose function is to take a URI
474
                  supplied as a string, and return a SAX <code>Source</code> object. It is invoked to
475
                  process URIs used in the <code>document()</code> function, in the
476
                     <code>xsl:include</code> and <code>xsl:import</code> elements, and (if
477
                     <code>-u</code> is also specified) to process the URIs of the source file and
478
                  stylesheet file provided on the command line.</p>
479
            </td>
480
         </tr>
481
         <tr>
482
            <td>
483
               <p>-relocate:(on|off)</p>
484
            </td>
485
            <td>
486
               <p>Used with <code>-export</code> to produce an export package which can be deployed
487
                  to a different location, with a different base URI. If <code>on</code>, then
488
                  <code>static-base-uri()</code> represents the deployed location of the package,
489
                  rather than its compile time location. The default is <code>off</code>.</p>
490
               <p>The practical effect of this is that if <code>relocate:off</code> (the default)
491
               is specified, then the generated SEF file will contain references to the stylesheet's
492
               original location as its static base URI, and run-time operations that are relative to this base
493
               URI (for example, calling <code>doc()</code> with a relative URI) will retrieve resources
494
               exactly as if the stylesheet had not been exported. By contrast, if <code>relocate:on</code> is
495
               specified, the SEF file will contain no reference to the original location of the source
496
               stylesheet, and operations such as <code>doc()</code> will be relative to the location
497
               from which the SEF file was loaded.</p>
498
            </td>
499
         </tr>
500
         <tr>
501
            <td>
502
               <p>-repeat:integer</p>
503
            </td>
504
            <td>
505
               <p>Performs the transformation N times, where N is the specified integer. This option
506
                  is useful for <dfn>performance measurement</dfn>, since timings for the first
507
                  transformation are often dominated by Java warm-up time.</p>
508
            </td>
509
         </tr>
510
         <tr>
511
            <td>
512
               <p>-s:filename</p>
513
            </td>
514
            <td>
515
               <p>Identifies the source file or directory. Mandatory unless the <code>-it</code>
516
                  option is used. The source file is parsed to create a tree, and the document node
517
                  of this tree acts as the initial context item for the transformation.</p>
518
              <p>The filename can be given as
519
                <code>"-"</code> to take the source from standard input, in which case the
520
                base URI is taken from that of the current directory. </p>
521
              <p>If the name
522
                  identifies a directory, all the files in the directory will be processed
523
                  individually. In this case the <code>-o</code> option is mandatory, and must also
524
                  identify a directory, to contain the corresponding output files. A directory must
525
                  be specified as a filename, not as a URL.</p> 
526
              <p><i>For backwards
527
                     compatibility the source filename can also be specified immediately before the
528
                     stylesheet filename, without the <code>-s</code> flag, provided that the
529
                        <code>-it</code> option is not present.</i>
530
               </p>
531
            </td>
532
         </tr>
533
         <tr>
534
            <td>
535
               <p>-sa</p>
536
            </td>
537
            <td>
538
               <p>Invoke a schema-aware transformation. Requires Saxon-EE to be installed. This
539
                  option is not needed if either (a) another option implying schema-awareness is
540
                  present (for example <code>-val:strict</code>) or (b) the stylesheet contains an
541
                     <code>xsl:import-schema</code> declaration.</p>
542
            </td>
543
         </tr>
544
         <tr>
545
            <td>
546
               <p>-scmin:filename</p>
547
            </td>
548
            <td>
549
               <p>Loads a precompiled schema component model from the given file. The file should be
550
                  generated in a previous run of <code>com.saxonica.Validate</code> using the <code>-export</code> option. When this
551
                  option is used, the <code>-xsd</code> option should not be present. Schemas loaded
552
                  from an SCM file are assumed to be valid, without checking.</p>
553
               <p><i>This option is retained for compatibility. From Saxon 9.7, SCM files can also be
554
                  supplied in the <code>-xsd</code> option.</i></p>
555
            </td>
556
         </tr>
557
         <tr>
558
            <td>
559
               <p>-strip:(all|none|ignorable)</p>
560
            </td>
561
            <td>
562
               <p>Specifies what <dfn>whitespace</dfn> is to be stripped from source documents
563
                  (applies both to the principal source document and to any documents loaded for
564
                  example using the <code>document()</code> function). The default is
565
                     <code>ignorable</code>: all ignorable whitespace is stripped. Whitespace text
566
                  nodes are ignorable if they appear in elements defined in the DTD or schema as
567
                  having element-only content. Specifying <code>all</code> strips all whitespace
568
                  text nodes from source documents before any further processing, regardless of any
569
                     <code>xsl:strip-space</code> declarations in the stylesheet, or any
570
                     <code>xml:space</code> attributes in the source document. Specifying
571
                     <code>ignorable</code> strips all ignorable whitespace text nodes from source
572
                  documents before any further processing, regardless of any
573
                     <code>xsl:strip-space</code> declarations in the stylesheet, or any
574
                     <code>xml:space</code> attributes in the source document. Specifying
575
                     <code>none</code> suppresses all whitespace stripping unless requested
576
                  elsewhere, for example using <code>xsl:strip-space</code>.</p>
577
            </td>
578
         </tr>
579
         <tr>
580
            <td>
581
               <p>-t</p>
582
            </td>
583
            <td>
584
               <p>Display version and timing information to the standard error output. The output
585
                  also traces the files that are read and written, and extension modules that are
586
                  loaded.</p>
587
            </td>
588
         </tr>
589
         <tr>
590
            <td>
591
               <p>-T[:classname]</p>
592
            </td>
593
            <td>
594
               <p>Display stylesheet <dfn>tracing</dfn> information. This traces execution of each
595
                  instruction in the stylesheet, so the output can be quite voluminous. Also
596
                  switches line numbering on for the source document. If a classname is specified,
597
                  it is a user-defined class, which must implement <a class="javalink"
598
                     href="net.sf.saxon.lib.TraceListener">TraceListener</a>. If the classname is
599
                  omitted, a system-supplied trace listener is used. For performance profiling, set
600
                  classname to <code>net.sf.saxon.trace.TimingTraceListener</code>. This creates an
601
                  output file giving timings for each instruction executed. This output file can
602
                  subsequently be analyzed to give an execution time profile for the stylesheet. See
603
                     <a class="bodylink" href="../performanceanalysis">Performance Analysis</a>.</p>
604
            </td>
605
         </tr>
606
         <tr>
607
            <td>
608
               <p>-target:(EE|PE|HE|JS)</p>
609
            </td>
610
            <td>
611
               <p>Relevant only when <code>-export</code> is specified, identifies the target platform
612
                  on which the exported stylesheet is to run. When exporting for Saxon-JS, the value
613
                  "JS" <bold>must</bold> be specified, because this adds information to the
614
                  SEF file that is required by Saxon-JS. Specifying "JS" means the SEF is produced
615
                  in JSON format for use with Saxon-JS 2.x. (To generate SEF files for Saxon-JS 1.x, 
616
                  you need to revert to Saxon-EE 9.9). In principle, specifying "HE" or "PE" will
617
                  inhibit optimizations that generate code which Saxon-HE/Saxon-PE cannot execute;
618
                  however, this is not fully tested.</p>
619
            </td>
620
         </tr>
621
         <tr>
622
            <td>
623

    
624
               <p>-TB:filename</p>
625
            </td>
626
            <td>
627
               <p>Monitors generation of hot-spot bytecode and produces an XML report on the given
628
                  filename giving, for each expression that was a candidate for bytecode generation
629
                  and that was actually executed, data about the number of times and speed of execution
630
                  in the interpreter, the number of times and speed of execution in compiled form,
631
                  and the cost of compilation.</p>
632
            </td>
633
         </tr>
634
         <tr>
635
            <td>
636
               <p>-threads:N</p>
637
            </td>
638
            <td>
639
               <p>Used only when the <code>-s</code> option specifies a directory. Controls the
640
                  number of threads used to process the files in the directory. Each transformation
641
                  runs in a single thread.</p>
642
            </td>
643
         </tr>
644
         <tr>
645
            <td>
646
               <p>-TJ</p>
647
            </td>
648
            <td>
649
               <p>Switches on tracing of the binding of calls to external Java methods. This is
650
                  useful when analyzing why Saxon fails to find a Java method to match an extension
651
                  function call in the stylesheet, or why it chooses one method over another when
652
                  several are available.</p>
653
            </td>
654
         </tr>
655
         <tr>
656
            <td>
657
               <p>-Tlevel:none|low|normal|high</p>
658
            </td>
659
            <td>
660
               <p>Controls the level of detail of the tracing produced by the <code>-T</code> option. The values are:</p>
661
               <ul>
662
                  <li><code>none</code> effectively switches tracing off.</li>
663
                  <li><code>low</code> traces function and template calls.</li>
664
                  <li><code>normal</code> traces execution of instructions.</li>
665
                  <li><code>high</code> traces execution of finer-grained expressions.</li>
666
               </ul>
667
            </td>
668
         </tr>
669
         <tr>
670
            <td>
671
               <p>-Tout:filename</p>
672
            </td>
673
            <td>
674
               <p>Directs the output of tracing to a specified file (assuming that <code>-T</code> is enabled).</p>
675
            </td>
676
         </tr>
677
         <tr>
678
            <td>
679
               <p>-TP:filename</p>
680
            </td>
681
            <td>
682
               <p>This is equivalent to setting
683
                     <code>-T:net.sf.saxon.trace.TimedTraceListener</code> and
684
                     <code>-traceout:filename</code>; that is, it causes trace profile information
685
                  to be set to the specified file. This output file can subsequently be analyzed to
686
                  give an execution time profile for the stylesheet. See <a class="bodylink"
687
                     href="../performanceanalysis">Performance Analysis</a>.</p>
688
            </td>
689
         </tr>
690
         <tr>
691
            <td>
692
               <p>-traceout:filename</p>
693
            </td>
694
            <td>
695
               <p>Indicates that the output of the <code>trace()</code> function should be directed
696
                  to a specified file. Alternatively, specify <code>#out</code> to direct the output
697
                  to <code>System.out</code>, <code>#err</code> to send it to
698
                     <code>System.err</code> (the default), or <code>#null</code> to have it
699
                  discarded. This option is ignored when a trace listener is in use: in that case,
700
                     <code>trace()</code> output goes to the registered trace listener.</p>
701
            </td>
702
         </tr>
703
         <tr>
704
            <td>
705
               <p>-tree:(linked|tiny|tinyc)</p>
706
            </td>
707
            <td>
708
               <p>Selects the implementation of the internal tree model: <code>tiny</code> selects
709
                  the "tiny tree" model (the default), <code>linked</code> selects the linked tree
710
                  model, <code>tinyc</code> selects the "condensed tiny tree" model. See <a
711
                     class="bodylink" href="/sourcedocs/choosingmodel"> Choosing a tree
712
                  model</a>.</p>
713
            </td>
714
         </tr>
715
         <tr>
716
            <td>
717
               <p>-u</p>
718
            </td>
719
            <td>
720
               <p>Indicates that the names of the source document and the stylesheet document are
721
                  URLs; otherwise they are taken as filenames, unless they start with
722
                     <code>http:</code>, <code>https:</code>, <code>file:</code> or
723
                     <code>classpath:</code>, in which case they are taken as URLs.</p>
724
            </td>
725
         </tr>
726
         <tr>
727
            <td>
728
               <p>-val[:(strict|lax)]</p>
729
            </td>
730
            <td>
731
               <p>Requests schema-based validation of the source file and of any files read using
732
                  the <code>document()</code> or similar functions. Validation is available only
733
                  with Saxon-EE, and this flag automatically switches on the <code>-sa</code>
734
                  option. Specify <code>-val</code> or <code>-val:strict</code> to request strict
735
                  validation, or <code>-val:lax</code> for lax validation.</p>
736
            </td>
737
         </tr>
738
         <tr>
739
            <td>
740
               <p>-warnings:(silent|recover|fatal)</p>
741
            </td>
742
            <td>
743
               <p>Indicates the policy for handling recoverable errors in the stylesheet:
744
                     <code>silent</code> means recover silently, <code>recover</code> means recover
745
                  after writing a warning message to the system error output, <code>fatal</code>
746
                  means signal the error and do not attempt recovery. (Note, this does not currently
747
                  apply to all errors that the XSLT recommendation describes as recoverable). The
748
                  default is <code>recover</code>.</p>
749
            </td>
750
         </tr>
751
         <tr>
752
            <td>
753
               <p>-x:classname</p>
754
            </td>
755
            <td>
756
               <p>Use the specified SAX parser for the source file and any files loaded using the
757
                     <code>document()</code> function. The parser must be the fully-qualified class
758
                  name of a Java class that implements the <code>org.xml.sax.XMLReader</code> or
759
                     <code>javax.xml.parsers.SAXParserFactory</code> interface, and it must be
760
                  instantiable using a zero-argument public constructor. One use of this option is
761
                  to select an HTML parser such as John Cowan's TagSoup rather than an XML parser.
762
                  In this case, the TagSoup JAR file must be on the classpath, and the class name to
763
                  use is <code>org.ccil.cowan.tagsoup.Parser</code>. Another common use is to
764
                  specify <code>org.apache.xml.resolver.tools.ResolvingXMLReader</code>. This parser
765
                  is provided by the Apache commons project, and it customizes the default parser by
766
                  using an <code>EntityResolver</code> that resolves external entity references
767
                  (note the reference to an external DTD in a DOCTYPE declaration) by reference to
768
                  an OASIS catalog file. This can be used to avoid repeated calls to external web
769
                  servers (such as the W3C server) for commonly used DTDs such as the XHTML DTD. The
770
                  option to supply a <code>SAXParserFactory</code> was introduced in 9.6 for the
771
                  benefit of the Aalto parser, whose <code>XMLReader</code> implementation cannot be
772
                  directly instantiated; this parser can therefore be requested by nominating its
773
                  factory class, <code>com.fasterxml.aalto.sax.SAXParserImpl</code>.</p>
774
            </td>
775
         </tr>
776
         <tr>
777
            <td>
778
               <p>-xi:(on|off)</p>
779
            </td>
780
            <td>
781
               <p>Apply XInclude processing to all source XML documents (but not to schema and
782
                  stylesheet modules). This currently only works when
783
                  documents are parsed using the Xerces parser, which is the default on the Java platform
784
                  (but not on .NET).</p>
785
            </td>
786
         </tr>
787
         <tr>
788
            <td>
789
               <p>-xmlversion:(1.0|1.1)</p>
790
            </td>
791
            <td>
792
               <p>If <code>-xmlversion:1.1</code> is specified, allows XML 1.1 and XML Namespaces
793
                  1.1 constructs. This option must be set if source documents using XML 1.1 are to
794
                  be read, or if result documents are to be serialized as XML 1.1. This option also
795
                  enables use of XML 1.1 constructs within the stylesheet itself.</p>
796
            </td>
797
         </tr>
798
         <tr>
799
            <td>
800
               <p>-xsd:file1;file2;file3...</p>
801
            </td>
802
            <td>
803
               <p>Loads additional schema documents. The declarations in these schema documents are
804
                  available when validating source documents (or for use by the
805
                     <code>validate{}</code> expression). This option may also be used to supply the
806
                  locations of schema documents that are imported into the stylesheet, in the case
807
                  where the <code>xsl:import-schema</code> declaration gives the target namespace of
808
                  the schema but not its location.</p>
809
            </td>
810
         </tr>
811
         <tr>
812
            <td>
813
               <p>-xsdversion:(1.0|1.1)</p>
814
            </td>
815
            <td>
816
               <p>If <code>-xsdversion:1.1</code> is specified (the default), allows schema
817
                  documents using XML Schema 1.1 to be read, and XML Schema 1.1 constructs
818
                  such as assertions.</p>
819
            </td>
820
         </tr>
821
         <tr>
822
            <td>
823
               <p>-xsiloc:(on|off)</p>
824
            </td>
825
            <td>
826
               <p>If set to <code>on</code> (the default) the schema processor attempts to load any
827
                  schema documents referenced in <code>xsi:schemaLocation</code> and
828
                     <code>xsi:noNamespaceSchemaLocation</code> attributes in the instance document,
829
                  unless a schema for the specified namespace (or non-namespace) is already
830
                  available. If set to <code>off</code>, these attributes are ignored.</p>
831
            </td>
832
         </tr>
833
         <tr>
834
            <td>
835
               <p>-xsl:filename</p>
836
            </td>
837
            <td>
838
               <p>Specifies the file containing the principal stylesheet module. Mandatory unless
839
                  the <code>-a</code> option is used. The value
840
                  <code>"-"</code> identifies the standard input stream, in which case the
841
                  static base URI is taken from that of the current directory. If the <code>-u</code>
842
                  option is specified then the value must be a URI rather than a filename.</p>
843
               
844
               <p>The selected file can contain either XSLT source code, or a compiled version of
845
                  the stylesheet (a SEF file) as produced using the <code>-export</code> option.</p>
846
            </td>
847
         </tr>
848
         
849
         <tr>
850
            <td>
851
               <p>-y:classname</p>
852
            </td>
853
            <td>
854
               <p>Use the specified SAX parser for stylesheet files, including any loaded using
855
                     <code>xsl:include</code> or <code>xsl:import</code>. The supplied classname
856
                  must be the fully-qualified class name of a Java class that implements the
857
                     <code>org.xml.sax.XMLReader</code> or
858
                     <code>javax.xml.parsers.SAXParserFactory</code> interface, and it must be
859
                  instantiable using a zero-argument public constructor.</p>
860
            </td>
861
         </tr>
862
         <tr>
863
            <td>
864
               <p>--<i>feature</i>:value</p>
865
            </td>
866
            <td>
867
               <p>Set a feature defined in the <code>Configuration</code> interface. The names of
868
                  features are defined in the Javadoc for class <a class="javalink"
869
                     href="net.sf.saxon.lib.Feature">Feature</a> (alternatively see 
870
                  <a class="bodylink" href="/configuration/config-features"
871
                     >Configuration Features</a>): the value used here is the
872
                  part of the name after the last "/", for example
873
                     <code>--allow-external-functions:off</code>. Only features accepting a string
874
                  or boolean may be set; for booleans the values true/false, on/off, yes/no, and 1/0
875
                  are recognized.</p>
876
            </td>
877
         </tr>
878
         <tr>
879
            <td>
880
               <p>-?</p>
881
            </td>
882
            <td>
883
               <p>Display command syntax.</p>
884
            </td>
885
         </tr>
886
         <tr>
887
            <td>
888
               <p>--?</p>
889
            </td>
890
            <td>
891
               <p>Display a list of features that are available using the <code>--feature:value</code> syntax</p>
892
            </td>
893
         </tr>
894

    
895
      </table>
896

    
897

    
898
      <h2 class="subtitle">Command line parameters</h2>
899

    
900
      <p>A <i>param</i> takes the form <code>name=value</code>, <i>name</i> being the name of the
901
         parameter, and <i>value</i> the value of the parameter. These parameters are accessible
902
         within the stylesheet as normal variables, using the <code>$name</code> syntax, provided
903
         they are declared using a top-level <code>xsl:param</code> element. If there is no such
904
         declaration, the supplied parameter value is silently ignored. If the
905
            <code>xsl:param</code> element has an <code>as</code> attribute indicating the required
906
         type, then the string value supplied on the command line is cast to this type: this may
907
         result in an error, for example if an integer is required and the supplied value cannot be
908
         converted to an integer. If the parameter is declared with the option
909
            <code>static="yes"</code> (new in XSLT 3.0) then the value is supplied as a static
910
         parameter value.</p>
911

    
912
      <p>A <i>param</i> preceded by a leading question mark (<code>?</code>) is interpreted as an
913
         XPath expression. For example, <code>?time=current-dateTime()</code> sets the value of the
914
         stylesheet parameter <code>$time</code> to the value of the current date and time, as an
915
         instance of <code>xs:dateTime</code>, while <code>?debug=false()</code> sets the value of
916
         the parameter <code>$debug</code> to the boolean value <code>false</code>. If the parameter
917
         has a required type (for example <code>&lt;xsl:param name="p" as="xs:date"/&gt;</code>),
918
         then the supplied value must be compatible with this type according to the standard rules
919
         for converting variable values and function arguments. The static context for this XPath
920
         expression includes only the standard namespaces conventionally bound to the prefixes
921
            <code>xs</code>, <code>fn</code>, <code>xsi</code>, and <code>saxon</code>. The static
922
         base URI (used when calling the <code>doc()</code> function) is the current directory. The
923
         dynamic context contains no context item, position, or size, and no variables.</p>
924

    
925
      <p>A <i>param</i> preceded by a leading exclamation mark (<code>!</code>) is interpreted as an
926
         output parameter. For example, <code>!indent=yes</code> requests indented output. This is
927
         equivalent to specifying the attribute <code>indent="yes"</code> on an
928
            <code>xsl:output</code> declaration in the stylesheet. An output parameter specified on
929
         the command line overrides one specified within the stylesheet. For parameters
930
            <code>doctype-system</code>, <code>doctype-public</code>, and
931
            <code>saxon:next-in-chain</code>, a zero-length value is treated as "absent", that is,
932
         the effect is to cancel any value that was set within the stylesheet.</p>
933

    
934
      <aside>If you are using the <code>bash</code> shell, you will need to escape "!" as
935
         "\!".</aside>
936

    
937
      <p>A <i>param</i> preceded by a leading plus sign (<code>+</code>) is interpreted as a
938
         filename or directory. The content of the file is parsed as XML, and the resulting document
939
         node is passed to the stylesheet as the value of the parameter. If the parameter value is a
940
         directory, then all the immediately contained files are parsed as XML, and the resulting
941
         sequence of document nodes is passed as the value of the parameter. For example,
942
            <code>+lookup=lookup.xml</code> sets the value of the stylesheet parameter
943
            <code>lookup</code> to the document node at the root of the tree representing the parsed
944
         contents of the file <code>lookup.xml</code>.</p>
945

    
946
      <p>Under most operating systems it is possible to supply a value containing spaces by
947
         enclosing it in double quotes, for example <code>name="John Smith"</code>. This is a
948
         feature of the operating system shell, not something Saxon does, so it may not work the
949
         same way under every operating system or command processor. (In the jEdit console plugin,
950
         for example, it has to be written as <code>"name=John Smith"</code>.)</p>
951

    
952
      <p>If the parameter name is in a non-null namespace, the parameter can be given a value using
953
         the syntax <code>{uri}localname=value</code>. Here <code>uri</code> is the namespace URI of
954
         the parameter's name, and <code>localname</code> is the local part of the name.</p>
955

    
956
      <p>This applies also to output parameters. For example, you can set the indentation level to 4
957
         by using the parameter <code>!{http://saxon.sf.net/}indent-spaces=4</code>. In this case,
958
         however, lexical QNames using the prefix <code>saxon</code> are also recognized, for
959
         example <code>!saxon:indent-spaces=4</code>. See also <a class="bodylink"
960
            href="/extensions/output-extras">Additional serialization parameters</a>.</p>
961

    
962
      <section id="aoption" title="Using the -a option">
963

    
964
         <h1>Using the <code>-a</code> option</h1>
965

    
966
         <p>If the <code>-a</code> option is used, the name of the stylesheet is omitted. The source
967
            document must contain a <code>&lt;?xml-stylesheet?&gt;</code> processing instruction
968
            before the first element start tag; this processing instruction must have a
969
            pseudo-attribute <code>href</code> that identifies the relative or absolute URL of the
970
            stylsheet document, and a pseudo-attribute type whose value is <code>text/xml</code>,
971
               <code>application/xml</code>, or <code>text/xsl</code>. For example:</p>
972
         <samp>&lt;?xml-stylesheet type="text/xsl" href="../style3.xsl" ?&gt;</samp>
973

    
974
         <p>It is also possible to refer to a stylesheet embedded within the source document,
975
            provided it has an <code>id</code> attribute and the <code>id</code> attribute is
976
            declared in the DTD as being of type <code>ID</code>. For example:</p>
977
         <samp><![CDATA[<?xml-stylesheet type="text/xsl" href="#style1" ?>
978
<!DOCTYPE BOOKLIST SYSTEM "books.dtd"
979
  <!ATTLIST xsl:transform id ID #IMPLIED>
980
>
981
<BOOKLIST>
982
  ...
983
  <xsl:transform id="style1" version="1.0" xmlns:xsl="...">
984
  ...
985
  </xsl:transform>
986
</BOOKLIST>]]></samp>
987
      </section>
988
   </section>
989

    
990
   <section id="xsltfromant" title="Running Saxon XSLT Transformations from Ant">
991
      <h1>Running Saxon XSLT Transformations from Ant</h1>
992

    
993

    
994
      <p>It is possible to run a Saxon transformation from Ant using the standard <a
995
            href="http://ant.apache.org/manual/Tasks/style.html" class="bodylink">xslt task</a>, by
996
         using the <code>trax</code> processor and with an appropriate <code>classpath</code> that
997
         forces Saxon to be selected. This can now be used to provide the ability to take advantage
998
         of the full range of capabilities offered by XSLT 3.0 in general and Saxon in particular
999
         (for example, schema aware processing and multiple output files).</p>
1000

    
1001
      <aside>The custom Ant task that was developed for earlier Saxon releases is no longer
1002
         supported.</aside>
1003
      
1004
      <p>To ensure that Saxon is the chosen XSLT processor it is safest to use the <code>&lt;factory name="factory-class"&gt;</code>
1005
      element in the the Ant task. The relevant factory classes are:</p>
1006
      
1007
      <ul>
1008
         <li><code java="net.sf.saxon.BasicTransformerFactory">net.sf.saxon.BasicTransformerFactory</code> for Saxon-HE</li>
1009
        <li><code java="com.saxonica.config.ProfessionalTransformerFactory">com.saxonica.config.ProfessionalTransformerFactory</code> for Saxon-PE</li>
1010
        <li><code java="com.saxonica.config.EnterpriseTransformerFactory">com.saxonica.config.EnterpriseTransformerFactory</code> for Saxon-EE</li>
1011
        <li><code java="com.saxonica.config.StreamingTransformerFactory">com.saxonica.config.StreamingTransformerFactory</code> for a streaming transformation in Saxon-EE.
1012
         Note that if this option is selected, the global context item for the transformation (used when a global variable
1013
         initializer references the context item) will be absent, so any reference to "." in a global variable throws an error.</li>
1014
      </ul>
1015

    
1016
      <p>Saxon-specific configuration options can be specified using the <code>attribute</code>
1017
         child of the <code>factory</code> element. For example, the following switches on Saxon
1018
         tracing (the equivalent of the <code>-T</code> option on the command line):</p>
1019
      <samp><![CDATA[  <factory name="net.sf.saxon.TransformerFactoryImpl">
1020
     <attribute name="http://saxon.sf.net/feature/traceListenerClass" 
1021
                value="net.sf.saxon.trace.XSLTTraceListener"/>
1022
  </factory>
1023
]]></samp>
1024

    
1025
      <p>For a full list of feature names, see <a class="bodylink"
1026
            href="/configuration/config-features">Configuration Features</a> or the Javadoc
1027
         documentation of class <a class="javalink" href="net.sf.saxon.lib.Feature"
1028
            >net.sf.saxon.lib.Feature</a>.</p>
1029

    
1030
      <p>A particularly useful feature for use with Ant is
1031
            <code>http://saxon.sf.net/feature/ignoreSAXSourceParser</code>. When Ant invokes Saxon,
1032
         it normally does so supplying a <code>SAXSource</code> object with a contained
1033
            <code>XMLReader</code>. Saxon will not normally change the properties of an
1034
            <code>XMLReader</code> supplied by the application. However, allowing Saxon to supply
1035
         its own <code>XMLReader</code> can be much more efficient, especially in the case where
1036
         there are references to W3C-defined HTML or SVG DTD and entity files: Saxon has internal
1037
         copies of these files, but can only use them if it is allowed to configure the parser
1038
         accordingly. Setting this property authorises Saxon to ignore the parser supplied by Ant
1039
         and use its own.</p>
1040

    
1041
      <p>It is possible to get detailed control of the configuration by specifying the name of a
1042
         Saxon configuration file using this mechanism, for example:</p>
1043
      <samp><![CDATA[  <factory name="com.saxonica.config.EnterpriseTransformerFactory">
1044
    <attribute name="http://saxon.sf.net/feature/configuration-file" 
1045
               value="config-de.xml"/>
1046
  </factory>]]></samp>
1047

    
1048
      <p>In this case this must be the first attribute.</p>
1049

    
1050
      <p>The initial template and initial mode for the transformation can be specified using the
1051
         attribute names <code>http://saxon.sf.net/feature/initialTemplate</code> and
1052
            <code>http://saxon.sf.net/feature/initialMode</code> respectively. The value is a QName
1053
         in Clark notation (that is <code>{uri}local</code>).</p>
1054

    
1055
      <p>Note that names in Clark notation may also be used for the qualified names of stylesheet
1056
         parameters and serialization options.</p>
1057

    
1058
      <p>Note that an Ant transformation always has an input file. If necessary, a dummy file can be
1059
         specified.</p>
1060

    
1061
      <p>There is a history of bugs in successive releases of Ant that mean not all these features
1062
         work in every Ant version. In particular, the <code>classpath</code> attribute of the
1063
            <code>xslt</code> task element has been unreliable: the safest approach is to ensure
1064
         that the Jar files needed to run Saxon are present on the externally-specified classpath
1065
         (the classpath at the point where Ant is invoked), rather than relying on the task-specific
1066
         classpath.</p>
1067
   </section>
1068
   <section id="embedding" title="Invoking XSLT from an application">
1069
      <h1>Invoking XSLT from an application</h1>
1070

    
1071

    
1072
      <p>Rather than running XSLT transformations from the command line, you may want to invoke
1073
         transformations from your own application, perhaps one that runs within a web-based
1074
         application server. If you use Saxon repeatedly to perform multiple transformations, this
1075
         will always be much faster than running it each time from a command line, because of the
1076
         overheads of starting up the Java Virtual Machine.</p>
1077

    
1078
      <p>There are several APIs you can use to invoke Saxon's XSLT processor from an
1079
         application.</p>
1080
      <h2 class="subtitle">The JAXP interface (Java)</h2>
1081

    
1082
      <p>On the Java platform, Saxon incorporates support for the standard <a
1083
            href="http://jaxp.java.net/" class="bodylink">JAXP transformation API</a> (originally
1084
         known as <dfn>TrAX</dfn>). This is compatible with the API for invoking other XSLT
1085
         processors such as Xalan and Oracle.</p>
1086

    
1087
      <p>Although the JAXP interface is convenient, it has several significant drawbacks:</p>
1088

    
1089
      <ol>
1090
         <li>It was defined for XSLT 1.0, and does not directly expose the new features exposed by
1091
            XSLT 2.0 and 3.0, such as the ability to use a named template as the entry point to a
1092
            transformation.</li>
1093
         <li>The interface is not integrated with other XML capabilities, for example schema
1094
            processing, making it cumbersome to combine XSLT processing with other tasks.</li>
1095
         <li>The mechanism for locating an XSLT processor is slow and unreliable; applications that
1096
            were tested to work with one XSLT processor can find themselves executing with another,
1097
            which can cause bugs if the code is not fully portable.</li>
1098
         <li>It does not take advantage of modern Java language features such as generics and streams.</li>
1099
         <li>It is biased towards use of DOM as the tree model; while Saxon supports DOM, it is much
1100
            slower (sometimes by a factor of 10) than other tree models.</li>
1101
      </ol>
1102

    
1103
      <p>This API is described in the documentation provided with JDK 1.5 and later. It is available
1104
         online at <a href="http://docs.oracle.com/javase/8/docs/api/" class="bodylink"
1105
            >http://docs.oracle.com/javase/8/docs/api/</a>. Look for the <a
1106
               href="https://docs.oracle.com/javase/8/docs/api/javax/xml/transform/package-summary.html"
1107
            class="bodylink">javax.xml.transform</a> package.</p>
1108

    
1109
      <p>For more information on using this API to invoke the Saxon XSLT processor, see <a
1110
            href="jaxp-transformation" class="bodylink">Using JAXP for Transformations</a>.</p>
1111

    
1112

    
1113

    
1114
      <h2 class="subtitle">The s9api interface (Java)</h2>
1115

    
1116
      <p>An alternative is to use Saxon's own <strong>s9api</strong> interface. This is designed to
1117
         provide an integrated approach to XML processing across the different range of languages
1118
         supported by Saxon; unlike JAXP, it includes support for XSLT 2.0 and 3.0 capabilities, and
1119
         it also takes advantage of Java generics, thus giving a more strongly typed and therefore more
1120
         robust interface.</p>
1121
      
1122
      <p>Saxon 9.9 introduced enhancements to the s9api interface to take advantage of Java 8 streams and
1123
      functions, providing a native Java interface for navigating XML trees that is comparable with XPath
1124
      in its power and expressiveness, while being much better integrated with the Java host language.</p>
1125
     
1126
      <p>Saxon 10 introduced further enhancements to provide programmatic tree construction (see
1127
      <a class="bodylink" href="/sourcedocs/builder-api">Building XML Trees Programmatically</a>).</p>
1128

    
1129
      <p>For more information on using this API to invoke the Saxon XSLT processor, see <a
1130
            href="s9api-transformation" class="bodylink">Using s9api for Transformations</a>.</p>
1131

    
1132

    
1133
      <h2 class="subtitle">The Saxon.Api interface (.NET)</h2>
1134

    
1135
      <p>There is also an API for Saxon on the .NET platform, designed to make Saxon available from
1136
         .NET languages such as C#, VB.NET, and ASP.NET. For more information on using this API to
1137
         invoke the Saxon XSLT processor, see <a class="bodylink" href="/dotnet/dotnetapi">Saxon API
1138
            for .NET</a>. </p>
1139

    
1140

    
1141
      <section id="s9api-transformation" title="Using s9api for Transformations">
1142
         <h1>Using s9api for Transformations</h1>
1143

    
1144

    
1145
         <p>You can perform a transformation using the s9api interface as follows:</p>
1146
         <ol>
1147
            <li>
1148
               <p>Create a <a class="javalink" href="net.sf.saxon.s9api.Processor">Processor</a> and
1149
                  set any global configuration options on the <code>Processor</code>. If your stylesheet
1150
               uses any features that require Saxon-PE or Saxon-EE, be sure to use the constructor <code>new Processor(true)</code>.</p>
1151
            </li>
1152
            <li>
1153
               <p>Call <code>newXsltCompiler()</code> to create an <a class="javalink"
1154
                     href="net.sf.saxon.s9api.XsltCompiler">XsltCompiler</a>, and set any options
1155
                  that are local to a specific compilation (for example, the destination of error
1156
                  messages).</p>
1157
               <aside>By default, error messages are directed to the <code>System.err</code> output
1158
                  stream, which is fine for an application run from a console, but not so good if
1159
                  it's executing on a web server, or behind a graphical interface. In such cases
1160
                  you'll want to think carefully about where to direct the error messages. One
1161
               mechanism that is often convenient is to call <code>XsltCompiler.setErrorList()</code> 
1162
               supplying a <code>List</code> into which Saxon will place the error messages; on
1163
               completion the application can examine the list and display the errors to the user in
1164
               whatever way is most suitable.</aside>
1165
            </li>
1166
            <li>
1167
               <p>Call the <code>compile()</code> method to compile a stylesheet. The result is an
1168
                     <a class="javalink" href="net.sf.saxon.s9api.XsltExecutable"
1169
                  >XsltExecutable</a>, which can be used as often as you like, in the same thread or
1170
                  in different threads.</p>
1171
            </li>
1172
            <li>
1173
               <p>To run a transformation, call either the <code>load()</code> or
1174
                     <code>load30()</code> method on the <a class="javalink"
1175
                     href="net.sf.saxon.s9api.XsltExecutable">XsltExecutable</a>. This creates an <a
1176
                     class="javalink" href="net.sf.saxon.s9api.XsltTransformer">XsltTransformer</a>
1177
                  or <a class="javalink" href="net.sf.saxon.s9api.Xslt30Transformer"
1178
                     >Xslt30Transformer</a> respectively. Either of these can be used to run the
1179
                  transformation (regardless of which XSLT version you are using), but they have
1180
                  different capabilities:</p>
1181

    
1182
               <ol>
1183
                  <li>
1184
                     <p>The <a class="javalink" href="net.sf.saxon.s9api.XsltTransformer"
1185
                           >XsltTransformer</a> is geared towards the traditional way of running an
1186
                        XSLT transformation, by supplying a principal source document as input. When
1187
                        you call the <code>transform()</code> method, the template rule that best
1188
                        matches this source document is located and executed. The result of
1189
                        executing this template is wrapped into a document node to create a result
1190
                        tree, which is optionally serialized using one of the output methods
1191
                           <code>xml</code>, <code>html</code>, or <code>text</code>. As well as
1192
                        processing the source document using template rules, it is also used as the
1193
                        context item for evaluating global variables.</p>
1194
                     <p>The <code>XsltTransformer</code> also allows you to start executing the
1195
                        stylesheet with a named template as the entry point. In this case there will
1196
                        not necessarily be a source document, though you can still supply one, and
1197
                        it will be used as the context item for global variables.</p>
1198
                     <p>You can use methods on the <code>XsltTransformer</code> to set values for
1199
                        global stylesheet parameters, but not for parameters declared at the level
1200
                        of a particular <code>xsl:template</code> element.</p>
1201
                     <p>The output of the transformation is specified as a <a class="javalink"
1202
                           href="net.sf.saxon.s9api.Destination">Destination</a> object, which
1203
                        allows a wide range of possibilities: you can send the output to a
1204
                        serializer, or to a SAX <code>ContentHandler</code>. You can build a tree
1205
                        either in Saxon's native format (represented by the s9api class
1206
                           <code>XdmNode</code>) or as a DOM. You can send the output to be
1207
                        validated against a schema by nominating a <a class="javalink"
1208
                           href="net.sf.saxon.s9api.SchemaValidator">SchemaValidator</a> as the
1209
                        destination, or you can pipe it through another transformation, because
1210
                           <code>XsltTransformer</code> itself implements the
1211
                           <code>Destination</code> interface.</p>
1212
                  </li>
1213
                  <li>
1214
                     <p>The <a class="javalink" href="net.sf.saxon.s9api.Xslt30Transformer"
1215
                           >Xslt30Transformer</a> class was introduced in Saxon 9.6, and as its name
1216
                        suggests, it provides new ways of executing stylesheet code that are defined
1217
                        in the XSLT 3.0 specification, though Saxon also allows you to use the same
1218
                        entry points with 1.0 or 2.0 stylesheets. Among the new capabilities
1219
                        are:</p>
1220
                     <ul>
1221
                        <li>You can invoke a specific stylesheet function, with parameters, rather
1222
                           than invoking a named template or template rule.</li>
1223
                        <li>If you start execution with a named template or template rule, you can
1224
                           supply values for the parameters defined on that template, as well as the
1225
                           global stylesheet parameters.</li>
1226
                        <li>Whether you execute a template or a function, you can return the results
1227
                           in raw form rather than wrapping them in a result tree. For example, a
1228
                           function (or template) might return a sequence of strings, or a single
1229
                           boolean, or a map, or even a function.</li>
1230
                        <li>There is no longer any necessary relationship between the "principal
1231
                           source document" (if it still exists) and the context item for evaluating
1232
                           global variables. The two things are quite independent of each
1233
                           other.</li>
1234
                     </ul>
1235
                     <p>It is still possible to wrap the output in a result tree and send it to a
1236
                           <code>Destination</code> (which might be a <code>Serializer</code>), but
1237
                        this is no longer mandatory.</p>
1238
                     <p>The <code>Xslt30Transformer</code> does not implement the
1239
                        <code>Destination</code> interface directly; but you can call its <code>asDocumentDestination()</code>
1240
                        method to get a <code>Destination</code> object allowing the transformation to act as the
1241
                        destination of some other process in the pipeline.</p>
1242
                  </li>
1243
               </ol>
1244

    
1245
               <p>Both <code>XsltTransformer</code> and <code>Xslt30Transformer</code> can be
1246
                  serially reused, but they must not be shared across multiple threads. Both allow
1247
                  you to set any options required for the specific transformation (for example, the
1248
                  global context item, the stylesheet parameters, and the error listener).</p>
1249
            </li>
1250
         </ol>
1251

    
1252

    
1253
          <p>Examples of s9api transformations are included in the <code>saxon-resources</code>
1254
              download file, see the sample application <strong>S9APIExamples.java</strong>, and <a
1255
                  class="bodylink" href="/samples/s9api">S9API Examples</a> for more information.</p>
1256
         
1257
         <p>For instance, "TransformA" in S9APIExamples tests the following (to run the <a class="bodylink"
1258
            href="/samples/books">Book List Example</a>):</p>
1259
         <samp><![CDATA[   Processor processor = new Processor(false);
1260
   XsltCompiler compiler = processor.newXsltCompiler();
1261
   XsltExecutable stylesheet = compiler.compile(new StreamSource(new File("styles/books.xsl")));
1262
   Serializer out = processor.newSerializer(new File("books.html"));
1263
   out.setOutputProperty(Serializer.Property.METHOD, "html");
1264
   out.setOutputProperty(Serializer.Property.INDENT, "yes");
1265
   Xslt30Transformer transformer = stylesheet.load30();
1266
   transformer.transform(new StreamSource(new File("data/books.xml")), out);]]></samp>
1267
         
1268
      </section>
1269

    
1270
      <section id="jaxp-transformation" title="Using JAXP for Transformations">
1271
         <h1>Using JAXP for Transformations</h1>
1272

    
1273

    
1274
         <p>This API is described in the documentation provided with JDK 1.5 and later. It is
1275
            available online at <a href="http://download.oracle.com/javase/6/docs/api/"
1276
               class="bodylink">http://download.oracle.com/javase/6/docs/api/</a>. Look for the <a
1277
               href="http://download.oracle.com/javase/6/docs/api/javax/xml/transform/package-summary.html"
1278
               class="bodylink">javax.xml.transform</a> package.</p>
1279

    
1280
         <p>More information and examples relating to the JAXP transformation API can be found in
1281
            the <strong>JAXPExamples.java</strong> example application found in the samples
1282
            directory of the <code>saxon-resources</code> file, see <a class="bodylink"
1283
                href="/samples/jaxp">JAXP Transformation Examples</a>.</p>
1284

    
1285
         <p>If you want to be sure that Saxon (and not some other XSLT engine) is loaded to perform
1286
            your transformations, you need to know the class name of Saxon's implementation of the
1287
            JAXP <code>TransformerFactory</code> class. This depends on which Saxon edition you are
1288
            using:</p>
1289

    
1290
         <ul>
1291
            <li>
1292
               <p>
1293
                  <strong>Any:</strong>
1294
                  <a class="javalink" href="net.sf.saxon.TransformerFactoryImpl"
1295
                     >net.sf.saxon.TransformerFactoryImpl</a>. This will create a Saxon
1296
                  configuration based on the software and license file that are available at
1297
                  run-time on the classpath. For example, if the Saxon-PE software is on the classpath,
1298
                  and a license file for Saxon-PE is available, then the Saxon configuration
1299
                  will allow use of Saxon-PE capabilities such as extended serialization
1300
                  attributes. If you want to be sure of loading a configuration aligned
1301
                  with the features of a specific Saxon edition, use one of the more
1302
                  specific implementations of <code>TransformerFactory</code>.
1303
               </p>
1304
            </li>
1305
            <li>
1306
               <p>
1307
                  <strong>Saxon-HE:</strong>
1308
                  <a class="javalink" href="net.sf.saxon.BasicTransformerFactory"
1309
                     >net.sf.saxon.BasicTransformerFactory</a>
1310
               </p>
1311
            </li>
1312
            <li>
1313
               <p>
1314
                  <strong>Saxon-PE:</strong>
1315
                  <a class="javalink" href="com.saxonica.config.ProfessionalTransformerFactory"
1316
                     >com.saxonica.config.ProfessionalTransformerFactory</a>
1317
               </p>
1318
            </li>
1319
            <li>
1320
               <p>
1321
                  <strong>Saxon-EE:</strong>
1322
                  <a class="javalink" href="com.saxonica.config.EnterpriseTransformerFactory"
1323
                     >com.saxonica.config.EnterpriseTransformerFactory</a>
1324
               </p>
1325
               <p>
1326
                  <strong>Saxon-EE with streaming:</strong>
1327
                  <a class="javalink" href="com.saxonica.config.StreamingTransformerFactory"
1328
                     >com.saxonica.config.StreamingTransformerFactory</a>. This differs from
1329
                  the standard JAXP <code>TransformerFactory</code> in that the document supplied
1330
                  as the <code>Source</code> argument of the <code>transform()</code> method does
1331
                  not cause the global context item to be set (any reference to the context item
1332
                  from the initializer of a global variable will therefore cause a dynamic error
1333
                  XPDY0002). When the source is supplied as a <code>SAXSource</code> or <code>StreamSource</code>
1334
                  and the initial mode is streamable, the transformation will run in streaming mode.
1335
               </p>
1336
               <p>The <code>newTransformerHandler()</code> method of the <code>StreamingTransformerFactory</code>
1337
               returns a SAX <code>TransformerHandler</code> to which streamed input can be supplied as a sequence
1338
               of calls on methods such as <code>startElement()</code>, <code>characters()</code>, and <code>endElement()</code>.</p>
1339
               <p>Similarly, the <code>newXMLFilter()</code> method of the <code>StreamingTransformerFactory</code>
1340
                  returns a SAX <code>XMLFilter</code> which takes streamed input and produces streamed output; a fully
1341
                  streamed pipeline can be created by assembling a sequence of such <code>XMLFilter</code> classes
1342
                  in the usual JAXP way.</p>
1343
            </li>
1344
         </ul>
1345

    
1346
         <p>To ensure that the relevant implementation of <code>TransformerFactory</code> is loaded,
1347
            several strategies are possible:</p>
1348

    
1349
         <ol>
1350
            <li>Set the system property:
1351
               <code><span class="nowrap">-Djava.xml.transform.TransformerFactory</span>=net.sf.saxon.BasicTransformerFactory</code></li>
1352
            <li>Use the version of <code>TransformerFactory.newInstance()</code> that accepts the
1353
               name of the required factory class as a string.</li>
1354
            <li>Instantiate the class directly: <code>TransformerFactory factory = new
1355
                  net.sf.saxon.BasicTransformerFactory()</code>. This has the benefit of being much
1356
               faster than the JAXP classpath search.</li>
1357
         </ol>
1358

    
1359
         <p>If your application uses this API in conjunction with other APIs such as the JAXP XPath
1360
            API or the JAXP Schema validation API, then you need to take care to ensure that all the
1361
            factory classes use the same underlying Saxon <a class="javalink"
1362
               href="net.sf.saxon.Configuration">Configuration</a> object. This is necessary to
1363
            ensure that the integer codes which Saxon uses internally for name matching
1364
               (<code>NamePool</code> codes) are consistent. All the Saxon implementations of these
1365
            factory classes allow you to get and set the <code>Configuration</code> so that you can
1366
            meet this requirement.</p>
1367

    
1368

    
1369

    
1370

    
1371

    
1372
         <p>The types of object that can be supplied as stylesheet parameters are not defined in the
1373
            JAXP specification: they are implementation-dependent. Saxon takes the Java object
1374
            supplied, and converts it to an XPath value using the same rules as it applies for the
1375
            return value from a Java extension function: for these rules, see <a class="bodylink"
1376
               href="/extensibility/functions/function-result">Extensibility Mechanisms</a>. If the
1377
            resulting value is an atomic value, it is cast to the required type of the parameter as
1378
            specified in the <code>xsl:param</code> declaration, using the XPath casting rules. If
1379
            the value is non-atomic (for example, if it is a node, or a sequence of integers), then
1380
            no conversion is attempted, instead, the value must match the required type as
1381
            stated.</p>
1382

    
1383
         <p>The JAXP <code>TransformerFactory</code> interface provides a configuration method
1384
               <code>setAttribute()</code> for setting implementation-defined configuration
1385
            parameters. The parameters supported by Saxon have names defined by constants in the
1386
            class <a class="javalink" href="net.sf.saxon.lib.Feature">net.sf.saxon.lib.Feature</a>.
1387
            The names of these properties and their meanings, are described in <a class="bodylink"
1388
               href="/configuration/config-features">Configuration Features</a>.</p>
1389

    
1390
         <p>Where the required value of a property is a <code>Boolean</code>, the supplied value may
1391
            be either a <code>java.lang.Boolean</code>, or a string holding the values "true" or
1392
            "false" (also accepted are "on"|"off", "1"|"0", or "yes"|"no"). The returned value of
1393
            the property, however, will be a <code>Boolean</code>.</p>
1394

    
1395
         <p>From Saxon 9.6, Saxon's implementation of JAXP is layered on top of the s9api interface.
1396
            This means that attempts to "downcast" JAXP objects to the underlying Saxon objects (for
1397
            example, casting the JAXP <code>Transformer</code> as an instance of
1398
           <code java="net.sf.saxon.Controller">net.sf.saxon.Controller</code>) will no longer work. The Saxon implementation
1399
            classes are in most cases still available, but by a different route (for example the
1400
               <code>Transformer</code> can now be cast to a
1401
           <code java="net.sf.saxon.jaxp.TransformerImpl">net.sf.saxon.jaxp.TransformerImpl</code> object, which offers a method
1402
               <code>getUnderlyingController()</code>). But internal objects such as
1403
           <code java="net.sf.saxon.Controller">net.sf.saxon.Controller</code> are not in general stable from one release to
1404
            the next.</p>
1405

    
1406

    
1407

    
1408
         <p>When using the JAXP interface, you can set serialization properties using a
1409
               <code>java.util.Properties</code> object. The names of the core XSLT 1.0 properties,
1410
            such as <code>method</code>, <code>encoding</code>, and <code>indent</code>, are defined
1411
            in the JAXP class <code>javax.xml.transform.OutputKeys</code>. Additional properties,
1412
            including Saxon extensions and XSLT 2.0/3.0 extensions, have names defined by constants in
1413
            the class <a class="javalink" href="net.sf.saxon.lib.SaxonOutputKeys"
1414
               >net.sf.saxon.lib.SaxonOutputKeys</a>. The values of the properties are exactly as
1415
            you would specify them in the <code>xsl:output</code> declaration, except that QNames
1416
            are written in Clark notation (<code>{uri}local</code>).</p>
1417
      </section>
1418
   </section>
1419

    
1420
   <section id="compiling" title="Compiling a Stylesheet">
1421
      <h1>Compiling a Stylesheet</h1>
1422

    
1423
      <p>Generally, the cost of analyzing the XSLT source code in a stylesheet and preparing it for
1424
         execution can be high in relation to the cost of actually running the code to transform an
1425
         individual source document, especially where the stylesheet is large and the source
1426
         document is small. Saxon provides several capabilities designed to ensure that when you use
1427
         the same stylesheet repeatedly, you only need to incur this overhead once.</p>
1428

    
1429
      <ul>
1430
         <li>In simple cases, you can exploit the ability to process an entire directory of source
1431
            files using a single invocation of the <code>Transform</code> command on the command
1432
            line.</li>
1433
         <li>Both the JAXP and s9api interfaces separate the process of compiling a stylesheet and
1434
            the process of using it to transform a source document. (With JAXP the object
1435
            representing the compiled stylesheet is the <code>javax.xml.transform.Templates</code>
1436
            object, with s9api it is the <code
1437
               java="net.sf.saxon.s9api.XsltExecutable">XsltExecutable</code>). If you run
1438
            transformations within a web service then it is always a good idea to cache the compiled
1439
            form of the stylesheets it uses.</li>
1440
         <li>From Saxon 9.7, it is also possible to export the compiled form of a stylesheet as an
1441
            XML file (called the <i>stylesheet export file</i>), in much the same way that 
1442
            object code from other languages is saved to
1443
            filestore, and distributed from developers to users.</li>
1444
         <li>A related capability is the ability in Saxon-EE to generate bytecode (intermediate Java
1445
            code) to improve the speed of stylesheet execution.</li>
1446
      </ul>
1447

    
1448
      <h2 class="subtitle">Caching compiled stylesheets in memory</h2>
1449

    
1450
      <p>The JAXP interface represents a compiled stylesheet as a <code>Templates</code> object. The
1451
         object contains the entire stylesheet; all modules must be compiled as a single unit. JAXP
1452
         was designed before packages were added to the XSLT 3.0 language. The
1453
            <code>Templates</code> object is thread-safe, so once created it can be used by many
1454
         transformations running separately in parallel. To use the <code>Templates</code> object to
1455
         run a transformation of a particular source document, a <code>Transformer</code> object is
1456
         created. The <code>Transformer</code> is not thread-safe; its <code>transform()</code>
1457
         method must not be called while a transformation is active. The <code>Transformer</code>
1458
         can be serially reused, but with Saxon there is no benefit in doing so; better garbage
1459
         collection generally occurs if a new <code>Transformer</code> is created for each
1460
         transformation.</p>
1461

    
1462
      <p>The s9api interface in its original form has a similar design: a compiled stylesheet is
1463
         represented by a <code java="net.sf.saxon.s9api.XsltExecutable">XsltExecutable</code>
1464
         object, and the instantiation of a stylesheet performing a single transformation by an
1465
            <code java="net.sf.saxon.s9api.XsltTransformer">XsltTransformer</code> object. The s9api
1466
         interface also adds a third class to the design, namely the <code
1467
            java="net.sf.saxon.s9api.XsltCompiler">XsltCompiler</code>, which holds compile-time
1468
         options such as the base URI of the stylesheet, values of static parameters, and
1469
         compile-time options such as whether to generate bytecode, how to resolve references to
1470
         modules (<code>xsl:include</code>/<code>xsl:import</code>), what schema definitions to use,
1471
         and where to report compile-time errors. The <code>XsltCompiler</code> is also thread-safe,
1472
         though the options in force should not be changed while the compiler is in use, and you may
1473
         need to think carefully about how to capture compilation errors if several compilations
1474
         are active at the same time. Different
1475
            <code>XsltCompiler</code> instances with different option settings can run concurrently
1476
         with each other.</p>
1477

    
1478
      <p>XSLT 3.0 packages have been supported since Saxon 9.6. A package may consist of a single module,
1479
         or of a number of modules connected using <code>xsl:include</code>/<code>xsl:import</code>;
1480
         a package is compiled as a unit, and may have references to other packages (via
1481
            <code>xsl:use-package)</code> that are compiled independently. To allow independent
1482
         compilation, there is much stronger control over the interfaces that a package exposes to
1483
         the outside world, and over the ability of declarations in one package to override another.
1484
         For example, if a function is declared to return an integer, then when compiling a call to
1485
         that function, the compiler can be confident that any overriding declaration of the
1486
         function will still return an integer result.</p>
1487

    
1488
      <p>In the s9api interface, a package is represented by an <code
1489
            java="net.sf.saxon.s9api.XsltPackage">XsltPackage</code> object. The
1490
            <code>XsltCompiler</code> has a method <code>compilePackage</code> which returns an
1491
            <code>XsltPackage</code> if successful. The package may be made available for use by
1492
         other packages being compiled, in the same or in a different <code>XsltCompiler</code>, by
1493
         the <code>XsltCompiler</code>'s <code>importPackage</code> method. When an
1494
            <code>xsl:use-package</code> declaration is found while compiling one package, the
1495
         compiler searches for a matching package among those that have been imported by the
1496
            <code>XsltCompiler</code> in this way. It is possible to import several different
1497
         versions of the same package, and the <code>package-version</code> attribute of
1498
            <code>xsl:use-package</code> determines which of them is loaded. </p>
1499

    
1500
      <p>The <code>XsltPackage</code> object, once created, is immutable and thread-safe. It is tied
1501
         to a Saxon <code java="net.sf.saxon.Configuration">Configuration</code> (or s9api <code
1502
            java="net.sf.saxon.s9api.Processor">Processor</code>) but it can be imported by multiple
1503
            <code>XsltCompiler</code> instances. If a common library package is used by many
1504
         different stylesheets, it makes sense to define it as a reusable package, since this avoids
1505
         the cost of compiling the code repeatedly, and avoids the need to keep multiple copies in
1506
         memory.</p>
1507
      
1508
      <h2 class="subtitle">JIT Compilation of Template Rules</h2>
1509
      
1510
      <p>Sometimes a stylesheet may contain hundreds of template rules to define the processing of elements
1511
      that never actually appear in the source documents; source documents may use a tiny fraction of the
1512
      defined vocabulary. In this situation, it is wasteful to compile all these template rules every time
1513
      the stylesheet is used. This isn't a problem when the stylesheet is compiled once, cached, and used
1514
      to run a large number of transformations; but it is a problem in a batch workflow where the stylesheet
1515
      is compiled every time it is used.</p>
1516
      
1517
      <p>To improve the efficiency of this kind of workload, Saxon-EE by default uses just-in-time compilation
1518
      of template rules. On first reading the stylesheet, all the match patterns are processed and a suitable decision table
1519
      is constructed; but the body of a template rule is not compiled into executable form until the first time that
1520
      template rule is matched.</p>
1521
      
1522
      <p>A consequence of this is that static errors (for example, invalid path expressions) in such templates
1523
      may go undetected if the code is not actually executed.</p>
1524
      
1525
      <p>JIT compilation is enabled by default. It can be suppressed from the command line by setting <code>-jit:off</code>.
1526
      Setting the <code>export</code>, <code>explain</code>, or <code>nogo</code> options also has the side-effect
1527
      of suppressing JIT compilation. There is also an option available on the <code>XsltCompiler</code> object.</p>
1528
      
1529
      <p>It probably makes sense to suppress JIT compilation in any workload where the compiled stylesheet is
1530
      cached and used repeatedly.</p>
1531

    
1532
      <h2 class="subtitle">Exporting Packages</h2>
1533

    
1534
      <p>A package, once compiled into an <code java="net.sf.saxon.s9api.XsltPackage"
1535
            >XsltPackage</code> object, can be saved as a <i>stylesheet export file</i> (SEF) using the <code>save()</code> method
1536
         of the <code>XsltPackage</code>. The generated file is intended to be used for one purpose
1537
         only, namely for reconstituting the <code>XsltPackage</code> at a different time and place.
1538
         The format is XML, but its interpretation is not published and should not be considered
1539
         stable. The file contains a checksum and cannot be loaded in the event of a checksum
1540
         failure, so modifications to the content are not permitted. The content of the file is
1541
         sufficiently far removed from the original source that distributing code in this form
1542
         achieves a useful level of IP protection, though like Java bytecode, it is not intended to
1543
         resist determined attempts at reverse engineering. Indeed, in the interests of run-time
1544
         diagnostics, it preserves information such as variable names and line numbers that are not
1545
         strictly needed at execution time.</p>
1546
      
1547
      <p>The simplest way to generate an export file is from the command line, for example with
1548
         Saxon-EE 10.0:</p>
1549
      
1550
      <kbd>java -jar <i>dir</i>/saxon-ee-10.0.jar -xsl:stylesheet.xsl -export:stylesheet.sef -nogo</kbd>
1551
      
1552
      <p>Here, the option <code>-nogo</code> suppresses any attempt to execute the stylesheet.</p>
1553
      
1554
      <p>Additionally, the <code>-relocate:on</code> option can be used to produce an export package
1555
         which can be deployed to a different location, with a different base URI.</p>
1556
      
1557
      <p>The <code>-target</code> option can be used to specify the edition of Saxon which will be used
1558
         to run the stylesheet export file. The accepted values are <code>EE|PE|HE|JS</code>, and the
1559
         default is <code>EE</code>. For instance, specify <code>-target:HE</code> to produce an
1560
         export file which can be executed by Saxon-HE (this will suppress the generation of optimized
1561
         constructs that Saxon-HE cannot execute).</p>
1562
      
1563
      <p>A stylesheet export file for a complete stylesheet (as distinct from a library package) is accepted
1564
      by any Saxon interface that accepts a source stylesheet. For example, from the command line:</p>
1565
      
1566
      <kbd>java -jar <i>dir</i>/saxon-ee-10.0.jar -xsl:stylesheet.sef -s:source.xml</kbd>
1567
      
1568
      <aside><p>This means that you can generally use a stylesheet export file transparently with third-party tools,
1569
      for example with the Ant <code>xslt</code> task. So long as the third-party tool does nothing with
1570
      the supplied stylesheet other than passing it to Saxon, passing a stylesheet export file instead of
1571
      a source stylesheet should always work.</p>
1572
      
1573
      <p>In particular, stylesheet export files can be passed to the JAXP <code>newTemplates()</code>
1574
      method in place of a source stylesheet.</p></aside>
1575
      
1576
      <p>A stylesheet export file is also needed when using the Saxon-JS product to run transformations
1577
      in the browser. In this case the export file must be generated with the option
1578
         <code>-target:JS</code>
1579
      because there are minor differences. SEF files for Saxon-JS 2.0 are generated in JSON rather than XML format.</p>
1580

    
1581
      <p>When exporting a package, all components (templates, functions, etc) from the packages it
1582
         uses are also exported. It is possible therefore either to export an individual library
1583
         package (typically having no dependencies on other packages), or a complete stylesheet (a
1584
         package together with its tree of dependencies). As well as the s9api interface, packages
1585
         can also be exported using the <code>-export</code> option on the <code
1586
            java="net.sf.saxon.Transform">net.sf.saxon.Transform</code> command line. Packages can
1587
         similarly be imported either by listing them in the <code>-pack</code> option of
1588
            <code>net.sf.saxon.Transform</code>, or within s9api by use of the <code
1589
            java="net.sf.saxon.s9api.XsltCompiler">XsltCompiler</code> methods
1590
            <code>loadLibraryPackage</code> and <code>loadExecutablePackage</code>.</p>
1591

    
1592
      <p>In the case of schema-aware stylesheets, the schema components needed by a stylesheet are
1593
         not exported along with the stylesheet code. The user of the stylesheet needs to import the
1594
         required schemas before the stylesheets can be loaded. The schema loaded at execution time
1595
         must match the schema used when the stylesheet was compiled. Saxon is not draconian about
1596
         checking this, and many minor changes will cause no trouble (for example, changing the
1597
         regular expression used in a pattern facet). Structural changes that invalidate the
1598
         assumptions made during XSLT compilation, however, are likely to cause execution to fail,
1599
         not necessarily in predictable ways.</p>
1600

    
1601
      <p>The computer on which the stylesheet is executed needs to have a Saxon license of
1602
         sufficient capability to meet the requirements of the stylesheet. There are two ways this
1603
         can be achieved. Either the run-time system can have a conventional Saxon license installed
1604
         in the normal way, or it can take advantage of a license embedded within the exported
1605
         stylesheet itself. Saxonica offers developers the option of purchasing a "developer master
1606
         key" which, if installed, will cause all exported stylesheets to contain an embedded
1607
         license key sufficient to execute the stylesheet in question. An embedded license key
1608
         applies only to that stylesheet and cannot be used for any other code developed elsewhere;
1609
         stylesheets that are exported with an embedded license can only be executed "as is", and
1610
         cannot be incorporated as libraries into larger applications.</p>
1611

    
1612
      <p>Exporting stylesheet packages requires Saxon-EE, optionally with the Developer Master Key
1613
         if stylesheets with embedded license information are to be exported. From Saxon 9.9, importing stylesheet
1614
         packages is possible using any Saxon edition, provided that the run-time software and the
1615
         run-time license key (where needed) support the features used by the stylesheet in question.</p>
1616
      
1617
      <p>There are a small number of cases where a valid stylesheet cannot be exported; but they
1618
      are very unlikely to be encountered in practice. Many of the restrictions relate to static global variables (or parameters).
1619
      A stylesheet cannot be exported if it contains static global variables that are bound to:</p>
1620

    
1621
      <ul>
1622
         <li>Functions defined in XQuery, for example, a variable initialized using
1623
         <code>fn:load-query-module()</code> (this is because Saxon cannot export functions containing XQuery-specific
1624
         constructs such as general FLWOR expressions)</li>
1625
         <li>Function items returned from
1626
         another stylesheet invoked by calling <code>fn:transform()</code></li>
1627
         <li>External Java objects</li>        
1628
      </ul>
1629
      
1630
      <p>Where a stylesheet being exported contains static variables bound to nodes, the nodes will be reconstructed
1631
      on import. The reconstructed nodes will be parentless, and will lose their inter-node relationships. For example
1632
      if the value of such a variable contains a sequence of ten elements that are siblings of each other, the
1633
      reconstructed element nodes will not be siblings of each other (they will be parentless).</p>
1634

    
1635
      <h2 class="subtitle">Bytecode generation</h2>
1636

    
1637
      <p>When a stylesheet package is compiled into its in-memory representation, Saxon-EE by
1638
         default generates Java bytecode for faster execution of selected parts of the code. The
1639
         generated bytecode is mixed with interpreted code, each calling the other where
1640
         appropriate.</p>
1641
      
1642
      <p>From Saxon 9.8, bytecode generation is by default applied only to hotspots, that is, parts of the 
1643
      executable code that are found to be frequently executed. These will often be predicates in filter
1644
      expressions. The threshold for generating bytecode is configurable. Bytecode generation can be monitored
1645
      using the <code>-TB</code> option on the command line.</p>
1646

    
1647
      <p>The performance boost achieved by bytecode generation is variable; 25% is typical. The
1648
         functions and templates that benefit the most are those where the expression tree contains
1649
         many constructs that are relatively cheap in themselves, such as type conversion,
1650
         comparisons, and arithmetic. This is because the saving from bytecode generation is mainly
1651
         not in the cost of performing primitive operations, but in the cost of deciding which
1652
         operations to perform: so the saving is greater where the number of operations is high
1653
         relative to their average cost.</p>
1654

    
1655
      <p>There are configuration options to suppress bytecode generation
1656
            (<code>Feature.GENERATE_BYTE_CODE</code>), to insert debugging logic into the
1657
         generated bytecode (<code>Feature.DEBUG_BYTE_CODE</code>), and to display the generated
1658
         bytecode (<code>Feature.DISPLAY_BYTE_CODE</code>). See <a class="bodylink"
1659
            href="/configuration/config-features">Configuration Features</a> for more
1660
         information.</p>
1661

    
1662
      <p>Currently, exported packages do not include bytecode.</p>
1663

    
1664
   </section>
1665
   <section id="performanceanalysis" title="Performance Analysis">
1666
      <h1>Performance Analysis</h1>
1667
      <p>This section describes tools designed to assist with performance monitoring and tuning.</p>
1668
      
1669
      <h2 class="subtitle">Profiling Execution Time</h2>
1670
      <p>Saxon comes with a simple tool allowing profiling of the execution time in a
1671
         stylesheet.</p>
1672
      <p>To run this tool, first execute the transformation with the <code>-TP:filename</code>
1673
         option, which will gather timed tracing information and create a profile report to the
1674
         specified file (or to the standard error output if no filename is given). For example:</p>
1675
      <kbd>java   net.sf.saxon.Transform   -TP:profile.html   -s:<i>source</i>  
1676
            -xsl:<i>stylesheet</i>
1677
      </kbd>
1678
      <p>Then view the resulting <code>profile.html</code> file in your browser.</p>
1679
      <p>The output identifies templates and functions in the original stylesheet by their name or
1680
         match pattern, line number, and the last part of the URI of their module. For
1681
         each instruction it gives the number of times the instruction was executed, the average
1682
         time in milliseconds of each execution, and the total time. Timings are given both gross
1683
         (the time for a template including all the templates it calls recursively), and net (the
1684
         time for a template excluding time in its called templates). The table is sorted according
1685
         to a weighting function that attempts to put the dominant functions and templates at the
1686
         top. These will not necessarily be those with the greatest time, which tend to be
1687
         instructions that were only executed once but remained active for the duration of the
1688
         transformation.</p>
1689
     
1690
      <h2 class="subtitle">Monitoring Bytecode Performance</h2>
1691
     
1692
     <p>Saxon-EE by default generates bytecode to speed up execution of the most frequently executed
1693
     parts of a stylesheet.</p>
1694
     
1695
     
1696
     <p>On the Transform command line, the option <code>-TB:filename</code> can be used to request a
1697
     report showing the effectiveness of bytecode generation. The output is in XML format, something 
1698
     like this:</p>
1699
     
1700
     <samp><![CDATA[<stats unit='microseconds'>
1701
 <exp id="0" text="($title, ...)" intCount="1" ... module="books.xsl" line="36" />
1702
 <exp id="2" text="@CODE" intCount="3" ... module="books.xsl" line="83" />
1703
 <exp id="1" text="@DESC" intCount="3" ... module="books.xsl" line="82" />
1704
</stats>]]></samp>
1705
     
1706
     <p>In this report, each <code>exp</code> element represents an expression that was compiled as
1707
     a candidate for bytecode generation. The report contains the following attributes:</p>
1708
     
1709
    <ul>
1710
       <li><code>text</code>: Abbreviated text of the expression</li>
1711
       <li><code>intCount</code>: Number of times the expression was evaluated in the interpreter</li>
1712
       <li><code>intTime</code>: Cumulative time spent evaluating the expression (including subexpressions) in the interpreter</li>
1713
       <li><code>bcCount</code>: Number of times the expression was evaluated as bytecode</li>
1714
       <li><code>bcTime</code>: Cumulative time spent evaluating the expression (including subexpressions) as bytecode</li>
1715
       <li><code>compileTime</code>: Time spent generating bytecode for the expression</li>
1716
       <li><code>ratio</code>: Average bytecode execution time as a proportion of average interpreted execution time</li>
1717
       <li><code>ebv</code>: Number of evaluations of the expression's <code>effectiveBooleanValue()</code> method</li>
1718
       <li><code>eval</code>: Number of evaluations of the expression's <code>evaluateItem()</code> method</li>
1719
       <li><code>iterate</code>: Number of evaluations of the expression's <code>iterate()</code> method</li>
1720
       <li><code>process</code>: Number of evaluations of the expression's <code>process()</code> method</li>
1721
       <li><code>module</code>: URI of the module containing the expression</li>
1722
       <li><code>line</code>: Line number of the expression within this module</li>
1723
     </ul>
1724

    
1725
     <aside>The execution counts can be a handy diagnostic tool for understanding where stylesheet execution
1726
     time is going, quite independent of bytecode generation.</aside>
1727
     
1728
     <p>Note that if an expression A contains an expression B
1729
     and both are candidates for bytecode generation, then the statistics for B relate only
1730
     to the time before A was compiled in its own right.</p>
1731
     
1732
      <!--<aside>From 9.7, Saxon-EE contains an additional experimental package to analyse template
1733
         pattern matching performance, for more information see <a class="bodylink"
1734
            href="statsTransform">Detailed Pattern-Matching Statistics</a>.</aside>
1735
-->
1736
      <!--<section id="statsTransform" title="Detailed Pattern-Matching Statistics">
1737
         <h1>Detailed Pattern-Matching Statistics</h1>
1738
         <p><b>Techniques described here are experimental and only available in Saxon-EE</b>.</p>
1739
         <p>Saxon-EE 9.7 has an additional experimental package (supplied in
1740
               <code>saxon9-stats.jar</code>) that analyses template pattern matching performance,
1741
            providing comparative statistics between a number of possible configurations and
1742
            optimization features operating on the same input data. The results are presented as a
1743
            small linked set of web pages and SVG graphs.</p>
1744
         <p>To run this tool, with an appropriate classpath pointing to a Saxon-EE jar <b>,
1745
               saxon9-stats.jar</b> and suitable licence file, execute</p>
1746
         <kbd>java com.saxonica.StatsTransform -s:<i>source</i>? -xsl:<i>stylesheet</i>?
1747
               -o:<i>output</i>? -stats:<i>statsfile</i>? ... </kbd>
1748
         <p>where <i>statsfile</i> is an optional control file described below. Many of the more
1749
            usual Saxon control options (<code>-repeat:</code> etc.) are relevant.</p>
1750
         <p>The stylesheet will be executed over the input for each of the cases given, with
1751
            statistical data being written into files within suitable local directories. Then an
1752
            internal stylesheet generates a set of web pages, whose master index will be at the
1753
            location <code>statistics/{replace(<em>statsfile</em>,'\.xml$','.html')}</code>, i.e in
1754
            a locally-relative subdirectory <code>statistics</code>, with a name usually
1755
            substituting html for trailing xml.</p>
1756

1757
         <h3>Statistic Control File</h3>
1758
         <p>The (optional) statistics control file has the following generic form</p>
1759
         <samp><![CDATA[  <stats xsl="stylesheet"? s="source"? description="description"?>    
1760
      <group name="group-name"  show="details? time? call? rank?">
1761
          <case  label="case-tag ; case-label"? dir="caseWorkingDirectory/"/>?
1762
       </group> *   
1763
  </stats>]]></samp>
1764
         <p>where the content is defined as follows:</p>
1765
         <dl>
1766
            <dt>stylesheet</dt>
1767
            <dd>The stylesheet to execute, relative to this file. This can be overridden through the
1768
                  <code>-xsl</code> switch. At least one of these (attribute or switch) must be
1769
               present.</dd>
1770
            <dt>source</dt>
1771
            <dd>The source document to process, relative to this file. This can be overridden
1772
               through the <code>-s</code> switch. At least one of these (attribute or switch) must
1773
               be present unless the initial-template has been specified via a command-line
1774
               switch.</dd>
1775
            <dt>group-name</dt>
1776
            <dd>The name to use for the comparison group, which should be exploitable as a directory
1777
               name.</dd>
1778
            <dt>show</dt>
1779
            <dd>What aspects to display, given as a whitespace separated list of directives: <ul>
1780
                  <li><code>details</code> - detailed comparison of individual templates in
1781
                     differing configurations</li>
1782
                  <li><code>time</code> - relative comparison of the most pattern-matching
1783
                     time-expensive templates, for each mode</li>
1784
                  <li><code>call</code> - relative comparison of the most called templates, for each
1785
                     mode</li>
1786
                  <li><code>rank</code> - display of the rule rank distribution for each mode</li>
1787
               </ul></dd>
1788
            <dt>case-tag</dt>
1789
            <dd>A tag to use as a class for all CSS styling of elements of that group, particularly
1790
               in graphics.</dd>
1791
            <dt>case-label</dt>
1792
            <dd>A string to label that particular case, in tables and in keys on graphs.</dd>
1793
            <dt>caseWorkingDirectory</dt>
1794
            <dd>The working directory to use for this particular case. In particular, if a
1795
               configuration file is required for that case, then <code>config.xml</code> should
1796
               exist in that directory, and either a label is defined on the <code>case</code>
1797
               element or the top-level <code>configuration</code> element should have a
1798
                  <code>@label</code> attribute (e.g. <code>label="Index ; comparison
1799
                  indexation"</code>) to enable the results to be labelled and differentiated. This
1800
               directory will be used both to keep generated statistics and other helped files, as
1801
               well as the output from the execution. (This implies <code>result-document</code>
1802
               URIs are relative to a point inside this directory.) </dd>
1803
         </dl>
1804
         <p>An example is:</p>
1805
         <samp> file <b>stats.simple.index.xml</b> = <![CDATA[<stats>    
1806
      <group name="statsTransform.default"  show="details time call rank">
1807
          <case label="OFF ; Normal XSLT templating" dir="statsTransform/"/>
1808
          <case dir="statsTransformIndex/"/>
1809
      </group>    
1810
  </stats>]]></samp>
1811
         <p>Where two different configurations for Saxon will be compared running the stylesheet
1812
            defined in the command line on the source file again defined in the command line. The
1813
            first case will be normal XSLT behaviour; the second will be with Saxon configured by
1814
            the configuration file <code>statsTransformIndex/config.xml</code>. (It is assumed that
1815
            that configuration file has a <code>/configuration/@label</code> description of similar
1816
            form, from whence suitable labels can be generated.)</p>
1817
         <p>The results will appear in a web-page
1818
            <code>statistics/stats.simple.index.html</code>.</p>
1819
         <p>For details of the experimental template pattern optimization options, which can be
1820
            defined in the configuration file, and for which this analysis package was developed,
1821
            see <a class="bodylink"
1822
               href="/configuration/configuration-file/config-xslt/config-xslt-patternOptimization"
1823
               >The &lt;PatternOptimization&gt; element</a>.</p>
1824
      </section>-->
1825
   </section>
1826
   <section id="xslt30" title="XSLT 3.0 Support">
1827
      <h1>XSLT 3.0 Support</h1>
1828

    
1829
      
1830
      <p>Saxon 9.8 and later releases implement the <a class="bodylink"
1831
            href="http://www.w3.org/TR/xslt-30/">XSLT 3.0 Recommendation</a> dated 8 June 2017.
1832
      Implementation in 9.8 was almost complete, and 9.9 filled the last remaining gaps (for example,
1833
      full support of the <code>item-separator</code> serialization property, and the 
1834
        <code>xsl:try/@rollback</code> option). Saxon 10 provides some extensions that have
1835
      been found necessary to take full advantage of the new capabilities in XSLT 3.0, for example
1836
      making it easier to transform JSON documents.</p>
1837

    
1838
      <p>XSLT 3.0 features are available in all Saxon editions. Saxon-HE includes basic conformance,
1839
         serialization, XSLT 1.0 compatability mode, XPath 3.1 support, dynamic evaluation, 
1840
         and higher-order functions. Schema-awareness and streaming require Saxon-EE.</p>
1841

    
1842
      <p>The XSLT 3.0 specification gives processors the option of supporting XPath 3.0 (plus maps),
1843
         or XPath 3.1. Saxon supports XPath 3.1. The specification requires the processor to provide
1844
         a mode of operation that is restricted to XPath 3.0; this is no longer available in Saxon 10.</p>
1845

    
1846

    
1847
      <p>For further details of the features implemented in the current Saxon release, and the Saxon
1848
         editions in which they are available see <a
1849
            class="bodylink" href="/conformance/xslt30">XSLT 3.0 Conformance</a>. Full details of
1850
         these features are in the W3C XSLT and XPath specifications; but further summary
1851
         information about many of them can be found in the relevant sections of the Saxon
1852
         documentation listed below:</p>
1853

    
1854
      <ul>
1855
         <li>
1856
            <p>
1857
               <a class="bodylink" href="/functions">Functions Library</a>
1858
            </p>
1859
         </li>
1860
         <li>
1861
            <p>
1862
               <a class="bodylink" href="/xsl-elements">XSLT Elements</a>
1863
            </p>
1864
         </li>
1865
         <li>
1866
            <p>
1867
               <a class="bodylink" href="/expressions/xpath30new">XPath 3.0 Expressions</a>
1868
            </p>
1869
         </li>
1870
         <li>
1871
            <p>
1872
               <a class="bodylink" href="/expressions/xpath31new">XPath 3.1 Expressions</a>
1873
            </p>
1874
         </li>
1875
         <li>
1876
            <p>
1877
               <a class="bodylink" href="/expressions/xpath30maps">Maps in XPath</a>
1878
            </p>
1879
         </li>
1880
         <li>
1881
            <p>
1882
               <a class="bodylink" href="/sourcedocs/streaming">Streaming of Large Documents</a>
1883
            </p>
1884
         </li>
1885
         <li>
1886
            <p>
1887
               <a class="bodylink" href="../compiling">Compiling a Stylesheet</a> (for details on
1888
               using packages) </p>
1889
         </li>
1890
      </ul>
1891

    
1892
   </section>
1893
</article>
(20-20/21)