# Changes to the XQuery Java API

The Java API for invoking XQuery has been simplified: there is no longer any need to create a `QueryProcessor` object, and the constructor for the `QueryProcessor` has been deprecated. Instead, all the methods that were previously available on the `QueryProcessor` can now be invoked directly on the `StaticQueryContext` object.

The constructor for the `DynamicQueryContext` object now requires a `Configuration` object to be supplied. This must be the same as the `Configuration` that was used when creating the `StaticQueryContext`.

A new extension function (technically a pseudo-function) `saxon:try()` has been added. This returns the value of its first argument, unless evaluation of the first argument fails, in which case it returns the value of its second argument. This provides a simple means for catching dynamic errors. No information is available about the actual error that occurred. This function is available only in Saxon-SA.

The EXSLT extension function `random:random-sequence` has been implemented (acknowledgements to Martin Szugat)

The `saxon:serialize()` extension function is now available in environments other than XSLT (for example, in XQuery): in such cases the second argument is the name of the serialization method (xml, html, xhtml, text), and the other serialization parameters are all defaulted.

The XPath expression used within a `saxon:evaluate` expression now has access to all the functions that would be available to a static XPath expression appearing in the same position: including constructor functions, user-defined stylesheet or XQuery functions, and Java extension functions. The default function namespace is also inherited from the calling environment.

In the case of a node in a temporary tree, the `saxon:line-number()` function now identifies the line in the stylesheet containing the instruction that created this node. As with line numbering in source documents, this only works if line numbering is enabled using the -l or -T option on the command line, or the corresponding API option. This line number is also used to identify such nodes in trace output.

A new extension function `saxon:string-to-utf8()` is available. It returns a sequence of integers representing the octets in the UTF8 encoding of a string.

New extension functions `saxon:octets-to-hexBinary()` and `hexBinary-to-octets` are available. They translate between a sequence of integers (in the range 0-255) representing a sequence of octets, and the `xs:hexBinary` value representing that sequence of octets.

New extension functions `saxon:octets-to-base64Binary()` and `base64Binary-to-octets` are available. They translate between a sequence of integers (in the range 0-255) representing a sequence of octets, and the `xs:base64Binary` value representing that sequence of octets.

The single-argument extension functions `saxon:min` and `saxon:max`, which had already been removed from the documentation, have now been dropped from the product. They are superseded by the standard XPath 2.0 `min()` and `max()` functions. The EXSLT `min()` and `max()` functions remain available.

The output of the `trace()` function is now sent to the TraceListener, if a TraceListener has been activated (for example by use of the -T option on the Query or XSLT command line). If no TraceListener is active, the output is sent directly to System.err as before.

Two new extension functions are available (in Saxon-SA only) to enable the use of higher-order functions in XSLT and XQuery. The first, `saxon:function()`, takes the name and arity of a user-defined function as input, and returns a value representing this function (a `FirstClassFunction` object). The second function, `saxon:call()` takes this FirstClassFunction object as its first argument, and the values to be supplied to the function as the second and subsequent arguments, and returns the result of calling the identified function with these arguments. Higher-order functions make XSLT and XQuery into fully-capable functional programming languages, and enable the implementation of many algorithms (for example, graph-searching algorithms) that would otherwise be extremely clumsy to program.

A new higher-order extension function `saxon:for-each-group` is available (in Saxon-SA only). This is intended primarily for use in XQuery, which lacks XSLT's `xsl:for-each-group` construct. The function takes three parameters: the population of items to be grouped, a function to calculate the grouping key, and a function to process each group (where a group is defined as a subset of the population having the same values of the grouping key). It returns the result of applying this function to each group in turn. The groups are processed in order of first appearance.

A new higher-order extension function `saxon:analyze-string` is available (in Saxon-SA only). This is intended primarily for use in XQuery, which lacks XSLT's `xsl:analyze-string` construct. The function takes four or five parameters: the string to be analyzed, a regular expresion (regex), a function to process matching substrings, a function to process non-matching substrings, and optionally, a set of flags corresponding to those available on the `matches()` function. The function splits the string into a sequence of substrings, each of which either matches the regex or does not match it, and then calls one of the two functions as appropriate, with this substring as an argument.

Versions of the XSLT functions `format-date()`, `format-dateTime`, `format-number()`, and `format-time()` have been made available as extension functions in the Saxon namespace, thus making them available to XQuery users. They are available in Saxon-SA only. There is no equivalent of XSLT's decimal formats, so it is not possible to change the characters used for the decimal point and grouping separators, for example.

A new extension function `saxon:namespace-node()` is added. This allows a parentless namespace node to be constructed. The function serves the same purpose in XQuery as the `xsl:namespace` instruction in XSLT: it allows dynamically-computed namespaces to be added to the result document.

Expand | Up Next