<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.6.0_18) on Fri Dec 09 20:48:51 GMT 2011 -->
<TITLE>
net.sf.saxon.query
</TITLE>
<META NAME="date" CONTENT="2011-12-09">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="net.sf.saxon.query";
}
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<HR>
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../net/sf/saxon/pull/package-summary.html"><B>PREV PACKAGE</B></A>
<A HREF="../../../../net/sf/saxon/s9api/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../index.html?net/sf/saxon/query/package-summary.html" target="_top"><B>FRAMES</B></A>
<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>
<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<H2>
Package net.sf.saxon.query
</H2>
This package provides a relatively low-level API for executing XQuery queries
directly from a Java application.
<P>
<B>See:</B>
<BR>
<A HREF="#package_description"><B>Description</B></A>
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Interface Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/Declaration.html" title="interface in net.sf.saxon.query">Declaration</A></B></TD>
<TD>This interface represents the union of global variable declarations and function declarations in XQuery
modules</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/UpdateAgent.html" title="interface in net.sf.saxon.query">UpdateAgent</A></B></TD>
<TD>An UpdateAgent is a callback class that is called to handle a document after it has been updated.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/XQueryFunctionBinder.html" title="interface in net.sf.saxon.query">XQueryFunctionBinder</A></B></TD>
<TD>XQueryFunctionBinder is an extension of the FunctionLibrary interface used for function libraries
that contain user-written XQuery functions.</TD>
</TR>
</TABLE>
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Class Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/DynamicQueryContext.html" title="class in net.sf.saxon.query">DynamicQueryContext</A></B></TD>
<TD>This object represents a dynamic context for query execution.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/GlobalVariableDefinition.html" title="class in net.sf.saxon.query">GlobalVariableDefinition</A></B></TD>
<TD>Class to hold compile-time information about an XQuery global variable
or parameter.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/ImportedFunctionLibrary.html" title="class in net.sf.saxon.query">ImportedFunctionLibrary</A></B></TD>
<TD>This implementation of FunctionLibrary contains all the functions imported into a Query Module.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/QueryLibrary.html" title="class in net.sf.saxon.query">QueryLibrary</A></B></TD>
<TD>A QueryLibrary represents an independently compiled set of query modules that does not include a
main module.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/QueryModule.html" title="class in net.sf.saxon.query">QueryModule</A></B></TD>
<TD>This class represents a query module, and includes information about the static context of the query module.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/QueryParser.html" title="class in net.sf.saxon.query">QueryParser</A></B></TD>
<TD>This class defines extensions to the XPath parser to handle the additional
syntax supported in XQuery</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/QueryReader.html" title="class in net.sf.saxon.query">QueryReader</A></B></TD>
<TD>This class contains static methods used to read a query as a byte stream, infer the encoding if
necessary, and return the text of the query as a string; also methods to import functions and variables
from one module into another, and check their consistency.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/QueryResult.html" title="class in net.sf.saxon.query">QueryResult</A></B></TD>
<TD>This utility class takes the result sequence produced by a query, and wraps it as
an XML document.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/SequenceWrapper.html" title="class in net.sf.saxon.query">SequenceWrapper</A></B></TD>
<TD>This class can be used in a push pipeline: it accepts any sequence as input, and generates
a document in which the items of the sequence are wrapped by elements containing information about
the types of the items in the input sequence.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/StaticQueryContext.html" title="class in net.sf.saxon.query">StaticQueryContext</A></B></TD>
<TD>StaticQueryContext contains information used to build a StaticContext for use when processing XQuery
expressions.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/UnboundFunctionLibrary.html" title="class in net.sf.saxon.query">UnboundFunctionLibrary</A></B></TD>
<TD>An UnboundFunctionLibrary is not a real function library; rather, it is used to keep track of function calls
that cannot yet be bound to a known declared function, but will have to be bound when all user-declared functions
are available.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/UndeclaredVariable.html" title="class in net.sf.saxon.query">UndeclaredVariable</A></B></TD>
<TD>An UndeclaredVariable object is created when a reference is encountered to a variable
that has not yet been declared.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/XQueryExpression.html" title="class in net.sf.saxon.query">XQueryExpression</A></B></TD>
<TD>XQueryExpression represents a compiled query.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/XQueryFunction.html" title="class in net.sf.saxon.query">XQueryFunction</A></B></TD>
<TD>A user-defined function in an XQuery module</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../net/sf/saxon/query/XQueryFunctionLibrary.html" title="class in net.sf.saxon.query">XQueryFunctionLibrary</A></B></TD>
<TD>An XQueryFunctionLibrary is a function library containing all the user-defined functions available for use within a
particular XQuery module: that is, the functions declared in that module, and the functions imported from other
modules.</TD>
</TR>
</TABLE>
<P>
<A NAME="package_description"><!-- --></A><H2>
Package net.sf.saxon.query Description
</H2>
<P>
<p>This package provides a relatively low-level API for executing XQuery queries
directly from a Java application. This is no longer the recommended API for writing Java
applications using XQuery: there are two higher-level APIs, s9api (<A HREF="../../../../net/sf/saxon/s9api/package-summary.html"><CODE>net.sf.saxon.s9api</CODE></A>,
and XQJ (<A HREF="../../../../javax/xml/xquery/package-summary.html"><CODE>javax.xml.xquery</CODE></A>. This package also includes internal supporting code
that implements XQuery within Saxon.</p>
<p>For details of the API, see the JavaDoc documentation of individual classes, starting
with the <A HREF="../../../../net/sf/saxon/query/StaticQueryContext.html" title="class in net.sf.saxon.query"><CODE>StaticQueryContext</CODE></A>.</p>
<p>The first thing you need to do is to create a <A HREF="../../../../net/sf/saxon/Configuration.html" title="class in net.sf.saxon"><CODE>Configuration</CODE></A> object.
This holds values of all the system settings, corresponding to flags available on the command line.
You don't need to set any properties in the <code>Configuration</code> object if you are happy
with the default settings. For schema-aware processing, you will need to create a
<A HREF="../../../../com/saxonica/config/EnterpriseConfiguration.html" title="class in com.saxonica.config"><CODE>EnterpriseConfiguration</CODE></A> instead.</p>
<p>Then you need to create a <A HREF="../../../../net/sf/saxon/query/StaticQueryContext.html" title="class in net.sf.saxon.query"><CODE>StaticQueryContext</CODE></A> object, which you can
do using the <code>newStaticQueryContext()</code> method on the <code>Configuration</code>. As the name
implies, this holds information about the static (compile-time) context for a query. Most aspects
of the static context can be defined in the Query Prolog, but this object allows you to initialize
the static context from the application instead if you need to. Some of the facilities provided are
very much for advanced users only, for example the ability to declare variables and functions, and
the ability to specify a <code>NamePool</code> to be used. One aspect of the static context that you may need
to use is the ability to declare collations. Using the method <code>declareCollation</code> you can
create a mapping between a collation URI (which can then be used anywhere in the Query) and a Java
<code>StringCollator</code> object used to implement that collation.</p>
<p>Having created, and possibly configured, the <code>Configuration</code> and
<code>StaticQueryContext</code> objects, you can now compile a Query using the <code>compileQuery</code>
method on the <code>StaticQueryContext</code>. The text of the
Query can be supplied either as a <code>String</code> or as a Java <code>Reader</code>. There
are thus two different <code>compileQuery</code> methods. Each of them returns the compiled
query in the form of a <code>XQueryExpression</code>. The <code>XQueryExpression</code>, as you would expect,
can be executed repeatedly, as often as you want, in the same or in different threads.</p>
<p>Before you run your query, you may want to build one or more trees representing
XML documents that can be used as input to your query. You don't need to do this: if the query
loads its source documents using the <code>doc()</code> function then this will be done
automatically, but doing it yourself gives you more control. A document node at the root of
a tree is represented in Saxon by the <A HREF="../../../../net/sf/saxon/om/DocumentInfo.html" title="interface in net.sf.saxon.om"><CODE>DocumentInfo</CODE></A> interface.
The <code>Configuration</code> provides a convenience method, <code>buildDocument()</code>,
that allows an instance of <code>DocumentInfo</code> to be constructed. The input parameter to
this is defined by the class <code>javax.xml.transform.Source</code>, which is part of the
standard Java JAXP API: the <code>Source</code> interface is an umbrella for different kinds of
XML document source, including a <code>StreamSource</code> which parses raw XML from a byte
or character stream, <code>SAXSource</code> which takes the input from a SAX parser (or an
object that is simulating a SAX parser), and <code>DOMSource</code> which provides the input
from a DOM. Saxon-PE also provides wrappers for third-party document models, for example a
<A HREF="../../../../net/sf/saxon/option/jdom/DocumentWrapper.html" title="class in net.sf.saxon.option.jdom"><CODE>DocumentWrapper</CODE></A> which allows
the input to be taken from a JDOM document.</p>
<p>To execute your compiled query, you need to create a <A HREF="../../../../net/sf/saxon/query/DynamicQueryContext.html" title="class in net.sf.saxon.query"><CODE>DynamicQueryContext</CODE></A> object
that holds the run-time context information. The main things you can set in the run-time context are:</p>
<ul>
<li>Values of parameters (external global variables). You can set these using the <code>setParameter()</code>
method. The mappings from Java classes to XQuery/XPath data types is the same as the mapping used for the
returned values from an external Java method call, and is described under
<a href="extensibility.html#function-result">Result of an Extension Function</a>.</li>
<li>The context node can be set using the method <code>setContextNode()</code>. For some reason
it isn't possible to set a context item other than a node.</li>
<li>You can also set a URIResolver and/or ErrorListener. These default to the ones that were
used during Query compilation.</li>
</ul>
<p>You are now ready to evaluate the query. There are several methods on the <code>QueryExpression</code>
object that you can use to achieve this. The <code>evaluate()</code> method returns the result sequence
as a Java <code>java.util.List</code>. The <code>evaluateSingle()</code> method is suitable when you know
that the result sequence will contain a single item: this returns this item as an Object, or returns null
if the result is an empty sequence. There is also an <code>iterator</code> method that returns an iterator
over the results. This is a Saxon object of class <code>net.sf.saxon.SequenceIterator</code>: it is similar
to the standard Java iterator, but not quite identical; for example, it can throw exceptions.</p>
<p>The <code>evaluate()</code> and <code>evaluateSingle()</code> methods return the result as a Java object
of the most appropriate type: for example a String is returned as a <code>java.lang.String</code>, a
boolean as a <code>java.lang.Boolean</code>. A node is returned using the Saxon representation of a node,
<code>net.sf.saxon.om.NodeInfo</code>. With the standard and tinytree models, this object also implements
the DOM <code>Node</code> interface (but any attempt to update the node throws an error).</p>
<p>The <code>iterator()</code> method, by contrast, does not do any conversion of the result. It is returned
using its native Saxon representation, for example a String is returned as an instance of
<code>sf.net.saxon.value.StringValue</code>. You can then use all the methods available on this class
to process the returned value.</p>
<p>If you want to process the results of the query in your application, that's all there is to it. But you
may want to output the results as serialized XML. Saxon provides two ways of doing this: you can produce
wrapped output, or raw output. Raw output works only if the result consists of a single document or element
node, and it outputs the subtree rooted at that element node in the form of a serialized XML document. Wrapped
output works for any result sequence, for example a sequence of integers or a sequence of attribute and
comment nodes; this works by wrapping each item in the result sequence as an XML element, with details
of its type and value.</p>
<p>To produce wrapped output, you first wrap the result sequence as an XML tree, and then serialize the
tree. To produce unwrapped output, you skip the wrapping stage and just call the serializer directly.</p>
<p>Both steps can be done using the <code>QueryResult</code> class. This class doesn't need to be
instantiated, its methods are static. The method <code>QueryResult.wrap</code> takes as input the iterator
produced by evaluating the query using the <code>iterator()</code> method, and produces as output
a <code>DocumentInfo</code> object representing the results wrapped as an XML tree. The method
<code>QueryResult.serialize</code> takes any document or element node as input, and writes it to
a specified destination, using specified output properties. The destination is supplied as an object
of class <code>javax.xml.transform.Result</code>. Like the <code>Source</code>, this is part of the
JAXP API, and allows the destination to be specified as a StreamResult (representing a byte stream or
character stream), a SAXResult (which wraps a SAX ContentHandler), or a DOMResult
(which delivers the result as a DOM). The output properties are used only when writing to
a StreamResult: they correspond to the properties available in the <code>xsl:output</code> element
for XSLT. The property names are defined by constants in the JAXP <code>javax.xml.transform.OutputKeys</code>
class (or <code>net.sf.saxon.event.SaxonOutputKeys</code> for Saxon extensions): for details of the
values that are accepted, see the JavaDoc documentation or the JAXP specification.</p>
<p align="center"><i>Michael H. Kay<br/>
Saxonica Limited<br/>
30 July 2010</i></p>
<P>
<P>
<DL>
</DL>
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../net/sf/saxon/pull/package-summary.html"><B>PREV PACKAGE</B></A>
<A HREF="../../../../net/sf/saxon/s9api/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../index.html?net/sf/saxon/query/package-summary.html" target="_top"><B>FRAMES</B></A>
<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>
<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
Copyright (c) 2004-2011 Saxonica Limited. All rights reserved.
</BODY>
</HTML>
