Project

Profile

Help

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

he / src / userdoc / extensibility.xml @ d2885105

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>. This can
441
        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
        by subclassing <a class="javalink" href="net.sf.saxon.Transform">net.sf.saxon.Transform</a>
444
        or <a class="javalink" href="net.sf.saxon.Query">net.sf.saxon.Query</a>, overriding the
445
        method <code>applyLocalOptions()</code> so that it makes the appropriate calls on
446
          <code>config.registerExtensionFunction()</code>; or it can be done in a user-defined class
447
        that implements the interface <a class="javalink" href="net.sf.saxon.lib.Initializer"
448
          >net.sf.saxon.Initializer</a>, and that is nominated on the command line using the
449
          <code>-init</code> option.</aside>
450

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
801

    
802

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

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

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

    
867

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

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

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

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

    
899

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

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

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

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

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

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

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

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

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

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

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

    
1006

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
1296

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

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

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

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

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

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

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

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

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

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

    
1353

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
1486

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

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

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

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

    
1515

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

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

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

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

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

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

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

    
1700

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

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

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

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

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

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

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

    
2001

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

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

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

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

    
2033

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

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

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

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

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

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

    
2105

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

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

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

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

    
2241

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
2497

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

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

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

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

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

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

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

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

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

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

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

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

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

    
2600

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

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

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

    
2621

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

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

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

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

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

    
2670

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

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

    
2680

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

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

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

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

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

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

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

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

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

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

    
2903

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

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

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

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

    
2925

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

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

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

    
2955

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

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

    
3034

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

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

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

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

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

    
3075

    
3076

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
3510

    
3511

    
3512

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

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

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

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

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

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

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

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

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

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

    
3623

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

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

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

    
3659

    
3660

    
3661

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

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

    
3696
        
3697
      </section>
3698

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

    
3717

    
3718
      </section>
3719
    </section>
3720

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

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

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

    
3772
 
3773

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

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

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

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

    
3809

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