Project

Profile

Help

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

he / src / userdoc / extensibility.xml @ d9cb5c62

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="extensibility" title="Extensibility Mechanisms">
3
  <h1>Extensibility Mechanisms</h1>
4

    
5

    
6
  <p>This section describes how to extend the capability of Saxon XSLT stylesheets and XQuery
7
    queries by adding extension functions, extending the configuration and other user hooks.</p>
8

    
9
  <p>The first two columns of the tables below indicate which sections of this page are applicable
10
    to XSLT and which are applicable to XQuery. The next three columns indicate which Saxon editions
11
    the information applies to.</p>
12
  <table>
13
    <tr>
14
      <td>
15
        <p>XSLT</p>
16
      </td>
17
      <td>
18
        <p>XQuery</p>
19
      </td>
20
      <td>
21
        <p>HE</p>
22
      </td>
23
      <td>
24
        <p>PE</p>
25
      </td>
26
      <td>
27
        <p>EE</p>
28
      </td>
29
      <td>
30
        <p>
31
          <strong>Contents</strong>
32
        </p>
33
      </td>
34
    </tr>
35
    <tr>
36
      <td>
37
        <p>§</p>
38
      </td>
39
      <td>
40
        <p>§</p>
41
      </td>
42
      <td>
43
        <p>§</p>
44
      </td>
45
      <td>
46
        <p>§</p>
47
      </td>
48
      <td>
49
        <p>§</p>
50
      </td>
51
      <td>
52
        <p>
53
          <a class="bodylink" href="integratedfunctions">Integrated extension functions</a>
54
        </p>
55
      </td>
56
    </tr>
57
    <tr>
58
      <td>
59
        <p>§</p>
60
      </td>
61
      <td>
62
        <p>§</p>
63
      </td>
64
      <td>
65
        <p> </p>
66
      </td>
67
      <td>
68
        <p>§</p>
69
      </td>
70
      <td>
71
        <p>§</p>
72
      </td>
73
      <td>
74
        <p>
75
          <a class="bodylink" href="functions">Reflexive extension functions (Java)</a>
76
        </p>
77
      </td>
78
    </tr>
79
    <tr>
80
      <td>
81
        <p>§</p>
82
      </td>
83
      <td>
84
        <p>§</p>
85
      </td>
86
      <td>
87
        <p> </p>
88
      </td>
89
      <td>
90
        <p>§</p>
91
      </td>
92
      <td>
93
        <p>§</p>
94
      </td>
95
      <td>
96
        <p>
97
          <a class="bodylink" href="dotnetextensions">Reflexive extension functions (.NET)</a>
98
        </p>
99
      </td>
100
    </tr>
101
    <tr>
102
      <td>
103
        <p>§</p>
104
      </td>
105
      <td>
106
        <p> </p>
107
      </td>
108
      <td>
109
        <p> </p>
110
      </td>
111
      <td>
112
        <p>§</p>
113
      </td>
114
      <td>
115
        <p>§</p>
116
      </td>
117
      <td>
118
        <p>
119
          <a class="bodylink" href="instructions">Writing XSLT extension instructions</a>
120
        </p>
121
      </td>
122
    </tr>
123
  </table>
124
  <p>In the section <a class="bodylink" href="config-extend">Configuration</a> are other mechanisms for extending the
125
    configuration, whose support is indicated thus:</p>
126
  <table>
127
    <tr>
128
      <td>
129
        <p>XSLT</p>
130
      </td>
131
      <td>
132
        <p>XQuery</p>
133
      </td>
134
      <td>
135
        <p>HE</p>
136
      </td>
137
      <td>
138
        <p>PE</p>
139
      </td>
140
      <td>
141
        <p>EE</p>
142
      </td>
143
      <td>
144
        <p>
145
          <strong>Contents</strong>
146
        </p>
147
      </td>
148
    </tr>
149
    <tr>
150
      <td>
151
        <p>§</p>
152
      </td>
153
      <td>
154
        <p>§</p>
155
      </td>
156
      <td>
157
        <p>§</p>
158
      </td>
159
      <td>
160
        <p>§</p>
161
      </td>
162
      <td>
163
        <p>§</p>
164
      </td>
165
      <td>
166
        <p>
167
          <a class="bodylink" href="config-extend/output-filters">Customizing serialization</a>
168
        </p>
169
      </td>
170
    </tr>
171
    <tr>
172
      <td>
173
        <p>§</p>
174
      </td>
175
      <td>
176
        <p>§</p>
177
      </td>
178
      <td>
179
        <p>§</p>
180
      </td>
181
      <td>
182
        <p>§</p>
183
      </td>
184
      <td>
185
        <p>§</p>
186
      </td>
187
      <td>
188
        <p>
189
          <a class="bodylink" href="config-extend/collation">Collation</a>
190
        </p>
191
      </td>
192
    </tr>
193
    <tr>
194
      <td>
195
        <p>§</p>
196
      </td>
197
      <td>
198
        <p>§</p>
199
      </td>
200
      <td>
201
        <p> </p>
202
      </td>
203
      <td>
204
        <p> </p>
205
      </td>
206
      <td>
207
        <p>§</p>
208
      </td>
209
      <td>
210
        <p>
211
          <a class="bodylink" href="config-extend/collation/UCA">Using the Unicode Collation
212
            Algorithm</a>
213
        </p>
214
      </td>
215
    </tr>
216
    <tr>
217
      <td>
218
        <p>§</p>
219
      </td>
220
      <td>
221
        <p>§</p>
222
      </td>
223
      <td>
224
        <p>§</p>
225
      </td>
226
      <td>
227
        <p>§</p>
228
      </td>
229
      <td>
230
        <p>§</p>
231
      </td>
232
      <td>
233
        <p>
234
          <a class="bodylink" href="config-extend/localizing">Implementing localized numbers and
235
            dates</a>
236
        </p>
237
      </td>
238
    </tr>
239
    <tr>
240
      <td>
241
        <p>§</p>
242
      </td>
243
      <td>
244
        <p>§</p>
245
      </td>
246
      <td>
247
        <p>§</p>
248
      </td>
249
      <td>
250
        <p>§</p>
251
      </td>
252
      <td>
253
        <p>§</p>
254
      </td>
255
      <td>
256
        <p>
257
          <a class="bodylink" href="config-extend/uri-resolution/uri-resolver">Writing a URI
258
            Resolver for input files</a>
259
        </p>
260
      </td>
261
    </tr>
262
    <tr>
263
      <td>
264
        <p>§</p>
265
      </td>
266
      <td>
267
        <p> </p>
268
      </td>
269
      <td>
270
        <p>§</p>
271
      </td>
272
      <td>
273
        <p>§</p>
274
      </td>
275
      <td>
276
        <p>§</p>
277
      </td>
278
      <td>
279
        <p>
280
          <a class="bodylink" href="config-extend/uri-resolution/output-uri-resolver">Resolving the
281
            URIs of Output Files</a>
282
        </p>
283
      </td>
284
    </tr>
285
    <tr>
286
      <td>
287
        <p>§</p>
288
      </td>
289
      <td>
290
        <p>§</p>
291
      </td>
292
      <td>
293
        <p>§</p>
294
      </td>
295
      <td>
296
        <p>§</p>
297
      </td>
298
      <td>
299
        <p>§</p>
300
      </td>
301
      <td>
302
        <p>
303
          <a class="bodylink" href="config-extend/uri-resolution/collection-uri-resolver">Writing a
304
            URI Resolver for collections</a>
305
        </p>
306
      </td>
307
    </tr>
308
  </table>
309
  <section id="integratedfunctions" title="Integrated extension functions">
310
    <h1>Integrated extension functions</h1>
311

    
312

    
313
    <p>There are two ways of writing extension functions. The traditional way is to map the name of
314
      the function to a <dfn>Java</dfn> or <dfn>.NET</dfn> method: specifically, the namespace URI
315
      of the function name maps to the Java or .NET class name, and the local part of the function
316
      name maps to the Java or .NET method name. These are known as <i>reflexive</i> extension
317
      functions, and are described in later pages (use of these requires Saxon-PE or Saxon-EE).</p>
318

    
319
    <p>Since Saxon 9.2, this technique has been supplemented by a new mechanism, referred to as
320
        <i>integrated extension functions</i> (available in all Saxon editions). </p>
321

    
322
    <p>There are several advantages in this approach:</p>
323
    <ul>
324
      <li>
325
        <p>You can choose any function name you like, in any namespace.</p>
326
      </li>
327
      <li>
328
        <p>The function signature is made explicit, in terms of XPath types for the arguments and
329
          result.</p>
330
      </li>
331
      <li>
332
        <p>There is no ambiguity about which of several candidate Java or .NET methods is
333
          invoked.</p>
334
      </li>
335
      <li>
336
        <p>There is less scope for configuration problems involving dynamic loading of named
337
          classes.</p>
338
      </li>
339
      <li>
340
        <p>All conversions from XPath values to Java or .NET values are entirely under user
341
          control.</p>
342
      </li>
343
      <li>
344
        <p>The function implementation is activated at compile time, allowing it to perform
345
          optimization based on the expressions supplied as arguments, or to save parts of the
346
          static context that it needs, such as the static base URI or the current namespace
347
          context.</p>
348
      </li>
349
      <li>
350
        <p>The function declares its properties, for example whether it uses the context item and
351
          whether it has side-effects, making it easier for the optimizer to manipulate the function
352
          call intelligently.</p>
353
      </li>
354
      <li>
355
        <p>Integrated extension functions are more secure, because the function must be explicitly
356
          registered by the calling application before it can be called.</p>
357
      </li>
358
    </ul>
359

    
360
    <p>There are two ways of writing integrated extension functions: the simple API and the full
361
      API. Both interfaces are now available for both the Java and .NET platforms (the simple API
362
      for .NET is available since 9.9.1). The resulting combinations are described on the following
363
      pages.</p>
364

    
365
    <nav>
366
      <ul/>
367
    </nav>
368

    
369
    <section id="ext-simple-J" title="Java extension functions: simple interface">
370
      <h1>Java extension functions: simple interface</h1>
371

    
372

    
373

    
374
      <p>The simple API for integrated Java extension functions is available via the s9api class <a
375
          class="javalink" href="net.sf.saxon.s9api.ExtensionFunction">ExtensionFunction</a>. Here
376
        is an example that defines an extension function to calculate square roots, registers this
377
        extension function with the s9api <a class="javalink" href="net.sf.saxon.s9api.Processor"
378
          >Processor</a>, and then invokes it from an XPath expression:</p>
379

    
380
      <samp><![CDATA[  Processor proc = new Processor(false);
381
  ExtensionFunction sqrt = new ExtensionFunction() {
382
      public QName getName() {
383
          return new QName("http://math.com/", "sqrt");
384
      }
385

    
386
      public SequenceType getResultType() {
387
          return SequenceType.makeSequenceType(
388
              ItemType.DOUBLE, OccurrenceIndicator.ONE
389
          );
390
      }
391

    
392
      public net.sf.saxon.s9api.SequenceType[] getArgumentTypes() {
393
          return new SequenceType[]{
394
              SequenceType.makeSequenceType(
395
                  ItemType.DOUBLE, OccurrenceIndicator.ONE)};
396
      }
397

    
398
      public XdmValue call(XdmValue[] arguments) throws SaxonApiException {
399
          double arg = ((XdmAtomicValue)arguments[0].itemAt(0)).getDoubleValue();
400
          double result = Math.sqrt(arg);
401
          return new XdmAtomicValue(result);
402
      }
403
  };
404

    
405
  proc.registerExtensionFunction(sqrt);
406
  XPathCompiler comp = proc.newXPathCompiler();
407
  comp.declareNamespace("mf", "http://math.com/");
408
  comp.declareVariable(new QName("arg"));
409
  XPathExecutable exp = comp.compile("mf:sqrt($arg)");
410
  XPathSelector ev = exp.load();
411
  ev.setVariable(new QName("arg"), new XdmAtomicValue(2.0));
412
  XdmValue val = ev.evaluate();
413
  String result = val.toString();]]></samp>
414

    
415
      <p>Full details of the interface are defined in the Javadoc for class <a class="javalink"
416
          href="net.sf.saxon.s9api.ExtensionFunction">ExtensionFunction</a>.</p>
417

    
418
      <p>The main restrictions of the simple interface are (a) that the extension function has no
419
        access to static or dynamic context information, and (b) that it does not support pipelined
420
        evaluation of the arguments or result. To avoid these restrictions, use the <a
421
          class="bodylink" href="../ext-full-J">full interface</a> described on the next page.</p>
422

    
423
    </section>
424

    
425
    <section id="ext-full-J" title="Java extension functions: full interface">
426
      <h1>Java extension functions: full interface</h1>
427

    
428

    
429

    
430
      <p>With this approach, each extension function is implemented as a pair of Java classes. The
431
        first class, the <a class="javalink" href="net.sf.saxon.lib.ExtensionFunctionDefinition"
432
          >ExtensionFunctionDefinition</a>, provides general static information about the extension
433
        function (including its name, arity, and the types of its arguments and result). The second
434
        class, an <a class="javalink" href="net.sf.saxon.lib.ExtensionFunctionCall"
435
          >ExtensionFunctionCall</a>, represents a specific call on the extension function, and
436
        includes the <code>call()</code> method that Saxon invokes to evaluate the function.</p>
437

    
438
      <aside>When a stylesheet or query uses integrated extension functions and is run from the
439
        command line, the classes that implement these extension functions must be registered with
440
        the <a class="javalink" href="net.sf.saxon.Configuration">Configuration</a>. On Saxon-PE and
441
        Saxon-EE this can conveniently be done by declaring them in a <a class="bodylink"
442
          href="/configuration/configuration-file">configuration file</a>. It can also be achieved
443
        (on all editions including Saxon-HE) by subclassing <a class="javalink"
444
          href="net.sf.saxon.Transform">net.sf.saxon.Transform</a> or <a class="javalink"
445
          href="net.sf.saxon.Query">net.sf.saxon.Query</a>, overriding the method
446
          <code>applyLocalOptions()</code> so that it makes the appropriate calls on
447
          <code>config.registerExtensionFunction()</code>; or it can be done in a user-defined class
448
        that implements the interface <a class="javalink" href="net.sf.saxon.lib.Initializer"
449
          >net.sf.saxon.Initializer</a>, and that is nominated on the command line using the
450
          <code>-init</code> option.</aside>
451

    
452
      <p>The arguments passed in a call to an integrated extension function are type-checked against
453
        the declared types in the same way as for any other XPath function call, including the
454
        standard conversions such as atomization and numeric promotion. The return value is checked
455
        against the declared return type but is not converted: it is the responsibility of the
456
        function implementation to return a value of the correct type.</p>
457

    
458
      <p>Here is an example extension written to the Java version of this interface. It takes two
459
        integer arguments and performs a "shift left" operation, shifting the first argument by the
460
        number of bit-positions indicated in the second argument:</p>
461
            
462
      <samp><![CDATA[class ShiftLeft extends ExtensionFunctionDefinition {
463
    @Override
464
    public StructuredQName getFunctionQName() {
465
        return new StructuredQName("eg", "http://example.com/saxon-extension", "shift-left");
466
    }
467
    
468
    @Override
469
    public SequenceType[] getArgumentTypes() {
470
        return new SequenceType[]{SequenceType.SINGLE_INTEGER, SequenceType.SINGLE_INTEGER};
471
    }
472
    
473
    @Override
474
    public SequenceType getResultType(SequenceType[] suppliedArgumentTypes) {
475
        return SequenceType.SINGLE_INTEGER;
476
    }
477
    
478
    @Override
479
    public ExtensionFunctionCall makeCallExpression() {
480
        return new ExtensionFunctionCall() {
481
            @Override
482
            public Sequence call(XPathContext context, Sequence[] arguments) throws XPathException {
483
                long v0 = ((IntegerValue)arguments[0]).longValue();
484
                long v1 = ((IntegerValue)arguments[1]).longValue();
485
                long result = v0<<v1;
486
                return Int64Value.makeIntegerValue(result);
487
            }
488
        };
489
    }
490
}]]></samp>
491

    
492
      <p>The extension must be registered with the configuration:</p>
493

    
494
      <samp><![CDATA[configuration.registerExtensionFunction(new ShiftLeft())]]></samp>
495

    
496
      <p>and it can then be called like this:</p>
497

    
498
      <samp><![CDATA[declare namespace eg="http://example.com/saxon-extension";
499
          for $i in 1 to 10 return eg:shift-left(2, $i)]]></samp>
500

    
501
      <p>The methods that must be implemented (or that may be implemented) by an integrated
502
        extension function are listed in the table below. Further details are in the Javadoc.</p>
503

    
504
      <p>First, the <a class="javalink" href="net.sf.saxon.lib.ExtensionFunctionDefinition"
505
          >ExtensionFunctionDefinition</a> class:</p>
506
      <table>
507
        <tr>
508
          <td>
509
            <p>
510
              <strong>Method</strong>
511
            </p>
512
          </td>
513
          <td>
514
            <p>
515
              <strong>Effect</strong>
516
            </p>
517
          </td>
518
        </tr>
519
        <tr>
520
          <td>
521
            <p>getFunctionQName</p>
522
          </td>
523
          <td>
524
            <p>Returns the name of the function, as a QName (represented by the Saxon class
525
                <a class="javalink" href="net.sf.saxon.om.StructuredQName">StructuredQName</a>). Like all other functions, integrated extension
526
              functions must be in a namespace. The prefix part of the QName is immaterial.</p>
527
          </td>
528
        </tr>
529
        <tr>
530
          <td>
531
            <p>getMinumumNumberOfArguments</p>
532
          </td>
533
          <td>
534
            <p>Indicates the minimum number of arguments that must be supplied in a call to the
535
              function. A call with fewer arguments than this will be rejected as a static
536
              error.</p>
537
          </td>
538
        </tr>
539
        <tr>
540
          <td>
541
            <p>getMaximumNumberOfArguments</p>
542
          </td>
543
          <td>
544
            <p>Indicates the maximum number of arguments that must be supplied in a call to the
545
              function. A call with more arguments than this will be rejected as a static error.</p>
546
          </td>
547
        </tr>
548
        <tr>
549
          <td>
550
            <p>getArgumentTypes</p>
551
          </td>
552
          <td>
553
            <p>Returns the static type of each argument to the function, as an array with one member
554
              per argument. The type is returned as an instance of the Saxon class
555
              <a class="javalink" href="net.sf.saxon.value.SequenceType">SequenceType</a>. Some of the more commonly-used types
556
              are represented by static constants in the <code>SequenceType</code> class. If there
557
              are fewer members in the array than there are arguments in the function call, Saxon
558
              assumes that all arguments have the same type as the last one that is explicitly
559
              declared; this allows for functions with a variable number of arguments, such as
560
                <code>concat()</code>.</p>
561
          </td>
562
        </tr>
563
        <tr>
564
          <td>
565
            <p>getResultType</p>
566
          </td>
567
          <td>
568
            <p>Returns the static type of the result of the function. The actual result returned at
569
              runtime will be checked against this declared type, but no conversion takes place.
570
              Like the argument types, the result type is returned as an instance of
571
              <a class="javalink" href="net.sf.saxon.value.SequenceType">SequenceType</a>. When Saxon calls this method, it
572
              supplies an array containing the inferred static types of the actual arguments to the
573
              function call. The implementation can use this information to return a more precise
574
              result, for example in cases where the value returned by the function is of the same
575
              type as the value supplied in the first argument.</p>
576
          </td>
577
        </tr>
578
        <tr>
579
          <td>
580
            <p>trustResultType</p>
581
          </td>
582
          <td>
583
            <p>This method normally returns <code>false</code>. It can return <code>true</code> if
584
              the implementor of the extension function is confident that no run-time checking of
585
              the function result is needed; that is, if the method is guaranteed to return a value
586
              of the declared result type.</p>
587
          </td>
588
        </tr>
589
        <tr>
590
          <td>
591
            <p>dependsOnFocus</p>
592
          </td>
593
          <td>
594
            <p>This method must return true if the implementation of the function accesses the
595
              context item, context position, or context size from the dynamic evaluation context.
596
              The method does not need to be implemented otherwise, as its default value is
597
              false.</p>
598
          </td>
599
        </tr>
600
        <tr>
601
          <td>
602
            <p>hasSideEffects</p>
603
          </td>
604
          <td>
605
            <p>This method should be implemented, and return true, if the function has side-effects
606
              of any kind, including constructing new nodes if the identity of the nodes is
607
              signficant. When this method returns true, Saxon will try to avoid moving the function
608
              call out of loops or otherwise rearranging the sequence of calls. However, functions
609
              with side-effects are still discouraged, because the optimizer cannot always detect
610
              their presence if they are deeply nested within other calls.</p>
611
          </td>
612
        </tr>
613
        <tr>
614
          <td>
615
            <p>makeCallExpression</p>
616
          </td>
617
          <td>
618
            <p>This method must be implemented; it is called at compile time when a call to this
619
              extension function is identified, to create an instance of the relevant
620
                <a class="javalink" href="net.sf.saxon.lib.ExtensionFunctionCall">ExtensionFunctionCall</a> 
621
              object to hold details of the function call expression.</p>
622
          </td>
623
        </tr>
624
      </table>
625

    
626
      <p>The methods defined on the second object, the <a class="javalink"
627
          href="net.sf.saxon.lib.ExtensionFunctionCall">ExtensionFunctionCall</a>, are:</p>
628
      <table>
629
        <tr>
630
          <td>
631
            <p>
632
              <strong>Method</strong>
633
            </p>
634
          </td>
635
          <td>
636
            <p>
637
              <strong>Effect</strong>
638
            </p>
639
          </td>
640
        </tr>
641
        <tr>
642
          <td>
643
            <p>supplyStaticContext</p>
644
          </td>
645
          <td>
646
            <p>Saxon calls this method fairly early on during the compilation process to supply
647
              details of the static context in which the function call appears. The method may in
648
              some circumstances be called more than once; it will always be called at least once.
649
              As well as the static context information itself, the expressions supplied as
650
              arguments are also made available. If evaluation of the function depends on
651
              information in the static context, this information should be copied into private
652
              variables for use at run-time.</p>
653
          </td>
654
        </tr>
655
        <tr>
656
          <td>
657
            <p>rewrite</p>
658
          </td>
659
          <td>
660
            <p>Saxon calls this method at a fairly late stage during compilation to give the
661
              implementation the opportunity to optimize itself, for example by performing partial
662
              evaluation of intermediate results, or if all the arguments are compile-time constants
663
              (instances of <a class="javalink" href="net.sf.saxon.expr.Literal">Literal</a>) even by early evaluation of the
664
              entire function call. The method can return any <a class="javalink" href="net.sf.saxon.expr.Expression">Expression</a> (which
665
              includes the option of returning a <code>Literal</code> to represent the final
666
              result); the returned expression will then be evaluated at run-time in place of the
667
              original. It is entirely the responsibility of the implementation to ensure that the
668
              substitute expression is equivalent in every way, including the type of its
669
              result.</p>
670
          </td>
671
        </tr>
672
        <tr>
673
          <td>
674
            <p>copyLocalData</p>
675
          </td>
676
          <td>
677
            <p>Saxon occasionally needs to make a copy of an expression tree. When it copies an
678
              integrated function call it will invoke this method, which is responsible for ensuring
679
              that any local data maintained within the function call objects is correctly
680
              copied.</p>
681
          </td>
682
        </tr>
683
        <tr>
684
          <td>
685
            <p>call</p>
686
          </td>
687
          <td>
688
            <p>Saxon calls this method at run-time to evaluate the function. The value of each
689
              argument is supplied in the form of a <a class="javalink" href="net.sf.saxon.om.Sequence">Sequence</a>, 
690
              representing the sequence that make up the value of the argument (this might of course be a single
691
              value, considered as a sequence of length one). This
692
              may use lazy evaluation, which means that a dynamic error can occur when reading the
693
              next item from the <code>Sequence</code>; it also means that if the implementation does not
694
              require all the items from the value of one of the arguments, they will not
695
              necessarily be evaluated at all.</p>
696
            <p>The <code>call</code> method must also deliver the result 
697
              in the form of a <a class="javalink" href="net.sf.saxon.om.Sequence">Sequence</a>.
698
              Saxon provides many subclasses of <code>Sequence</code> that are available for use.
699
              To return a string <code>S</code>, use <code>new net.sf.saxon.value.StringValue(S)</code>;
700
              to return a boolean <code>B</code>, use <code>net.sf.saxon.value.BooleanValue.get(B)</code>; to return
701
              an integer <code>I</code>, use <code>net.sf.saxon.value.Int64Value.makeIntegerValue(I)</code>.
702
              The Saxon class <a class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a> also implements
703
              <code>Sequence</code>, and can be used to return single nodes. To return an empty sequence,
704
              use <a class="javalink" href="net.sf.saxon.value.EmptySequence">EmptySequence.getInstance()</a>.
705
              If you want to return a sequence of two or more items, a convenient class to use is 
706
              <a class="javalink" href="net.sf.saxon.om.ZeroOrMore">ZeroOrMore</a>, which has a constructor
707
              that takes a Java <code>List&lt;net.sf.saxon.om.Item&gt;</code>, where the items can
708
              be, for example, strings, booleans, integers, or nodes represented as described above.</p>
709
              
710
              <p>For ultimate performance when returning a very long sequence (for example, the results of a database
711
                query), use the class
712
              <a class="javalink" href="net.sf.saxon.om.LazySequence">LazySequence</a>, which allows the items
713
              in the sequence to be computed on demand rather than being stored <i>en bloc</i> in memory.</p>
714
          </td>
715
        </tr>
716
      </table>
717

    
718
      <p>Having written an integrated extension function, it must be registered with Saxon so that
719
        calls on the function are recognized by the parser. This is done using the
720
          <code>registerExtensionFunction</code> method available on the <a class="javalink"
721
          href="net.sf.saxon.Configuration">Configuration</a> class, and also on the s9api <a
722
          class="javalink" href="net.sf.saxon.s9api.Processor">Processor</a> class. It can also be
723
        registered via an entry in the <a class="bodylink"
724
          href="/configuration/configuration-file">configuration file</a>. The function can be given any name,
725
        although names in the <code>fn:</code>, <code>xs:</code>, and <code>saxon:</code> namespaces
726
        are strongly discouraged and may not work.</p>
727

    
728
      <p>It is also possible to register integrated extension functions under XQJ: this is done by
729
        locating the <code>Configuration</code> that underpins the <code>XQDataSource</code> or
730
          <code>XQConnection</code> by casting it to the Saxon implementation class
731
          (<code>SaxonXQDataSource</code> or <code>SaxonXQConnection</code>) and calling
732
          <code>getConfiguration()</code>.</p>
733

    
734
    </section>
735
    
736
    <section id="ext-simple-N" title=".NET extension functions: simple interface">
737
      <h1>.NET extension functions: simple interface</h1>
738
      
739
      
740
      
741
      <p>The simple API for integrated .NET extension functions is available via the .NET class
742
        <a class="javalink" href="Saxon.Api.ExtensionFunction">ExtensionFunction</a>
743
        defined in the <code>Saxon.Api</code> module. Here is a simple example that defines an extension function
744
        to calculate square roots, registers this extension function with the 
745
        <a class="javalink" href="Saxon.Api.Processor">Processor</a>, and then invokes it from an XPath expression:</p>
746
      
747
      <samp><![CDATA[public class SqrtSimple : ExtensionFunction {
748
    
749
    public XdmValue Call(XdmValue[] arguments)
750
    {
751
        if (!(arguments[0] is XdmEmptySequence))
752
        {
753
            XdmAtomicValue arg = (XdmAtomicValue)arguments[0].ItemAt(0);
754
            double val = (double)arg.Value;
755
            double sqrt = System.Math.Sqrt(val);
756
            return new XdmAtomicValue(sqrt);
757
        }
758
        else
759
        {
760
            return XdmValue.MakeValue((double)0);
761
        }
762
    }
763

    
764
    public XdmSequenceType[] GetArgumentTypes()
765
    {
766
        return new XdmSequenceType[]{
767
            new XdmSequenceType(XdmAtomicType.BuiltInAtomicType(QName.XS_DOUBLE), '?')
768
        };
769
    }
770

    
771
    public QName GetName()
772
    {
773
        return new QName("http://math.com/", "sqrtSimple");
774
    }
775

    
776
    public XdmSequenceType GetResultType()
777
    {
778
        return new XdmSequenceType(XdmAtomicType.BuiltInAtomicType(QName.XS_DOUBLE), ' ');
779
    }
780
}
781
            
782
Processor proc = new Processor();
783
proc.RegisterExtensionFunction(new SqrtSimple());
784
XPathCompiler xpc = proc.NewXPathCompiler();
785
xpc.DeclareNamespace("mf", "http://math.com/");
786
XdmItem result = xpc.EvaluateSingle("mf:sqrtSimple(2)", null);
787
Console.WriteLine("Square root of 2 is " + result);]]></samp>
788
      
789
      
790
      <p>Full details of the interface are defined in the <a class="apilink" href="/dotnetdoc">.NET API documentation</a>.</p>
791
      
792
      <p>The main restrictions of the simple interface are (a) that the extension function has no
793
        access to static or dynamic context information, and (b) that it does not support pipelined
794
        evaluation of the arguments or result. To avoid these restrictions, use the <a
795
          class="bodylink" href="../ext-fns-N">full interface</a> described on the next page.</p>
796
      
797
    </section>
798

    
799
    <section id="ext-fns-N" title=".NET extension functions: full interface">
800
      <h1>.NET extension functions: full interface</h1>
801

    
802

    
803

    
804
      <p>The full API for integrated .NET extension functions is available via the .NET classes
805
        <a class="javalink" href="Saxon.Api.ExtensionFunctionDefinition">ExtensionFunctionDefinition</a> and 
806
        <a class="javalink" href="Saxon.Api.ExtensionFunctionCall">ExtensionFunctionCall</a>, both
807
        defined in the <code>Saxon.Api</code> module. Here is a simple example that defines an extension function
808
        to calculate square roots, registers this extension function with the 
809
        <a class="javalink" href="Saxon.Api.Processor">Processor</a>, and then invokes it from an XPath expression:</p>
810

    
811
      <samp><![CDATA[public class Sqrt : ExtensionFunctionDefinition {
812
            
813
    public override QName FunctionName {
814
        get { return new QName("http://math.com/", "sqrt") };
815
    }
816
                
817
    public override int MinimumNumberOfArguments {
818
        get { return 1 };
819
    }
820
                
821
    public override int MaximumNumberOfArguments {
822
        get { return 1 };
823
    }
824
                
825
    public override XdmSequenceType[] ArgumentTypes {
826
        get { return new XdmSequenceType[] {
827
               new XdmSequenceType(XdmAtomicType.BuiltInAtomicType(QName.XS_DOUBLE), '?')
828
               }
829
        }
830
    }
831
                
832
    public override XdmSequenceType ResultType(XdmSequenceType[] ArgumentTypes) {
833
        return new XdmSequenceType(XdmAtomicType.BuiltInAtomicType(QName.XS_DOUBLE), '?');
834
    }
835
                
836
    public override bool TrustResultType {
837
        get { return true };
838
    }
839
                
840
    public override ExtensionFunctionCall MakeFunctionCall() {
841
        return new SqrtCall();
842
    }
843
}
844
            
845
public class SqrtCall : ExtensionFunctionCall {
846

    
847
    public override IEnumerator<XdmItem> Call(IEnumerator<XdmItem>[] arguments, DynamicContext context) 
848
    {
849
        Boolean exists = arguments[0].MoveNext();
850
        if (exists) {
851
            XdmAtomicValue arg = (XdmAtomicValue)arguments[0].Current;
852
            double val = (double)arg.Value;
853
            double sqrt = System.Math.Sqrt(val);
854
            return new XdmAtomicValue(sqrt).GetEnumerator();
855
        } else {
856
            return EmptyEnumerator<XdmItem>.INSTANCE;
857
        }
858
    }
859
}
860
            
861
Processor proc = new Processor();
862
proc.RegisterExtensionFunction(new Sqrt());
863
XPathCompiler xpc = proc.NewXPathCompiler();
864
xpc.DeclareNamespace("mf", "http://math.com/");
865
XdmItem result = xpc.EvaluateSingle("mf:sqrt(2)", null);
866
Console.WriteLine("Square root of 2 is " + result);]]></samp>
867

    
868

    
869
      <p>Full details of the interface are defined in the <a class="apilink" href="/dotnetdoc">.NET API documentation</a>.</p>
870

    
871
    </section>
872
  </section>
873
  <section id="functions" title="Writing reflexive extension functions in Java">
874
    <h1>Writing reflexive extension functions in Java</h1>
875

    
876
    <aside>This section applies to Saxon-PE and Saxon-EE only</aside>
877

    
878
    <p>Reflexive extension functions written in Java map the expanded name (namespace plus
879
      local-name) of the XPath function to a Java fully-qualified class name and method or field
880
      name. There are two ways of doing the mapping:</p>
881
    <ul>
882
      <li>
883
        <p>The namespace URI can define the class (for example <code>java:java.io.File</code>), and
884
          the local name then defines the method or field name (for example <code>exists</code>).</p>
885
      </li>
886
      <li>
887
        <p>The namespace URI can be <code>http://saxon.sf.net/java-type</code>, and the local name
888
          then defines both the class name and the method or field name (for example
889
            <code>java.io.File.exists</code>).</p>
890
      </li>
891
    </ul>
892
    <aside>Java extension functions can also be used when you are running on the .NET platform,
893
      provided the class implementing the function is a standard class in the OpenJDK class library
894
      (which covers nearly all the classes defined in the JDK). In other cases, you should compile
895
      the Java code into a .NET assembly using the IKVMC compiler, in which case it behaves in the
896
      same way as an extension function written in any other .NET language and compiled into CIL:
897
      see <a class="bodylink" href="../dotnetextensions">Writing extension functions for .NET</a>
898
    </aside>
899

    
900

    
901
    <p>There are a number of extension functions supplied with the Saxon product: for details, see
902
        <a class="bodylink" href="/extensions">Extensions</a>. The source code of these methods,
903
      which in most cases is extremely simple, can be used as an example for writing other user
904
      extension functions. It is found in class <a class="javalink" href="com.saxonica.functions.extfn">com.saxonica.functions.extfn</a>.</p>
905

    
906
    <p>
907
      <strong>The command line option <code>-TJ</code> is useful for <dfn>debugging</dfn> the loading of Java
908
        extensions. It gives detailed information about the methods that are examined for a possible
909
        match.</strong>
910
    </p>
911
    <h2 class="subtitle">Identifying the Java Class from the Namespace URI</h2>
912

    
913
    <p>There are various ways a mapping from URIs to Java classes can be established. The simplest
914
      is to use a URI that identifies the Java class explicitly. The namespace URI should be <code>java:</code>
915
      followed by the fully-qualified class name (for example
916
        <code>xmlns:date="java:java.util.Date"</code>). The class must be on the classpath. </p>
917
    
918
    <p>Optionally, this URI can be followed by <code>?void=this</code> (for example, 
919
      <code>xmlns:date="java:java.util.Date?void=this"</code>. The effect of this option, which was introduced
920
    in Saxon 9.7, is that calling a non-static method with a declared type of <code>void</code> returns
921
    the object to which it is applied, rather than returning an empty sequence. This makes it easier to
922
    avoid the problems that can arise from calls on such methods being optimized away.</p>
923
    
924
    <p>For example, with the help of the XPath 3.1 arrow operator, it makes it possible to chain function calls like this: 
925
      <code>let $x := c:myObject.new() => c:setLength(3) => c:setColor('blue')</code>.</p>
926
    
927
    <aside>For compatibility with other products and previous Saxon releases, Saxon <strong>at user
928
        request</strong> also supports certain other formats of URI. The URI may be a string
929
      containing a "/", in which the fully-qualified class name appears after the final "/" (for
930
      example <code>xmlns:date="http://www.jclark.com/xt/java/java.util.Date"</code>). The part of
931
      the URI before the final "/" is immaterial. The format
932
        <code>xmlns:date="java.util.Date"</code> is also supported. To permit this extended syntax
933
      for namespaces, you need to set a property on the <a class="javalink"
934
        href="net.sf.saxon.Configuration">Configuration</a>:
935
        <code>config.setConfigurationProperty(Feature.ALLOW_OLD_JAVA_URI_FORMAT, true)</code>.
936
      The flag can also be set in the <a class="bodylink"
937
        href="/configuration/configuration-file">configuration file</a>.</aside>
938

    
939
    <p>The Saxon namespace URI <code>http://saxon.sf.net/</code> is recognised as a special case. In
940
      most cases it causes the function to be loaded from the class
941
      <a class="javalink" href="com.saxonica.functions.extfn">com.saxonica.functions.extfn</a> but in a few cases, such as
942
        <code>saxon:evaluate</code>, the function is recognized by the compiler as if it were a
943
      built-in function. The various EXSLT and EXpath namespaces are also recognized specially.</p>
944

    
945
    <p>In XSLT, the system function <a class="bodylink code" href="/functions/fn/function-available">function-available(String name)</a> returns true if
946
      there appears to be a method available with the right name. The function also has an optional
947
      second argument to test whether there is a method with the appropriate number of arguments.
948
      However, it is not possible to test whether the arguments are of appropriate types. If the
949
      function name is "new" it returns true so long as the class is not an abstract class or
950
      interface, and so long as it has at least one constructor.</p>
951
    <h2 class="subtitle">Identifying the Java constructor, method, or field</h2>
952

    
953
    <p>The local name used in the XPath function call determines which constructor, method, or field
954
      of the Java class is invoked. This decision (called binding) is always made at the time the
955
      XPath expression is compiled. If methods are overloaded, static type information will be used
956
      to decide between them.</p>
957
    <ul>
958
      <li>
959
        <p>If the local name is <code>new</code>, a constructor is invoked. If several constructors
960
          are available, the one that is chosen is based on the number and types of the supplied
961
          arguments.</p>
962
      </li>
963
      <li>
964

    
965
        <p>In other cases, the system looks for a matching method or field based on the XPath function name as a QName.</p>
966

    
967
        <p>Firstly, the name must match. If the namespace URI is
968
            <code>http://saxon.sf.net/java-type</code> then the local name should be in the form
969
          <code>com.mycorp.app.MyClass.callMethod</code> where everything up to the last "."
970
          (here <code>com.mycorp.app.MyClass</code>) is taken as the full class name, and the remainder
971
          (<code>callMethod</code> is taken as the method or field name. But if the namespace URI is
972
          (for example) <code>java:com.mycorp.app.MyClass</code>, then <code>mycorp.app.MyClass</code> is taken as the class name,
973
          and the local name of the function call is <code>callMethod</code>, then the local name is
974
          taken as the Java method or field name.
975
          In both cases the name is converted to
976
          <dfn>camelCase</dfn>: this is done by removing any hyphen in the XPath name and forcing
977
          the immediately following character to upper case. For example the XPath function call
978
            <code>to-string()</code> matches the Java method <code>toString()</code>; but the
979
          function call can also be written as <code>toString()</code> if you prefer.</p>
980

    
981
        <p>Secondly, the number of arguments must match, after taking into account that (a) if the
982
          Java method expects a first argument of class <a class="javalink" href="net.sf.saxon.expr.XPathContext">net.sf.saxon.expr.XPathContext</a>
983
          then this will be supplied automatically by the system and does not correspond to any
984
          explicit argument in the XPath function call, and (b) when invoking an instance-level
985
          (non-static) method or field, the XPath function call must supply an extra first argument,
986
          which identifies the target object for the invocation.</p>
987

    
988
        <p>A public field in a class is treated as if it were a zero-argument method, so public
989
          static fields can be accessed in the same way as public static methods, and public
990
          instance-level fields in the same way as instance-level methods.</p>
991
      </li>
992
      <li>
993
        <p>If there are several matching methods, the one that is chosen is determined by comparing
994
          the static types of the supplied arguments with the required types in the method
995
          signature. See <a class="bodylink" href="choosing-overload">Choosing among overloaded
996
            methods</a>.</p>
997
      </li>
998
    </ul>
999
    <p>Further information can be found in the following sections:</p>
1000
    <nav>
1001
      <ul/>
1002
    </nav>
1003

    
1004
    <section id="choosing-overload" title="Choosing among overloaded methods">
1005
      <h1>Choosing among overloaded methods</h1>
1006

    
1007

    
1008
      <p>If there is no method with the required name and number of parameters, Saxon reports a
1009
        compile-time error.</p>
1010

    
1011
      <p>If there is only one method with the required name and number of parameters, then Saxon
1012
        chooses it, and goes on to the next stage, which allocates converters for the supplied
1013
        arguments.</p>
1014

    
1015
      <p>If there are several methods in the class that match the localname, and that have the
1016
        correct number of arguments, then the system attempts to find the one that is the best fit
1017
        to the types of the supplied arguments: for example if the call is <code>f(1,2)</code> then
1018
        a method with two <code>int</code> arguments will be preferred to one with two
1019
          <code>float</code> arguments. This decision is typically made during static type analysis.
1020
        The rules for deciding between methods are quite complex.
1021
        Essentially, for each candidate method, Saxon calculates the "distance" between the types of
1022
        the supplied arguments and the Java class of the corresponding method in the method's
1023
        signature, using a set of tables (see below). For example, the distance between the XPath data type
1024
          <code>xs:integer</code> and the Java class <code>long</code> is very small, while the
1025
        distance between an XPath <code>xs:integer</code> and a Java <code>Object</code> is much
1026
        larger. If there is one candidate method where the distances of all arguments are
1027
        less-than-or-equal-to the distances computed for other candidate methods, and the distance
1028
        of at least one argument is smaller, then that method is chosen.</p>
1029

    
1030
      <p>If there are several methods with the same name and the correct number of arguments, but
1031
        none is preferable to the others under these rules, an error is reported: the message
1032
        indicates that there is more than one method that matches the function call.</p>
1033

    
1034
      <p>This <dfn>binding</dfn> is carried out statically, using the static types of the supplied
1035
        arguments, not the dynamic types obtained when the arguments are evaluated. If there is
1036
        insufficient static type information to distinguish the candidate methods, an error is
1037
        reported. You can supply additional type information using the <code>treat as</code>
1038
        expression, or by casting. Often it is enough simply to declare the types of the variables
1039
        used as arguments to the function call.</p>
1040

    
1041
      <p>The distances are calculated using the following rules (in order).</p>
1042
      <ul>
1043
        <li>
1044
          <p>If the required type is <code>Object</code>, the distance is 100.</p>
1045
        </li>
1046
        <li>
1047

    
1048
          <p>If the required type is one of the following Saxon-specific classes (or is a superclass
1049
            of that class), then the distance is as given:</p>
1050
          <ul>
1051
            <li>
1052
              <p>
1053
                <a class="javalink" href="net.sf.saxon.om.SequenceIterator"
1054
                  >net.sf.saxon.om.SequenceIterator</a>: 26</p>
1055
            </li>
1056
            <li>
1057
              <p>
1058
                <a class="javalink" href="net.sf.saxon.om.Sequence"
1059
                  >net.sf.saxon.om.Sequence</a>: 25</p>
1060
            </li>
1061
            <li>
1062
              <p>
1063
                <a class="javalink" href="net.sf.saxon.om.GroundedValue">net.sf.saxon.om.GroundedValue</a>:
1064
                24</p>
1065
            </li>
1066
            <li>
1067
              <p>
1068
                <a class="javalink" href="net.sf.saxon.om.Item">net.sf.saxon.om.Item</a>: 23</p>
1069
            </li>
1070
            <li>
1071
              <p>
1072
                <a class="javalink" href="net.sf.saxon.om.NodeInfo">net.sf.saxon.om.NodeInfo</a>:
1073
                22</p>
1074
            </li>
1075
            <li>
1076
              <p>
1077
                <a class="javalink" href="net.sf.saxon.value.AtomicValue"
1078
                  >net.sf.saxon.value.AtomicValue</a>, 20</p>
1079
            </li>
1080
          </ul>
1081

    
1082
          <p>
1083
            <i>Note that Saxon does not recognize the classes defined in the s9api package for use
1084
              with extension functions (for example, <a class="javalink"
1085
                href="net.sf.saxon.s9api.XdmNode">XdmNode</a> and <a class="javalink"
1086
                href="net.sf.saxon.s9api.XdmAtomicValue">XdmAtomicValue</a>).</i>
1087
          </p>
1088
        </li>
1089
        <li>
1090

    
1091
          <p>If the static type of the supplied argument allows more than one item, the distance is
1092
            the first one of the following that applies:</p>
1093
          <ul>
1094
            <li>
1095
              <p>If the method expects <code>java.lang.Collection</code> or a class that implements
1096
                  <code>Collection</code>: 30</p>
1097
            </li>
1098
            <li>
1099
              <p>If the method expects an array: 31</p>
1100
            </li>
1101
            <li>
1102
              <p>In all other cases: 80</p>
1103
            </li>
1104
          </ul>
1105

    
1106
          <p><i>Note that the item type of the supplied value plays no role in choosing the method to
1107
            call, even though it could potentially be used to disambiguate overloaded methods when
1108
            arrays or parameterized collection types are used.</i></p>
1109
        </li>
1110
        <li>
1111

    
1112
          <p>Otherwise (the static type allows only one item):</p>
1113
          <ul>
1114
            <li>
1115
              <p>If the static type of the supplied value matches <code>node()</code>: 80</p>
1116
            </li>
1117
            <li>
1118
              <p>If the static type of the supplied value is a wrapped Java object, then 10 if the
1119
                class of the object matches the required Java class, else -1 (meaning this method is
1120
                not a candidate)</p>
1121
            </li>
1122
            <li>
1123
              <p>Otherwise, the value given by the table of atomic types below.</p>
1124
            </li>
1125
          </ul>
1126
        </li>
1127
      </ul>
1128
      
1129
      <p>For each of the atomic types listed below, the distance between the supplied type and the 
1130
        first corresponding required type (the Saxon-specific class in italics) is 50. Distances then 
1131
        increase (by 1 or 2) as you go along the ordered list of other possible required types. 
1132
        If there is no entry for the combination of
1133
        supplied type and required type, the method is removed from consideration. For unboxed types
1134
        (int, float, etc) the distance is always one less than the corresponding boxed type
1135
        (java.lang.Integer, java.lang.Float).</p>
1136
      <table>
1137
        <tr>
1138
          <td>
1139
            <p>
1140
              <strong>Supplied type</strong>
1141
            </p>
1142
          </td>
1143
          <td>
1144
            <p>
1145
              <strong>Required type</strong>
1146
            </p>
1147
          </td>
1148
        </tr>
1149
        <tr>
1150
          <td>
1151
            <p>xs:string</p>
1152
          </td>
1153
          <td>
1154
            <p>
1155
              <i>StringValue</i>, String, CharSequence</p>
1156
          </td>
1157
        </tr>        
1158
        <tr>
1159
          <td>
1160
            <p>xs:boolean</p>
1161
          </td>
1162
          <td>
1163
            <p>
1164
              <i>BooleanValue</i>, Boolean</p>
1165
          </td>
1166
        </tr>
1167
        <tr>
1168
          <td>
1169
            <p>xs:float</p>
1170
          </td>
1171
          <td>
1172
            <p>
1173
              <i>FloatValue</i>, Float, Double</p>
1174
          </td>
1175
        </tr>
1176
        <tr>
1177
          <td>
1178
            <p>xs:double</p>
1179
          </td>
1180
          <td>
1181
            <p>
1182
              <i>DoubleValue</i>, Double</p>
1183
          </td>
1184
        </tr>
1185
        <tr>
1186
          <td>
1187
            <p>xs:decimal</p>
1188
          </td>
1189
          <td>
1190
            <p>
1191
              <i>DecimalValue</i>, BigDecimal, Double, Float</p>
1192
          </td>
1193
        </tr>        
1194
        <tr>
1195
          <td>
1196
            <p>xs:integer</p>
1197
          </td>
1198
          <td>
1199
            <p>
1200
              <i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Short, Byte, Double, Float</p>
1201
          </td>
1202
        </tr>
1203
        <tr>
1204
          <td>
1205
            <p>xs:date, xs:gDay, xs:gMonthDay, xs:gMonth, xs:gYearMonth, xs: gYear</p>
1206
          </td>
1207
          <td>
1208
            <p>
1209
              <i>DateValue</i>, Date</p>
1210
          </td>
1211
        </tr>
1212
        <tr>
1213
          <td>
1214
            <p>xs:dateTime</p>
1215
          </td>
1216
          <td>
1217
            <p>
1218
              <i>DateTimeValue</i>, Date</p>
1219
          </td>
1220
        </tr>
1221
        <tr>
1222
          <td>
1223
            <p>xs:time</p>
1224
          </td>
1225
          <td>
1226
            <p>
1227
              <i>TimeValue</i></p>
1228
          </td>
1229
        </tr>
1230
        <tr>
1231
          <td>
1232
            <p>xs:duration, xs:yearMonthDuration, xs:dayTimeDuration</p>
1233
          </td>
1234
          <td>
1235
            <p>
1236
              <i>DurationValue</i>
1237
            </p>
1238
          </td>
1239
        </tr>        
1240
        <tr>
1241
          <td>
1242
            <p>xs:hexBinary</p>
1243
          </td>
1244
          <td>
1245
            <p>
1246
              <i>HexBinaryValue</i></p>
1247
          </td>
1248
        </tr>
1249
        <tr>
1250
          <td>
1251
            <p>xs:base64Binary</p>
1252
          </td>
1253
          <td>
1254
            <p>
1255
              <i>Base64BinaryValue</i></p>
1256
          </td>
1257
        </tr>
1258
        <tr>
1259
          <td>
1260
            <p>xs:anyURI</p>
1261
          </td>
1262
          <td>
1263
            <p>
1264
              <i>AnyURIValue</i>, java.net.URI, java.net.URL, String, CharSequence</p>
1265
          </td>
1266
        </tr>
1267
        <tr>
1268
          <td>
1269
            <p>xs:QName</p>
1270
          </td>
1271
          <td>
1272
            <p>
1273
              <i>QNameValue</i>, javax.xml.namespace.QName</p>
1274
          </td>
1275
        </tr>
1276
      </table>
1277
      
1278
      <p>Saxon tries to select the appropriate method based on the <i>static type</i> of the
1279
        arguments to the function call. If there are several candidate methods, and there is
1280
        insufficient information available to decide which is most appropriate, an error is
1281
        reported. The remedy is to cast the arguments to a more specific type.</p>
1282

    
1283
      <p>A required type of one of the Java primitive types such as <code>int</code> or
1284
          <code>bool</code> is treated as equivalent to the corresponding boxed type
1285
          (<code>Integer</code> or <code>Boolean</code>), except that with the boxed types, an empty
1286
        sequence can be supplied in the function call and is translated to a Java null value as the
1287
        actual argument.</p>
1288

    
1289
      <p>The fact that a particular method is chosen as the target does not give a guarantee that
1290
        conversion of the arguments will succeed at run-time. This is particularly true with methods
1291
        that expect a node in an external object model such as DOM or XOM.</p>
1292
    </section>
1293

    
1294
    <section id="staticmethods" title="Calling Static Methods in a Java Class">
1295
      <h1>Calling Static Methods in a Java Class</h1>
1296

    
1297

    
1298
      <p><strong>Static methods</strong> can be called directly.</p>
1299

    
1300
      <p>For example (in XSLT):</p>
1301
      <samp><![CDATA[<xsl:value-of select="math:sqrt($arg)"
1302
   xmlns:math="java:java.lang.Math"/>
1303
]]></samp>
1304

    
1305
      <p>This will invoke the static method <code>java.lang.Math#sqrt()</code>, applying it to the
1306
        value of the variable <code>$arg</code>, and copying the value of the square root of
1307
          <code>$arg</code> to the result tree.</p>
1308

    
1309
      <p>Similarly (in XQuery):</p>
1310
      <samp><![CDATA[<a xmlns:double="java:java.lang.Double"> 
1311
                              {double:MAX_VALUE()} </a>
1312
]]></samp>
1313

    
1314
      <p>This will output the value of the static field <code>java.lang.Double#MAX_VALUE</code>. (In
1315
        practice, it is better to declare the namespace in the query prolog, because it will then
1316
        not be copied to the result tree.)</p>
1317

    
1318
      <p>A static Java method called as an extension function may have an extra first argument of
1319
        class <a class="javalink" href="net.sf.saxon.expr.XPathContext"
1320
          >net.sf.saxon.expr.XPathContext</a>. This argument is not supplied by the calling XPath or
1321
        XQuery code, but by Saxon itself. The <code>XPathContext</code> object provides methods to
1322
        access many internal Saxon resources, the most useful being <code>getContextItem()</code>
1323
        which returns the context item from the dynamic context. The XPathContext object is
1324
        available with static or instance-level methods, but not with constructors.</p>
1325

    
1326
      <p>The following example shows a function that obtains the line number of the context node
1327
        (this is actually a built-in Saxon extension):</p>
1328
      <samp><![CDATA[/**
1329
* Return the line number of the context node.
1330
*/
1331
public static int lineNumber(XPathContext c) {
1332
    Item item = c.getCurrentIterator().current();
1333
    if (item instanceof NodeInfo) {
1334
        return ((NodeInfo)item).getLineNumber();
1335
    } else {
1336
        return -1;
1337
    }
1338
}]]></samp>
1339

    
1340
      <p>If this method appears in class <code>com.example.code.NodeData</code>, then it can be
1341
        accessed using the following code in XSLT:</p>
1342
      <samp><![CDATA[<xsl:value-of select="nd:line-number()" 
1343
    xmlns:nd="java:com.example.code.NodeData"/>]]></samp>
1344

    
1345
      <p>or the following in XQuery:</p>
1346
      <samp><![CDATA[<line xmlns:nd="java:com.example.code.NodeData">
1347
    { nd:line-number() }
1348
</line>]]></samp>
1349
    </section>
1350

    
1351
    <section id="constructors" title="Calling Java Constructors">
1352
      <h1>Calling Java Constructors</h1>
1353

    
1354

    
1355
      <p><strong>Java constructors</strong> are called by using the function named
1356
          <code>new()</code>. If there are several constructors, then again the system tries to find
1357
        the one that is the best fit, according to the types of the supplied arguments. The result
1358
        of calling <code>new()</code> is an XPath value whose type is denoted by a QName whose local
1359
        name is the actual Java class (for example <code>java.sql.Connection</code> or
1360
          <code>java.util.List</code>) and whose namespace URI is
1361
          <code>http://saxon.sf.net/java-type</code> (conventional prefix <code>jt</code>). Any '$'
1362
        characters in the Java class name are replaced by '-' characters in the QName, and for array
1363
        types, any '[' characters at the start of the Java binary class name are replaced by '_-'
1364
        (underscore then hyphen). So for example the QName representing the Java class
1365
          <code>byte[]</code> (binary name <code>[B</code>) becomes
1366
          <code>Q{http://saxon.sf.net/java-type}_-B</code>, while <code>byte[][]</code> (binary name
1367
          <code>[[B</code>) becomes <code>Q{http://saxon.sf.net/java-type}_-_-B</code>.</p>
1368

    
1369
      <p>The only things that can be done with a wrapped Java Object are to assign it to a variable,
1370
        to pass it to an extension function, and to convert it to a string, number, or boolean,
1371
        using the rules given below.</p>
1372

    
1373
      <p>The use of external object types in namespace <code>http://saxon.sf.net/java-type</code>
1374
        reflects the Java type hierarchy. For example, if a variable is declared to accept a type of
1375
          <code>jt:java.util.List</code>, then a value of type <code>jt:java.util.ArrayList</code>
1376
        will be accepted, but a value of type <code>jt:java.util.HashMap</code> will not.</p>
1377

    
1378
      <p>In the XPath type hierarchy, external object types are a fourth kind of item, alongside
1379
        nodes, atomic values, and functions. (In earlier Saxon releases, external object types were
1380
        considered subtypes of <code>xs:anyAtomicType</code>, but this is no longer the case.)</p>
1381
    </section>
1382

    
1383
    <section id="instance-methods" title="Calling Java Instance-Level Methods">
1384
      <h1>Calling Java Instance-Level Methods</h1>
1385
      
1386
      <p>There are two ways of calling <strong>instance-level methods</strong>
1387
        (that is, non-static methods). In both cases you first need to get a value representing
1388
      the Java object whose method is to be called: this will usually be obtained by invoking a constructor
1389
      or static factory method, or it may be supplied as an external parameter to a stylesheet or query.</p>
1390
      
1391
      <ol>
1392
      
1393
      <li><p>From Saxon 9.9, an external Java object can be converted to an XDM map item. This conversion can be done
1394
        explicitly using the <a class="bodylink"
1395
          href="/functions/saxon/object-map">saxon:object-map</a> extension function; it is also done implicitly
1396
        if the left-hand operand of the lookup operator "?" evaluates to an external Java object.
1397
        The entries in the map
1398
      are key-value pairs, and there is one entry for each public non-static method in the Java object,
1399
      provided that it is not overloaded. The key of the entry is the method name, and the value of the
1400
      entry is a function that can be invoked using a dynamic function call. So, for example, you can create
1401
      an object of type <code>javatype:java.net.URI</code> using the code <code>let $uri := Q{java:java.net.URI}new('https://saxonica.com/')</code>
1402
      and you can then find the "scheme' part of this URI with the expression <code>$uri?getScheme()</code>
1403
      (which returns the <code>xs:string</code> value <code>"https"</code>).</p>
1404
      
1405
      <p>In fact there will be two entries in the map for this method: <code>getScheme</code> and <code>getScheme_0</code>.
1406
      The version with an arity suffix can be used where the class defines multiple methods having the same name but
1407
      different arity. If there are two methods with the same name and the same arity, however, no entry is created
1408
      and the method cannot be called. Note that there is no conversion of the name to hyphenated form: the method
1409
      must be invoked as <code>getScheme</code> rather than <code>get-scheme</code>.</p>
1410
      
1411
      <p>The map produced to represent the object also has an entry with key <code>"this"</code>
1412
      whose value is the original external object.</p>
1413
      
1414
        <aside>Calling instance-level methods using a dynamic call (<code>$uri?getScheme()</code>
1415
          rather than <code>Q{java:java.net.URI}getScheme($uri)</code>) has advantages in terms of
1416
          readability, but it has the disadvantage that there is currently no static type checking. This
1417
          means that overloaded methods are not available, and there will be no compile-time diagnostics
1418
          if the method does not exist: only a rather cryptic run-time message that the target of a dynamic
1419
          function call must not be an empty sequence.</aside>
1420
      </li>
1421
      
1422
      <li><p>The second way to call instance-level methods is as a regular (static) function call with an extra
1423
      first argument. In this case matching of method names is done as for static methods. If
1424
        there are several methods in the class that match the localname, the system again tries to
1425
        find the one that is the best fit, according to the types of the supplied arguments (see
1426
        <a class="bodylink" href="../choosing-overload">Choosing among overloaded methods</a>.</p>
1427

    
1428
      <p>For example, the following XSLT stylesheet prints the date and time. (From XSLT 2.0, of
1429
        course, this no longer requires extension functions, but the example is still valid.)</p>
1430
      <samp><![CDATA[<xsl:stylesheet
1431
  version="1.0"
1432
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
1433
  xmlns:date="java:java.util.Date">
1434

    
1435
<xsl:template match="/">
1436
  <html>
1437
    <xsl:if test="function-available('date:to-string') and 
1438
                          function-available('date:new')">
1439
      <p><xsl:value-of select="date:to-string(date:new())"/></p>
1440
    </xsl:if>
1441
  </html>
1442
</xsl:template>
1443

    
1444
</xsl:stylesheet>
1445
]]></samp>
1446

    
1447
      <p>The equivalent in XQuery is:</p>
1448
      <samp><![CDATA[declare namespace date="java:java.util.Date";
1449
<p>{date:to-string(date:new())}</p>
1450
]]></samp>
1451
        </li>
1452
      </ol>
1453

    
1454
      <p>As with static methods, an instance-level Java method called as an extension function may
1455
        have an extra first argument of class <a class="javalink"
1456
          href="net.sf.saxon.expr.XPathContext">net.sf.saxon.expr.XPathContext</a>. This argument is
1457
        not supplied by the calling XPath or XQuery code, but by Saxon itself. The
1458
          <code>XPathContext</code> object provides methods to access many internal Saxon resources,
1459
        the most useful being <code>getContextItem()</code> which returns the context item from the
1460
        dynamic context. The XPathContext object is not available with constructors.</p>
1461

    
1462
      <p>If any exceptions are thrown by the method, or if a matching method cannot be found,
1463
        processing of the stylesheet will be abandoned. If the tracing option <code>-T</code> has been set on
1464
        the command line, a full stack trace will be output. The exception will be wrapped in a
1465
          <code>TransformerException</code> and passed to any user-specified
1466
          <code>ErrorListener</code> object, so the <code>ErrorListener</code> can also produce
1467
        extra diagnostics.</p>
1468
      
1469
      
1470

    
1471
      <p>It is also possible to use the reflexive call mechanism to call instance-level methods of
1472
        the implementation classes for XDM values. For example, the following gets the current
1473
        Julian instant as a decimal number:</p>
1474

    
1475
      <samp><![CDATA[<xsl:value-of select="d:toJulianInstant(current-dateTime())"
1476
         xmlns:d="java:net.sf.saxon.value.DateTimeValue"/>]]></samp>
1477

    
1478
      <p>This will only work if the value of the expression (<code>current-dateTime()</code> in this
1479
        example) is implemented internally as an instance of the class defined in the namespace used
1480
        to invoke the method. Using this mechanism successfully therefore requires some knowledge of
1481
        the Saxon internals.</p>
1482
    </section>
1483
  
1484
  <section id="converting-args" title="Converting Arguments to Java Extension Functions">
1485
    <h1>Converting Arguments to Java Extension Functions</h1>
1486

    
1487

    
1488
    <p>This section describes how XPath values supplied in a call to a Java extension function are
1489
      converted to Java values.</p>
1490

    
1491
    <p>There are three phases of decision-making:</p>
1492
    <ul>
1493
      <li>
1494
        <p>First, Saxon decides which method to call. See <a class="bodylink" href="../choosing-overload">Choosing among overloaded
1495
          methods</a> above.</p>
1496
      </li>
1497
      <li>
1498
        <p>Saxon allocates a converter, wherever possible at compile time, based on the static type
1499
          of the supplied argument and the Java type expected by the method.</p>
1500
      </li>
1501
      <li>
1502
        <p>At run-time the converter performs the conversion from the supplied value to the required
1503
          type. Some converters will make further decisions based on run-time types at this
1504
          stage.</p>
1505
      </li>
1506
    </ul>
1507

    
1508
    <p>The process of argument conversion is described further in the following pages.</p>
1509
    <nav>
1510
      <ul/>
1511
    </nav>
1512

    
1513
    <section id="converting-arguments" title="Converting Method Arguments - General Rules">
1514
      <h1>Converting Method Arguments - General Rules</h1>
1515

    
1516

    
1517
      <p>Having decided which method to call, Saxon has to convert the supplied XPath argument
1518
        values to the Java objects required by this method.</p>
1519
      
1520
      <p>The conversion is done as follows:</p>
1521
      
1522
      <ol>
1523
        <li><p>If there is an <em>equivalent XPath type</em>
1524
        to the declared type of the Java method or constructor, then the supplied value is first converted to this
1525
        equivalent XPath type using the standard function conversion rules used in all XPath function calls (without 1.0
1526
        backwards compatibility mode): for example an untyped attribute node can be supplied to a function that expects a string.
1527
        The conversion from the equivalent XPath type to the actual Java type is then trivial, for example an <code>xs:string</code>
1528
        value is converted to the corresponding <code>java.lang.String</code>.</p>
1529
 
1530
      
1531
        <p>The <em>equivalent XPath type</em> is determined as follows:</p>
1532
        
1533
        <ul>
1534
          <li><p>If the Java class is an array of X, then the equivalent XPath type is T*, where T is the equivalent
1535
          type to X. (For example <code>String[]</code> maps to <code>xs:string*</code>)</p></li>
1536
          <li><p>If the Java class is one of the Saxon classes <code>One&lt;X&gt;</code>, <code>ZeroOrOne&lt;X&gt;</code>,
1537
            <code>OneOrMore&lt;X&gt;</code>, or <code>ZeroOrMore&lt;X&gt;</code>, then the equivalent XPath type is
1538
          the equivalent type to X, with an appropriate occurrence indicator. For example <code>OneOrMore&lt;String&gt;</code>
1539
          maps to <code>xs:string+</code>.</p></li>
1540
          <li><p>If the Java class is a Saxon class used to implement items, such as <code>net.sf.saxon.value.StringValue</code>
1541
          or <code>net.sf.saxon.om.NodeInfo</code>, then the equivalent XPath type is the XPath item type that this Java class implements.</p></li>
1542
          <li><p>If the Java class is one of those listed in the table below, the equivalent XPath type is taken from this table:</p>
1543
          <table>
1544
            <thead>
1545
              <tr>
1546
                <td>Java class</td>
1547
                <td>Equivalent XPath type</td>
1548
              </tr>
1549
            </thead>
1550
            <tbody>
1551
              <tr>
1552
                <td><code>boolean</code></td>
1553
                <td><code>xs:boolean</code></td>
1554
              </tr>
1555
              <tr>
1556
                <td><code>Boolean</code></td>
1557
                <td><code>xs:boolean?</code></td>
1558
              </tr>
1559
              <tr>
1560
                <td><code>String</code></td>
1561
                <td><code>xs:string?</code></td>
1562
              </tr>
1563
              <tr>
1564
                <td><code>CharSequence</code></td>
1565
                <td><code>xs:string?</code></td>
1566
              </tr>
1567
              <tr>
1568
                <td><code>long</code></td>
1569
                <td><code>xs:integer</code></td>
1570
              </tr>
1571
              <tr>
1572
                <td><code>Long</code></td>
1573
                <td><code>xs:integer?</code></td>
1574
              </tr>
1575
              <tr>
1576
                <td><code>int</code></td>
1577
                <td><code>xs:integer</code></td>
1578
              </tr>
1579
              <tr>
1580
                <td><code>Integer</code></td>
1581
                <td><code>xs:integer?</code></td>
1582
              </tr>
1583
              <tr>
1584
                <td><code>short</code></td>
1585
                <td><code>xs:short</code></td>
1586
              </tr>
1587
              <tr>
1588
                <td><code>Short</code></td>
1589
                <td><code>xs:short?</code></td>
1590
              </tr>
1591
              <tr>
1592
                <td><code>byte</code></td>
1593
                <td><code>xs:byte</code></td>
1594
              </tr>
1595
              <tr>
1596
                <td><code>Byte</code></td>
1597
                <td><code>xs:byte?</code></td>
1598
              </tr>
1599
              <tr>
1600
                <td><code>float</code></td>
1601
                <td><code>xs:float</code></td>
1602
              </tr>
1603
              <tr>
1604
                <td><code>Float</code></td>
1605
                <td><code>xs:float?</code></td>
1606
              </tr>
1607
              <tr>
1608
                <td><code>double</code></td>
1609
                <td><code>xs:double</code></td>
1610
              </tr>
1611
              <tr>
1612
                <td><code>Double</code></td>
1613
                <td><code>xs:double?</code></td>
1614
              </tr>
1615
              <tr>
1616
                <td><code>URI</code></td>
1617
                <td><code>xs:anyURI?</code></td>
1618
              </tr>
1619
              <tr>
1620
                <td><code>URL</code></td>
1621
                <td><code>xs:anyURI?</code></td>
1622
              </tr>
1623
              <tr>
1624
                <td><code>BigInteger</code></td>
1625
                <td><code>xs:integer?</code></td>
1626
              </tr>
1627
              <tr>
1628
                <td><code>BigDecimal</code></td>
1629
                <td><code>xs:decimal?</code></td>
1630
              </tr>
1631
              
1632
            </tbody>
1633
          </table>
1634
  
1635
          </li>
1636
        </ul>
1637
        </li>
1638
      <li>
1639
    
1640
      
1641
      <p>Where there is no equivalent XPath type, the following rules apply:</p>
1642
        
1643
        <ul>
1644

    
1645
      <li><p>If the expected type is <code>Object</code>, the supplied value must either be a singleton,
1646
        or an empty sequence. If it is an empty sequence, null will be passed. If it is a singleton
1647
        node, an instance of <a class="javalink" href="net.sf.saxon.om.NodeInfo"
1648
          >net.sf.saxon.om.NodeInfo</a> will be passed. If it is a wrapped Java object, that Java
1649
        object will be passed. If it is a singleton atomic value, the value will be converted to the
1650
        nearest equivalent Java object: for example an <code>xs:boolean</code> becomes
1651
          <code>java.lang.Boolean</code>, an <code>xs:string</code> becomes
1652
          <code>java.lang.String</code>, and so on. An untyped atomic value is treated as a string.
1653
        An <code>xs:integer</code> (even if it belongs to a subtype such as <code>xs:short</code>)
1654
        is converted to a Java <code>BigInteger</code>. The more specialized XML Schema primitive
1655
        types such as <code>xs:hexBinary</code> and <code>xs:duration</code> are passed in their
1656
        native Saxon representation (a subclass of <a class="javalink"
1657
          href="net.sf.saxon.value.AtomicValue">net.sf.saxon.value.AtomicValue</a>).</p></li>
1658

    
1659
      <li><p>If the expected type is one of the Saxon-specific classes (<a class="javalink"
1660
          href="net.sf.saxon.om.SequenceIterator">SequenceIterator</a>, <a class="javalink"
1661
          href="net.sf.saxon.om.Sequence">Sequence</a>, <a class="javalink"
1662
          href="net.sf.saxon.om.Item">Item</a>, <a class="javalink" href="net.sf.saxon.value.AtomicValue">AtomicValue</a>, <a
1663
          class="javalink" href="net.sf.saxon.value.SequenceExtent">SequenceExtent</a>), then the
1664
        value is passed unchanged. An error occurs if the supplied value contains more than one item
1665
        and the expected type does not allow this.</p></li>
1666

    
1667
      <li><p>The types <a class="javalink" href="net.sf.saxon.om.ZeroOrMore">ZeroOrMore</a>, <a
1668
          class="javalink" href="net.sf.saxon.om.OneOrMore">OneOrMore</a>, <a class="javalink"
1669
          href="net.sf.saxon.om.ZeroOrOne">ZeroOrOne</a>, and <a class="javalink"
1670
          href="net.sf.saxon.om.One">One</a> can be used to specify the permitted cardinality, and
1671
        can also be parameterized to define the permitted item type. For example, an argument
1672
        defined as <code>One&lt;StringValue></code> is equivalent to the XPath SequenceType
1673
          <code>string</code>, and allows a single string only. When such declarations are used, the
1674
        conversion of the supplied argument to the required type follows the standard XPath
1675
        conversion rules precisely.</p></li>
1676

    
1677
      <li><p>If the expected type implements <code>java.util.Collection</code>, Saxon attempts to
1678
        convert each value in the supplied sequence to the most appropriate Java class, following
1679
        the same rules as when converting a singleton to <code>java.lang.Object</code>. This process
1680
        takes no account of parameterized collection types (such as
1681
        <code>List&lt;String&gt;</code>). If the required collection type accepts an
1682
          <code>java.util.ArrayList</code>, Saxon will create an <code>ArrayList</code> to hold the
1683
        values; otherwise it will attempt to instantiate the required type of collection, which will
1684
        only work if it is a concrete class with a zero-argument public constructor (so it will
1685
        fail, for example, if the required type is <code>java.util.Set</code>). If an empty sequence
1686
        is supplied as the argument value, this is converted to an empty <code>Collection</code>.</p></li>
1687

    
1688
      <li><p>If the required type is an array, Saxon will attempt to create an array of the required
1689
        type. This will not always succeed, for example if the array has type <code>X[]</code> where
1690
        <code>X</code> is an interface rather than a concrete class. If it is an array of items or nodes, the
1691
        nodes in the supplied sequence will be inserted into the array directly; if it is an array
1692
        of a type such as integer or double, the sequence will first be atomized.</p></li>
1693
        </ul>
1694
      </li>
1695
      </ol>
1696
    </section>
1697

    
1698
    <section id="converting-atomic" title="Converting Atomic Values">
1699
      <h1>Converting Atomic Values</h1>
1700

    
1701

    
1702
      <p>This section describes the conversions that occur when calling a method that expects an
1703
        atomic value, such as a <code>String</code> or a <code>Boolean</code>.</p>
1704

    
1705
      <p>If the supplied value is a node, then it is atomized.</p>
1706

    
1707
      <p>If the supplied value contains more than item and only a single item is expected, an error
1708
        is reported. There is no implicit extraction of the first value (as happened in earlier
1709
        Saxon releases).</p>
1710

    
1711
      <p>If the supplied value is an empty sequence, then a null value is passed. However, if the
1712
        required type is a primitive Java type such as <code>int</code> or <code>bool</code>, then
1713
        passing an empty sequence will result in a type error.</p>
1714

    
1715
      <p>In other cases, the supported conversions are as follows. Italicized names are
1716
        Saxon-specific classes in package <a class="javalink" href="net.sf.saxon.value">net.sf.saxon.value</a>.</p>
1717
      <table>
1718
        <tr>
1719
          <td>
1720
            <p>
1721
              <strong>Supplied type</strong>
1722
            </p>
1723
          </td>
1724
          <td>
1725
            <p>
1726
              <strong>Required type</strong>
1727
            </p>
1728
          </td>
1729
        </tr>
1730
        <tr>
1731
          <td>
1732
            <p>xs:string</p>
1733
          </td>
1734
          <td>
1735
            <p>
1736
              <i>StringValue</i>, String, CharSequence</p>
1737
          </td>
1738
        </tr>        
1739
        <tr>
1740
          <td>
1741
            <p>xs:boolean</p>
1742
          </td>
1743
          <td>
1744
            <p>
1745
              <i>BooleanValue</i>, Boolean</p>
1746
          </td>
1747
        </tr>
1748
        <tr>
1749
          <td>
1750
            <p>xs:float</p>
1751
          </td>
1752
          <td>
1753
            <p>
1754
              <i>FloatValue</i>, Float, Double</p>
1755
          </td>
1756
        </tr>
1757
        <tr>
1758
          <td>
1759
            <p>xs:double</p>
1760
          </td>
1761
          <td>
1762
            <p>
1763
              <i>DoubleValue</i>, Double</p>
1764
          </td>
1765
        </tr>
1766
        <tr>
1767
          <td>
1768
            <p>xs:decimal</p>
1769
          </td>
1770
          <td>
1771
            <p>
1772
              <i>DecimalValue</i>, BigDecimal, Double, Float</p>
1773
          </td>
1774
        </tr>        
1775
        <tr>
1776
          <td>
1777
            <p>xs:integer</p>
1778
          </td>
1779
          <td>
1780
            <p>
1781
              <i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Short, Byte, Double, Float</p>
1782
          </td>
1783
        </tr>
1784
        <tr>
1785
          <td>
1786
            <p>xs:date, xs:gDay, xs:gMonthDay, xs:gMonth, xs:gYearMonth, xs: gYear</p>
1787
          </td>
1788
          <td>
1789
            <p>
1790
              <i>DateValue</i>, java.time.ZonedDateTime, java.time.Instant, java.util.Date</p>
1791
          </td>
1792
        </tr>
1793
        <tr>
1794
          <td>
1795
            <p>xs:dateTime</p>
1796
          </td>
1797
          <td>
1798
            <p>
1799
              <i>DateTimeValue</i>, java.time.ZonedDateTime, java.time.Instant, java.util.Date</p>
1800
          </td>
1801
        </tr>
1802
        <tr>
1803
          <td>
1804
            <p>xs:time</p>
1805
          </td>
1806
          <td>
1807
            <p>
1808
              <i>TimeValue</i></p>
1809
          </td>
1810
        </tr>
1811
        <tr>
1812
          <td>
1813
            <p>xs:duration, xs:yearMonthDuration, xs:dayTimeDuration</p>
1814
          </td>
1815
          <td>
1816
            <p>
1817
              <i>DurationValue</i>
1818
            </p>
1819
          </td>
1820
        </tr>        
1821
        <tr>
1822
          <td>
1823
            <p>xs:hexBinary</p>
1824
          </td>
1825
          <td>
1826
            <p>
1827
              <i>HexBinaryValue</i></p>
1828
          </td>
1829
        </tr>
1830
        <tr>
1831
          <td>
1832
            <p>xs:base64Binary</p>
1833
          </td>
1834
          <td>
1835
            <p>
1836
              <i>Base64BinaryValue</i></p>
1837
          </td>
1838
        </tr>
1839
        <tr>
1840
          <td>
1841
            <p>xs:anyURI</p>
1842
          </td>
1843
          <td>
1844
            <p>
1845
              <i>AnyURIValue</i>, java.net.URI, java.net.URL, String, CharSequence</p>
1846
          </td>
1847
        </tr>
1848
        <tr>
1849
          <td>
1850
            <p>xs:QName</p>
1851
          </td>
1852
          <td>
1853
            <p>
1854
              <i>QNameValue</i>, javax.xml.namespace.QName</p>
1855
          </td>
1856
        </tr>
1857
      </table>
1858
      <!--<table>
1859
        <tr>
1860
          <td>
1861
            <p>
1862
              <strong>Supplied type</strong>
1863
            </p>
1864
          </td>
1865
          <td>
1866
            <p>
1867
              <strong>Required type</strong>
1868
            </p>
1869
          </td>
1870
        </tr>
1871
        <tr>
1872
          <td>
1873
            <p>boolean</p>
1874
          </td>
1875
          <td>
1876
            <p>
1877
              <i>BooleanValue</i>, Boolean</p>
1878
          </td>
1879
        </tr>
1880
        <tr>
1881
          <td>
1882
            <p>dateTime</p>
1883
          </td>
1884
          <td>
1885
            <p>
1886
              <i>DateTimeValue</i>, Date</p>
1887
          </td>
1888
        </tr>
1889
        <tr>
1890
          <td>
1891
            <p>date</p>
1892
          </td>
1893
          <td>
1894
            <p>
1895
              <i>DateValue</i>, Date</p>
1896
          </td>
1897
        </tr>
1898
        <tr>
1899
          <td>
1900
            <p>decimal</p>
1901
          </td>
1902
          <td>
1903
            <p>
1904
              <i>DecimalValue</i>, BigDecimal, Double, Float</p>
1905
          </td>
1906
        </tr>
1907
        <tr>
1908
          <td>
1909
            <p>double</p>
1910
          </td>
1911
          <td>
1912
            <p>
1913
              <i>DoubleValue</i>, Double</p>
1914
          </td>
1915
        </tr>
1916
        <tr>
1917
          <td>
1918
            <p>duration</p>
1919
          </td>
1920
          <td>
1921
            <p>
1922
              <i>DurationValue</i>
1923
            </p>
1924
          </td>
1925
        </tr>
1926
        <tr>
1927
          <td>
1928
            <p>float</p>
1929
          </td>
1930
          <td>
1931
            <p>
1932
              <i>FloatValue</i>, Float, Double</p>
1933
          </td>
1934
        </tr>
1935
        <tr>
1936
          <td>
1937
            <p>integer, long, int</p>
1938
          </td>
1939
          <td>
1940
            <p>
1941
              <i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Double, Float</p>
1942
          </td>
1943
        </tr>
1944
        <tr>
1945
          <td>
1946
            <p>short</p>
1947
          </td>
1948
          <td>
1949
            <p>
1950
              <i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Short, Double, Float</p>
1951
          </td>
1952
        </tr>
1953
        <tr>
1954
          <td>
1955
            <p>byte</p>
1956
          </td>
1957
          <td>
1958
            <p>
1959
              <i>IntegerValue</i>, BigInteger, BigDecimal, Long, Integer, Short, Byte, Double,
1960
              Float</p>
1961
          </td>
1962
        </tr>
1963
        <tr>
1964
          <td>
1965
            <p>string</p>
1966
          </td>
1967
          <td>
1968
            <p>
1969
              <i>StringValue</i>, (String, CharSequence)</p>
1970
          </td>
1971
        </tr>
1972
        <tr>
1973
          <td>
1974
            <p>anyURI</p>
1975
          </td>
1976
          <td>
1977
            <p>
1978
              <i>AnyURIValue</i>, java.net.URI, java.net.URL, (String, CharSequence)</p>
1979
          </td>
1980
        </tr>
1981
        <tr>
1982
          <td>
1983
            <p>QName</p>
1984
          </td>
1985
          <td>
1986
            <p>
1987
              <i>QNameValue</i>, javax.xml.namespace.QName</p>
1988
          </td>
1989
        </tr>
1990
      </table>-->
1991

    
1992
      <p>A required type of one of the Java primitive types such as <code>int</code> or
1993
          <code>bool</code> is treated as equivalent to the corresponding boxed type
1994
          (<code>Integer</code> or <code>Boolean</code>), except that with the boxed types, an empty
1995
        sequence can be supplied in the function call and is translated to a Java null value as the
1996
        actual argument.</p>
1997
    </section>
1998

    
1999
    <section id="converting-node" title="Converting Nodes">
2000
      <h1>Converting Nodes</h1>
2001

    
2002

    
2003
      <p>If the expected type is a generic collection type, or an array of the Saxon class <a
2004
          class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a>, or a <a class="javalink"
2005
          href="net.sf.saxon.om.Sequence">Sequence</a> or <a class="javalink"
2006
          href="net.sf.saxon.om.SequenceIterator">SequenceIterator</a>, Saxon will pass the nodes
2007
        supplied in the call in their native Saxon representation, that is, as instances of
2008
          <code>net.sf.saxon.om.NodeInfo</code>.</p>
2009

    
2010
      <p>Saxon recognizes methods that expect nodes in an external object model (DOM, DOM4J, JDOM,
2011
        or XOM). In all four cases, if the XPath node is actually a view of a DOM, DOM4J, JDOM, or
2012
        XOM node, then the underlying node will be passed to the method. If the XPath node is a text
2013
        node that maps to a sequence of adjacent text and/or CDATA nodes in the underlying model,
2014
        the first node in this sequence will be passed to the extension function.</p>
2015

    
2016
      <p>In addition, in the case of DOM only, if the XPath node is <strong>not</strong> a view of a
2017
        DOM node, Saxon will create a DOM wrapper for the native Saxon node, and pass this wrapper.
2018
        This is also done if the required type is a DOM <code>NodeList</code>. Note that the wrapper
2019
        is a read-only DOM implementation: any attempt to update nodes through the wrapper interface
2020
        will throw an exception. A consequence of the way the wrapping works is that it's not safe
2021
        to rely on object identity when testing node identity - the same node can be represented by
2022
        more than one Java object. Use the DOM method <code>isSameNode()</code> instead.</p>
2023
      
2024
      <p>Note that it is generally not recommended to use extension functions that expect DOM nodes,
2025
        since the quirks of the DOM interface are such that a mapping from XDM to DOM is always
2026
        going to have odd behaviour in edge cases. The only real reason for using it is to interface
2027
        existing code that already uses the DOM. In general it is better to write extension functions
2028
        to use the <code>NodeInfo</code> interface.</p>
2029
    </section>
2030

    
2031
    <section id="converting-wrapped-java" title="Converting Wrapped Java Objects">
2032
      <h1>Converting Wrapped Java Objects</h1>
2033

    
2034

    
2035
      <p>Saxon allows an extension function to return an arbitrary Java object. This will then be
2036
        wrapped as an XPath item, so that it can be held in a variable and passed subsequently as an
2037
        argument to another extension function. This second extension function will see the original
2038
        Java object minus its wrapper, provided it is declared to expect the appropriate Java
2039
        class.</p>
2040

    
2041
      <p>A wrapped Java object always holds a non-null object value. The Java value null converts to
2042
        the XPath empty sequence.</p>
2043

    
2044
      <p>A wrapped Java object may be converted to another data type as follows.</p>
2045
      <ul>
2046
        <li>
2047
          <p>It is converted to a string by calling its <code>toString()</code> method.</p>
2048
        </li>
2049
        <li>
2050
          <p>It is atomized by calling its <code>toString()</code> method.</p>
2051
        </li>
2052
        <li>
2053
          <p>It is converted to a number by converting it first to a string, and then applying the
2054
            XPath <code>number()</code> conversion.</p>
2055
        </li>
2056
        <li>
2057
          <p>The effective boolean value of a wrapped Java object (like that of a node) is always
2058
            true.</p>
2059
        </li>
2060
      </ul>
2061

    
2062
      <p>The type of a wrapped Java object may be declared in a variable declaration or function
2063
        signature using a type name whose namespace URI is <code>http://saxon.sf.net/java-type</code>, and
2064
        whose local name is the fully qualified name of the Java class, with any "$" signs replaced
2065
        by hyphens, and with leading "[" characters replaced by "_-". For example, the
2066
          <code>sql:connection</code> extension function returns a value of type
2067
          <code>{http://saxon.sf.net/java-type}java.sql.Connection</code>.</p>
2068

    
2069
      <p>Note that a call on a constructor function (using <code>prefix:new()</code>) always returns a wrapped
2070
        Java object, regardless of the class. But a call on a static method, instance-level method,
2071
        or field will return a wrapped Java object only if the result is a class that Saxon does not
2072
        specifically recognize as one that it can convert to a regular XPath value. Such classes
2073
        include <code>String</code>, <code>Long</code>, <code>Double</code>, <code>Date</code>,
2074
          <code>BigInteger</code>, <code>URI</code>, <code>List</code>, <code>Map</code>, and so on.</p>
2075
      
2076
      <p>If you want an object of one of these "recognized" classes to be returned as a wrapped Java object
2077
        rather than being converted to its XDM equivalent (for example, if you want a Java <code>java.util.List</code>
2078
        kept as an instance of <code>java.util.List</code>, rather than being converted to an XDM Sequence),
2079
        you can achieve this by binding the result of a function call to a variable that declares the required
2080
        type (or by using it as an argument of a function call whose signature defines the required type).
2081
        For example if you write <code>&lt;xsl:variable name="list" select="Q{java:java.util.Collections}emptyList()"/></code>
2082
        then the result will be an XDM empty sequence. But if you add the attribute <code>as="jt:java.util.List"</code>,
2083
        where the prefix <code>jt</code> is bound to the namespace <code>http://saxon.sf.net/java-type</code>, then
2084
        the conversion to an XDM sequence will be prevented, and the result will be a wrapped Java object of type
2085
        <code>java.util.List</code>.
2086
      </p>
2087
      
2088
      <p>A wrapped Java object is also used in an expression such as <code>Q{java:java.util.List}size(my:bigList())</code>,
2089
      where Saxon knows that the first argument to size() must be an instance of <code>java.util.List</code>,
2090
        or <code>Q{java:java.lang.String}split('a,b,c', ',')</code> where it knows that <code>split</code>
2091
        requires a Java string (this means that the XPath <code>xs:string</code> value is converted to a wrapped Java object
2092
        of class <code>java.lang.String</code>).</p>
2093

    
2094
      <p>In Saxon 9.4 and earlier releases, a wrapped Java object was considered to be an atomic
2095
        value (in the XDM type hierarchy, the type representing <code>java.lang.Object</code> was a
2096
        peer of primitive types such as <code>xs:string</code> and <code>xs:boolean</code>). In Saxon
2097
        9.5, this changed so that wrapped objects are a fourth subtype of <code>item()</code>, at
2098
        the same level in the type hierarchy as nodes, atomic values, and function items. Atomizing
2099
        a wrapped Java object produces an instance of <code>xs:string</code> containing the
2100
        result of the <code>toString()</code> method applied to the underlying object.</p>
2101
    </section>
2102
  </section>
2103
  <section id="function-result" title="Converting the Result of a Java Extension Function">
2104
    <h1>Converting Java values to XDM values</h1>
2105

    
2106

    
2107
    <p>This section explains how the value returned by a Java extension function is converted to an
2108
      XPath value. The same rules are used in converting a Java object supplied as a parameter to a
2109
      stylesheet or query in cases where the API defines no particular rules (for example, these rules 
2110
      apply to the second argument of the
2111
      <code>javax.xml.transform.Transformer.setParameter()</code> method, and to the result of the 
2112
      <code>javax.xml.xpath.XPathVariableResolver.resolveVariable() method</code>; but not to methods
2113
      like <code>javax.xml.xquery.XQDataSource.createItemFromObject()</code> where the specification defines
2114
    specific conversion rules.)</p>
2115

    
2116
    <p>The Java value is converted to an XPath value as follows.</p>
2117
    <ul>
2118
      <li>
2119
        <p>In the case of a method returning void, then:</p>
2120
        <ul>
2121
          <li>If the option <code>?void=this</code> was present in the namespace URI of the function name, and the
2122
            method is an instance-level (non-static) method, then the return value is the value of the first argument,
2123
            that is, the Java object to which the method was applied, wrapped as an external Java object. (This option
2124
            can help to make execution of extensions with side-effects more predictable, by explicit chaining of such
2125
            methods in the XPath code.)
2126
          </li>
2127
          <li>Otherwise, the return value is an empty sequence.</li>
2128
        </ul>
2129
      </li>
2130
      <li>
2131
        <p>If the Java value is null, the XPath value is an empty sequence.</p>
2132
      </li>
2133
      <li>
2134

    
2135
        <p>When calling a constructor, the resulting XPath value is of type "wrapped Java object". The
2136
          only way of using this is by passing it to another external function, or by converting it
2137
          to one of the standard XPath data types as described above.</p>
2138

    
2139
        <p>
2140
          <i>Note that calling <code>ArrayList.new()</code> will result in a wrapped
2141
              <code>ArrayList</code> object. By constrast, calling a method that returns an
2142
              <code>ArrayList</code> will result in an XPath sequence whose items are constructed
2143
            by converting the members of the returned <code>ArrayList</code>.</i>
2144
        </p>
2145
      </li>
2146
      <li>
2147
        <p>If the Java value is a boolean or Boolean, the XPath result is an xs:boolean.</p>
2148
      </li>
2149
      <li>
2150
        <p>If the Java value is a double or Double, the XPath result is an xs:double.</p>
2151
      </li>
2152
      <li>
2153
        <p>If the Java value is a float or Float, the XPath result is an xs:float.</p>
2154
      </li>
2155
      <li>
2156
        <p>If the Java value is an int, short, long, character, or byte, or one of their
2157
          object wrapper equivalents, the XPath result is an instance of the
2158
          corresponding subtype of xs:integer: for example a Java short produces
2159
          an instance of <code>xs:short</code>.</p>
2160
      </li>
2161
      <li>
2162
        <p>If the Java value is a String, the XPath result is an <code>xs:string</code>.
2163
        Unless otherwise specified, Saxon does not actually check that the characters in the
2164
        Java string are legal XML characters.</p>
2165
      </li>
2166
      <li>
2167
        <p>If the Java value is an instance of the Saxon class <a class="javalink"
2168
            href="net.sf.saxon.om.NodeInfo">net.sf.saxon.om.NodeInfo</a> (a node in a Saxon tree),
2169
          the XPath value will be a sequence containing a single node.</p>
2170
      </li>
2171
      <li>
2172
        <p>If the Java value is an instance of <code>javax.xml.transform.Source</code> (other
2173
          than a <code>NodeInfo</code>), a tree is built from the specified <code>Source</code>
2174
          object, and the XPath result is the root node of this tree.</p>
2175
      </li>
2176
      <li>
2177
        <p>If the Java value is an instance of the Saxon class <a class="javalink"
2178
          href="net.sf.saxon.om.Sequence"
2179
          >net.sf.saxon.om.Sequence</a>, the value is used unchanged.</p>
2180
      </li>
2181
      <li>
2182
        <p>If the Java value is an instance of the Saxon class <a class="javalink"
2183
            href="net.sf.saxon.s9api.XdmValue"
2184
          >net.sf.saxon.s9api.XdmValue</a>, (including its subclasses such as <a class="javalink"
2185
            href="net.sf.saxon.s9api.XdmAtomicValue"
2186
            >net.sf.saxon.s9api.XdmAtomicValue</a> and <a class="javalink"
2187
              href="net.sf.saxon.s9api.XdmNode"
2188
              >net.sf.saxon.s9api.XdmNode</a>) the returned value is used unchanged.</p>
2189
        <aside><p>If you want to pass a map or array, it's best to do explicit construction
2190
        of an <code>XdmMap</code> or <code>XdmArray</code> object using the static factory
2191
        methods provided by these classes.</p></aside>
2192
      </li>
2193
      <li>
2194
        <p>If the returned value is is an instance of the Saxon class <a class="javalink"
2195
            href="net.sf.saxon.om.SequenceIterator">net.sf.saxon.om.SequenceIterator</a> (an
2196
          iterator over a sequence), the XPath value will be the sequence represented by this
2197
          iterator. The iterator should be positioned at its start position, and it will normally 
2198
          be consumed, unless for some reason the result can be obtained without consuming the iterator.</p>
2199
      </li>
2200
      <li>
2201
        <p>If the returned value is an instance of the Java class <code>java.util.Collection</code>,
2202
          or if it is an array, the XPath value will be the sequence represented by the contents of
2203
          this <code>Collection</code> or array. The members of the collection or array will each be
2204
          converted to an XPath value, as if each member was supplied from a separate function call.
2205
          An error is reported if the result contains a list or array nested within another list or
2206
          array. The contents of the list or array are copied immediately on return from the
2207
          function, so the original <code>List</code> or array object itself may be safely
2208
          re-used.</p>
2209
        <p>There is an exception to this rule where the return type is defined as <code>byte[]</code>.
2210
        Partly for historical reasons, and partly to reflect the fact that a <code>byte[]</code> array
2211
        is often used to represent binary data in the form of a sequence of octets, a <code>byte[]</code>
2212
        value is converted to a sequence of <code>xs:unsignedByte</code> items, each in the range 0..255.</p>
2213
        <aside><p>Java collections and arrays are converted to XDM sequences, never to XDM arrays.
2214
          If you want to pass an XDM array, it's best to construct it explicitly using the static factory
2215
          method <code>XdmArray.makeArray()</code>.</p></aside>
2216
      </li>
2217
      <li>
2218
        <p>If the returned value is a DOM Node, and it is recognized as a wrapper around a Saxon
2219
          node, then the node is unwrapped and the underlying Saxon node is returned. If the
2220
          returned value is some other kind of DOM Node, then a Saxon wrapper is added. (This is an
2221
          imperfect solution, since it can lead to problems with node identity and document order.)
2222
        </p>
2223
      </li>
2224
      <li>
2225
        <p>If the returned value is a DOM <code>NodeList</code>, the list of nodes is returned as a
2226
          Saxon node-set. Each node is handled in the same way as a Node that is returned directly
2227
          as the result.</p>
2228
      </li>
2229
      <li>
2230
        <p>If the result is any other Java object (including null), it is returned as a "wrapped
2231
          Java object". It is also possible to force the result to be returned as a wrapped Java
2232
        object by making the function call in the initializer of a variable with an appropriate type
2233
        declaration. The required type for a wrapped object of Java class <code>java.util.Map</code>
2234
        is written using the QName <code>jt:java.util.Map</code>, where the namespace prefix
2235
          <code>jt</code> represents the namespace <code>http://saxon.sf.net/java-type</code>.</p>
2236
      </li>
2237
    </ul>
2238
  </section>
2239
  <section id="exceptions" title="Handling exceptions in reflexive extension functions">
2240
    <h1>Handling exceptions in reflexive extension functions</h1>
2241

    
2242

    
2243
    <p>If a Java extension function throws an exception, the exception can be caught using the
2244
      try/catch facilities in XQuery 3.0 and XSLT 3.0.</p>
2245

    
2246
    <p>The exception triggers a dynamic error, whose details are derived from the exception
2247
      details:</p>
2248

    
2249
    <ul>
2250
      <li>
2251
        <p>The error code (<code>err:code</code>) is a QName whose namespace URI is
2252
            <code>http://saxon.sf.net/java-type</code> and whose local name is the class name of
2253
          the exception type, for example <code>java.net.URISyntaxException</code>.</p>
2254
      </li>
2255

    
2256
      <li>
2257
        <p>The error description (<code>err:description</code>) includes the content of the exception
2258
          message, with a prefix to identify the extension function that was called.</p>
2259
      </li>
2260

    
2261
      <li>
2262
        <p>The error object (<code>err:value</code>) is the wrapped Java object whose method was
2263
          being invoked in the case of an instance method, or the wrapped Java Class object in the
2264
          case of a static method or constructor.</p>
2265
      </li>
2266
    </ul>
2267

    
2268
    <p>Note that this applies to cases where the extension function is successfully called, and the
2269
      called function throws an exception. Failures to invoke the extension function are mapped to
2270
      Saxon error codes and the original Java exception is not directly available.</p>
2271
  </section>
2272
  </section>
2273
  <section id="dotnetextensions" title="Writing reflexive extension functions for .NET">
2274
    <h1>Writing reflexive extension functions for .NET</h1>
2275

    
2276
    <aside>Reflexive extension functions involve dynamic loading of assemblies, which can be tricky
2277
      to get working. Also, they aren't supported under Saxon-HE. Consider using <a class="bodylink"
2278
        href="../integratedfunctions">integrated extension functions</a> instead.</aside>
2279

    
2280
    <p>On the .NET platform extension functions may be implemented in any .NET language (the
2281
      examples here assume C#).</p>
2282
    <aside>Queries and stylesheets running on the .NET platform may also call Java extension
2283
      functions, provided the Java class is part of the standard library implemented in the OpenJDK
2284
      DLL, or in Saxon itself. For calling conventions, see <a class="bodylink" href="../functions"
2285
        >Writing extension functions in Java</a>. If you want to write your own extensions in Java,
2286
      you will need to compile them to .NET assemblies using IKVMC.</aside>
2287

    
2288
    <p>An extension function is invoked using a name such as <code>prefix:localname()</code>. The
2289
      prefix must be the prefix associated with a namespace declaration that is in scope. The
2290
      namespace URI is used to identify a .NET class, and the local name is used to identify a
2291
      method, property, or constructor within the class.</p>
2292

    
2293
    <p>
2294
      <strong>The command line option <code>-TJ</code> is useful for debugging the loading of .NET extensions. It
2295
        gives detailed information about the methods that are examined for a possible
2296
        match.</strong>
2297
    </p>
2298

    
2299
    <p>The basic form of the namespace URI is <code>clitype:</code> followed by the fully-qualified type name
2300
      (for example <code>xmlns:env="clitype:System.Environment"</code>). This form works for system
2301
      classes and classes in a loaded <dfn>assembly</dfn>. If an assembly needs to be loaded, extra
2302
      information can be given in the form of URI query parameters. For example
2303
        <code>xmlns:env="clitype:Acme.Payroll.Employee?asm=payroll;ver=4.12.0.0"</code>.</p>
2304

    
2305
    <p>The parameters that are recognized are:</p>
2306
    <table>
2307
      <tr>
2308
        <td>
2309
          <p><strong>Keyword</strong></p>
2310
        </td>
2311
        <td>
2312
          <p><strong>Value</strong></p>
2313
        </td>
2314
      </tr>
2315
      <tr>
2316
        <td>
2317
          <p>asm</p>
2318
        </td>
2319
        <td>
2320
          <p>The simple name of the assembly</p>
2321
        </td>
2322
      </tr>
2323
      <tr>
2324
        <td>
2325
          <p>ver</p>
2326
        </td>
2327
        <td>
2328
          <p>The version number, up to four integers separated by periods</p>
2329
        </td>
2330
      </tr>
2331
      <tr>
2332
        <td>
2333
          <p>loc</p>
2334
        </td>
2335
        <td>
2336
          <p>The culture (locale), for example "en-US"</p>
2337
        </td>
2338
      </tr>
2339
      <tr>
2340
        <td>
2341
          <p>sn</p>
2342
        </td>
2343
        <td>
2344
          <p>The public key token of the assembly's strong name, as 16 hex digits</p>
2345
        </td>
2346
      </tr>
2347
      <tr>
2348
        <td>
2349
          <p>from</p>
2350
        </td>
2351
        <td>
2352
          <p>The location of the assembly, as a URI</p>
2353
        </td>
2354
      </tr>
2355
      <tr>
2356
        <td>
2357
          <p>partialname</p>
2358
        </td>
2359
        <td>
2360
          <p>The partial name of the assembly (as supplied to
2361
              <code>Assembly.LoadWithPartialName()</code>)</p>
2362
        </td>
2363
      </tr>
2364
    </table>
2365

    
2366
    <p>If the <code>from</code> keyword is present, the other parameters are ignored. The value of
2367
        <code>from</code> must be the URI of the DLL to be loaded: if it is relative, it is relative
2368
      to the base URI of the expression containing the call to the extension function (regardless of
2369
      where the namespace is actually declared).</p>
2370

    
2371
    <p>If the <code>partialname</code> keyword is present, the assembly is loaded (if possible)
2372
      using <code>Assembly.LoadWithPartialName()</code> and the other parameters are ignored.</p>
2373

    
2374
    <p>If the assembly is a library DLL in the global assembly cache, use the <code>gacutil
2375
        /l</code> command to list the assemblies present in the GAC, and to extract the required
2376
      version, culture, and strong name attributes. For example, suppose you want to call a static
2377
      method <code>disappear()</code> in class <code>Conjurer</code> in namespace
2378
        <code>Magic.Circle</code>, and this class is contained in an assembly <code>Magic</code>
2379
      listed as:</p>
2380

    
2381
    <p>
2382
      <code>Magic, Version=7.2.2200.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a4b,
2383
        Custom=null</code>
2384
    </p>
2385

    
2386
    <p>Then the URI you would use to identify this class is
2387
        <code>clitype:Magic.Circle.Conjurer?asm=Magic;ver=7.2.2200.0;sn=b03f5f7f11d50a4b</code>, and
2388
      an actual call of the function might take the form:</p>
2389
    <samp><![CDATA[<xsl:value-of select="m:disappear()"
2390
     xmlns:m="clitype:Magic.Circle.Conjurer?asm=Magic;ver=7.2.2200.0;sn=b03f5f7f11d50a4b"/> 
2391
]]></samp>
2392
    <h2 class="subtitle">Tips for Dynamic Loading in .NET</h2>
2393

    
2394
    <p>Here are some hints and tips that might help you to get dynamic loading working under
2395
      .NET.</p>
2396
    
2397
    <p>First, do you actually need to use dynamic loading? An easier approach is to link the code
2398
      containing the extension functions into your C# or VB.NET code and pass Saxon a reference to
2399
      the containing type. This can be done with:</p>
2400
    
2401
    <samp><![CDATA[Processor proc = new Processor(true);
2402
proc.BindExtensions("http://example.com", typeof(Extension.Functions));
2403
]]></samp>
2404
    
2405
    <p>If you do this, then extension functions using the namespace URI
2406
      <code>"http://example.com"</code> will be found in the class/type
2407
      <code>Extension.Functions</code> without any need for dynamic loading.</p>
2408

    
2409
    <p><strong>The command line option <code>-TJ</code> is useful for <dfn>debugging</dfn> the loading of .NET
2410
        extensions. It gives detailed information about the methods that are examined for a possible
2411
        match. The equivalent in the API is to set the Processor property
2412
          <code>"http://saxon.sf.net/feature/trace-external-functions"</code></strong>.</p>
2413

    
2414
    <p>First decide whether you want to load the assembly (DLL) containing the extension functions
2415
      from local filestore or from the <dfn>Global Assembly Cache</dfn>.</p>
2416

    
2417
    <p>If you want to load it from the <dfn>GAC</dfn> you must compile the assembly with a
2418
        <dfn>strong name</dfn>, and deploy it to the GAC. For advice on doing this, see <a
2419
        href="http://support.microsoft.com/kb/324168" class="bodylink"
2420
        >http://support.microsoft.com/kb/324168</a>. (In .NET framework 2.0 there was a handy
2421
      Control Panel tool for this, but it is no longer available for security reasons.)</p>
2422

    
2423
    <p>For local loading, the following techniques work:</p>
2424
    <ul>
2425
      <li>
2426
        <p>If the query or transformation is controlled from a user-written application in C# or
2427
          another .NET language, include the extension function implementation in the same assembly
2428
          as the controlling application, or in another assembly which is statically referenced from
2429
          the controlling application. In this case it is only necessary to name the assembly, for
2430
          example <code>&lt;e att="{my:ext()}"
2431
            xmlns:my="clitype:Namespace.ClassName?asm=Samples"/&gt;</code>.
2432
        </p>
2433
      </li>
2434
      <li>
2435
        <p>Another approach is to copy the assembly into the same directory as the controlling
2436
          application or, if using the Saxon <code>Query</code> or <code>Transform</code> command
2437
          from the command line, the directory containing the Saxon <code>Query.exe</code> and
2438
            <code>Transform.exe</code> executables. Again in this case it should simply be necessary
2439
          to give the assembly name as above.</p>
2440
      </li>
2441
      <li>
2442
        <p>As an alternative, an assembly held in local filestore can be loaded by reference to the
2443
          file, for example
2444
            <code>xmlns:my="clitype:Namespace.ClassName?from=file:///c:/lib/Samples.dll"</code>. The
2445
          URI can be given as an absolute URI, or as a relative URI which is interpreted relative to
2446
          the base URI of the expression containing the function call.</p>
2447
      </li>
2448
    </ul>
2449

    
2450
    <p>For production running it is probably more appropriate to place the assembly holding
2451
      extension functions in the global assembly cache. It can then generally be referenced in one
2452
      of two ways:</p>
2453
    <ul>
2454
      <li>
2455
        <p>By partial name, for example
2456
            <code>xmlns:my="clitype:Namespace.ClassName?partialname=Samples"</code>
2457
        </p>
2458
      </li>
2459
      <li>
2460
        <p>By fully-qualified name, for example
2461
            <code>xmlns:my="clitype:Namespace.ClassName?asm=Samples;ver=3.0.0.1;loc=neutral;sn=e1f2a3b4e1f2a3b4"</code>
2462
        </p>
2463
      </li>
2464
    </ul>
2465

    
2466
    <p>The following example shows how to call system methods in the .NET framework:</p>
2467
    <samp><![CDATA[<out xmlns:Environment="clitype:System.Environment" 
2468
     xmlns:OS="clitype:System.OperatingSystem">
2469
    <xsl:variable name="os" select="Environment:OSVersion()"/>
2470
    <v platform="{OS:Platform($os)}" version="{OS:Version($os)}"/>
2471
</out>
2472
]]></samp>
2473
    <h2 class="subtitle">Identifying and Calling Specific Methods</h2>
2474

    
2475
    <p>The rest of this section considers how a .NET method, property, or constructor is identified.
2476
      This decision (called binding) is always made at the time the XPath expression is
2477
      compiled.</p>
2478

    
2479
    <p>There are three cases to consider: static methods, constructors, and instance-level methods.
2480
      In addition, a public property in a class is treated as if it were a zero-argument method, so
2481
      static properties can be accessed in the same way as static methods, and instance-level
2482
      properties in the same way as instance-level methods. (Note that the property name is used
2483
      directly: it is not prefixed by "get".)</p>
2484
    <nav>
2485
      <ul/>
2486
    </nav>
2487
    
2488
    <p>In XSLT, the system function <code>function-available(String name)</code> returns true if
2489
      there appears to be a method available with the right name. The function also has an optional
2490
      second argument to test whether there is a method with the appropriate number of arguments.
2491
      However, it is not possible to test whether the arguments are of appropriate types. If the
2492
      function name is "new" it returns true so long as the class is not an abstract class or
2493
      interface, and so long as it has at least one constructor.</p>
2494

    
2495
    <section id="staticmethods.net" title="Calling Static Methods in a .NET Class">
2496
      <h1>Calling Static Methods in a .NET Class</h1>
2497

    
2498

    
2499
      <p><strong>Static methods</strong> can be called directly. The localname of the function must
2500
        match the name of a public static method in this class. The names match if they contain the
2501
        same characters, excluding hyphens and forcing any character that follows a hyphen to
2502
        upper-case. For example the XPath function call <code>To-string()</code> matches the .NET
2503
        method <code>ToString()</code>; but the function call can also be written as
2504
          <code>ToString()</code> if you prefer.</p>
2505

    
2506
      <p>If there are several methods in the class that match the localname, and that have the
2507
        correct number of arguments, then the system attempts to find the one that is the best fit
2508
        to the types of the supplied arguments: for example if the call is <code>f(1,2)</code> then
2509
        a method with two <code>int</code> arguments will be preferred to one with two
2510
          <code>float</code> arguments. The rules for deciding between methods are quite complex.
2511
        Essentially, for each candidate method, Saxon calculates the "distance" between the types of
2512
        the supplied arguments and the .NET class of the corresponding argument in the method's
2513
        signature, using a set of tables. For example, the distance between the XPath
2514
        data type <code>xs:integer</code> and the .NET type <code>long</code> is very small, while
2515
        the distance between an XPath <code>xs:integer</code> and a .NET <code>bool</code> is much
2516
        larger. If there is one candidate method where the distances of all arguments are
2517
        less-than-or-equal-to the distances computed for other candidate methods, and the distance
2518
        of at least one argument is smaller, then that method is chosen.</p>
2519

    
2520
      <p>If there are several methods with the same name and the correct number of arguments, but
2521
        none is preferable to the others under these rules, an error is reported: the message
2522
        indicates that there is more than one method that matches the function call.</p>
2523

    
2524
      <p>This binding is carried out statically, using the static types of the supplied arguments,
2525
        not the dynamic types obtained when the arguments are evaluated. If there is insufficient
2526
        static type information to distinguish the candidate methods, an error is reported. You can
2527
        supply additional type information using the <code>treat as</code> expression, or by
2528
        casting. Often it is enough simply to declare the types of the variables used as arguments
2529
        to the function call. <i>Note however that if the argument can be evaluated at compile time, 
2530
        then the type of the actual value will be used in preference to the declared type. 
2531
        This is particularly relevant if the argument evaluates to an empty sequence. 
2532
        If you need to invoke an overloaded method in this way, use an argument expression 
2533
        that cannot be evaluated at compile time.</i></p>
2534

    
2535
      <p>For example (in XSLT):</p>
2536
      <samp><![CDATA[<xsl:value-of select="math:Sqrt($arg)" xmlns:math="clitype:System.Math"/>
2537
]]></samp>
2538

    
2539
      <p>This will invoke the static method <code>System.Math#Sqrt()</code>, applying it to the
2540
        value of the variable <code>$arg</code>, and copying the value of the square root of
2541
          <code>$arg</code> to the result tree. The value of $arg must be convertible to a double
2542
        under the same rules as for a native XPath function call.</p>
2543

    
2544
      <p>Similarly (in XQuery):</p>
2545
      <samp><![CDATA[<a xmlns:double="type:System.Double"/> 
2546
                              {double:MaxValue()} </a>
2547
]]></samp>
2548

    
2549
      <p>This will output the value of the static field <code>System.Double#MaxValue</code>. (In
2550
        practice, it is better to declare the namespace in the query prolog, or predeclare it using
2551
        the API, because it will then not be copied to the result tree.)</p>
2552

    
2553
      <p>A static method called as an extension function may have an extra first argument of type <a
2554
          class="javalink" href="net.sf.saxon.expr.XPathContext">net.sf.saxon.expr.XPathContext</a>.
2555
        This argument is not supplied by the calling XPath or XQuery code, but by Saxon itself. The
2556
          <code>XPathContext</code> object provides methods to access many internal Saxon resources,
2557
        the most useful being <code>getContextItem()</code> which returns the context item from the
2558
        dynamic context. The class <code>net.sf.saxon.expr.XPathContext</code> is in the assembly
2559
        <code>saxon-he-10.#.dll</code>, and the module containing the code of the extension function will
2560
        therefore need to contain a reference to that DLL. The class itself is written in Java, and
2561
        is documented in the Javadoc documentation. The <code>XPathContext</code> object is
2562
        available with static or instance-level methods, but not with constructors.</p>
2563

    
2564
      <p>The following example shows a function that obtains the host language from the Saxon
2565
        evaluation context:</p>
2566
      <samp><![CDATA[public static string HostLanguage(net.sf.saxon.expr.XPathContext context)
2567
{
2568
    int lang = context.getController().getExecutable().getHostLanguage();
2569
    if (lang == net.sf.saxon.Configuration.XQUERY)
2570
    {
2571
        return "XQuery";
2572
    }
2573
    else if (lang == net.sf.saxon.Configuration.XSLT)
2574
    {
2575
        return "XSLT";
2576
    }
2577
    else if (lang == net.sf.saxon.Configuration.XPATH)
2578
    {
2579
        return "XPath";
2580
    }
2581
    else
2582
    {
2583
        return "unknown";
2584
    }
2585
}]]></samp>
2586

    
2587
      <p>If this method appears in class <code>com.example.code.Utils</code>, then it can be
2588
        accessed using the following code in XSLT:</p>
2589
      <samp><![CDATA[<xsl:value-of select="nd:HostLanguage()" 
2590
    xmlns:nd="java:com.example.code.Utils"/>]]></samp>
2591

    
2592
      <p>or the following in XQuery:</p>
2593
      <samp><![CDATA[<line xmlns:nd="java:com.example.code.Utils">
2594
    { nd:HostLanguage() }
2595
</line>]]></samp>
2596
    </section>
2597

    
2598
    <section id="constructors.net" title="Calling .NET Constructors">
2599
      <h1>Calling .NET Constructors</h1>
2600

    
2601

    
2602
      <p><strong>.NET class constructors</strong> are called by using the function named
2603
          <code>new()</code>. If there are several constructors, then again the system tries to find
2604
        the one that is the best fit, according to the types of the supplied arguments. The result
2605
        of calling <code>new()</code> is an XPath value whose type is denoted by a QName whose local
2606
        name is the actual .NET class (for example <code>System.Data.SqlClient.SqlConnection</code>
2607
        or <code>System.Collections.ArrayList</code>) and whose namespace URI is
2608
          <code>http://saxon.sf.net/clitype</code>. The only things that can be done with a wrapped
2609
        .NET Object are to assign it to a variable, to pass it to an extension function, and to
2610
        convert it to a string or boolean, using the rules given below.</p>
2611

    
2612
      <p>The use of external object types in namespace <code>http://saxon.sf.net/clitype</code>
2613
        reflects the .NET type hierarchy. For example, if a variable is declared to accept a type of
2614
          <code>net:System.Collections.IList</code>, then a value of type
2615
          <code>net:System.Collections.ArrayList</code> will be accepted, but a value of type
2616
          <code>net:System.Collections.HashTable</code> will not.</p>
2617
    </section>
2618

    
2619
    <section id="instance-methods.net" title="Calling .NET Instance-Level Methods">
2620
      <h1>Calling .NET Instance-Level Methods</h1>
2621

    
2622

    
2623
      <p><strong>Instance-level methods</strong> (that is, non-static methods) are called by
2624
        supplying an extra first argument of type <code>external .NET object</code> which is the
2625
        object on which the method is to be invoked. An external .NET Object may be created by
2626
        calling an extension function (e.g. a constructor) that returns an object; it may also be
2627
        passed to the query or stylesheet as the value of a global parameter. Matching of method
2628
        names is done as for static methods. If there are several methods in the class that match
2629
        the localname, the system again tries to find the one that is the best fit, according to the
2630
        types of the supplied arguments.</p>
2631

    
2632
      <p>For example, the following XSLT stylesheet prints the operating system name and
2633
        version.</p>
2634
      <samp><![CDATA[<xsl:stylesheet version="2.0" 
2635
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
2636
                                
2637
<xsl:template name="main">
2638
  <out xmlns:env="clitype:System.Environment" xmlns:os="clitype:System.OperatingSystem">
2639
    <xsl:variable name="os" select="env:OSVersion()"/>
2640
      <v platform="{os:Platform($os)}" version="{os:Version($os)}"/>
2641
  </out>  
2642
</xsl:template>
2643
</xsl:stylesheet>]]></samp>
2644

    
2645
      <p>The equivalent in XQuery is:</p>
2646
      <samp><![CDATA[declare namespace env="clitype:System.Environment";
2647
declare namespace os="clitype:System.OperatingSystem";
2648
let $os := env:OSVersion() return
2649
<v platform="{os:Platform($os)}" version="{os:Version($os)}"/>
2650
]]></samp>
2651

    
2652
      <p>As with static methods, an instance-level .NET method called as an extension function may
2653
        have an extra first argument of class <a class="javalink"
2654
          href="net.sf.saxon.expr.XPathContext">net.sf.saxon.expr.XPathContext</a>. This argument is
2655
        not supplied by the calling XPath or XQuery code, but by Saxon itself. The
2656
          <code>XPathContext</code> object provides methods to access many internal Saxon resources,
2657
        the most useful being <code>getContextItem()</code> which returns the context item from the
2658
        dynamic context.</p>
2659

    
2660
      <p>If any exceptions are thrown by the method, or if a matching method cannot be found,
2661
        processing of the stylesheet will be abandoned. If the tracing option <code>-TJ</code> has been set on
2662
        the command line, a full stack trace will be output. The exception will be wrapped in a
2663
          <code>TransformerException</code> and passed to any user-specified
2664
          <code>ErrorListener</code> object, so the <code>ErrorListener</code> can also produce
2665
        extra diagnostics.</p>
2666
    </section>
2667
  
2668
  <section id="converting-args.net" title="Converting Arguments to .NET Extension Functions">
2669
    <h1>Converting Arguments to .NET Extension Functions</h1>
2670

    
2671

    
2672
    <p>This section describes how XPath values supplied in a call to a .NET extension function are
2673
      converted to .NET values.</p>
2674
    <nav>
2675
      <ul/>
2676
    </nav>
2677

    
2678
    <section id="converting-atomic.net" title="Converting Atomic Values and Sequences">
2679
      <h1>Converting Atomic Values and Sequences</h1>
2680

    
2681

    
2682
      <p>The following conversions are supported between the static type of the supplied value of
2683
        the argument, and the declared .NET type of the argument. The mappings are given in order of
2684
        preference; a type that appears earlier in the list has smaller "conversion distance" than
2685
        one appearing later. These priorities are used to decide which method to call when the class
2686
        has several methods of the same name. Simple classes (such as boolean) are acceptable
2687
        wherever the corresponding wrapper class (Boolean) is allowed. Class names shown in italics
2688
        are Saxon-specific classes.</p>
2689

    
2690
      <p>If the value is a <i>.NET external object</i> (typically the result of a call to another
2691
        extension function), then the underlying .NET object is passed to the method. An error will
2692
        occur if it is the wrong .NET type.</p>
2693

    
2694
      <p>If the required type is one of the types used in the <code>Saxon.Api</code> namespace to
2695
        represent XPath values (for example <a class="javalink" href="Saxon.Api.XdmValue">XdmValue</a>, 
2696
        <a class="javalink" href="Saxon.Api.XdmNode">XdmNode</a>,
2697
          <a class="javalink" href="Saxon.Api.XdmAtomicValue">XdmAtomicValue</a>), 
2698
        then the value is converted to an instance of this class and
2699
        passed over unchanged. If the expected type is <code>XdmAtomicValue</code> and the supplied
2700
        value is a node, the node will be atomized (this must result in a single atomic value). Use
2701
        of types such as <code>XdmValue</code> is available only when the query or transformation is
2702
        invoked using the .NET API, it does not work when running from the command line.</p>
2703

    
2704
      <p>If the static type of the supplied value allows a sequence of more than one item, then
2705
        Saxon looks for a method that expects a <a class="javalink" href="net.sf.saxon.om.SequenceIterator">net.sf.saxon.om.SequenceIterator</a>, a
2706
        <a class="javalink" href="net.sf.saxon.om.Sequence">net.sf.saxon.om.Sequence</a>, an <code>ICollection</code> or an array, in that
2707
        order. (The first two classes are Saxon-specific.) In all these cases except the last, the
2708
        item type of the supplied value plays no role.</p>
2709

    
2710
      <p>Nodes in the supplied sequence are atomized only if the .NET method requires an atomic type
2711
        such as an integer or string. If the method requires an <code>ICollection</code>, then the contents of
2712
        the sequence will be supplied unchanged. The objects in the list will typically be Saxon
2713
          <a class="javalink" href="net.sf.saxon.om.Item">net.sf.saxon.om.Item</a> objects. (Saxon
2714
        does not yet recognize the generic types in .NET 2.0, which allow the item type of a
2715
        collection to be declared.) If atomization is required, you can force it by calling the
2716
          <code>data()</code> function.</p>
2717

    
2718
      <p>If the required type is an array, Saxon will attempt to create an array of the required
2719
        type. This will not always succeed, for example if the array has type <code>X[]</code> where
2720
        <code>X</code> is an interface rather than a concrete class. If it is an array of items or nodes, the
2721
        nodes in the supplied sequence will be inserted into the array directly; if it is an array
2722
        of a type such as integer or double, the sequence will first be atomized.</p>
2723

    
2724
      <p>If the supplied value is a singleton (a sequence of one item) then the type of that item is
2725
        decisive. If it is a sequence of length zero or more than one, then the general rules for a
2726
        sequence are applied, and the types of the items within the sequence are irrelevant.</p>
2727

    
2728
      <p>If the supplied value contains more than one item and only a single item is expected, an error
2729
        is reported. There is no implicit extraction of the first value (as happened in earlier
2730
        releases).</p>
2731
      <table>
2732
        <tr>
2733
          <td>
2734
            <p>
2735
              <strong>Supplied type</strong>
2736
            </p>
2737
          </td>
2738
          <td>
2739
            <p>
2740
              <strong>Required type</strong>
2741
            </p>
2742
          </td>
2743
        </tr>
2744
        <tr>
2745
          <td>
2746
            <p>xs:string</p>
2747
          </td>
2748
          <td>
2749
            <p>
2750
              <i>StringValue</i>, String</p>
2751
          </td>
2752
        </tr>        
2753
        <tr>
2754
          <td>
2755
            <p>xs:boolean</p>
2756
          </td>
2757
          <td>
2758
            <p>
2759
              <i>BooleanValue</i>, Boolean</p>
2760
          </td>
2761
        </tr>
2762
        <tr>
2763
          <td>
2764
            <p>xs:float</p>
2765
          </td>
2766
          <td>
2767
            <p>
2768
              <i>FloatValue</i>, Single, Double</p>
2769
          </td>
2770
        </tr>
2771
        <tr>
2772
          <td>
2773
            <p>xs:double</p>
2774
          </td>
2775
          <td>
2776
            <p>
2777
              <i>DoubleValue</i>, Double</p>
2778
          </td>
2779
        </tr>
2780
        <tr>
2781
          <td>
2782
            <p>xs:decimal</p>
2783
          </td>
2784
          <td>
2785
            <p>
2786
              <i>DecimalValue</i>, Decimal, Double, Single</p>
2787
          </td>
2788
        </tr>        
2789
        <tr>
2790
          <td>
2791
            <p>xs:integer</p>
2792
          </td>
2793
          <td>
2794
            <p>
2795
              <i>IntegerValue</i>, Decimal, Int64, Int32, Int16, Double, Single</p>
2796
          </td>
2797
        </tr>
2798
        <tr>
2799
          <td>
2800
            <p>xs:date, xs:gDay, xs:gMonthDay, xs:gMonth, xs:gYearMonth, xs: gYear</p>
2801
          </td>
2802
          <td>
2803
            <p>
2804
              <i>DateValue</i>, DateTime</p>
2805
          </td>
2806
        </tr>
2807
        <tr>
2808
          <td>
2809
            <p>xs:dateTime</p>
2810
          </td>
2811
          <td>
2812
            <p>
2813
              <i>DateTimeValue</i>, DateTime</p>
2814
          </td>
2815
        </tr>
2816
        <tr>
2817
          <td>
2818
            <p>xs:time</p>
2819
          </td>
2820
          <td>
2821
            <p>
2822
              <i>TimeValue</i>, DateTime</p>
2823
          </td>
2824
        </tr>
2825
        <tr>
2826
          <td>
2827
            <p>xs:duration, xs:yearMonthDuration, xs:dayTimeDuration</p>
2828
          </td>
2829
          <td>
2830
            <p>
2831
              <i>DurationValue</i>
2832
            </p>
2833
          </td>
2834
        </tr>        
2835
        <tr>
2836
          <td>
2837
            <p>xs:hexBinary</p>
2838
          </td>
2839
          <td>
2840
            <p>
2841
              <i>HexBinaryValue</i></p>
2842
          </td>
2843
        </tr>
2844
        <tr>
2845
          <td>
2846
            <p>xs:base64Binary</p>
2847
          </td>
2848
          <td>
2849
            <p>
2850
              <i>Base64BinaryValue</i></p>
2851
          </td>
2852
        </tr>
2853
        <tr>
2854
          <td>
2855
            <p>xs:anyURI</p>
2856
          </td>
2857
          <td>
2858
            <p>
2859
              <i>AnyURIValue</i>, Uri, String</p>
2860
          </td>
2861
        </tr>
2862
        <tr>
2863
          <td>
2864
            <p>xs:QName</p>
2865
          </td>
2866
          <td>
2867
            <p>
2868
              <i>QNameValue</i>, System.Xml.XmlQualifiedName</p>
2869
          </td>
2870
        </tr>            
2871
        <!--<tr>
2872
          <td>
2873
            <p>node</p>
2874
          </td>
2875
          <td>
2876
            <p>
2877
              <i>SingletonNodeSet</i>, NodeList, (Element, Attr, Document, DocumentFragment,
2878
              Comment, Text, ProcessingInstruction, CharacterData), Node, Boolean, Byte, Character,
2879
              Double, Float, Integer, Long, Short, (String, CharSequence), Object</p>
2880
          </td>
2881
        </tr>
2882
        <tr>
2883
          <td>
2884
            <p>sequence</p>
2885
          </td>
2886
          <td>
2887
            <p>
2888
              <i>SequenceIterator</i>, <i>SequenceValue</i>, List, NodeList, <i>NodeInfo</i>, Node,
2889
              (String, CharSequence), Boolean, Byte, Character, Double, Float, Integer, Long, Short,
2890
              Object</p>
2891
          </td>
2892
        </tr>-->      
2893
      </table>  
2894

    
2895
      <p>Saxon tries to select the appropriate method based on the <i>static type</i> of the
2896
        arguments to the function call. If there are several candidate methods, and there is
2897
        insufficient information available to decide which is most appropriate, an error is
2898
        reported. The remedy is to cast the arguments to a more specific type.</p>
2899
    </section>
2900

    
2901
    <section id="converting-node.net" title="Converting Nodes and Sequences of Nodes">
2902
      <h1>Converting Nodes and Sequences of Nodes</h1>
2903

    
2904

    
2905
      <p>If the expected type is a generic collection type, an array of the Saxon class <a
2906
          class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a>, a 
2907
        <a class="javalink" href="net.sf.saxon.om.Sequence">Sequence</a> or a
2908
          <a class="javalink" href="net.sf.saxon.om.SequenceIterator">SequenceIterator</a>, Saxon
2909
        will pass the nodes supplied in the call in their native Saxon representation.</p>
2910

    
2911
      <p>Saxon also recognizes <code>System.Xml.Node</code> and its subtypes. However, calling a
2912
        method that expects an instance if <code>System.Xml.Node</code> will only work if the actual
2913
        node supplied as the argument value is a Saxon-wrapped DOM node, that is (a) the input to
2914
        the stylesheet or query must be supplied in the form of a wrapped DOM, and (b) the external
2915
        function must be called supplying a node obtained from the input document, not some node in
2916
        a temporary tree created in the course of stylesheet or query processing.</p>
2917

    
2918
      <p>If an external function returns an <code>System.Xml.Node</code> then it will be wrapped as
2919
        a Saxon node. This may be expensive if it is done a lot, since each such node will acquire
2920
        its own document wrapper.</p>
2921
    </section>
2922

    
2923
    <section id="converting-wrapped-dotnet" title="Converting Wrapped .NET Objects">
2924
      <h1>Converting Wrapped .NET Objects</h1>
2925

    
2926

    
2927
      <p>Saxon allows an extension function to return an arbitrary .NET object. This will then be
2928
        wrapped as an XPath item, so that it can be held in a variable and passed subsequently as an
2929
        argument to another extension function. This second extension function will see the original
2930
        .NET object minus its wrapper, provided it is declared to expect the appropriate .NET
2931
        class.</p>
2932

    
2933
      <p>A wrapped .NET object may be converted to another data type as follows.</p>
2934
      <ul>
2935
        <li>
2936
          <p>It is converted to a string by using its <code>ToString()</code> method; if the object is null, the
2937
            result is the empty string "".</p>
2938
        </li>
2939
        <li>
2940
          <p>It is converted to a boolean as follows: if it is null, the result is false, otherwise
2941
            it is converted to a string and the result is true if and only if the string is
2942
            non-empty.</p>
2943
        </li>
2944
      </ul>
2945

    
2946
      <p>The type of a wrapped .NET object may be declared in a variable declaration or function
2947
        signature using a type name whose namespace URI is <code>http://saxon.sf.net/clitype</code>, and
2948
        whose local name is the fully qualified name of the .NET class, with any "$" signs replaced
2949
        by hyphens. For example, the <code>sql:connection</code> extension function returns a value
2950
        of type <code>{http://saxon.sf.net/clitype}System.Data.SqlClient.SqlConnection</code>.</p>
2951
    </section>
2952
  </section>
2953
  <section id="function-result.net" title="Converting the Result of a .NET Extension Function">
2954
    <h1>Converting the Result of a .NET Extension Function</h1>
2955

    
2956

    
2957
    <p>This section explains how the value returned by a .NET extension function is converted to an
2958
      XPath value.</p>
2959

    
2960
    <p>The result type of the method is converted to an XPath value as follows.</p>
2961
    <ul>
2962
      <li>
2963
        <p>If the method returns void, the XPath value is an empty sequence.</p>
2964
      </li>
2965
      <li>
2966
        <p>If the method returns null, the XPath value is an empty sequence.</p>
2967
      </li>
2968
      <li>
2969
        <p>If the method is a constructor, the XPath value is of type "wrapped .NET object". The
2970
          only way of using this is by passing it to another external function, or by converting it
2971
          to one of the standard XPath data types as described above.</p>
2972
      </li>
2973
      <li>
2974
        <p>If the returned value is an <a class="javalink" href="Saxon.Api.XdmValue">XdmValue</a> or one of its subclasses such as
2975
            <a class="javalink" href="Saxon.Api.XdmNode">XdmNode</a> or 
2976
          <a class="javalink" href="Saxon.Api.XdmAtomicValue">XdmAtomicValue</a>, then it is used unchanged, after
2977
          unwrapping. (These types are defined in the <code>Saxon.Api</code> namespace.) Note that if the method
2978
          constructs a new <code>XdmNode</code> and returns it, then it must be built using the name pool that is
2979
          in use by the transformation or query, which means in practice that it must be built using
2980
          a <a class="javalink" href="Saxon.Api.DocumentBuilder">DocumentBuilder</a> derived from the same <code>Saxon.Api.Processor</code>.</p>
2981
      </li>
2982
      <li>
2983
        <p>If the returned value is a .NET bool, the XPath result is a boolean.</p>
2984
      </li>
2985
      <li>
2986
        <p>If the returned value is a .NET double, the XPath result is a double.</p>
2987
      </li>
2988
      <li>
2989
        <p>If the returned value is a .NET float, the XPath result is a float.</p>
2990
      </li>
2991
      <li>
2992
        <p>If the returned value is a .NET Int64, Int32, or Int16, or one of their object wrapper
2993
          equivalents, the XPath result is an integer.</p>
2994
      </li>
2995
      <li>
2996
        <p>If the returned value is a .NET string, the XPath result is a string.</p>
2997
      </li>
2998
      <li>
2999
        <p>If the returned value is an instance of the Saxon class
3000
          <a class="javalink" href="net.sf.saxon.om.NodeInfo">net.sf.saxon.om.NodeInfo</a> (a node in a Saxon tree), the XPath value will be
3001
          a sequence containing a single node.</p>
3002
      </li>
3003
      <li>
3004
        <p>If the returned value is an instance of the Saxon class
3005
          <a class="javalink" href="net.sf.saxon.om.Sequence">net.sf.saxon.om.Sequence</a>, the returned value is used unchanged.</p>
3006
      </li>
3007
      <li>
3008
        <p>If the returned value is is an instance of the Saxon class
3009
          <a class="javalink" href="net.sf.saxon.om.SequenceIterator">net.sf.saxon.om.SequenceIterator</a> (an iterator over a sequence), the XPath
3010
          value will be the sequence represented by this iterator. It is essential that this
3011
          iterator properly implements the method <code>getAnother()</code> which returns a new
3012
          iterator over the same sequence of nodes or values, positioned at the start of the
3013
          sequence.</p>
3014
      </li>
3015
      <li>
3016
        <p>If the returned value is an instance of the .NET interface
3017
            <code>System.Collections.IEnumerable</code>, or if it is an array, the XPath value will
3018
          be the sequence represented by the contents of this collection or array. The members of
3019
          the list or array will each be converted to an XPath value, as if each member was supplied
3020
          from a separate function call. An error is reported if the result contains a list or array
3021
          nested within another list or array. The contents of the list or array are copied
3022
          immediately on return from the function, so the original collection or array object itself
3023
          may be safely re-used.</p>
3024
      </li>
3025
      <li>
3026
        <p>If the result is any other .NET object (including null), it is returned as a "wrapped
3027
          .NET object".</p>
3028
      </li>
3029
    </ul>
3030
  </section>
3031
  </section>
3032
  <section id="instructions" title="Writing XSLT extension instructions">
3033
    <h1>Writing XSLT extension instructions</h1>
3034

    
3035

    
3036
    <p>
3037
      <aside>This feature is available in Saxon-PE and Saxon-EE only.<br/>
3038
        User-written extension instructions are not currently supported on the .NET platform.</aside>
3039
    </p>
3040

    
3041
    <p>Saxon implements the element extensibility feature defined in the XSLT standard. This feature
3042
      allows you to define your own instruction types for use in the stylesheet. These instructions
3043
      can be used anywhere within a <i>sequence constructor</i>, for example as a child of
3044
        <code>xsl:template</code>, <code>xsl:if</code>, <code>xsl:variable</code>, or of a literal
3045
      result element.</p>
3046

    
3047
    <p>To implement and use extension instructions, three steps are necessary:</p>
3048

    
3049
    <ol>
3050
      <li>
3051
        <p>There must be a class that implements the interface <a class="javalink"
3052
            href="com.saxonica.xsltextn.ExtensionElementFactory">ExtensionElementFactory</a>, which
3053
          recognizes all the extension elements in a particular namespace and provides the Java code
3054
          to implement them.</p>
3055
      </li>
3056

    
3057
      <li>
3058
        <p>This factory class must be associated with a namespace URI and registered with the <a
3059
            class="javalink" href="net.sf.saxon.Configuration">Configuration</a>, which can be done
3060
          either by calling the method <a class="javalink"
3061
            href="com.saxonica.config.ProfessionalConfiguration#setExtensionElementNamespace"
3062
            >setExtensionElementNamespace(namespace, classname)</a>, or by means of an entry in the
3063
          <a class="bodylink"
3064
            href="/configuration/configuration-file">configuration file</a>.</p>
3065
      </li>
3066
      <li>
3067
        <p>Within the stylesheet, there must be a namespace declaration that binds a prefix to this
3068
          namespace URI, and the prefix must be declared as an extension namespace by means of the
3069
            <code>extension-element-prefixes</code> attribute, typically on the
3070
            <code>xsl:stylesheet</code> element. (A rarely-used alternative is to declare it in the
3071
            <code>xsl:extension-element-prefixes</code> attribute of an enclosing literal result
3072
          element.)</p>
3073
      </li>
3074
    </ol>
3075

    
3076

    
3077

    
3078
    <p>Saxon itself provides a number of stylesheet elements beyond those defined in the XSLT
3079
      specification, including <code>saxon:assign</code>, <code>saxon:entity-ref</code>, and
3080
        <code>saxon:while</code> (see the <a class="bodylink" href="/extensions/instructions">Saxon 
3081
          Extension Instructions</a> section). To enable these, use the standard XSLT extension mechanism: define
3082
        <code>extension-element-prefixes="saxon"</code> on the <code>xsl:stylesheet element</code>, or
3083
        <code>xsl:extension-element-prefixes="saxon"</code> on any enclosing literal result
3084
      element.</p>
3085

    
3086
    <p>Any element whose prefix matches a namespace listed in the
3087
        <code>extension-element-prefixes</code> attribute of an enclosing element is treated as an
3088
      extension element. If no class can be instantiated for the element (for example, because no <a
3089
        class="javalink" href="com.saxonica.xsltextn.ExtensionElementFactory"
3090
        >ExtensionElementFactory</a> has been registered for the relevant namespace, or because the
3091
        <code>ExtensionElementFactory</code> doesn't recognise the local name), then fallback action
3092
      is taken as follows:</p>
3093
    
3094
    <ul><li><p>If the element has one or more <a class="bodylink code" href="/xsl-elements/fallback">xsl:fallback</a> 
3095
      children, they are processed.</p></li> 
3096
    <li><p>Otherwise, an error is reported. </p></li></ul>
3097
    <p>When <code>xsl:fallback</code> is used in any
3098
      other context, it and its children are ignored.</p>
3099

    
3100
    <p>Within the stylesheet it is possible to test whether an extension element is implemented by
3101
      using the system function <a class="bodylink code" href="/functions/fn/element-available">element-available()</a>. 
3102
      This returns true if the namespace
3103
      of the element identifies it as an extension element (or indeed as a standard XSLT
3104
      instruction) and if a class can be instantiated to represent it. If the namespace is not that
3105
      of an extension element, or if no class can be instantiated, it returns false.</p>
3106

    
3107
    <p>The <a class="javalink" href="com.saxonica.xsltextn.ExtensionElementFactory"
3108
        >ExtensionElementFactory</a> interface defines a single method,
3109
        <code>getExtensionClass()</code>, which takes the local name of the element (that is, the
3110
      name without its namespace prefix) as a parameter, and returns the Java class used to
3111
      implement this extension element (for example, <code>return SQLConnect.class</code>). The
3112
      class returned must be a subclass of <a class="javalink" href="net.sf.saxon.style.StyleElement">
3113
        net.sf.saxon.style.StyleElement</a>, and the easiest way to implement it is as a subclass of
3114
      <a class="javalink" href="net.sf.saxon.style.ExtensionInstruction">net.sf.saxon.style.ExtensionInstruction</a>.</p>
3115

    
3116
    <h2 class="subtitle">Implementing extension instructions</h2>
3117

    
3118
    <p>The best way to see how to implement an extension element is by looking at the <a
3119
      class="bodylink" href="/sql-extension/instructions/example">example</a>, for
3120
      SQL extension elements, provided in package <code>net.sf.saxon.option.sql</code>, and at the
3121
      sample stylesheet <strong>books-sql.xsl</strong> which uses these extension elements. Start
3122
      with the class <a class="javalink" href="net.sf.saxon.option.sql.SQLElementFactory"
3123
        >net.sf.saxon.option.sql.SQLElementFactory</a>.</p>
3124

    
3125
    <p>The <a class="javalink" href="net.sf.saxon.style.StyleElement">StyleElement</a> class represents 
3126
      an element node in the stylesheet document.
3127
      Saxon calls methods on this class to validate and type-check the element, and to generate a
3128
      node in the expression tree that is evaluated at run-time. Assuming that the class is written
3129
      to extend <a class="javalink" href="net.sf.saxon.style.ExtensionInstruction"
3130
        >ExtensionInstruction</a>, the methods it should provide are:</p>
3131
    <table>
3132
      <tr>
3133
        <td>
3134
          <p>prepareAttributes()</p>
3135
        </td>
3136
        <td>
3137
          <p>This is called while the stylesheet tree is still being built, so it should not attempt
3138
            to navigate the tree. Its task is to validate the attributes of the stylesheet element
3139
            and perform any preprocessing necessary. For example, if the attribute is an attribute
3140
            value template, this includes creating an <code>Expression</code> that can subsequently be evaluated
3141
            to get the AVT's value.</p>
3142
        </td>
3143
      </tr>
3144
      <tr>
3145
        <td>
3146
          <p>validate()</p>
3147
        </td>
3148
        <td>
3149
          <p>This is called once the tree has been built, and its task is to check that the
3150
            stylesheet element is valid "in context": that is, it may navigate the tree and check
3151
            the validity of the element in relation to other elements in the stylesheet module, or
3152
            in the stylesheet as a whole. By convention, a parent element contains checks on its
3153
            children, rather than the other way around: this allows child elements to be reused in a
3154
            new context without changing their code. The system will automatically call the method
3155
              <code>mayContainSequenceConstructor()</code>. If this returns true, it will
3156
            automatically check that all the children are instructions (that is, that their
3157
              <code>isInstruction()</code> method returns true). If the extension element is not
3158
            allowed to have any children, you can call <code>checkEmpty()</code> from the
3159
              <code>validate()</code> method. However, users will normally expect that an extension
3160
            instruction is allowed to contain an <code>xsl:fallback</code> child instruction, and
3161
            you should design for this. If there are any XPath expressions in attributes of the
3162
            extension instruction (for example a <code>select</code> attribute or an attribute value
3163
            template), then the <code>validate()</code> method should call the
3164
              <code>typeCheck()</code> method to process these expressions: for example <code>select
3165
              = typeCheck("select", select);</code>
3166
          </p>
3167
        </td>
3168
      </tr>
3169
      <tr>
3170
        <td>
3171
          <p>compile()</p>
3172
        </td>
3173
        <td>
3174
          <p>This is called to create an <code>Expression</code> object which is added to the expression tree.
3175
            See below for further details.</p>
3176
        </td>
3177
      </tr>
3178
      <tr>
3179
        <td>
3180
          <p>isInstruction()</p>
3181
        </td>
3182
        <td>
3183
          <p>This should return true, to ensure that the element is allowed to appear within a
3184
            template body.</p>
3185
        </td>
3186
      </tr>
3187
      <tr>
3188
        <td>
3189
          <p>mayContainSequenceConstructor()</p>
3190
        </td>
3191
        <td>
3192
          <p>This should return true, to ensure that the element can contain instructions. Even if
3193
            it can't contain anything else, extension elements should allow an <code>xsl:fallback</code>
3194
            instruction to provide portability between processors.</p>
3195
        </td>
3196
      </tr>
3197
    </table>
3198

    
3199
    <p>The <a class="javalink" href="net.sf.saxon.style.StyleElement">StyleElement</a> class has
3200
      access to many services supplied either via its superclasses or via the <code>XPathContext</code> object.
3201
      For details, see the API documentation of the individual classes.</p>
3202

    
3203
    <p>The simplest way to implement the <code>compile()</code> method is to return an instance of a
3204
      class that is defined as a subclass of <a class="javalink" href="net.sf.saxon.expr.SimpleExpression">SimpleExpression</a>. 
3205
      However, in principle
3206
      any <a class="javalink" href="net.sf.saxon.expr.Expression">Expression</a> object can be
3207
      returned, either an expression class that already exists within Saxon, or a user-written
3208
      implementation. The following notes assume that <code>SimpleExpression</code> is being used.</p>
3209
    
3210
    <p>At compile time, the method <code>SimpleExpression.setArguments()</code> must be called to
3211
    give a list of sub-expressions that act as operands for the extension instruction. These might
3212
    derive from XPath expressions in attributes of the instruction (including attribute value templates,
3213
    which can be compiled to expressions), or from a contained sequence constructor (which can also be
3214
    compiled to an expression).</p>
3215
    
3216
    <p>At run-time, Saxon will call the <code>SimpleExpression.call()</code> method to evaluate the
3217
    extension instruction, supplying the values of these sub-expressions, each in the form of a 
3218
      <a class="javalink" href="net.sf.saxon.om.Sequence">Sequence</a> object. The implementation
3219
    of this method should return the result of the extension instruction, also as a <code>Sequence</code>.
3220
    Saxon also supplies an <code>XPathContext</code> object which contains details of the dynamic context.
3221
    This should not be modified, but can be used as the basis for creating a new dynamic context if required.</p>
3222
    
3223

    
3224
  </section>
3225
  <section id="config-extend" title="Extending the Configuration">
3226
    <h1>Extending the Configuration</h1>
3227
    <p>This section describes various ways in which the configuration can be extended.</p>
3228
    <p>These methods are described further in the following pages.</p>
3229
    <nav>
3230
      <ul/>
3231
    </nav>
3232

    
3233
    <section id="collation" title="Collation">
3234
      <h1>Collation</h1>
3235
      <p>Collations used for comparing strings can be specified by means of a URI. A collation URI
3236
        may be used as an argument to many of the <a class="bodylink" href="/functions">standard
3237
          functions</a>, and also as an attribute of various instructions (<dfn><code>xsl:sort</code></dfn>,
3238
        <dfn><code>xsl:for-each-group</code></dfn>, <dfn><code>xsl:merge-key</code></dfn> in XSLT, and
3239
        in the <dfn><code>order by</code></dfn> clause of a FLWOR expression in XQuery.</p>
3240

    
3241
      <p>Saxon provides a range of mechanisms for binding collation URIs. The language
3242
        specifications simply say that collations used in sorting and in string-comparison functions
3243
        are identified by a URI, and leaves it up to the implementation how these URIs are
3244
        defined.</p>
3245

    
3246
      <p>There are some predefined collations that cannot be changed. Specifically:
3247
        
3248
        <ul>
3249
          <li><p>The <dfn>Unicode
3250
            Codepoint Collation</dfn> defined in the W3C specifications (see 
3251
            <a class="bodylink" href="http://www.w3.org/2005/xpath-functions/collation/codepoint">
3252
              http://www.w3.org/2005/xpath-functions/collation/codepoint</a>). This collates
3253
            strings based on the integer values assigned by Unicode to each character, for example "ah!"
3254
            sorts before "ah?" because the Unicode codepoints for "ah!" are (97, 104, 33) while the
3255
            codepoints for "ah?" are (97, 104, 63).</p></li>
3256
          <li><p>The "HTML ASCII case-blind collation", <a class="bodylink" href="http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive">
3257
            http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive"</a>. This is designed
3258
          to mimic the HTML5 rules for matching many names and keywords, whereby case distinctions
3259
          are ignored for the English letters (A-Z, a-z) but not for accented or non-English letters.</p>
3260
          <p>Saxon implements this effectively by converting upper-case letters A-Z to their lower-case
3261
          equivalents, and then using the codepoint collation.</p></li>
3262
          <li><p>The family of collations implementing the Unicode Collation Algorithm, 
3263
            <a class="bodylink" href="http://www.w3.org/2013/collation/UCA">
3264
              'http://www.w3.org/2013/collation/UCA?keyword=value;...</a></p>
3265
            
3266
          <p>Saxon-PE and Saxon-EE implement UCA collations by use of the ICU-J open source
3267
          library, which supports a large range of languages and all the parameters defined in the
3268
          UCA specification. Saxon-HE has a simpler implementation which relies on the collation
3269
          support available in the built-in Java library; the languages this supports depend on the
3270
          particular Java installation, and not all parameters are supported. For this reason,
3271
          Saxon-HE supports UCA collations only if fallback implementation is allowed (that is,
3272
          if the option <code>fallback=no</code> is not present in the collation URI.</p></li>
3273
        </ul></p>
3274
      
3275
      <p>For backwards compatibility reasons the standard collation resolver in Saxon also
3276
        accepts URIs in the form <code>http://saxon.sf.net/collation</code> followed by query
3277
      parameters; the query parameters that are recognized are the same as those defined by W3C
3278
      UCA collation URIs.</p>
3279
      
3280
      <p>The keywords defined by W3C are: <code>fallback</code>, <code>lang</code>,
3281
      <code>version</code>, <code>strength</code>, <code>maxVariable</code>, <code>alternate</code>,
3282
      <code>backwards</code>, <code>normalization</code>, <code>caseLevel</code>, <code>caseFirst</code>,
3283
      <code>numeric</code>, <code>reorder</code>. The values for these parameters and their meaning
3284
        can be found at <a class="bodylink" href="https://www.w3.org/TR/xslt-30/#uca-collations">https://www.w3.org/TR/xslt-30/#uca-collations</a>.</p>
3285
      
3286
      <p>Whether the W3C URI <code>http://www.w3.org/2013/collation/UCA</code> or the
3287
        Saxon URI <code>http://saxon.sf.net/collation</code> is used, Saxon accepts a number
3288
      of collation parameters additional to those defined by W3C, as follows:</p>
3289
      
3290
      <table>
3291
        <thead class="params">
3292
          <tr>
3293
            <td>
3294
              <p> keyword </p>
3295
            </td>
3296
            <td>
3297
              <p> values </p>
3298
            </td>
3299
            <td>
3300
              <p> effect </p>
3301
            </td>
3302
          </tr>
3303
        </thead>
3304
        <tbody>
3305
          <tr>
3306
            <td class="keyword">
3307
              <p>class</p>
3308
            </td>
3309
            <td>
3310
              <p>fully-qualified Java class name of a class that implements
3311
                <code>java.util.Comparator</code>.</p>
3312
            </td>
3313
            <td>
3314
              <p>This parameter should not be combined with any other parameter. An instance of
3315
                the requested class is created, and is used to perform the comparisons. Note that
3316
                if the collation is to be used in functions such as <code>contains()</code> and
3317
                <code>starts-with()</code>, this class must also be a
3318
                <code>java.text.RuleBasedCollator</code>. This approach allows a user-defined
3319
                collation to be implemented in Java. This option is also available on the .NET
3320
                platform, but the class must implement the Java interface
3321
                <code>java.util.Comparator</code>.</p>
3322
            </td>
3323
          </tr>
3324
          <tr>
3325
            <td class="keyword">
3326
              <p>rules</p>
3327
            </td>
3328
            <td>
3329
              <p>details of the ordering required, using the syntax of the Java
3330
                <code>RuleBasedCollator</code>
3331
              </p>
3332
            </td>
3333
            <td>
3334
              <p>This defines exactly how individual characters are collated. (It's not very
3335
                convenient to specify this as part of a URI, but the option is provided for
3336
                completeness.) This option is also available on the .NET platform, and if used
3337
                will select a collation provided using the OpenJDK implementation of
3338
                <code>RuleBasedCollator</code>.</p>
3339
            </td>
3340
          </tr>
3341
          <tr>
3342
            <td class="keyword">
3343
              <p>ignore-case</p>
3344
            </td>
3345
            <td>
3346
              <p class="value">yes | no</p>
3347
            </td>
3348
            <td>
3349
              <p>Indicates whether the case of letters should be ignored: equivalent to <code>strength=secondary</code>.</p>
3350
            </td>
3351
          </tr>
3352
          <tr>
3353
            <td class="keyword">
3354
              <p>ignore-modifiers</p>
3355
            </td>
3356
            <td>
3357
              <p class="value">yes | no</p>
3358
            </td>
3359
            <td>
3360
              <p>Indicates whether non-spacing combining characters (such as accents and
3361
                diacritical marks) are considered significant. Note that even when
3362
                ignore-modifiers is set to "no", modifiers are less significant than the actual
3363
                letter value, so that "Hofen" and "Höfen" will appear next to each other in the
3364
                sorted sequence. Equivalent to <code>strength=secondary</code>.</p>
3365
            </td>
3366
          </tr>
3367
          <tr>
3368
            <td class="keyword">
3369
              <p>ignore-symbols</p>
3370
            </td>
3371
            <td>
3372
              <p class="value">yes | no</p>
3373
            </td>
3374
            <td>
3375
              <p>Indicates whether symbols such as whitespace characters and punctuation marks are
3376
                to be ignored. This option currently has no effect on the Java platform, where
3377
                such symbols are in most cases ignored by default.</p>
3378
            </td>
3379
          </tr>
3380
          <tr>
3381
            <td class="keyword">
3382
              <p>ignore-width</p>
3383
            </td>
3384
            <td>
3385
              <p class="value">yes | no</p>
3386
            </td>
3387
            <td>
3388
              <p>Indicates whether characters that differ only in width should be considered
3389
                equivalent. On the Java platform, setting ignore-width sets the collation strength
3390
                to tertiary.</p>
3391
            </td>
3392
          </tr>
3393
          <tr>
3394
            <td class="keyword">
3395
              <p>
3396
                <dfn>decomposition</dfn>
3397
              </p>
3398
            </td>
3399
            <td>
3400
              <p class="value">none | standard | full</p>
3401
            </td>
3402
            <td>
3403
              <p>Indicates how the collator handles Unicode <dfn>composed characters</dfn>. See
3404
                the JDK documentation for details. This option is ignored on the .NET
3405
                platform.</p>
3406
            </td>
3407
          </tr>
3408
          <tr>
3409
            <td class="keyword">
3410
              <p>alphanumeric</p>
3411
            </td>
3412
            <td>
3413
              <p class="value">yes | no | codepoint</p>
3414
            </td>
3415
            <td>
3416
              <p>If set to yes, the string is split into a sequence of alphabetic and numeric
3417
                parts (a numeric part is any consecutive sequence of ASCII digits; anything else
3418
                is considered alphabetic). Each numeric part is considered to be preceded by an
3419
                alphabetic part even if it is zero-length. The parts are then compared pairwise:
3420
                alphabetic parts using the collation implied by the other query parameters,
3421
                numeric parts using their numeric value. The result is that, for example, AD985
3422
                collates before AD1066. (This is sometimes called <dfn>natural sorting</dfn>.) The
3423
                value "codepoint" requests <dfn>alphanumeric collation</dfn> with the
3424
                "alpha" parts being collated by Unicode codepoint, rather than by the default
3425
                collation for the <dfn>Locale</dfn>. This may give better results in the case of
3426
                strings that contain spaces. Note that an alphanumeric collation cannot be used in
3427
                conjunction with functions such as <code>contains()</code> and <code>substring-before()</code>.</p>
3428
            </td>
3429
          </tr>
3430
          <tr>
3431
            <td class="keyword">
3432
              <p>case-order</p>
3433
            </td>
3434
            <td>
3435
              <p class="value">upper-first | lower-first</p>
3436
            </td>
3437
            <td>
3438
              <p>Indicates whether <dfn>upper case</dfn> letters collate before or after
3439
                <dfn>lower case</dfn> letters.</p>
3440
            </td>
3441
          </tr>
3442
        </tbody>
3443
      </table>
3444
      
3445
      <p>If you want to use your own URIs to define collations, there are two ways of doing this:</p>
3446
      
3447
      <ul>
3448
        <li><p>You can use the Saxon configuration file to define collations: see <a class="bodylink"
3449
          href="/configuration/configuration-file/config-collations">The collations element</a>.</p></li>
3450
        <li><p>You can register a collation with the Saxon Configuration using the method
3451
        s9api method <code>Processor.declareCollation()</code> or the underlying method
3452
          <code>Configuration.registerCollation()</code>.</p></li></ul>
3453
      
3454
      <p>In either case, the collation is supplied in the form
3455
        of an implementation of the interface <code>net.sf.saxon.lib.StringCollator</code>. You must supply methods
3456
        <code>compareStrings()</code> and <code>comparesEqual()</code> for comparing strings for
3457
        ordering or equality, and a method getCollationKey() which returns a collation key
3458
        for any string. If you want your collation to be used in calls of <code>fn:contains()</code>,
3459
        <code>fn:starts-with()</code>, <code>fn:ends-with()</code>, <code>fn:substring-before()</code>,
3460
        or <code>fn:substring-after()</code>, then it must also implement the interface 
3461
        <code>net.sf.saxon.lib.SubstringMatcher</code>.</p>
3462
      
3463
      <aside>The set of collation URIs known to Saxon is defined in the <code>Configuration</code>. In earlier releases,
3464
      it was possible to define collation URIs with narrower scope, for example a single query or stylesheet. Some legacy
3465
      APIs reflect this capability, but they are generally deprecated and either have no effect, or have a Configuration-wide
3466
      effect.</aside>
3467
      
3468
      <aside>The choice of default collation, however, is local to a query or stylesheet (in XSLT, it can even vary between
3469
      different parts of a stylesheet). The default collation must always be one of the collations defined in the
3470
        <code>Configuration</code>.</aside>
3471
      
3472
      
3473

    
3474
      <xi:include href="extensibility/UCA.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
3475
    </section>
3476

    
3477
    <section id="localizing" title="Localizing numbers and dates">
3478
      <h1>Localizing numbers and dates</h1>
3479

    
3480
      <p>It is possible to define a <dfn>localized numbering</dfn> sequence for use by
3481
          <a class="bodylink code" href="/xsl-elements/number">xsl:number</a> and 
3482
        <a  class="bodylink code" href="/functions/fn/format-date">format-date()</a>. 
3483
        This sequence will be used when
3484
        you specify a language in the <code>lang</code> attribute of the <code>xsl:number</code>
3485
        element, or in the third argument of the functions <code>format-date()</code>,
3486
          <code>format-time()</code>, and <code>format-dateTime()</code>. The feature is primarily
3487
        intended to provide language-dependent numbers and dates, but in fact it can be used to
3488
        provide arbitrary numbering sequences.</p>
3489

    
3490
      <p>For Saxon-PE/EE from version 9.6 the repertoire of supported languages for numbering and
3491
        dates can be extended (or replaced) by the use of facilities from <a
3492
          href="http://site.icu-project.org/">ICU - International Components for Unicode</a>, as
3493
        described in <a class="bodylink" href="ICU-numbering-dates">Numbers and Dates from
3494
        ICU</a>.</p>
3495

    
3496
      <p>The numbering sequence for English is used by default if no other can be loaded.</p>
3497

    
3498
      <p>Additional numbering sequences are available as described in <a
3499
          href="/extensibility/config-extend/localizing/other-numberings">Numberings for selected
3500
          languages</a>.</p>
3501

    
3502
      <!--<p>Predefined versions of the numberer for Danish, Dutch, Flemish, French (and Belgian
3503
        French), German, Italian and Swedish were shipped with all versions of Saxon 9.5 and sources
3504
        for these are available in the archive.</p>-->
3505

    
3506
      <p>To implement a numberer for language X, you need to define a class that implements the
3507
        interface <a class="javalink" href="net.sf.saxon.lib.Numberer">Numberer</a>; usually it will
3508
        be convenient to write the class as a subclass of the supplied <a class="javalink"
3509
          href="net.sf.saxon.expr.number.AbstractNumberer">AbstractNumberer</a>.</p>
3510

    
3511

    
3512

    
3513

    
3514
      <p>Normally your localization class will extend the class <code>AbstractNumberer</code> so
3515
        that you can reuse functionality like roman numerals which do not need to be localized.
3516
        Alternatively, if you only want to modify the existing English localization, you could
3517
        choose to implement a subclass of <code>Numberer_en</code>.</p>
3518

    
3519
      <p>You can override any of the non-private methods in the base class, but the most useful ones
3520
        to implement are the following:</p>
3521
      <table>
3522
        <thead>
3523
          <tr>
3524
            <td>
3525
              <p>Method</p>
3526
            </td>
3527
            <td>
3528
              <p>Effect</p>
3529
            </td>
3530
          </tr>
3531
        </thead>
3532
        <tbody>
3533
          <tr>
3534
            <td>
3535
              <p>ordinalSuffix</p>
3536
            </td>
3537
            <td>
3538
              <p>Supplies a suffix to be appended to a number to create the ordinal form, for
3539
                example "1" becomes "1st" in English</p>
3540
            </td>
3541
          </tr>
3542
          <tr>
3543
            <td>
3544
              <p>toWords</p>
3545
            </td>
3546
            <td>
3547
              <p>Displays a number in words, in title case: for example "53" becomes "Fifty Three"
3548
                in English</p>
3549
            </td>
3550
          </tr>
3551
          <tr>
3552
            <td>
3553
              <p>toOrdinalWords</p>
3554
            </td>
3555
            <td>
3556
              <p>Displays an ordinal number in words, in title case: for example "53" becomes "Fifty
3557
                Third" in English</p>
3558
            </td>
3559
          </tr>
3560
          <tr>
3561
            <td>
3562
              <p>monthName</p>
3563
            </td>
3564
            <td>
3565
              <p>Displays the name of a month, optionally abbreviated</p>
3566
            </td>
3567
          </tr>
3568
          <tr>
3569
            <td>
3570
              <p>dayName</p>
3571
            </td>
3572
            <td>
3573
              <p>Displays the name of a day of the week, optionally abbreviated</p>
3574
            </td>
3575
          </tr>
3576
        </tbody>
3577
      </table>
3578

    
3579
      <p>The class name can be anything you like, but by convention the Numberer for language LL is
3580
        named <code>net.sf.saxon.option.local.Numberer_LL</code>.</p>
3581

    
3582
      <p>The way that the numberer is registered with the Saxon 
3583
        <a class="javalink" href="net.sf.saxon.Configuration">Configuration</a> differs between
3584
        Saxon-HE on the one hand, and Saxon-PE/EE on the other. On Saxon-HE, you need to supply a
3585
          <code>LocalizerFactory</code> that responds to the request for a particular language, for
3586
        example:</p>
3587

    
3588
      <samp><![CDATA[Configuration config = new Configuration();
3589
config.setLocalizerFactory(new LocalizerFactory() {
3590
  public Numberer getNumberer(String language, String country) {
3591
    if (language.equals("jp")) {
3592
      return Numberer_JP.getInstance();
3593
    } else {
3594
      return null;
3595
    }
3596
  }
3597
}]]></samp>
3598

    
3599
      <p>You can also use this mechanism on Saxon-PE/EE, but an alternative is to register the
3600
        localization module in the <a class="bodylink" href="/configuration/configuration-file"
3601
          >configuration file</a>.</p>
3602

    
3603
      <!--<p>
3604
        <i>If you write a comprehensive <code>Numberer</code> for a particular language, please
3605
          submit it, and we will be happy to include it in future versions of the product as an
3606
          open-source component. You must agree to release it under the Mozilla Public License or
3607
          under any other recognized open source license that Saxon might adopt in the future.</i>
3608
      </p>-->
3609

    
3610
      <xi:include href="extensibility/locales-ICU-numbering.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
3611
      <xi:include href="extensibility/other-numbering.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
3612
    </section>
3613

    
3614
    <section id="uri-resolution" title="Customizing URI Resolution">
3615
      <h1>Customizing URI Resolution</h1>
3616
      <p>The resolution of URIs can be extended in several ways:</p>
3617
      <nav>
3618
        <ul/>
3619
      </nav>
3620

    
3621
      <section id="uri-resolver" title="Writing a URI Resolver for Input Files">
3622
        <h1>Writing a URI Resolver for Input Files</h1>
3623

    
3624

    
3625
        <p>Saxon allows you to write your own <code>URIResolver</code> to handle the URIs of input
3626
          documents, as defined in the JAXP specification. Such a <code>URIResolver</code> is used
3627
          to process the URIs supplied to the <a class="bodylink code" href="/functions/fn/doc">doc()</a> 
3628
          and <a class="bodylink code" href="/functions/fn/document">document()</a>
3629
          functions. It is also used to process the URIs supplied for the source document and the
3630
          stylesheet on the command line. In XSLT it is used to process the URIs used in the
3631
            <a class="bodylink code" href="/xsl-elements/include">xsl:include</a>, 
3632
          <a class="bodylink code" href="/xsl-elements/import">xsl:import</a> and 
3633
          <a class="bodylink code" href="/xsl-elements/import-schema">xsl:import-schema</a>
3634
          declarations, and in XQuery it supports the location URIs in <code>import
3635
          schema</code>.</p>
3636

    
3637
        <p>The <code>URIResolver</code> is called to process the supplied URI, and it returns a JAXP
3638
            <code>Source</code> object, which Saxon uses as the source of the input. Note that the
3639
            <code>Source</code> must be one of the implementations of <code>Source</code> that Saxon
3640
          recognizes: you cannot write your own implementations of the JAXP <code>Source</code>
3641
          class.</p>
3642

    
3643
        <p>The <code>URIResolver</code> is used only for XML files. It is therefore not used to
3644
          support the <a class="bodylink code" href="/functions/fn/unparsed-text">unparsed-text()</a> 
3645
          function in XSLT, or to support <code>import
3646
            module</code> in XQuery. There are other mechanisms for such cases:</p>
3647
        
3648
        <ul>
3649
          <li>The <code>UnparsedTextURIResolver</code> is used by the <code>unparsed-text()</code>,
3650
          <code>unparsed-text-lines()</code>, <code>unparsed-text-available()</code>, and
3651
          <code>parse-json</code> functions.</li>
3652
          <li>The <code>ModuleURIResolver</code> is used to locate XQuery modules.</li>
3653
        </ul>
3654
        
3655
        <aside>XSLT 3.0 packages can by located by name and version number by registering them
3656
        in the configuration file.</aside>
3657
        
3658
      </section>
3659

    
3660

    
3661

    
3662

    
3663
      <section id="output-uri-resolver" title="Resolving the URIs of Output Files">
3664
        <h1>Resolving the URIs of Output Files</h1>
3665
        
3666
        <p>Saxon 9.9 introduces a new mechanism for handling the URIs of output documents
3667
        specified in the <code>@href</code> attribute of <a class="bodylink code"
3668
          href="/xsl-elements/result-document">xsl:result-document</a>.</p>
3669
        
3670
        <p>Various interfaces, such as the s9api <code>Xslt30Transformer</code>, have a method
3671
          <code>setResultDocumentHandler()</code> which accepts a Java <code>Function&lt;URI, Destination&gt;</code>,
3672
        that is, a function that accepts an absolute URI and returns a <code>Destination</code> for the output. For example, you
3673
        might write:</p>
3674
        
3675
        <p><code>transformer.setResultDocumentHandler(uri -> processor.newSerializer(....))</code></p>
3676
        
3677
        <p>When writing to the secondary result document is complete, Saxon will call the method <code>Destination.close()</code>,
3678
        whose effect depends on the kind of destination. For example, in the case of a <code>Serializer</code>, the <code>close()</code>
3679
        method will close any input stream that Saxon created, but not one that the user created, unless the method <code>Serializer.setCloseOnCompletion()</code>
3680
        is called to request this.</p>
3681
        
3682
        <p>You can also call the method <code>Destination.onClose()</code> to supply an application-specific action
3683
        to be performed when the destination is closed. For example, if the URI is a <code>mailto:</code> URI, you might
3684
        want to attach the serialized result to an email message and send it to a nominated recipient.</p>
3685

    
3686
        <p>The older <code>OutputURIResolver</code> mechanism is retained for backwards compatibility. This is limited by the fact
3687
        that it returns a JAXP <code>Result</code> object, which doesn't allow, for example, for returning a "raw" result in which the
3688
        XSLT results are not wrapped in a document node.</p>
3689
        
3690
        <p>There is a change in Saxon 9.9 regarding the way in which an <code>xsl:result-document</code> instruction
3691
        with no <code>href</code> attribute is handled. In previous releases Saxon attempted to reuse the output stream
3692
        established for the primary output of the transformation. The new XSLT 3.0 options (such as raw output) make
3693
        this difficult, and possibly non-conformant. The new model is therefore that the <code>href</code> attribute simply
3694
          defaults to the base output URI, and is otherwise handled in the same way as any other call on <code>xsl:result-document</code>.
3695
          The main difference will be noticed if no base output URI is supplied, which will now cause a failure.</p>
3696

    
3697
        
3698
      </section>
3699

    
3700
      <section id="collection-uri-resolver" title="Writing a URI Resolver for Collections">
3701
        <h1>Writing a URI Resolver for Collections</h1>
3702
        
3703
        <p>Saxon 9.7 introduced a new <code>CollectionFinder</code> interface, superseding
3704
        the older <code>CollectionURIResolver</code> (which has been dropped in Saxon 10). The new
3705
          mechanism was needed in response
3706
        to changes in XPath 3.1 that allowed a collection to return any kind of values, not only XML documents.
3707
        For example a collection might include JSON documents, unparsed text files, or binary files.</p>
3708
        
3709
        <p>The built-in <code>CollectionFinder</code> supports several ways of defining collections (they can
3710
        be mapped to directories, JAR/ZIP files, or lists of files in a catalog), and media types for
3711
        recognizing XML files, text files, JSON files, and binary files. The mechanisms are highly configurable
3712
        and APIs are provided to define new kinds of collection and new media types.</p>
3713
        
3714
        <p>For details of the behavior of the standard collection finder, and more
3715
          information on supplying your own, see <a class="bodylink"
3716
            href="/sourcedocs/collections">Collections</a>.</p>
3717

    
3718

    
3719
      </section>
3720
    </section>
3721

    
3722
    <section id="output-filters" title="Customizing Serialization">
3723
      <h1>Customizing Serialization</h1>
3724
      
3725
      <p>In XSLT 3.0 there are three ways the result of a stylesheet may be delivered: it may be delivered as a raw sequence
3726
      (any XDM value), it may be subjected to <i>sequence normalization</i> as defined in the W3C serialization specification,
3727
      or it may be serialized after sequence normalization. This turns out to be a substantial change with significant implications,
3728
      which has led to considerable internal change in the output pipeline in Saxon, some of which is visible in terms of changed
3729
      API behavior.</p>
3730
      
3731
      <p>At the s9api level, the data passed from an <code>Xslt30Transformer</code> or <code>XQueryEvaluator</code>
3732
      to a <code>Destination</code> is always a raw sequence (any sequence of items, nodes or atomic values or functions, not wrapped
3733
      in a document node). This is delivered over Saxon's internal <code>Receiver</code> interface, which allows nodes to be passed either 
3734
      in <i>composed</i> form (as a <code>NodeInfo</code> object along with its entire subtree), or in <i>decomposed</i> form
3735
      (as a sequence of events like <code>startElement</code> and <code>endElement</code>). There are strict rules on the "well-formedness" of
3736
        the calls made across this interface, defined in the JavaDoc for class
3737
        <a class="javalink" href="net.sf.saxon.event.RegularSequenceChecker">net.sf.saxon.event.RegularSequenceChecker</a>,
3738
        and it is possible to insert a <code>RegularSequenceChecker</code> into the pipeline to check that the rules are being adhered to.</p>
3739
      
3740
      <p>It is the responsibility of the <code>Destination</code> to perform sequence normalization (if requested) and/or serialization.</p>
3741
      
3742
      <p>Because sequence normalization may involve inserting item separators based on the <code>item-separator</code> serialization property,
3743
      all destinations now have access to the full set of serialization properties.</p>
3744
      
3745
      <p>There are a number of implementations of the <code>Destination</code> interface supplied with the product: </p>
3746
      <ul>
3747
        <li>The <code>RawDestination</code> delivers the raw result as an <code>XdmValue</code>.</li>
3748
        <li>The <code>Serializer</code> supports various serialization methods.</li>
3749
        <li>The <code>SAXDestination</code> allows output to a SAX <code>ContentHandler</code>.</li>
3750
        <li>The <code>XMLStreamWriterDestination</code> allows output to an <code>XMLStreamWriter</code>.</li>
3751
        <li>The <code>DOMDestination</code> allows building of a DOM tree.</li>
3752
        <li>The <code>TeeDestination</code> allows forking of the output to two different destinations.</li>
3753
        <li>A destination can be obtained that streams data into an XSLT transformation or a schema validator.</li>
3754
      </ul>
3755
      
3756
      <p>In addition, it is quite possible to write your own implementation of the <code>Destination</code> interface, either from scratch
3757
        or by subclassing an existing implementation.</p>
3758
      
3759
 
3760

    
3761
      <p>Some <code>ContentHandler</code> implementations require a sequence of events corresponding
3762
        to a well-formed document (that is, one whose document node has exactly one element node and
3763
        no text nodes among its children). If this is the case, you can specify the additional
3764
        output property <code>saxon:require-well-formed="yes"</code>, which will cause Saxon to
3765
        report an error if the result tree is not well-formed.</p>
3766

    
3767
      <p>As specified in the JAXP interface, requests to disable or re-enable output escaping are
3768
        also notified to the content handler by means of special processing instructions. The names
3769
        of these processing instructions are defined by the constants
3770
          <code>PI_DISABLE_OUTPUT_ESCAPING</code> and <code>PI_ENABLE_OUTPUT_ESCAPING</code> defined
3771
        in class <code>javax.xml.transform.Result</code>.</p>
3772

    
3773
 
3774

    
3775
      <p>An abstract implementation of the <a class="javalink" href="net.sf.saxon.event.Receiver"
3776
          >Receiver</a> interface is available in the <a class="javalink"
3777
          href="net.sf.saxon.serialize.Emitter">Emitter</a> class. This class provides additional
3778
        functionality which is useful if you want to serialize the result to a byte or character output
3779
        stream. If the <code>Receiver</code> that you supply as an output destination is an instance
3780
        of <code>Emitter</code>, then it has access to all the serialization parameters supplied in
3781
        the <code>xsl:output</code> declaration, or made available using the Java API.</p>
3782

    
3783
      <p>See the documentation of class <a class="javalink" href="net.sf.saxon.event.Receiver"
3784
          >net.sf.saxon.event.Receiver</a> for details of the methods available, or implementations
3785
        such as <a class="javalink" href="net.sf.saxon.serialize.HTMLEmitter">HTMLEmitter</a> and <a
3786
          class="javalink" href="net.sf.saxon.serialize.XMLEmitter">XMLEmitter</a> and <a
3787
          class="javalink" href="net.sf.saxon.serialize.TEXTEmitter">TEXTEmitter</a> for the
3788
        standard output formats supported by Saxon.</p>
3789

    
3790
      <p>It can sometimes be useful to set up a chain of <code>Receiver</code>s working as a
3791
        pipeline. To write a filter that participates in such a pipeline, the class <a
3792
          class="javalink" href="net.sf.saxon.event.ProxyReceiver">ProxyReceiver</a> is supplied.
3793
        See the class <a class="javalink" href="net.sf.saxon.serialize.XMLIndenter">XMLIndenter</a>,
3794
        which handles XML indentation, as an example of how to write a
3795
        <code>ProxyReceiver</code>.</p>
3796

    
3797
      <p>Saxon sets up such a pipeline when an output file is opened, using a class called the <a
3798
          class="javalink" href="net.sf.saxon.lib.SerializerFactory">SerializerFactory</a>. You can
3799
        override the standard <code>SerializerFactory</code> with your own subclass, which you can
3800
        nominate to the <code>setSerializerFactory()</code> method of the <a class="javalink"
3801
          href="net.sf.saxon.Configuration">Configuration</a>. This uses individual methods to
3802
        create each stage of the pipeline, so you can either override the method that constructs the
3803
        entire pipeline, or override a method that creates one of its stages. For example, if you
3804
        want to subclass the <a class="javalink" href="net.sf.saxon.serialize.XMLEmitter"
3805
          >XMLEmitter</a> (perhaps to force all non-ASCII characters to be output as hexadecimal
3806
        character references), you can override the method <code>newXMLEmitter()</code> to return an
3807
        instance of your own subclass of <code>XMLEmitter</code>, which might override the method
3808
          <code>writeEscape()</code>.</p>
3809

    
3810

    
3811
      <p>Any number of user-defined attributes may be defined on <a class="bodylink code" 
3812
        href="/xsl-elements/output">xsl:output</a>. These
3813
        attributes must have names in a non-null namespace, which must not be either the XSLT or the
3814
        Saxon namespace. The value of the attribute is inserted into the <code>Properties</code>
3815
        object made available to the <code>Emitter</code> handling the output; they will be ignored
3816
        by the standard output methods, but can supply arbitrary information to a user-defined
3817
        output method. The name of the property will be the expanded name of the attribute in JAXP
3818
        format, for example <code>{http://my-namespace/uri}local-name</code>, and the value will be
3819
        the value as given, after evaluation as an attribute value template.</p>
3820
    </section>
3821
  </section>
3822
</article>
(11-11/21)