Project

Profile

Help

Revision cbf1771e

Added by Debbie Lockett 9 months ago

Documentation: rename changes-10.xml source file

View differences:

src/userdoc/changes.xml
51 51
      <cat name="applet" title="Using Saxon as a Java applet"/>
52 52
   </categories>
53 53
   
54
   <xi:include href="changes/changes-10.0.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
54
   <xi:include href="changes/changes-10.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
55 55
   
56 56
   <xi:include href="changes/changes-9.9.1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
57 57
   
src/userdoc/changes/changes-10.0.xml
1
<?xml version="1.0" encoding="UTF-8"?>
2

  
3
<release number="10" date="2020-03-16" xmlns="http://www.saxonica.com/ns/doc/changes">
4
    
5
    <!--<category name="documentation">
6
        
7
    </category>-->
8
    
9
    <category name="xslt30">
10
      
11
        <p>Higher order functions and the <a class="bodylink code"
12
            href="/xsl-elements/evaluate">xsl:evaluate</a> instruction are now available in Saxon-HE.</p>
13
        
14
        <p>Error XTDE1160 (which occurs when an invalid fragment appears in the URI passed to the
15
            <a class="bodylink code" href="/functions/fn/document">document()</a> function)
16
        is now reported unconditionally; it is no longer a recoverable error. This change is in line with the XSLT 3.0
17
        specification. This was the last remaining "recoverable error", and in consequence, the configuration options controlling
18
        how recoverable errors were handled have now been dropped.</p>
19
        
20
        <p>Deterministic functions (specifically, the option <code>&lt;xsl:function new-each-time="no"&gt;</code>) are now
21
        available in Saxon-HE as well as Saxon-PE and Saxon-EE. This change is made because it is Saxonica policy that all
22
        mandatory features of the XSLT 3.0 specification should be available in Saxon-HE. Note: these functions are implemented
23
        as memo functions: the results of previous calls are remembered, and if a new call is made with the same arguments, the
24
        remembered result is returned. The main use case is in fact for the performance effect (using more memory to achieve
25
        higher speed) rather than for the rather technical effect of returning repeatable results. Setting the option <code>cache="yes"</code>
26
        achieves the same effect.</p>
27
        
28
        <p>Some extensions to XSLT 3.0 streaming capability have been implemented:</p>
29
        
30
        <ul>
31
            <li><p>The existing higher order function <a class="bodylink code" href="/functions/fn/filter">fn:filter</a>, and the
32
                new extension functions <a class="bodylink code"
33
                    href="/functions/saxon/items-after">saxon:items-after</a>, <a
34
                        class="bodylink code"
35
                        href="/functions/saxon/items-before">saxon:items-before</a>, <a class="bodylink code"
36
                            href="/functions/saxon/items-from">saxon:items-from</a>, and <a class="bodylink code"
37
                                href="/functions/saxon/items-until">saxon:items-until</a> are now streamable, under the right
38
                conditions. Provided that the second argument is either:</p>
39
                <ol>
40
                    <li>A function reference to a user-defined stylesheet function declared with <code>streamability=inspection</code>, or</li>
41
                    <li>An inline function whose body is grounded and motionless</li>
42
                </ol>
43
                <p>then the posture and sweep of the function call are the same as the posture and sweep of the first argument.</p>
44
                <p>For example, the call <code>saxon:ends-where(/article/*, function($e){$e[@title="Introduction"]})</code> processes all
45
                    sections of an article up to and including the one with title "Introduction". This call is striding and consuming
46
                    (which means that when used in an appropriate context it is streamable).</p>
47
            </li>
48
        </ul>
49
        
50
        
51
        
52
        <p>In interfaces that require Saxon to parse the <code>&lt;?xml-stylesheet?></code> processing instruction to locate a stylesheet,
53
            the parsing of the instruction now follows the <a href="https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028/">W3C specification</a> much
54
        more rigorously, meaning that errors may now be detected that previously passed unnoticed.</p>
55
 
56
        <p>Saxon 10 is capable of generating SEF files suitable for Saxon 10 or Saxon-JS 2.0. The formats
57
        are different (the most obvious difference is that SEF files for Saxon 10 are in XML format, while
58
        those for Saxon-JS 2.0 are in JSON), so the right target must be selected when exporting. SEF files
59
        generated using Saxon 10 cannot be loaded by Saxon 9.9 or by Saxon-JS 1.x. SEF files generated using
60
        Saxon 9.9 or earlier releases cannot be loaded by Saxon 10.</p>
61
      
62
      <aside><p>Saxon-JS 2.0 is not available at the time of first release of Saxon 10; however,
63
      development is well advanced.</p></aside>
64
 
65
    </category>
66
    
67
    <category name="xpath31">
68
      
69
      <p>The higher-order functions optional feature is now available in Saxon-HE.</p>
70
 
71
    </category>
72
    
73
    <category name="functions31">
74
        
75
        <p>The <a class="bodylink code" href="/functions/fn/parse-json">parse-json()</a> and
76
            <a class="bodylink code" href="/functions/fn/json-doc">json-doc()</a> functions now have improved diagnostics when the JSON input
77
        is invalid (most notably, the error message now includes a line number).</p>
78
      
79
      <p>The standard library of higher-order functions (<code>fn:filter</code>, <code>fn:fold-left</code>, etc)
80
      are now available in Saxon-HE.</p>
81
 
82
    </category>
83
    
84
    <category name="s9api">
85
        
86
        <h2>Support for new Java date/time system</h2>
87
        
88
        <p><code java="net.sf.saxon.s9api.XdmAtomicValue">XdmAtomicValue</code> provides additional constructors and getter
89
            methods supporting conversion to or from: <code>java.time.Instant</code>, <code>java.time.LocalDateTime</code>,
90
            <code>java.time.OffsetDateTime</code>, <code>java.time.ZonedDateTime</code>, and <code>java.time.LocalDate</code>.</p>
91
        
92
        <h2>Tree Construction APIs</h2>
93
        
94
        <p>Two new APIs have been introduced to make construction of XDM trees easier. One is oriented to construction of
95
        in-memory documents, the other is an event-based push API:</p>
96
        
97
        <ul>
98
            <li><p>The Sapling API provides a set of very
99
                simple classes and methods to construct "sapling trees"; once constructed, these can then be converted using a single method call to a
100
                full XDM tree. They can also be used without conversion as input to a transformation, serializer, or schema validator.
101
                Sapling trees use immutable (or "persistent") data structures, so a tree can be built incrementally without the overhead of copying
102
                objects when a subtree is added to a parent tree. Details of the API can be found in the Javadoc for class 
103
                <code java="net.sf.saxon.sapling.SaplingNode">SaplingNode</code>.</p></li>
104
            <li><p>The <code>Push</code> API is modelled on existing APIs such as the SAX <code>ContentHandler</code> and
105
            the StAX <code>XMLStreamWriter</code>, but attempts to achieve much higher levels of usability, especially for constructing
106
            simple documents. The need for a stable API at this level arises partly because a number of Saxon users have taken to using
107
            the <code>Receiver</code> interface, which is complex and error-prone to use, and is not always stable between releases. The new
108
                <code>Push</code> API is documented at <code java="net.sf.saxon.s9api.Push">net.sf.saxon.s9api.Push</code>.
109
                A <code>Push</code> provider allowing the application to write to any 
110
                <code java="net.sf.saxon.s9api.Destination">Destination</code> may be obtained by calling <code>Processor.newPush()</code>.</p></li>
111
        </ul>
112
        
113
        <h2>Serialization</h2>
114
        
115
        <p>The s9api <code java="net.sf.saxon.s9api.Serializer">Serializer</code> object has new methods allowing any JAXP
116
            <code>Source</code> to be serialized. This
117
        allows for direct pass-through from an XML parser to a serializer (for example, to add indenting), for serialization of
118
        DOM trees, Sapling trees, and trees in third-party tree models.</p>
119
        
120
        <h2>XSLT and default namespaces</h2>
121
        
122
        <p>The <code java="net.sf.saxon.s9api.XsltCompiler">XsltCompiler</code> object has two new properties that can be set:</p>
123
        
124
        <ul>
125
            <li><code>setDefaultElementNamespace()</code> sets the default namespace for elements and types: in effect, a
126
                default for the <code>xpath-default-namespace</code> attribute. (If an explicit <code>xpath-default-namespace</code>
127
            is present in the stylesheet, the API setting is ignored.)</li>
128
            <li><code>setUnprefixedElementMatchingPolicy()</code> sets the policy for handling unprefixed element names appearing
129
            in XPath expressions and match patterns. Three values are supported: <code>DEFAULT_NAMESPACE</code> (this is the default,
130
            as specified in the W3C specification); <code>ANY_NAMESPACE</code>, which causes such names to match by local part only,
131
            ignoring the namespace; and <code>DEFAULT_NAMESPACE_OR_NONE</code>, which causes such names to match (a) elements
132
            in the default namespace, and (b) elements in no namespace. This is designed primarily to approximate the special
133
            rules defined in the HTML5 specification for matching unprefixed element names.</li>
134
        </ul>
135
        
136
        <h2>ErrorListener and ErrorReporter</h2>
137
        
138
        <p>A new mechanism for reporting errors to user applications has been introduced. The new 
139
          <code>ErrorReporter</code> interface is a functional replacement for the old <code>ErrorListener</code>,
140
          though the <code>ErrorListener</code> interfaces are retained for the time being for backwards
141
        compatibility.</p>  
142
      
143
      <p>The <code>ErrorListener</code> class as defined in JAXP has a number of
144
        disadvantages:</p>
145
        
146
        <ul>
147
            <li>All errors and warnings are reported as <code>Exception</code> objects, which are very expensive to construct and
148
            occupy a lot of memory; exceptions are not appropiate for holding error information unless the exception is actually thrown.</li>
149
            <li>The exceptions are instances of the JAXP <code>TransformerException</code> class, which links them to XSLT and makes
150
            it clumsy to reuse the mechanism for use outside XSLT.</li>
151
            <li>The distinction between the <code>warning()</code>, <code>error()</code>, and <code>fatalError()</code>
152
            callbacks has never been entirely clear; it is motivated by distinctions in the XSLT 1.0 specification that
153
            have changed in subsequent versions of XSLT, and have never related clearly to errors in other contexts such as schema
154
            validation.</li>
155
          <li>The <code>ErrorListener</code> methods are allowed to throw a checked exception, but the effect of doing
156
          so has never been very well defined. The fact that they can throw checked exceptions has a pervasive effect;
157
          it means that any method within Saxon that issues a warning has to declare that it is capable of throwing
158
          an exception, and this cascades to its callers. In the past Saxon has used an <code>UnfailingErrorListener</code>
159
          internally to limit the damage, but this only complicates the design.</li>
160
            <li>Generally, a processing task (such as an XSLT compilation episode, or an XSLT execution) will make a sequence of calls
161
            to an <code>ErrorListener</code> and to be useful, different concurrent tasks need to write their messages to different
162
            <code>ErrorListeners</code> so that the output messages can be distinguished. This makes APIs that set an <code>ErrorListener</code>
163
            on a shared object (such as the Saxon <code>Configuration</code> or the JAXP <code>TransformerFactory</code>) troublesome
164
                as regards thread safety. For the JAXP <code>TransformerFactory</code> this has been addressed by making the
165
            <code>newTemplates()</code> method synchronised; it is therefore no longer possible for two concurrent stylesheet compilations
166
            to interleave their error messages to the same <code>ErrorListener</code>. At the Saxon <code>Configuration</code> level
167
            it is no longer possible to set an <code>ErrorListener</code> as a configuration property.</li>
168
        </ul>
169
        
170
        <p>The replacement <code>ErrorReporter</code> interface has a single method (<code>report</code>), and is defined as a Java 
171
          <code>FunctionalInterface</code>, which makes it convenient to supply an <code>ErrorReporter</code> in the form 
172
          of a lambda expression. The object passed to the <code>report()</code> method (in general, an 
173
          <code>XmlProcessingError</code>) is not itself an exception (though in some cases it may wrap an exception),
174
          which means that Saxon does not have to create exception objects unnecessarily. The <code>report()</code> method 
175
          throws no checked exceptions. The severity of the error (warning, error, or fatal) is defined as a property of the
176
        error object, rather than being distinguished by calling different methods of the error handler. The error handler
177
        is allowed to upgrade the severity of the error.</p>
178
        
179
        <p>Interfaces at the s9api level continue to accept an <code>ErrorListener</code> for backwards compatibility, but the methods
180
            have been deprecated. Interfaces deeper in the Saxon internals have dropped support for the <code>ErrorListener</code>.</p>
181
        
182
        
183
      
184
        <p>In previous releases, although it was not documented, an <code>ErrorListener</code> that was set on the
185
        <code>XsltCompiler</code> was inherited by any <code>XsltTransformer</code> or <code>Xslt30Transformer</code>
186
        created from that <code>XsltCompiler</code>. This is no longer the case (and the same is true if an <code>ErrorList</code>
187
        or <code>ErrorReporter</code> is provided).</p>
188
      
189
        <h2>XPathCompiler</h2>
190
        
191
        <p>A new method is added for <code java="net.sf.saxon.s9api.XPathCompiler">XPathCompiler</code>: <code>addXsltFunctionLibrary()</code>. This takes an <code>XsltPackage</code> as argument,
192
        representing a compiled XSLT 3.0 library package. The global public functions in the package (those declared using <code>&lt;xsl:function visibility='public'&gt;</code>)
193
        become available for calling from XPath expressions compiled using this <code>XPathCompiler</code>.</p>
194
  
195
    </category>
196
    
197
    <category name="spi">
198
        
199
        <h2>Sequence and SequenceIterator</h2>
200
        
201
        <p>The class <code>Sequence</code>, and its many subclasses such as <code>GroundedValue</code> and <code>Item</code>, 
202
            were changed in Saxon 9.9 to use Java Generics; the same change was also made to <code>SequenceIterator</code>
203
            and its many subclasses. This change has been reverted in Saxon 10. The reason for this is basically that the change added
204
            a lot of complexity and delivered no benefits: an analysis of the motivation can be found in a 
205
            <a href="http://dev.saxonica.com/blog/mike/2020/01/java-generics-revisited.html">Saxon blog article</a>.</p>
206
        
207
        <h2>NodeInfo</h2>
208
        
209
        <p>The way in which namespaces are represented in the <code java="net.sf.saxon.om.NodeInfo">NodeInfo</code> interface has changed, to be closer to the
210
        XDM model. Instead of <code>getDeclaredNamespaces()</code>, which returned the namespace information as a set of
211
        declarations and undeclarations relative to the parent element, the interface now has <code>getAllNamespaces()</code>,
212
            which returns all the in-scope namespaces as a <code java="net.sf.saxon.om.NamespaceMap">NamespaceMap</code> object.
213
            This brings the API much closer to the way that the XDM data model
214
        is defined, which ultimately makes it easier to use. The potential inefficiency of having namespaces defined redundantly
215
        on every single element node is handled by sharing <code>NamespaceMap</code> objects (so two elements with the same
216
            in-scope namespaces share the same <code>NamespaceMap</code>). The <code>NamespaceMap</code> object is immutable,
217
        which makes such sharing easy to manage.</p>
218
        
219
        <ul>
220
            <li><p>The native tree models in Saxon (the TinyTree and LinkedTree) implement this by maintaining stored <code>NamespaceMap</code>
221
                objects within the internal data structure. The tree builders ensure that these objects are shared, so that a child element
222
                with no local namespace declarations will point to the same <code>NamespaceMap</code> object as its parent element.
223
                In many documents, namespaces are all declared on the root element, so there will only be one <code>NamespaceMap</code> object
224
                for the whole document.</p></li>
225
            <li><p>The external tree models (DOM, XOM, JDOM2, etc.) generally cache the <code>NamespaceMap</code> for an element, so
226
                computing the in-scope namespaces for an element involves getting the cached <code>NamespaceMap</code> for the
227
            parent element, and then making any changes needed if there are local namespace declarations or undeclarations present on
228
            the child element.</p></li>
229
        </ul>
230
        
231
        <p>To make it easier to iterate over the children of a node, the <code>NodeInfo</code> interface now has a method
232
        <code>children()</code> returning <code>Iterable&lt;NodeInfo&gt;</code>. The method has a default implementation.
233
        This makes it possible to use a Java "for each":</p>
234
        <samp>for (NodeInfo child : children()) { ... }</samp>
235
        
236
        <p>There is also a variant of <code>children()</code> that takes a Java <code>Predicate</code> as its second argument. 
237
            The <code>NodeTest</code> class now implements <code>Predicate&lt;NodeInfo&gt;</code>, so you can write for example:</p>
238
        
239
        <samp>for (NodeInfo childElement : children(NodeKindTest.ELEMENT)) { ... }</samp>
240
        
241
        <p>which processes the children of a node that are themselves element nodes.</p>
242
        
243
        <p>Similarly, there is a new method <code>attributes()</code> which returns an <code>AttributeMap</code>. This class
244
            replaces the old <code>AttributeCollection</code> throughout the product. The most notable differences are (a) an <code>AttributeMap</code>
245
            is immutable, and (b) its primary access is as an <code>Iterable</code>, rather than using integer subscripts to index into it.
246
            There are different implementations of <code>AttributeMap</code> depending on the number of attributes; for larger attribute sets,
247
            a hash trie structure is used to give faster access by name, and to enable addition of attributes without copying the whole structure.</p>
248
        
249
        <p>The method <code>NodeInfo.iterateAxis(axisNumber, condition)</code> has been generalized to take a Java <code>Predicate</code> as its 
250
            second argument.</p>
251
        
252
        
253
        <h2>Receiver</h2>
254
        
255
        <p>The <code>Receiver</code> interface has been forked into two interfaces: <code>Receiver</code> and <code>Outputter</code>.</p>
256
        
257
        <ul>
258
            <li><p>The new <code java="net.sf.saxon.event.Receiver">Receiver</code> interface receives information about the start 
259
                of an element in a single call containing
260
                information about the element name and type, the in-scope namespaces of the element, and the attributes of the element.
261
                This interface is used in the validation pipeline and
262
                the serialization pipeline, where it simplifies many of the operations performed by these complex pipelines.</p></li>
263
        
264
            <li><p>The <code java="net.sf.saxon.event.Outputter">Outputter</code> interface splits the start-of-element information across a sequence of calls: <code>startElement()</code> for the element
265
                name and type, one call on <code>namespace()</code> for each namespace declaration, one on <code>attribute()</code>
266
                for each attribute, and finally a call on <code>startContent()</code> (which in some cases may be implicit).
267
                The <code>Outputter</code> interface is used primarily to capture the result of push-mode XSLT and XQuery instructions,
268
        notably instructions that generate elements and attributes. It's necessary in this case to be able to capture attributes
269
        and namespaces as independent events because instructions can generate them as separate events. Most commonly these
270
        instructions feed directly into a <code java="net.sf.saxon.event.ComplexContentOutputter">ComplexContentOutputter</code>, which amalgamates start tag events into a single
271
        <code>startElement()</code> call which is then sent to a <code>Receiver</code> pipeline.</p></li>
272
        </ul>
273
        
274
        
275
        
276
        <h2>DateTimeValue</h2>
277
        
278
        <p><code java="net.sf.saxon.value.DateTimeValue">DateTimeValue</code> and related classes such as
279
          <code java="net.sf.saxon.value.DateValue">DateValue</code> and <code java="net.sf.saxon.value.TimeValue">TimeValue</code> 
280
          provide additional constructors and getter methods supporting conversion to or from: 
281
            <code>java.time.Instant</code>, <code>java.time.LocalDateTime</code>,
282
            <code>java.time.OffsetDateTime</code>, <code>java.time.ZonedDateTime</code>, and <code>java.time.LocalDate</code>.</p>
283
        
284
        <p>Conversion of <code>DateTimeValue</code> to/from classes in the <code>java.time</code> package now retains
285
        nano-second precision (previously, it only retained micro-second precision).</p>
286
        
287
        <h2>Miscellaneous</h2>
288
        
289
        <p>For push-mode instruction execution, the current receiver/outputter is no longer held in the <code>XPathContext</code>
290
            object. Instead it is passed to the relevant methods (such as <code>Expression.process()</code>) as an explicit parameter.
291
            This reduces the need to create new <code>XPathContext</code> objects.</p>
292
        
293
        <p>The <code java="net.sf.saxon.pull.PullProvider">PullProvider</code> interface has changed to use a type-safe
294
            <code>enum</code> class for event types rather than integer constants.</p>
295
        
296
        <p>The <code java="net.sf.saxon.om.SequenceIterator">SequenceIterator</code> interface has changed: the
297
            <code>getProperties()</code> method now returns a type-safe <code>EnumSet</code> rather than an integer with
298
            bit-significant flags.</p>
299
      
300
        <p>Saxon has generally moved to the use of EQName notation (<code>Q{uri}local</code>) 
301
          in preference to Clark names (<code>{uri}local</code>) for internal use. Clark names
302
        are still used where mandated by the JAXP specification, and in other stable APIs. 
303
        In lower-level system programming interfaces, however, applications may notice the 
304
        change. For example the change affects the representation of output properties such as
305
        <code>method</code> and <code>cdata-section-elements</code>, which are exposed to
306
        user-written serialization methods and customised serializers.</p>
307
        
308
        <h2>Dropped interfaces</h2>
309
        
310
        <p>The method <code>StaticQueryContext.setExternalNamespaceResolver()</code> is dropped (it has been present in the product
311
        for many years but appears to be untested, and its intended behavior is unclear).</p>
312
        
313
        <p>Some long-deprecated classes and methods have been dropped, including those listed below. The general principle is that
314
        methods deprecated since 9.7 or earlier have all been dropped; methods first deprecated in 9.8 have been dropped if they
315
        were producing no useful effect in 9.9 (for example, setter methods that did nothing).</p>
316
        <ul>
317
            <li><code>StaticQueryContext.buildDocument()</code>, deprecated since Saxon 9.2 (use a s9api <code>DocumentBuilder</code>)</li>
318
            <li><code>Configuration.buildDocument(Source)</code> and <code>Configuration.buildDocument(Source, ParseOptions)</code>,
319
                deprecated since Saxon 9.7 (use a s9api <code>DocumentBuilder</code>,
320
                or <code>Configuration.buildDocumentTree()</code>)</li>
321
            <li><code>net.sf.saxon.om.DocumentInfo</code>, since 9.7 used only by deprecated methods</li>
322
            <li><code>AbstractStaticContext.declareCollation()</code>, <code>StaticQueryContext.declareCollation()</code>, and
323
                <code>StaticContext.getCollation()</code>, deprecated since 9.6 (collations should be now registered at the level of the
324
            <code>Configuration</code>)</li>
325
            <li><code>XsltTransformer.setInitialContextNode()</code>, deprecated since 9.7 (use <code>setGlobalContextItem()</code>)</li>
326
            <li><code>Xslt30Transformer.setInitialContextItem()</code>, deprecated since 9.8 (use <code>setGlobalContextItem()</code>)</li>
327
            <li><code>XQueryExpression.pull()</code>, deprecated since 9.8 (use <code>run()</code>)</li>
328
            <li><code>ParseOptions.setStripSpace()</code>, <code>AugmentedSource.setStripSpace()</code>,
329
                <code>ParseOptions.getStripSpace()</code> and <code>AugmentedSource.getStripSpace()</code>,
330
                deprecated since 9.8 (use <code>setSpaceStrippingRule()</code>)</li>
331
            <li><code>XsltCompiler.compilePackages()</code> and <code>addCompilePackages()</code>, deprecated since 9.8 (use a
332
                <code>PackageLibrary</code>)</li>
333
            <li><code>BuildingStreamWriter.setInventPrefixes()</code> and <code>isInventPrefixes()</code>, deprecated since 9.7. The method previously
334
            had no effect, so the call can be dropped. (Note, the method was previously marked as deprecated in the implementation class,
335
            but not in the interface.)</li>
336
            <li><code>CollectionURIResolver</code> and associated methods: deprecated since 9.7. (Use a <code>CollectionFinder</code>.
337
                If necessary, wrap the old <code>CollectionURIResolver</code> in a <code>CollectionURIResolverWrapper</code>, whose
338
                source code can be found in Saxon 9.9.)
339
            This change also causes <code>Feature.COLLECTION_URI_RESOLVER</code> and <code>Feature.COLLECTION_URI_RESOLVER_CLASS</code> to
340
            be dropped, as well as the <code>-cr</code> option on the <code>Transform</code> and <code>Query</code> command line.</li>
341
            <li><code>CompilerInfo.setExtensionFunctionLibrary()</code> and <code>getExtensionFunctionLibrary()</code>: deprecated
342
                since 9.7 (use other mechanisms, such as packages)</li>
343
        </ul>
344
      
345
        <p>The methods <code>setRecoveryPolicy</code> and <code>getRecoveryPolicy</code> have been dropped from
346
        the <code>Configuration</code> and <code>CompilerInfo</code> classes, along with the configuration feature
347
        <code>Feature.RECOVERY_POLICY</code>. In recent releases the only remaining effect of this switch was
348
        to provide a default for the <code>xsl:mode</code> attributes <code>on-multiple-match="fail"</code> and
349
        <code>warning-on-multiple-match="true"</code>; this must now be controlled via the <code>xsl:mode</code>
350
        declaration in the stylesheet.</p>
351
        
352
        <h2>Tracing</h2>
353
        
354
        <p>The mechanism supporting execution tracing (including the -T and -TP options on the command line) has been substantially
355
        revamped, involving some changes to interfaces:</p>
356
        
357
        <ul>
358
            <li>If a <code java="net.sf.saxon.expr.parser.CodeInjector">CodeInjector</code> is nominated, it now operates as a
359
                pass over the fully-constructed expression tree,
360
            rather than being invoked by the XSLT and XPath parsers as expressions and instructions are created. This means that
361
            it now visits every node in the expression tree, not only selected nodes as before. Of course a <code>CodeInjector</code>
362
            can always ignore nodes that it is not interested in. The new mechanism opens the way to much more variety in the kind of
363
            instrumentation tasks that the <code>CodeInjector</code> can undertake.</li>
364
            
365
            <li>The object passed to the <code java="net.sf.saxon.lib.TraceListener">TraceListener</code> at run-time is now a
366
                <code java="net.sf.saxon.trace.Traceable">Traceable</code>, replacing the
367
            old <code>InstructionInfo</code>. A <code>Traceable</code> is either an expression, or a component such as a
368
            <code>UserFunction</code>, <code>GlobalVariable</code>, or <code>TemplateRule</code>.
369
            The <code>InstructionInfo</code> class was something of a rag-bag, and duplicated a lot
370
            of information that in the last few releases has been mantained in the <code>RetainedStaticContext</code> and <code>Location</code>
371
            objects attached to the expression itself.</li>
372
            
373
            <li>This has enabled the dropping of a number of auxiliary classes such as <code>InstructionDetails</code> and 
374
                <code>LocationKind</code>.</li>
375
            
376
            <li>The way in which expressions are identified by the <code>StandardErrorListener</code> is now better aligned with the
377
            way they are identified by the <code>TraceListener</code>.</li>
378
            
379
            <li>In the <code>CodeInjector</code> and <code>TraceListener</code> interfaces, default implementations of methods are
380
            now provided; among other things, this eliminates the need for the <code>TraceListener2</code> interface.</li>
381
        </ul>
382
        
383
        <h2>ErrorListener</h2>
384
        
385
        <p>The <code java="net.sf.saxon.lib.StandardErrorListener">StandardErrorListener</code> and <code
386
            java="net.sf.saxon.lib.StandardInvalidityHandler">StandardInvalidityHandler</code> have been refactored internally
387
        (a) to make better reuse of common code, and (b) to make it easier to write customised subclasses to achieve tailored
388
        diagnostic output. To this end, some static methods have been replaced by non-static methods, and large methods have been
389
        split into smaller pieces, documented to allow them to be overridden. A consequence of these changes is that existing
390
        user-written code subclassing these two classes may need changing. If this is onerous, one way of getting around the problem
391
        is to copy the open-source implementations of these methods from the Saxon 9.9 distribution, and rename this as a user-defined
392
        class.</p>
393
        
394
        <p>A new configuration option <code>Feature.RETAIN_NODE_FOR_DIAGNOSTICS</code> is provided. If set, this causes the location information
395
        associated with instructions and expressions in an XSLT stylesheet to retain a reference to the node in the stylesheet tree where the
396
        error occurred (rather than simply retaining the node name and line number). This information can be useful to IDEs that wish to highlight
397
        where in the source the error occurred. The information is retained both for static and dynamic error reporting. The option is off by default 
398
        because retaining the links prevents the temporary data used during compilation being garbage-collected. Previous releases attempted to retain
399
        the information for static errors but not for dynamic errors; it is now retained for both, but only if this option is set.</p>
400
 
401
        </category>
402
    
403
    <category name="extensibility">
404
        
405
        <p>Reflexive extension functions now support conversion between:</p>
406
        
407
        <ul>
408
            <li><code>xs:dateTime</code> and <code>java.time.Instant</code>, <code>java.time.LocalDateTime</code>,
409
                <code>java.time.OffsetDateTime</code>, and <code>java.time.ZonedDateTime</code></li>
410
            <li><code>xs:date</code> and <code>java.time.LocalDate</code></li>
411
        </ul>
412
 
413

  
414
    </category>
415
    
416
    <category name="optimization">
417
      
418
      <p>Some optimizations that were previously done in Saxon-HE have been moved into Saxon-EE.
419
      The aim is to clarify and simplify the differentiation of the products, and the change compensates
420
      for the move of some functionality (such as higher order functions) into Saxon-HE.</p>
421
      
422
      <p>Certain optimizations are now placed under a new optimization category <code>n</code> (constant folding), and can therefore be enabled
423
        or suppressed by setting this optimization option. The category includes compile-time evaluation of simple expressions such as arithmetic
424
        expressions (<code>2+2</code>) or function calls (<code>boolean(1)</code>), and compile-time evaluation of function calls and other
425
        expressions where it is known what the result will be if one of the operands is empty (<code>2+()</code>).</p>
426
      
427
      
428
        <p>The amount of memory needed for the indexes used to support <a class="bodylink code"
429
            href="/xsl-elements/key">xsl:key</a> has been reduced, particularly in the common cases
430
        (a) where the keys are strings compared using codepoint collation, and (b) where the key values are unique.</p>
431
        
432
        <p>A new <code java="net.sf.saxon.expr.CompareToStringConstant">CompareToStringConstant</code> expression has been
433
            introduced for value comparisons of the form <code>EXPR eq "literal"</code>
434
        (with any of the permitted operators) using Unicode codepoint collation.</p>
435
        
436
        <p>The <a class="bodylink code" href="/xsl-elements/where-populated">xsl:where-populated</a> instruction now has a
437
            push-mode implementation. (The push-mode implementation already existed in principle, but it was incomplete, and was
438
            used only when streaming.)</p>
439
        
440
        <p>A number of functions that are capable of returning large strings (<code>concat</code>, 
441
            <code>string-join</code>, <code>unparsed-text</code>, <code>xml-to-json</code>) are now able in appropriate cases
442
            to stream their output incrementally to the serializer rather than materializing the result as a string in memory.</p>
443
        
444
        <p>Match patterns of the form <code>match="$nodeset"</code> where <code>$nodeset</code> is a global variable are now optimized
445
        (Saxon-EE only): the variable is stored in an indexed form that allows a quick lookup of whether a particular node is present,
446
        without a serial search of the entire node-set.</p>
447
        
448
        <p>A new implementation of XDM maps, the <code>DictionaryMap</code>, is used in cases where all the keys will be
449
        simple strings, and further changes to the map are considered unlikely. For example, this is used to represent a map constructed by 
450
            <code>fn:parse-json()</code>. Optimizing for string-valued keys saves space, and makes lookup faster, while optimizing
451
        for immutability enables the standard Java HashMap structure to be used internally. If <code>map:put()</code> or <code>map:remove()</code>
452
        are used on such a map, it is first copied in its entirety to a new <code>HashTrie</code> using the existing data structure.
453
        The <code>DictionaryMap</code> is internally mutable during its construction phase, so adding entries incrementally during the course
454
        of an operation such as <code>fn:parse-json()</code> is much more efficient than if a pure immutable structure were used.</p>
455
        
456
        
457
        <p>Node tests of the form <code>*:NAME</code> (and predicates of the form <code>*[local-name() = 'NAME']</code>), when executed against
458
        a TinyTree, are now more efficient: the first time such a test is used against a particular tree, an index is built mapping local names
459
        present in the tree to integer fingerprints, and the search then compares fingerprints rather than looking up each node name in the
460
        name pool and comparing strings.</p>
461
        
462
        <p>Sorting is now done using the standard sort routines in the JDK, rather than the third-party library that was previously used.
463
        In some cases this has been found to give a substantial performance boost (for example, in the common case where a node sequence is sorted into document order,
464
        and the input is already sorted or nearly sorted).</p>
465
        
466
        <p>At various stages in the 9.8 and 9.9 releases, attempts were made to introduce an optimization for copying of subtrees.
467
        One approach was "bulk copy", which attempted to copy part of a tinytree into another tinytree by combining the low-level
468
        data structures, rather than by node-by-node copying at the logical level. Another attempt was "grafting", whereby a subtree
469
        could by physically shared between two or more trees, while representing distinct nodes at the logical level. Both attempts
470
        have now been abandoned. Although they gave good performance results, there were so many restrictions that they weren't
471
        invoked very often; and the implementation had so many complexities (primarily related to namespace handling) that it 
472
        proved near impossible to get all the edge cases correct.</p>
473
    </category>
474

  
475
    <category name="installation">
476
         <p>Saxon 10 introduces a change to the version numbering policy. In future three-part version numbers will be used.
477
         Major releases will be numbered 10, 11, 12, etc; maintenance releases will use the second component 10.1, 10.2 and so on, while
478
         the third digit will be used only to distinguish internal or limited-release builds. JAR files will carry the two-part
479
         version number in their names, for example <code>saxon-ee-10.3.jar</code>.</p>
480
      
481
        <p>In previous releases, higher-order functions and <a class="bodylink code"
482
            href="/xsl-elements/evaluate">xsl:evaluate</a> (which are optional features
483
        in the W3C specifications) required Saxon-PE or higher. From Saxon 10, they are available in Saxon-HE.</p>
484
      
485
        <p>On the other hand, a few optimizations which were previously available across all editions are
486
        now restricted to Saxon-EE.</p>
487
      
488
        <p>Along with Saxon 10, new commercial product offerings are being introduced (for example,
489
        for deployment "in the cloud"). These entail the introduction of subscription-based licenses with
490
        a built-in expiry date.</p>
491
         
492
    </category>
493

  
494
    <category name="serialization">
495
        
496
        <p>The default HTML version (when not explicitly specified using the <code>version</code> or <code>html-version</code>
497
        serialization properties) is now HTML5.</p>
498
      
499
      <aside>The most obvious consequence of this change is that the HTML output will start with
500
      <code>&lt;!DOCTYPE HTML&gt;</code>. If you have regression tests that perform character-by-character
501
      comparison against expected results, these tests may need to change.</aside>
502
 
503
    </category>
504
    
505
    <category name="command-line">
506
        
507
        <h2>net.sf.saxon.Transform</h2>
508
        
509
        <p>A new option <code>-ns</code> is available on the <code>net.sf.saxon.Transform</code> command line (see <a
510
            class="bodylink" href="/using-xsl/commandline">Running XSLT from the Command Line</a>). It can be used
511
        to specify the default namespace for elements and types (in effect, a default for the <code>xpath-default-namespace</code>
512
        attribute). In addition, the value <code>-ns:##any</code> means that unprefixed element names appearing in path expressions and
513
        match patterns will match elements in any namespace (or none), and the value <code>-ns:##html5</code> simulates the rules
514
        in the HTML5 specification, meaning that unprefixed element names match elements that are either in no namespace, or in the
515
        XHTML namespace.</p>
516
        
517
        <p>The option <code>-warnings</code> is now ignored.</p>
518
        
519
        <h2>Gizmo Commands</h2>
520
        
521
      <p>A new interactive command-based utility called <b>Gizmo</b> is available. See <a
522
        class="bodylink" href="/gizmo">Gizmo</a> for details.</p>
523
      
524
        <p>The utility is invoked using a command such as:</p>
525
        
526
        <samp>java net.sf.saxon.Gizmo -s:catalog.xml </samp>
527
      
528
        <p>It then allows sub-commands to be entered, including the ability to:</p>
529
      
530
         <ul>
531
           <li>Execute XPath expressions and display their results</li>
532
           <li>Make modifications to a document such as renaming, deleting, or inserting nodes</li>
533
           <li>Perform XSD validation and XSLT transformation</li>
534
           <li>Save a modified document to filestore</li>
535
         </ul>
536
      
537
        <p>The utility provides assisted content completion based on the actual vocabulary of the
538
        individual document, and it allows previous commands to be retrieved from the session history.</p>
539
  
540
       
541
        
542
    </category>
543
    
544
    <category name="extensions">
545
        
546
        
547
        
548
        <h2>Extension Functions</h2>
549
      
550
      <p>A number of new extension functions are available:</p>
551
      
552
      <ul>
553
        <li>
554
          <p><a class="bodylink code"
555
            href="/functions/saxon/analyze-uri">saxon:analyze-uri($string)</a></p>
556
          <p>Parses a supplied URI, returning a map containing its various components
557
            (such as the scheme, port, path, fragment, and query).</p>
558
         
559
        </li>
560
        <li>
561
          <p><a class="bodylink code"
562
            href="/functions/saxon/characters">saxon:characters($string)</a></p>
563
          <p>Splits the supplied string into a sequence of single-character strings.</p>
564
        </li>
565
        <li>
566
          <p><a class="bodylink code" href="/functions/saxon/EQName">saxon:EQName($string)</a></p>
567
          <p>Given a string in the form of a lexical EQName, returns the corresponding <code>xs:QName</code> value.</p>
568
        </li>
569
        <li>
570
          <p><a class="bodylink code"
571
            href="/functions/saxon/in-scope-namespaces">saxon:in-scope-namespaces($element)</a></p>
572
          <p>Returns the in-scope namespaces of an element, in the form of a map from prefixes to URIs.</p>
573
        </li>
574
        <li>
575
          <p><a class="bodylink code"
576
            href="/functions/saxon/index-where">saxon:index-where($sequence, $predicate)</a></p>
577
          <p>Returns the integer positions of items in the sequence that match the supplied predicate
578
            function.</p>
579
        </li>
580
        
581
        <li>
582
          <p><a class="bodylink code"
583
            href="/functions/saxon/is-NaN">saxon:is-NaN($atomic)</a></p>
584
          <p>Returns true if the supplied argument is the <code>xs:float</code> or <code>xs:double</code>
585
            value <code>NaN</code>.</p>
586
        </li>
587
        
588
        <li>
589
          <p><a class="bodylink code" href="/functions/saxon/items-after">saxon:items-after($input, $predicate)</a></p>
590
          <p>Returns all items in the input sequence that follow the
591
            first item that matches the predicate.</p>
592
        </li>
593
        <li>
594
          <p><a class="bodylink code" href="/functions/saxon/items-before">saxon:items-before($input, $predicate)</a></p>
595
          <p>Returns all items in the input sequence that precede the
596
            first item that matches the predicate.</p>
597
        </li>
598
        <li>
599
          <p><a class="bodylink code" href="/functions/saxon/items-from">saxon:items-from($input, $predicate)</a></p>
600
          <p>Returns all items in the input sequence starting with the
601
            first item that matches the predicate.</p>
602
        </li>
603
        <li>
604
          <p><a class="bodylink code" href="/functions/saxon/items-until">saxon:items-until($input, $predicate)</a></p>
605
          <p>Returns all items in the input sequence up to and including the
606
            first item that matches the predicate.</p>
607
        </li>
608
        <li>
609
          <p><a class="bodylink code" href="/functions/saxon/parse-dateTime">saxon:parse-dateTime($string, $format)</a></p>
610
          <p>Parses dates and times in non-standard
611
            formats. The first argument is a string containing the value to be parsed; the second is a pattern giving the expected
612
            format, in the notation used by the Java <code>DateTimeFormatter</code> class. The result is an <code>xs:dateTime</code>,
613
            <code>xs:date</code>, <code>xs:time</code>, <code>xs:gYear</code>, <code>xs:gYearMonth</code>,
614
            <code>xs:gMonth</code>, <code>xs:gMonthDay</code>, or <code>xs:gDay</code> depending on the components that were
615
            actually present in the input value.
616
          </p>
617
        </li>
618
        <li>
619
          <p><a class="bodylink code" href="/functions/saxon/replace-with">saxon:replace-with()</a></p>
620
          <p>Similar to <code>fn:replace</code>, but instead of supplying a replacement string, the
621
            caller supplies a callback function that computes the replacement string from the matched
622
            substring.
623
          </p>
624
        </li>
625
        <li>
626
          <p><a class="bodylink code" href="/functions/saxon/tunnel-params">saxon:tunnel-params()</a></p>
627
          <p>Returns a map containing the values of all tunnel parameters (whether or not they are declared in the current template). The keys in the map
628
            are QNames (the parameter names); the corresponding values are arbitrary XDM values.
629
          </p>
630
        </li>
631
        
632

  
633
      </ul>
634
        
635
      <p>A number of changes have been made to existing extension functions:</p>
636
      <ul>
637
          <li><p>The <code>saxon:evaluate-node()</code> function is dropped. The functionality is
638
              available using <a class="bodylink code" href="/xsl-elements/evaluate">xsl:evaluate</a>
639
        in XSLT 3.0.</p></li>
640
        
641
        
642
        
643
        <li><p>The extension function <code>saxon:get-pseudo-attribute()</code> now parses the supplied input much more rigorously, applying the
644
            rules found in <a href="https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028/">the W3C specification</a>, and raising an error
645
            for invalid syntax that was previously allowed through.</p></li>
646
        
647

  
648
        
649
      </ul>
650
        <h2>Extensions to Standard Functions</h2>
651
        
652
        <p>Various Saxon-specific options have been provided for the <a class="bodylink code"
653
            href="/functions/map/merge">map:merge()</a> function: <code>saxon:on-duplicates</code>
654
        provides a call-back function for handling duplicate keys; <code>saxon:key-type</code> allows Saxon to optimize the resulting
655
        map if the keys are all strings; <code>saxon:final</code> allows Saxon to optimize for the case where no further changes to the
656
            content of the map are likely; <code>saxon:duplicates-error-code</code> defines an error code to be used when duplicate
657
        keys are encountered.</p>
658
        
659
 
660
        
661

  
662
 
663
        <h2>Extension Instructions</h2>
664
        
665
        <p>A new instruction <a class="bodylink code" href="/extensions/instructions/for-each-member">saxon:for-each-member</a> is
666
            available; it iterates over the members of a supplied array.</p>
667
        
668
        <p>For example:</p>
669
        
670
        <samp><![CDATA[<saxon:for-each-member select="[(1,2), (3,4)]" bind-to="m">
671
  <subtotal>{sum($m)}</subtotal>
672
</saxon:for-each-member>]]></samp>
673
        
674
        <p>outputs <code><![CDATA[<subtotal>3</subtotal><subtotal>7</subtotal>]]></code></p>
675
        
676
        <p>A new attribute <code>xsl:mode/@saxon:as</code> is available. Its value is a sequence type, with Saxon extensions permitted.
677
        This provides a default value for the <code>as</code> attribute of all template rules in the mode, unless they have their own
678
        required type defined in an <code>as</code> or <code>saxon:as</code> attribute. This is handy in cases where, for example, all the
679
        template rules in a particular mode are required to return a boolean value. It is particularly useful in cases where the return
680
        type is a complex tuple type, as this means that changes to the tuple type only need to be made in one place.</p>
681
        
682
        <h2>XPath Syntax Extensions</h2>
683
        
684
        <aside>XPath Syntax Extensions require Saxon-PE or higher, and are available only if the configuration option
685
            <a class="bodylink code"
686
                href="/configuration/config-features">Feature.ALLOW_SYNTAX_EXTENSIONS</a> is enabled.</aside>
687
        
688
        <h3>Tuple Types</h3>
689
        
690
        <p>The experimental syntax for declaring tuple types has been revised; the specification has been
691
            expanded and clarified, and the implementation is much more thoroughly tested. 
692
            The colon separating field name and required type has been replaced with "<code>as</code>"; and the 
693
            notation "<code>,*"</code>" can be used after the last field to indicate that the tuple type
694
            is extensible (that is, additional fields are permitted beyond those declared). In addition, field names
695
            that are not NCNames can now be used, written in quotes. For example, a tuple type may now
696
        be declared as <code>tuple(key as xs:string, 'max size' as xs:numeric?, value, *)</code>.</p>
697
      
698
        
699
        
700
        <h3>Item Type Aliases</h3>
701
        
702
        <p>Where named type aliases are defined in XSLT or XQuery, the syntax for referring to them in an XPath <code>SequenceType</code> has changed
703
        from <code>~typename</code> to <code>type(typename)</code>.</p>
704
        
705
        <h3>Processing all Members of an Array</h3>
706
        
707
        <p>A new <a class="bodylink" href="/extensions/syntax-extensions/for-member-expression">For-Member</a> expression is available to 
708
            process all the members of an array:</p>
709
        
710
        <p><code>for member $x in EXPR (, $y in EXPR)* return EXPR</code></p>
711
        
712
        <p>For example: <code>for member $m in [(3,5,6), (8,12)] return sum($m)</code> returns the sequence <code>(14, 20)</code>.</p>
713
        
714
        <p>This syntax is currently available only as a free-standing expression, not as a clause in a FLWOR expression; it has
715
        been designed, however, to allow integration into a FLWOR expression in the future.</p>
716
        
717
        <h3>Extensions to the Lookup Operator</h3>
718
        
719
        <p>Following a unary or binary "?" operator, Saxon now allows a string literal or variable reference to appear without
720
        surrounding parentheses: for example <code>$map?"first name"</code> or <code>[1 to 10]?$i</code>.</p>
721
        
722
        <h3>The <code>otherwise</code> Operator</h3>
723
        
724
        <p>The expression <code>chapter[title='Introduction'] otherwise chapter[1]</code> returns the chapter(s) whose title
725
        is "Introduction" if such a chapter exists, or the first chapter if not. More generally, <code>A otherwise B</code>
726
        returns <code>A</code>, unless it is an empty sequence, in which case it returns <code>B</code>.</p>
727
        
728
        <h3>KindTests</h3>
729
        
730
        <p>The syntax for the <code>element()</code> and <code>attribute()</code> <code>KindTests</code> is extended to allow constructs of the form
731
            <code>element(*:div)</code> or <code>attribute(myns:*, myns:someType)</code>.</p>
732
        
733
        <h3>Abbreviated inline functions</h3>
734
        
735
        <p>The expression <code>.{@x}</code> (referred to as a "dot function") is an anonymous inline function that 
736
            returns an attribute of the node passed as the
737
        function parameter. (This obsoletes the syntax <code>fn{@x}</code> introduced experimentally in Saxon 9.9,
738
        which is retained for the time being.) For example, <code>sort(//employee, .{@lastname, @firstname})</code>
739
        returns employees sorted by last name then first name. A dot function has signature <code>function(item()) as item()*</code>:
740
        that is, it has arity one, and expects a single item as its argument.</p>
741
        
742
        <p>The expression <code>_{$1 + $2}</code> (referred to as an "underscore function") is an anonymous inline
743
        function with two arguments, which may be of any type; it returns the sum of the two arguments. 
744
        The numeric variable references <code>$1</code>
745
        and <code>$2</code> refer to the argument values based on their position in the argument list. The arity
746
        of the function is determined from the highest numeric variable reference. It is not necessary to reference
747
        all the arguments other than the last, for example <code>_{$2}</code> is an arity-2 function that returns
748
        the value of the second argument, ignoring the first. The numeric argument references must appear directly
749
        in the body of the underscore function; they cannot be referenced in a nested inline function (whether or
750
        not this is itself an underscore function). For example, <code>for-each-pair((1,2,3), (4,5,6), _{$1 + $2})</code>
751
        returns <code>(5,7,9)</code>. The signature of the function in this example is 
752
            <code>function(item()*, item()*) as item()*</code>.</p>
753
        
754
        <p>As a special case, <code>_{12}</code> is a zero-arity function that always returns the value 12.</p>
755
        
756
        <h2>XSLT extensions</h2>
757
        
758
        <p>The <a class="bodylink code" href="/xsl-elements/map">xsl:map</a> instruction has acquired an extension attribute <code>saxon:on-duplicates</code>. The value is a user-supplied
759
            function which is called when map entries with duplicate keys are encountered. The function is supplied with the two conflicting
760
            values and can combine them to create a new value which is stored in the resulting map. This can be used to emulate all the
761
            options supplied on the <a class="bodylink code" href="/functions/map/merge">map:merge</a> function (use-first,
762
            use-last, combine, or fail) and to achieve other effects, for example delivering the sum, maximum, or string-join of
763
            the set of values associated with a single key, or selecting one of the values based on data such as a time-stamp
764
            attribute.</p>
765
        
766
        <p>Provided that Saxon syntax extensions are enabled, some extensions to XSLT 3.0 syntax
767
            are implemented:</p>
768
        
769
        <ul>
770
            <li><p>The <code>xsl:when</code> and <code>xsl:otherwise</code> elements can have a <code>select</code> attribute in place of a contained
771
                sequence constructor.</p></li>
772
            <li><p>The <code>xsl:if</code> elements can have a <code>then</code> attribute in place of a contained
773
                sequence constructor, and it can also have an <code>else</code> attribute.</p>
774
            <p>For example, this function found in a W3C specification:</p>
775
            <samp><![CDATA[<xsl:function name="f:product">
776
  <xsl:param name="seq"/>
777
  <xsl:choose>
778
    <xsl:when test="empty($seq)">
779
      <xsl:sequence select="1"/
780
    </xsl:when>
781
    <xsl:otherwise>
782
      <xsl:sequence select="head($seq) * f:product(tail($seq))"/>
783
    </xsl:otherwise>
784
  </xsl:choose>
785
</xsl:function>]]></samp>
786
                <p>Can now be written:</p>
787
                <samp><![CDATA[<xsl:function name="f:product">
788
  <xsl:param name="seq"/>
789
  <xsl:if test="empty($seq)" then="1" else="head($seq) * f:product(tail($seq))"/>
790
</xsl:function>]]></samp>
791
            </li>
792
        </ul>
793
      
794
        <p>Provided Saxon syntax extensions are enabled, a range of new match patterns can be defined, 
795
        particularly suitable when processing JSON. These include (by example):</p>
796
      
797
      <ul>
798
        <li><code>atomic(xs:integer)</code>: matches an atomic value of a given atomic type</li>
799
        <li><code>union(xs:integer, xs:date)</code>: matches an atomic value of a given union type</li>
800
        <li><code>map(xs:integer, element()*)</code>: matches a map of a given type</li>
801
        <li><code>array(xs:integer*)</code>: matches an array of a given type</li>
802
        <li><code>tuple(first, middle, last, *)</code>: matches a map conforming to a given tuple type</li>
803
      </ul>
804
      
805
      <p>All of these may be followed by optional predicates. Default priorities are defined, designed
806
      to reflect the type hierarchy so that more selective types have higher priority than less selective
807
      types; the rules for allocating priorities, however, should be regarded as provisional.</p>
808
        
809
        
810
        <p>The s9api <code java="net.sf.saxon.s9api.XsltCompiler">XsltCompiler</code> interface, and the <code>net.sf.saxon.Transform</code> command line, now
811
        allow a default namespace to be specified; this acts as a "default default" for the value of the <code>xpath-default-namespace</code>
812
            attribute, and it has no effect if an explicit value for <code>xpath-default-namespace</code> appears in the stylesheet.</p>
813
        
814
        <p>The s9api <code>XsltCompiler</code> interface, and the <code>net.sf.saxon.Transform</code> command line, also allow
815
        you to specify that unprefixed element names used in path expressions and match patterns should match by local name only,
816
        ignoring the namespace entirely. For example, a path <code>X/Y/Z</code> is then treated as if it were written <code>*:X/*:Y/*:Z</code>.
817
        This option overrides the effect of <code>xpath-default-namespace</code> in cases where it applies.</p>
818
        
819
        <p>A further option is to indicate that unprefixed element names should match elements either in the default namespace (as specified
820
        using <code>xpath-default-namespace</code>) or in no namespace. This option is provided primarily to reflect the XSLT/XPath
821
        variation defined in the HTML5 specification, which says that unprefixed element names should match elements in the XHTML namespace
822
        when the context item is a node "in an HTML DOM", and elements in no namespace otherwise. It is difficult to reproduce this
823
        rule precisely in Saxon, because it's not clear what being "in an HTML DOM" means when the data model is XDM (for example, does it apply
824
        to a node constructed by using <code>xsl:copy-of</code> applied to an HTML element?). But this option provides an approximation
825
        that ensures Saxon (in particular, Saxon-JS) will behave the same way as an XSLT 1.0 stylesheet running in the browser in most
826
        practical situations. The option applies when an NCName is used as a <code>NameTest</code> (on any axis other than the attribute and namespace
827
        axes) and to the element name in an <code>ElementTest</code> (that is, <code>element(name)</code>), whether in an XPath expression,
828
        a pattern, or a <code>SequenceType</code>. It does not apply to unprefixed type names or to names used in a <code>SchemaElementTest</code>
829
        (that is, <code>schema-element(name)</code>).</p>
830
        
831
        <!--<p>TODO: document this somewhere....</p>-->
832
        
833
        
834
        <h2>XSD extensions</h2>
835
        
836
        <p>The <a class="bodylink code" href="/schema-processing/extensions11/saxon.flags">saxon:flags</a> attribute of the
837
            <code>xs:pattern</code> facet was implemented in Saxon 9.9 but not
838
        documented or tested; it has now been made official. It allows flags for regular expression matching to be specified,
839
        following the rules for XPath functions such as <code>matches()</code>.</p>
840
        
841
        <p>A new attribute <a href="/schema-processing/extensions11/saxon.separator" class="bodylink
842
            code">xs:list/@saxon:separator</a> is available for list types. The attribute holds
843
        a regular expression that is used to tokenize the supplied value, according to the rules of the XPath <code>tokenize()</code>
844
        function. For example with <code>&lt;xs:list saxon:separator=","/></code>, a list of integers in an attribute can now be
845
        comma-separated rather than space-separated.</p>
846
        
847
        <p>A new constraining facet <a href="/schema-processing/extensions11/distinct" class="bodylink code">saxon:distinct</a> is
848
            available for list types; if present (with the value "true"), the list must not contain
849
            duplicate values. If a list type has this property, then any types derived by retriction must also have the property.</p>
850
        
851
        <p>A new constraining facet <a href="/schema-processing/extensions11/order" class="bodylink code">saxon:order</a> is
852
            available for list types. The value may be <code>ascending</code>
853
            or <code>descending</code>. If present, the items in the list must be
854
            in ascending or descending order (which implies that they must all be comparable). If a list type has this property, 
855
            then any types derived by retriction must have the same property.</p>
856
        
857
        <p>A new attribute <a href="/schema-processing/extensions11/saxon.order-unique" class="bodylink
858
            code">xs:unique/xs:field/@saxon:order="ascending|descending"</a> is available for use with uniqueness constraints.
859
            If the attribute is present on any field of a uniqueness constraint, it indicates that the fields participating in the
860
            constraint must not only have unique values, they must also be correctly ordered. If the attribute is present on at
861
            least one field of a uniqueness constraint, then it defaults to <code>saxon:order="ascending"</code> on any fields
862
            where it is not specified. 
863
        Not only does this provide another kind of integrity constraint that is quite hard to express using assertions, it also provides
864
        much more efficient checking of uniqueness constraints in the case where it is known that the data is correctly sorted.
865
        This validation check can be usefully applied to a document that is to form the input of the <code>xsl:merge</code> instruction
866
        in XSLT 3.0.</p>
867
        
868
       
869
        
870

  
871
        
872
 
873

  
874
    
875
    </category>
876
    
877
    <!--<category name="sql">
878
  
879
    </category>-->
880
    
881
    <category name="sourcedocs">
882
        
883
        <p>Support for JDOM version 1 is dropped. Applications should switch to JDOM2.</p>
884
        
885
        <p>Support for Saxon PTree files is dropped. PTree was a binary serialization format for XML documents. It never
886
        achieved the (space or time) performance characteristics of alternative third-party solutions such as EXI, which can be
887
        readily used for the same purpose.</p>
888
        
889
        <h2>Streaming</h2>
890
        
891
        <p>There have been significant internal changes to the implementation of XSLT 3.0 streaming; this should have
892
        no effect on applications, except to make a few cases streamable that were not previously handled. The basic
893
        architecture, whereby evaluation of child expressions triggers evaluation of parent expressions by passing
894
        events up a push pipeline, remains unchanged, but the actual implementation of the pipeline has changed
895
        considerably; in particular it is now closely aligned with the push pipeline interfaces used by the schema
896
        validator and the serializer, which enables much better re-use of code.</p>
897
        
898
 
899
    </category>
900
    
901
    <category name="xsd11">
902
       <p>There is a change to the way in which unresolved references to schema components
903
       are handled.</p>
904
      
905
      <p>The XSD specification (at both XSD 1.0 and 1.1) says that a schema should be treated
906
      as valid even though it contains references to missing components (for example, an
907
      attribute declaration referring to an <code>xs:simpleType</code> that has not been
908
      declared), provided that the missing components are not actually needed for validation.
909
      This provision has always been rather unsatisfactory. Saxon has attempted to implement
910
      it, but not always successfully. It doesn't help that the W3C conformance tests for XSD
911
      expect such schemas to be reported as invalid.</p>
912
      
913
      <p>In Saxon 10, by default, schemas containing such dangling references are reported
914
      as invalid.</p>
915
      
916
      <p>A new configuration option is provided to accept dangling references. In this case
917
      the schema compiler outputs a warning, and (where possible) generates a schema in which 
918
      the dangling references are "repaired".</p>
919
      
920
      <p>The repair strategies are as follows:</p>
921
      
922
      <ul>
923
        <li>Missing reference to a type: the type is substituted by <code>xs:error</code>,
924
        a type with no valid instances.</li>
925
        <li>Missing reference to a global element or attribute declaration: the declaration
926
        is substituted with a local element or attribute having type <code>xs:error</code>.</li>
927
        <li>Missing reference to a named attribute group or model group: the reference
928
        is replaced with a reference to an empty attribute group or model group. Note that
929
        this will not always lead to a run-time validation error.</li>
930
        <li>Missing reference to a substitution group: the reference is ignored.</li>
931
        <li>Missing reference from a type to its base type: this is always a fatal error
932
        and causes the schema to be treated as invalid.</li>
933
      </ul>
934
       
935
       
936
       
937
      
938
      <p>In earlier releases, when a missing component was detected at run-time (that is, during
939
        validation/assessment of a document instance) it was handled by throwing a 
940
        <code>MissingComponentException</code>.</p>
941
      
942
      <p>This exception has now been changed to an unchecked exception, so it does not have such
943
        an all-pervasive effect on the code. The result is that we can now attempt to provide more
944
        cases where absent components leave the schema usable; but with increased risk that references
945
        to components that are needed but absent cause a more severe failure when they occur.</p>
946
      
947
  
948
        
949
    </category>
950
    
951
    <category name="dotnet">
952
        
953
        <p>The classes <code java="Saxon.Api.Step">Step</code> and <code
954
            java="Saxon.Api.Predicate">Predicate</code> are now available on .NET. As on Java these
955
            classes can be used to navigate XML documents from the Saxon API. The extensions
956
            are designed to make it easier to manipulate the inputs and outputs of the XPath, XSLT,
957
            XQuery, and XSD processors directly in the Java or .NET code. (These were introduced for
958
            the Java s9api interface in Saxon 9.9, and more information can be found in the 9.9
959
            change log in the "S9API interface" category.) In the .NET API, <code>Step</code> and
960
            <code>Predicate</code> are wrapper classes for <code>Func</code>s, which map an
961
            <code>XdmItem</code> to an <code>IEnumerable</code> of <code>XdmItem</code> objects,
962
            or to a boolean value respectively. The <code java="Saxon.Api.Steps">Steps</code>
963
            and <code java="Saxon.Api.Predicates">Predicates</code> classes provide
964
            a library of useful predefined <code>Step</code> and <code>Predicate</code> functions.</p>
965

  
966
        <p>For use with the above classes, the <code java="Saxon.Api.XdmValue">XdmValue</code> class
967
            has a number of new methods. The <code>Select</code> method makes use of the
968
            <code>Step</code> class to apply a function to the items of the XDM value, to produce an
969
            <code>IEnumerable</code> of XDM items. The <code>Concat</code> method provides a way
970
            to concatenate two <code>IEnumerable</code> objects of <code>XdmItem</code>s.
971
            The methods <code>Where</code>, <code>AnyMatch</code> and <code>AllMatch</code> provide
972
            a way to filter the items of the <code>XdmValue</code> by some predicate.</p>
973
        
974
        <p>In addition, the <code java="Saxon.Api.XdmNode">XdmNode</code> class now has a
975
            <code>Select</code> method which applies a step navigation to the node object. The class also
976
            has new <code>Children</code> methods: the first has a single <code>Predicate</code>
977
            argument to filter the child nodes, while the other versions can be used to select the
978
            child nodes with a specified name.</p>
979

  
980
        <p>The <code java="Saxon.Api.XdmItem">XdmItem</code> class has a new <code>IsNode</code>
981
            method to provide an simple way to determine if the item is a node or some other type.</p>
982
        
983
        <p>The <code java="Saxon.Api.Processor">Processor</code> class now has the
984
            <code>BindExtensions</code> method which provides a simple way to load reflexive
985
            extension functions written in C# or VB.NET, as an alternative dynamic loading. The
986
            method passes Saxon a reference to the containing type.</p>
987

  
988
        <p>The enum type <code java="Saxon.Api.HostLanguage">HostLanguage</code> is added which
989
            provides a better way to identify the origins of an error.</p>
990

  
991
        <p>For the XPath, XQuery, and XSLT compilers it is now possible to set the error list as an
992
            <code>IList</code> of <code
993
                java="Saxon.Api.XmlProcessingError">XmlProcessingError</code> objects. This new
994
            error class provides more informative details about the error detected.</p>
995

  
996
        <p>The <code java="Saxon.Api.XsltCompiler">XsltCompiler</code> class now has a
997
            <code>ClearParameter</code> method to clear the values of all stylesheet parameters
998
            previously set.</p>
999
        
1000
    </category>
1001
    
1002
    <!--<category name="xquery-update">
1003
        
1004
  
1005
    </category>-->
1006
    
1007
    <!--<category name="xquery31">
1008
        
1009
 </category>-->
1010

  
1011

  
1012

  
1013
</release>
src/userdoc/changes/changes-10.xml
1
<?xml version="1.0" encoding="UTF-8"?>
2

  
3
<release number="10" date="2020-03-16" xmlns="http://www.saxonica.com/ns/doc/changes">
4
    
5
    <!--<category name="documentation">
6
        
7
    </category>-->
8
    
9
    <category name="xslt30">
10
      
11
        <p>Higher order functions and the <a class="bodylink code"
12
            href="/xsl-elements/evaluate">xsl:evaluate</a> instruction are now available in Saxon-HE.</p>
13
        
14
        <p>Error XTDE1160 (which occurs when an invalid fragment appears in the URI passed to the
15
            <a class="bodylink code" href="/functions/fn/document">document()</a> function)
16
        is now reported unconditionally; it is no longer a recoverable error. This change is in line with the XSLT 3.0
17
        specification. This was the last remaining "recoverable error", and in consequence, the configuration options controlling
18
        how recoverable errors were handled have now been dropped.</p>
19
        
20
        <p>Deterministic functions (specifically, the option <code>&lt;xsl:function new-each-time="no"&gt;</code>) are now
21
        available in Saxon-HE as well as Saxon-PE and Saxon-EE. This change is made because it is Saxonica policy that all
22
        mandatory features of the XSLT 3.0 specification should be available in Saxon-HE. Note: these functions are implemented
23
        as memo functions: the results of previous calls are remembered, and if a new call is made with the same arguments, the
24
        remembered result is returned. The main use case is in fact for the performance effect (using more memory to achieve
25
        higher speed) rather than for the rather technical effect of returning repeatable results. Setting the option <code>cache="yes"</code>
26
        achieves the same effect.</p>
27
        
28
        <p>Some extensions to XSLT 3.0 streaming capability have been implemented:</p>
29
        
30
        <ul>
31
            <li><p>The existing higher order function <a class="bodylink code" href="/functions/fn/filter">fn:filter</a>, and the
32
                new extension functions <a class="bodylink code"
33
                    href="/functions/saxon/items-after">saxon:items-after</a>, <a
34
                        class="bodylink code"
35
                        href="/functions/saxon/items-before">saxon:items-before</a>, <a class="bodylink code"
36
                            href="/functions/saxon/items-from">saxon:items-from</a>, and <a class="bodylink code"
37
                                href="/functions/saxon/items-until">saxon:items-until</a> are now streamable, under the right
38
                conditions. Provided that the second argument is either:</p>
39
                <ol>
40
                    <li>A function reference to a user-defined stylesheet function declared with <code>streamability=inspection</code>, or</li>
41
                    <li>An inline function whose body is grounded and motionless</li>
42
                </ol>
43
                <p>then the posture and sweep of the function call are the same as the posture and sweep of the first argument.</p>
44
                <p>For example, the call <code>saxon:ends-where(/article/*, function($e){$e[@title="Introduction"]})</code> processes all
45
                    sections of an article up to and including the one with title "Introduction". This call is striding and consuming
46
                    (which means that when used in an appropriate context it is streamable).</p>
47
            </li>
48
        </ul>
49
        
50
        
51
        
52
        <p>In interfaces that require Saxon to parse the <code>&lt;?xml-stylesheet?></code> processing instruction to locate a stylesheet,
53
            the parsing of the instruction now follows the <a href="https://www.w3.org/TR/2010/REC-xml-stylesheet-20101028/">W3C specification</a> much
54
        more rigorously, meaning that errors may now be detected that previously passed unnoticed.</p>
55
 
56
        <p>Saxon 10 is capable of generating SEF files suitable for Saxon 10 or Saxon-JS 2.0. The formats
57
        are different (the most obvious difference is that SEF files for Saxon 10 are in XML format, while
58
        those for Saxon-JS 2.0 are in JSON), so the right target must be selected when exporting. SEF files
59
        generated using Saxon 10 cannot be loaded by Saxon 9.9 or by Saxon-JS 1.x. SEF files generated using
60
        Saxon 9.9 or earlier releases cannot be loaded by Saxon 10.</p>
61
      
62
      <aside><p>Saxon-JS 2.0 is not available at the time of first release of Saxon 10; however,
63
      development is well advanced.</p></aside>
64
 
65
    </category>
66
    
67
    <category name="xpath31">
68
      
69
      <p>The higher-order functions optional feature is now available in Saxon-HE.</p>
70
 
71
    </category>
72
    
73
    <category name="functions31">
74
        
75
        <p>The <a class="bodylink code" href="/functions/fn/parse-json">parse-json()</a> and
76
            <a class="bodylink code" href="/functions/fn/json-doc">json-doc()</a> functions now have improved diagnostics when the JSON input
77
        is invalid (most notably, the error message now includes a line number).</p>
78
      
79
      <p>The standard library of higher-order functions (<code>fn:filter</code>, <code>fn:fold-left</code>, etc)
80
      are now available in Saxon-HE.</p>
81
 
82
    </category>
83
    
84
    <category name="s9api">
85
        
86
        <h2>Support for new Java date/time system</h2>
87
        
88
        <p><code java="net.sf.saxon.s9api.XdmAtomicValue">XdmAtomicValue</code> provides additional constructors and getter
89
            methods supporting conversion to or from: <code>java.time.Instant</code>, <code>java.time.LocalDateTime</code>,
90
            <code>java.time.OffsetDateTime</code>, <code>java.time.ZonedDateTime</code>, and <code>java.time.LocalDate</code>.</p>
91
        
92
        <h2>Tree Construction APIs</h2>
93
        
94
        <p>Two new APIs have been introduced to make construction of XDM trees easier. One is oriented to construction of
95
        in-memory documents, the other is an event-based push API:</p>
96
        
97
        <ul>
98
            <li><p>The Sapling API provides a set of very
99
                simple classes and methods to construct "sapling trees"; once constructed, these can then be converted using a single method call to a
100
                full XDM tree. They can also be used without conversion as input to a transformation, serializer, or schema validator.
101
                Sapling trees use immutable (or "persistent") data structures, so a tree can be built incrementally without the overhead of copying
102
                objects when a subtree is added to a parent tree. Details of the API can be found in the Javadoc for class 
103
                <code java="net.sf.saxon.sapling.SaplingNode">SaplingNode</code>.</p></li>
104
            <li><p>The <code>Push</code> API is modelled on existing APIs such as the SAX <code>ContentHandler</code> and
105
            the StAX <code>XMLStreamWriter</code>, but attempts to achieve much higher levels of usability, especially for constructing
106
            simple documents. The need for a stable API at this level arises partly because a number of Saxon users have taken to using
107
            the <code>Receiver</code> interface, which is complex and error-prone to use, and is not always stable between releases. The new
108
                <code>Push</code> API is documented at <code java="net.sf.saxon.s9api.Push">net.sf.saxon.s9api.Push</code>.
109
                A <code>Push</code> provider allowing the application to write to any 
110
                <code java="net.sf.saxon.s9api.Destination">Destination</code> may be obtained by calling <code>Processor.newPush()</code>.</p></li>
111
        </ul>
112
        
113
        <h2>Serialization</h2>
114
        
115
        <p>The s9api <code java="net.sf.saxon.s9api.Serializer">Serializer</code> object has new methods allowing any JAXP
116
            <code>Source</code> to be serialized. This
117
        allows for direct pass-through from an XML parser to a serializer (for example, to add indenting), for serialization of
118
        DOM trees, Sapling trees, and trees in third-party tree models.</p>
119
        
120
        <h2>XSLT and default namespaces</h2>
121
        
122
        <p>The <code java="net.sf.saxon.s9api.XsltCompiler">XsltCompiler</code> object has two new properties that can be set:</p>
123
        
124
        <ul>
125
            <li><code>setDefaultElementNamespace()</code> sets the default namespace for elements and types: in effect, a
126
                default for the <code>xpath-default-namespace</code> attribute. (If an explicit <code>xpath-default-namespace</code>
127
            is present in the stylesheet, the API setting is ignored.)</li>
128
            <li><code>setUnprefixedElementMatchingPolicy()</code> sets the policy for handling unprefixed element names appearing
129
            in XPath expressions and match patterns. Three values are supported: <code>DEFAULT_NAMESPACE</code> (this is the default,
130
            as specified in the W3C specification); <code>ANY_NAMESPACE</code>, which causes such names to match by local part only,
131
            ignoring the namespace; and <code>DEFAULT_NAMESPACE_OR_NONE</code>, which causes such names to match (a) elements
132
            in the default namespace, and (b) elements in no namespace. This is designed primarily to approximate the special
133
            rules defined in the HTML5 specification for matching unprefixed element names.</li>
134
        </ul>
135
        
136
        <h2>ErrorListener and ErrorReporter</h2>
137
        
138
        <p>A new mechanism for reporting errors to user applications has been introduced. The new 
139
          <code>ErrorReporter</code> interface is a functional replacement for the old <code>ErrorListener</code>,
140
          though the <code>ErrorListener</code> interfaces are retained for the time being for backwards
141
        compatibility.</p>  
142
      
143
      <p>The <code>ErrorListener</code> class as defined in JAXP has a number of
144
        disadvantages:</p>
145
        
146
        <ul>
147
            <li>All errors and warnings are reported as <code>Exception</code> objects, which are very expensive to construct and
148
            occupy a lot of memory; exceptions are not appropiate for holding error information unless the exception is actually thrown.</li>
149
            <li>The exceptions are instances of the JAXP <code>TransformerException</code> class, which links them to XSLT and makes
150
            it clumsy to reuse the mechanism for use outside XSLT.</li>
151
            <li>The distinction between the <code>warning()</code>, <code>error()</code>, and <code>fatalError()</code>
152
            callbacks has never been entirely clear; it is motivated by distinctions in the XSLT 1.0 specification that
153
            have changed in subsequent versions of XSLT, and have never related clearly to errors in other contexts such as schema
154
            validation.</li>
155
          <li>The <code>ErrorListener</code> methods are allowed to throw a checked exception, but the effect of doing
156
          so has never been very well defined. The fact that they can throw checked exceptions has a pervasive effect;
157
          it means that any method within Saxon that issues a warning has to declare that it is capable of throwing
158
          an exception, and this cascades to its callers. In the past Saxon has used an <code>UnfailingErrorListener</code>
159
          internally to limit the damage, but this only complicates the design.</li>
160
            <li>Generally, a processing task (such as an XSLT compilation episode, or an XSLT execution) will make a sequence of calls
161
            to an <code>ErrorListener</code> and to be useful, different concurrent tasks need to write their messages to different
162
            <code>ErrorListeners</code> so that the output messages can be distinguished. This makes APIs that set an <code>ErrorListener</code>
163
            on a shared object (such as the Saxon <code>Configuration</code> or the JAXP <code>TransformerFactory</code>) troublesome
164
                as regards thread safety. For the JAXP <code>TransformerFactory</code> this has been addressed by making the
165
            <code>newTemplates()</code> method synchronised; it is therefore no longer possible for two concurrent stylesheet compilations
166
            to interleave their error messages to the same <code>ErrorListener</code>. At the Saxon <code>Configuration</code> level
167
            it is no longer possible to set an <code>ErrorListener</code> as a configuration property.</li>
168
        </ul>
169
        
170
        <p>The replacement <code>ErrorReporter</code> interface has a single method (<code>report</code>), and is defined as a Java 
171
          <code>FunctionalInterface</code>, which makes it convenient to supply an <code>ErrorReporter</code> in the form 
172
          of a lambda expression. The object passed to the <code>report()</code> method (in general, an 
173
          <code>XmlProcessingError</code>) is not itself an exception (though in some cases it may wrap an exception),
174
          which means that Saxon does not have to create exception objects unnecessarily. The <code>report()</code> method 
175
          throws no checked exceptions. The severity of the error (warning, error, or fatal) is defined as a property of the
176
        error object, rather than being distinguished by calling different methods of the error handler. The error handler
177
        is allowed to upgrade the severity of the error.</p>
178
        
179
        <p>Interfaces at the s9api level continue to accept an <code>ErrorListener</code> for backwards compatibility, but the methods
180
            have been deprecated. Interfaces deeper in the Saxon internals have dropped support for the <code>ErrorListener</code>.</p>
181
        
182
        
183
      
184
        <p>In previous releases, although it was not documented, an <code>ErrorListener</code> that was set on the
185
        <code>XsltCompiler</code> was inherited by any <code>XsltTransformer</code> or <code>Xslt30Transformer</code>
186
        created from that <code>XsltCompiler</code>. This is no longer the case (and the same is true if an <code>ErrorList</code>
187
        or <code>ErrorReporter</code> is provided).</p>
188
      
189
        <h2>XPathCompiler</h2>
190
        
191
        <p>A new method is added for <code java="net.sf.saxon.s9api.XPathCompiler">XPathCompiler</code>: <code>addXsltFunctionLibrary()</code>. This takes an <code>XsltPackage</code> as argument,
192
        representing a compiled XSLT 3.0 library package. The global public functions in the package (those declared using <code>&lt;xsl:function visibility='public'&gt;</code>)
193
        become available for calling from XPath expressions compiled using this <code>XPathCompiler</code>.</p>
194
  
195
    </category>
196
    
197
    <category name="spi">
198
        
199
        <h2>Sequence and SequenceIterator</h2>
200
        
201
        <p>The class <code>Sequence</code>, and its many subclasses such as <code>GroundedValue</code> and <code>Item</code>, 
202
            were changed in Saxon 9.9 to use Java Generics; the same change was also made to <code>SequenceIterator</code>
203
            and its many subclasses. This change has been reverted in Saxon 10. The reason for this is basically that the change added
204
            a lot of complexity and delivered no benefits: an analysis of the motivation can be found in a 
205
            <a href="http://dev.saxonica.com/blog/mike/2020/01/java-generics-revisited.html">Saxon blog article</a>.</p>
206
        
207
        <h2>NodeInfo</h2>
208
        
209
        <p>The way in which namespaces are represented in the <code java="net.sf.saxon.om.NodeInfo">NodeInfo</code> interface has changed, to be closer to the
210
        XDM model. Instead of <code>getDeclaredNamespaces()</code>, which returned the namespace information as a set of
211
        declarations and undeclarations relative to the parent element, the interface now has <code>getAllNamespaces()</code>,
212
            which returns all the in-scope namespaces as a <code java="net.sf.saxon.om.NamespaceMap">NamespaceMap</code> object.
213
            This brings the API much closer to the way that the XDM data model
214
        is defined, which ultimately makes it easier to use. The potential inefficiency of having namespaces defined redundantly
215
        on every single element node is handled by sharing <code>NamespaceMap</code> objects (so two elements with the same
216
            in-scope namespaces share the same <code>NamespaceMap</code>). The <code>NamespaceMap</code> object is immutable,
217
        which makes such sharing easy to manage.</p>
218
        
219
        <ul>
220
            <li><p>The native tree models in Saxon (the TinyTree and LinkedTree) implement this by maintaining stored <code>NamespaceMap</code>
221
                objects within the internal data structure. The tree builders ensure that these objects are shared, so that a child element
222
                with no local namespace declarations will point to the same <code>NamespaceMap</code> object as its parent element.
223
                In many documents, namespaces are all declared on the root element, so there will only be one <code>NamespaceMap</code> object
224
                for the whole document.</p></li>
225
            <li><p>The external tree models (DOM, XOM, JDOM2, etc.) generally cache the <code>NamespaceMap</code> for an element, so
226
                computing the in-scope namespaces for an element involves getting the cached <code>NamespaceMap</code> for the
227
            parent element, and then making any changes needed if there are local namespace declarations or undeclarations present on
228
            the child element.</p></li>
229
        </ul>
230
        
231
        <p>To make it easier to iterate over the children of a node, the <code>NodeInfo</code> interface now has a method
232
        <code>children()</code> returning <code>Iterable&lt;NodeInfo&gt;</code>. The method has a default implementation.
233
        This makes it possible to use a Java "for each":</p>
234
        <samp>for (NodeInfo child : children()) { ... }</samp>
235
        
236
        <p>There is also a variant of <code>children()</code> that takes a Java <code>Predicate</code> as its second argument. 
237
            The <code>NodeTest</code> class now implements <code>Predicate&lt;NodeInfo&gt;</code>, so you can write for example:</p>
238
        
239
        <samp>for (NodeInfo childElement : children(NodeKindTest.ELEMENT)) { ... }</samp>
240
        
241
        <p>which processes the children of a node that are themselves element nodes.</p>
242
        
243
        <p>Similarly, there is a new method <code>attributes()</code> which returns an <code>AttributeMap</code>. This class
244
            replaces the old <code>AttributeCollection</code> throughout the product. The most notable differences are (a) an <code>AttributeMap</code>
245
            is immutable, and (b) its primary access is as an <code>Iterable</code>, rather than using integer subscripts to index into it.
246
            There are different implementations of <code>AttributeMap</code> depending on the number of attributes; for larger attribute sets,
247
            a hash trie structure is used to give faster access by name, and to enable addition of attributes without copying the whole structure.</p>
248
        
249
        <p>The method <code>NodeInfo.iterateAxis(axisNumber, condition)</code> has been generalized to take a Java <code>Predicate</code> as its 
250
            second argument.</p>
251
        
252
        
253
        <h2>Receiver</h2>
254
        
255
        <p>The <code>Receiver</code> interface has been forked into two interfaces: <code>Receiver</code> and <code>Outputter</code>.</p>
256
        
257
        <ul>
258
            <li><p>The new <code java="net.sf.saxon.event.Receiver">Receiver</code> interface receives information about the start 
259
                of an element in a single call containing
260
                information about the element name and type, the in-scope namespaces of the element, and the attributes of the element.
261
                This interface is used in the validation pipeline and
262
                the serialization pipeline, where it simplifies many of the operations performed by these complex pipelines.</p></li>
263
        
264
            <li><p>The <code java="net.sf.saxon.event.Outputter">Outputter</code> interface splits the start-of-element information across a sequence of calls: <code>startElement()</code> for the element
265
                name and type, one call on <code>namespace()</code> for each namespace declaration, one on <code>attribute()</code>
266
                for each attribute, and finally a call on <code>startContent()</code> (which in some cases may be implicit).
267
                The <code>Outputter</code> interface is used primarily to capture the result of push-mode XSLT and XQuery instructions,
268
        notably instructions that generate elements and attributes. It's necessary in this case to be able to capture attributes
269
        and namespaces as independent events because instructions can generate them as separate events. Most commonly these
270
        instructions feed directly into a <code java="net.sf.saxon.event.ComplexContentOutputter">ComplexContentOutputter</code>, which amalgamates start tag events into a single
271
        <code>startElement()</code> call which is then sent to a <code>Receiver</code> pipeline.</p></li>
272
        </ul>
273
        
274
        
275
        
276
        <h2>DateTimeValue</h2>
277
        
278
        <p><code java="net.sf.saxon.value.DateTimeValue">DateTimeValue</code> and related classes such as
279
          <code java="net.sf.saxon.value.DateValue">DateValue</code> and <code java="net.sf.saxon.value.TimeValue">TimeValue</code> 
280
          provide additional constructors and getter methods supporting conversion to or from: 
281
            <code>java.time.Instant</code>, <code>java.time.LocalDateTime</code>,
282
            <code>java.time.OffsetDateTime</code>, <code>java.time.ZonedDateTime</code>, and <code>java.time.LocalDate</code>.</p>
283
        
284
        <p>Conversion of <code>DateTimeValue</code> to/from classes in the <code>java.time</code> package now retains
285
        nano-second precision (previously, it only retained micro-second precision).</p>
286
        
287
        <h2>Miscellaneous</h2>
288
        
289
        <p>For push-mode instruction execution, the current receiver/outputter is no longer held in the <code>XPathContext</code>
290
            object. Instead it is passed to the relevant methods (such as <code>Expression.process()</code>) as an explicit parameter.
291
            This reduces the need to create new <code>XPathContext</code> objects.</p>
292
        
293
        <p>The <code java="net.sf.saxon.pull.PullProvider">PullProvider</code> interface has changed to use a type-safe
294
            <code>enum</code> class for event types rather than integer constants.</p>
295
        
296
        <p>The <code java="net.sf.saxon.om.SequenceIterator">SequenceIterator</code> interface has changed: the
297
            <code>getProperties()</code> method now returns a type-safe <code>EnumSet</code> rather than an integer with
298
            bit-significant flags.</p>
299
      
300
        <p>Saxon has generally moved to the use of EQName notation (<code>Q{uri}local</code>) 
301
          in preference to Clark names (<code>{uri}local</code>) for internal use. Clark names
302
        are still used where mandated by the JAXP specification, and in other stable APIs. 
303
        In lower-level system programming interfaces, however, applications may notice the 
304
        change. For example the change affects the representation of output properties such as
305
        <code>method</code> and <code>cdata-section-elements</code>, which are exposed to
306
        user-written serialization methods and customised serializers.</p>
307
        
308
        <h2>Dropped interfaces</h2>
309
        
310
        <p>The method <code>StaticQueryContext.setExternalNamespaceResolver()</code> is dropped (it has been present in the product
311
        for many years but appears to be untested, and its intended behavior is unclear).</p>
312
        
313
        <p>Some long-deprecated classes and methods have been dropped, including those listed below. The general principle is that
314
        methods deprecated since 9.7 or earlier have all been dropped; methods first deprecated in 9.8 have been dropped if they
315
        were producing no useful effect in 9.9 (for example, setter methods that did nothing).</p>
316
        <ul>
317
            <li><code>StaticQueryContext.buildDocument()</code>, deprecated since Saxon 9.2 (use a s9api <code>DocumentBuilder</code>)</li>
318
            <li><code>Configuration.buildDocument(Source)</code> and <code>Configuration.buildDocument(Source, ParseOptions)</code>,
319
                deprecated since Saxon 9.7 (use a s9api <code>DocumentBuilder</code>,
320
                or <code>Configuration.buildDocumentTree()</code>)</li>
321
            <li><code>net.sf.saxon.om.DocumentInfo</code>, since 9.7 used only by deprecated methods</li>
322
            <li><code>AbstractStaticContext.declareCollation()</code>, <code>StaticQueryContext.declareCollation()</code>, and
323
                <code>StaticContext.getCollation()</code>, deprecated since 9.6 (collations should be now registered at the level of the
324
            <code>Configuration</code>)</li>
325
            <li><code>XsltTransformer.setInitialContextNode()</code>, deprecated since 9.7 (use <code>setGlobalContextItem()</code>)</li>
326
            <li><code>Xslt30Transformer.setInitialContextItem()</code>, deprecated since 9.8 (use <code>setGlobalContextItem()</code>)</li>
327
            <li><code>XQueryExpression.pull()</code>, deprecated since 9.8 (use <code>run()</code>)</li>
328
            <li><code>ParseOptions.setStripSpace()</code>, <code>AugmentedSource.setStripSpace()</code>,
329
                <code>ParseOptions.getStripSpace()</code> and <code>AugmentedSource.getStripSpace()</code>,
330
                deprecated since 9.8 (use <code>setSpaceStrippingRule()</code>)</li>
331
            <li><code>XsltCompiler.compilePackages()</code> and <code>addCompilePackages()</code>, deprecated since 9.8 (use a
332
                <code>PackageLibrary</code>)</li>
333
            <li><code>BuildingStreamWriter.setInventPrefixes()</code> and <code>isInventPrefixes()</code>, deprecated since 9.7. The method previously
334
            had no effect, so the call can be dropped. (Note, the method was previously marked as deprecated in the implementation class,
335
            but not in the interface.)</li>
336
            <li><code>CollectionURIResolver</code> and associated methods: deprecated since 9.7. (Use a <code>CollectionFinder</code>.
337
                If necessary, wrap the old <code>CollectionURIResolver</code> in a <code>CollectionURIResolverWrapper</code>, whose
338
                source code can be found in Saxon 9.9.)
339
            This change also causes <code>Feature.COLLECTION_URI_RESOLVER</code> and <code>Feature.COLLECTION_URI_RESOLVER_CLASS</code> to
340
            be dropped, as well as the <code>-cr</code> option on the <code>Transform</code> and <code>Query</code> command line.</li>
341
            <li><code>CompilerInfo.setExtensionFunctionLibrary()</code> and <code>getExtensionFunctionLibrary()</code>: deprecated
342
                since 9.7 (use other mechanisms, such as packages)</li>
343
        </ul>
344
      
345
        <p>The methods <code>setRecoveryPolicy</code> and <code>getRecoveryPolicy</code> have been dropped from
346
        the <code>Configuration</code> and <code>CompilerInfo</code> classes, along with the configuration feature
347
        <code>Feature.RECOVERY_POLICY</code>. In recent releases the only remaining effect of this switch was
348
        to provide a default for the <code>xsl:mode</code> attributes <code>on-multiple-match="fail"</code> and
349
        <code>warning-on-multiple-match="true"</code>; this must now be controlled via the <code>xsl:mode</code>
350
        declaration in the stylesheet.</p>
351
        
352
        <h2>Tracing</h2>
353
        
354
        <p>The mechanism supporting execution tracing (including the -T and -TP options on the command line) has been substantially
355
        revamped, involving some changes to interfaces:</p>
356
        
357
        <ul>
358
            <li>If a <code java="net.sf.saxon.expr.parser.CodeInjector">CodeInjector</code> is nominated, it now operates as a
359
                pass over the fully-constructed expression tree,
360
            rather than being invoked by the XSLT and XPath parsers as expressions and instructions are created. This means that
361
            it now visits every node in the expression tree, not only selected nodes as before. Of course a <code>CodeInjector</code>
362
            can always ignore nodes that it is not interested in. The new mechanism opens the way to much more variety in the kind of
363
            instrumentation tasks that the <code>CodeInjector</code> can undertake.</li>
364
            
365
            <li>The object passed to the <code java="net.sf.saxon.lib.TraceListener">TraceListener</code> at run-time is now a
366
                <code java="net.sf.saxon.trace.Traceable">Traceable</code>, replacing the
367
            old <code>InstructionInfo</code>. A <code>Traceable</code> is either an expression, or a component such as a
368
            <code>UserFunction</code>, <code>GlobalVariable</code>, or <code>TemplateRule</code>.
369
            The <code>InstructionInfo</code> class was something of a rag-bag, and duplicated a lot
370
            of information that in the last few releases has been mantained in the <code>RetainedStaticContext</code> and <code>Location</code>
371
            objects attached to the expression itself.</li>
372
            
373
            <li>This has enabled the dropping of a number of auxiliary classes such as <code>InstructionDetails</code> and 
374
                <code>LocationKind</code>.</li>
375
            
376
            <li>The way in which expressions are identified by the <code>StandardErrorListener</code> is now better aligned with the
377
            way they are identified by the <code>TraceListener</code>.</li>
378
            
379
            <li>In the <code>CodeInjector</code> and <code>TraceListener</code> interfaces, default implementations of methods are
380
            now provided; among other things, this eliminates the need for the <code>TraceListener2</code> interface.</li>
381
        </ul>
382
        
383
        <h2>ErrorListener</h2>
384
        
385
        <p>The <code java="net.sf.saxon.lib.StandardErrorListener">StandardErrorListener</code> and <code
386
            java="net.sf.saxon.lib.StandardInvalidityHandler">StandardInvalidityHandler</code> have been refactored internally
387
        (a) to make better reuse of common code, and (b) to make it easier to write customised subclasses to achieve tailored
388
        diagnostic output. To this end, some static methods have been replaced by non-static methods, and large methods have been
389
        split into smaller pieces, documented to allow them to be overridden. A consequence of these changes is that existing
390
        user-written code subclassing these two classes may need changing. If this is onerous, one way of getting around the problem
391
        is to copy the open-source implementations of these methods from the Saxon 9.9 distribution, and rename this as a user-defined
392
        class.</p>
393
        
394
        <p>A new configuration option <code>Feature.RETAIN_NODE_FOR_DIAGNOSTICS</code> is provided. If set, this causes the location information
395
        associated with instructions and expressions in an XSLT stylesheet to retain a reference to the node in the stylesheet tree where the
396
        error occurred (rather than simply retaining the node name and line number). This information can be useful to IDEs that wish to highlight
397
        where in the source the error occurred. The information is retained both for static and dynamic error reporting. The option is off by default 
398
        because retaining the links prevents the temporary data used during compilation being garbage-collected. Previous releases attempted to retain
399
        the information for static errors but not for dynamic errors; it is now retained for both, but only if this option is set.</p>
400
 
401
        </category>
402
    
403
    <category name="extensibility">
404
        
405
        <p>Reflexive extension functions now support conversion between:</p>
406
        
407
        <ul>
408
            <li><code>xs:dateTime</code> and <code>java.time.Instant</code>, <code>java.time.LocalDateTime</code>,
409
                <code>java.time.OffsetDateTime</code>, and <code>java.time.ZonedDateTime</code></li>
410
            <li><code>xs:date</code> and <code>java.time.LocalDate</code></li>
411
        </ul>
412
 
413

  
414
    </category>
415
    
416
    <category name="optimization">
417
      
418
      <p>Some optimizations that were previously done in Saxon-HE have been moved into Saxon-EE.
419
      The aim is to clarify and simplify the differentiation of the products, and the change compensates
420
      for the move of some functionality (such as higher order functions) into Saxon-HE.</p>
421
      
422
      <p>Certain optimizations are now placed under a new optimization category <code>n</code> (constant folding), and can therefore be enabled
423
        or suppressed by setting this optimization option. The category includes compile-time evaluation of simple expressions such as arithmetic
424
        expressions (<code>2+2</code>) or function calls (<code>boolean(1)</code>), and compile-time evaluation of function calls and other
425
        expressions where it is known what the result will be if one of the operands is empty (<code>2+()</code>).</p>
426
      
427
      
428
        <p>The amount of memory needed for the indexes used to support <a class="bodylink code"
429
            href="/xsl-elements/key">xsl:key</a> has been reduced, particularly in the common cases
430
        (a) where the keys are strings compared using codepoint collation, and (b) where the key values are unique.</p>
431
        
432
        <p>A new <code java="net.sf.saxon.expr.CompareToStringConstant">CompareToStringConstant</code> expression has been
433
            introduced for value comparisons of the form <code>EXPR eq "literal"</code>
434
        (with any of the permitted operators) using Unicode codepoint collation.</p>
435
        
436
        <p>The <a class="bodylink code" href="/xsl-elements/where-populated">xsl:where-populated</a> instruction now has a
437
            push-mode implementation. (The push-mode implementation already existed in principle, but it was incomplete, and was
438
            used only when streaming.)</p>
439
        
440
        <p>A number of functions that are capable of returning large strings (<code>concat</code>, 
441
            <code>string-join</code>, <code>unparsed-text</code>, <code>xml-to-json</code>) are now able in appropriate cases
442
            to stream their output incrementally to the serializer rather than materializing the result as a string in memory.</p>
443
        
444
        <p>Match patterns of the form <code>match="$nodeset"</code> where <code>$nodeset</code> is a global variable are now optimized
445
        (Saxon-EE only): the variable is stored in an indexed form that allows a quick lookup of whether a particular node is present,
446
        without a serial search of the entire node-set.</p>
447
        
448
        <p>A new implementation of XDM maps, the <code>DictionaryMap</code>, is used in cases where all the keys will be
449
        simple strings, and further changes to the map are considered unlikely. For example, this is used to represent a map constructed by 
450
            <code>fn:parse-json()</code>. Optimizing for string-valued keys saves space, and makes lookup faster, while optimizing
451
        for immutability enables the standard Java HashMap structure to be used internally. If <code>map:put()</code> or <code>map:remove()</code>
452
        are used on such a map, it is first copied in its entirety to a new <code>HashTrie</code> using the existing data structure.
453
        The <code>DictionaryMap</code> is internally mutable during its construction phase, so adding entries incrementally during the course
454
        of an operation such as <code>fn:parse-json()</code> is much more efficient than if a pure immutable structure were used.</p>
455
        
456
        
457
        <p>Node tests of the form <code>*:NAME</code> (and predicates of the form <code>*[local-name() = 'NAME']</code>), when executed against
... This diff was truncated because it exceeds the maximum size that can be displayed.

Also available in: Unified diff