Using s9api for XQuery

You can perform a query using the s9api interface as follows:

  1. Create a Processor and set any global configuration options on the Processor. If the query needs any Saxon-PE or Saxon-EE features, use the constructor new Processor(true);.

  2. Optionally, build the source document by calling newDocumentBuilder() to create a document builder, setting appropriate options, and then calling the build() method. This returns an XdmNode which can be supplied as input to the query either as the context item, or as the value of an external variable.

  3. Call newXQueryCompiler() to create an XQueryCompiler. Then set any options that are local to a specific compilation (for example, the destination of error messages, the base URI, or the character encoding of the query text).

  4. Call one of the compile() methods to compile a query. The result is an XQueryExecutable, which can be used as often as you like in the same thread or in different threads.

  5. To run a query, call the load() method on the XQueryExecutable. This creates an XQueryEvaluator. The XQueryEvaluator can be serially reused, but it must not be shared across multiple threads. Set any options required for the specific query execution (for example, the initial context node, the values of external variables, and the destination for the query result), and then call either the iterator() or the run() method to execute the query.

  6. Because the XQueryEvaluator is an Iterable, it is possible to iterate over the results directly using the Java "for-each" construct.

  7. The result of the XQueryEvaluator.run() method is an XdmValue. From 9.9 Saxon provides powerful facilities to process an XdmValue using Java 8 streams. For example, if the query returns a single node section,(XdmNode is a subclass of XdmValue), then you could test whether it has any descendant para elements with @class="normal" by writing if (section.select(descendant("para").where(eq(attribute("class"), "normal")).exists()) {...}.

The output of the query may be retrieved as an iterator over a sequence of items, or it may be specified as a Destination object, which allows a wide range of possibilities: you can send the output to a serializer, or to a SAX ContentHandler. You can build a tree either in Saxon's native format (represented by the s9api class XdmNode) or as a DOM. You can send the output to be validated against a schema by nominating a SchemaValidator as the destination, or you can pipe it through an XSLT transformation, because XsltTransformer also implements the Destination interface.

Examples of s9api queries are included in the saxon-resources file, see module S9APIExamples.java.

Separate compilation of library modules

Under Saxon-EE, it is possible to compile library modules separately from the main module. This reduces the compilation time and memory usage when the same library module is imported by many main modules for different queries. A method compileLibrary() (with a number of overloaded variants supplying the input in different ways) is provided in the XQueryCompiler class; any library module compiled using this method will be available to all subsequent compilations using the same XQueryCompiler. To import the module, simply use import module specifying the module URI in the normal way. It is not necessary to supply a module location hint (at "URI"), and if any is supplied, it will be ignored.