<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="xpath-api" page="s9api-xpath" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Evaluating XPath Expressions using s9api</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Evaluating XPath Expressions using s9api"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Evaluating XPath Expressions using s9api</h1>
<p>The s9api interface is a custom-designed API for Saxon, allowing integrated access to all
Saxon's XML processing capabilities in a uniform way, taking advantage of the type safety
offered by generics in Java 5.</p>
<p>You can evaluate an XPath expression 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 <code>Processor</code>.</p>
</li>
<li content="para">
<p>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 the context item to the XPath expression.</p>
</li>
<li content="para">
<p>Call <code>newXPathCompiler()</code> to create an <a class="bodylink" href="../javadoc/net/sf/saxon/s9api/XPathCompiler.html"><code>XPathCompiler</code></a>, and set any options that are local to a specific
compilation (notably declaring namespace prefixes that are used in the XPath expression).</p>
</li>
<li content="para">
<p>Call the <code>compile()</code> method to compile an expression. The result is an <a class="bodylink" href="../javadoc/net/sf/saxon/s9api/XPathExecutable.html"><code>XPathExecutable</code></a>,
which can be used as often as you like in the same thread or in different threads.</p>
</li>
<li content="para">
<p>To evaluate the expression, call the <code>load()</code> method on the <code>XPathExecutable</code>. This creates
an <a class="bodylink" href="../javadoc/net/sf/saxon/s9api/Processor.html"><code>XPathSelector</code></a>. The <code>XPathSelector</code> can be serially reused, but it must not be shared across
multiple threads. Set any options required for the specific XPath execution (for example, the initial context node, the
values of any variables referenced in the expression), and then call one of the methods <code>iterator()</code>
<code>evaluate()</code>, or <code>evaluateSingle()</code> to execute the XPath expression.</p>
</li>
<li content="para">
<p>Because the <code>XPathSelector</code> is an <code>Iterable</code>, it is possible to iterate over the results
directly using the Java 5 "for-each" construct.</p>
</li>
<li content="para">
<p>The result of an XPath expression is in general an
<a class="bodylink" href="../javadoc/net/sf/saxon/s9api/XdmValue.html"><code>XdmValue</code></a>, representing a value as defined in the
XDM data model (that is, a sequence of nodes and/or atomic values). Subclasses of <code>XdmValue</code> include
<a class="bodylink" href="../javadoc/net/sf/saxon/s9api/XdmItem.html"><code>XdmItem</code></a>,
<a class="bodylink" href="../javadoc/net/sf/saxon/s9api/XdmNode.html"><code>XdmNode</code></a>,
and <a class="bodylink" href="../javadoc/net/sf/saxon/s9api/XdmAtomicValue.html"><code>XdmAtomicValue</code></a>, and these relate directly to the corresponding
concepts in XDM. Various methods are available to translate between this model and native Java data types.</p>
</li>
</ol>
<p>The <a class="bodylink" href="../javadoc/net/sf/saxon/s9api/XdmCompiler.html"><code>XdmCompiler</code></a> also has compile-and-go methods <code>evaluate()</code> and <code>evaluateSingle()</code> to execute
an expression directly without going through an explicit compilation process. This provides a simpler approach if the expression
is only evaluated once. The <code>XdmCompiler</code> also has the option of caching compiled expressions, so that if the same expression
is evaluated repeatedly, the compiled form of the expression is re-used.</p>
<p>Examples of the use of s9api to evaluate XPath expressions are included in the Saxon resources file,
see module S9APIExamples.java.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="jaxp-xpath.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
