<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="using-xquery" page="api-query" subpage="s9api-query"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Using s9api for XQuery</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Using s9api for XQuery"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Using s9api for XQuery</h1>
<p>You can perform a query using the s9api interface as follows:</p>
<ol>
<li content="para">
<p>Create a <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Processor.html"><code>Processor</code></a>) and set any global
configuration options on the Processor.</p>
</li>
<li content="para">
<p>Optionally, build the source document by calling <code>newDocumentBuilder()</code> to create a document builder,
setting appropriate options, and then calling the <code>build()</code> method. This returns an <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XdmNode.html"><code>XdmNode</code></a>
which can be supplied as input to the query either as the context item, or as the value of an external variable.</p>
</li>
<li content="para">
<p>Call <code>newXQueryCompiler()</code> to create an XQuery Compiler. 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).</p>
</li>
<li content="para">
<p>Call one of the <code>compile()</code> methods to compile a query. The result is an <code>XQueryExecutable</code>,
which can be used as often as you like in the same thread or in different threads.</p>
</li>
<li content="para">
<p>To run a query, call the <code>load()</code> method on the <code>XQueryExecutable</code>. This creates
an <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XQueryEvaluator.html"><code>XQueryEvaluator</code></a>. The <code>XQueryEvaluator</code> 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 <code>iterator()</code>
or the <code>run()</code> method to execute the query.</p>
</li>
<li content="para">
<p>Because the <code>XQueryEvaluator</code> is an <code>Iterable</code>, it is possible to iterate over the results
directly using the Java 5 "for-each" construct.</p>
</li>
</ol>
<p>The output of the query may be retrieved as an iterator over a sequence of items, or it may is specified as a
<a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/Destination.html"><code>Destination</code></a> 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 <code>XdmNode</code>) or as a DOM. You can send the output to be validated against a schema by nominating a
<a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/SchemaValidator.html"><code>SchemaValidator</code></a> as the destination, or you can pipe it through an XSLT transformation,
because <a class="bodylink" href="../../javadoc/net/sf/saxon/s9api/XsltTransformer.html"><code>XsltTransformer</code></a> also implements the <code>Destination</code> interface.</p>
<p>Examples of s9api queries are included in the Saxon resources file, see module S9APIExamples.java.</p>
<p class="subhead">Separate compilation of library modules</p>
<p>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 <code>compileLibrary()</code>
(with a number of overloaded variants supplying the input in different ways) is provided in the <code>XQueryCompiler</code> class;
any library module compiled using this method will be available to all subsequent compilations using the same <code>XQueryCompiler</code>.
To import the module, simply use <code>import module</code> specifying the module URI in the normal way. It is not necessary to supply
a module location hint (<code>at "URI"</code>), and if any is supplied, it will be ignored.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="xqj.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
