<?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="xqj"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Invoking XQuery using the XQJ API</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Invoking XQuery using the XQJ API"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Invoking XQuery using the XQJ API</h1>
<p>XQJ (XQuery API for Java, also known as JSR 225) is a vendor-neutral API for invoking XQuery from
Java applications. The Final Release (1.0) is published at <a href="http://jcp.org/en/jsr/detail?id=225" class="bodylink">http://jcp.org/en/jsr/detail?id=225</a>.
Saxon includes a complete and conformant implementation of this API.</p>
<p>For information on how to use the API, please see the JSR 225 documentation.</p>
<p>XQJ has many similarities with JDBC, and its general style is that of a client-server API
in which the application opens a "connection" to a database. This of course does not fit the
Saxon in-process model particularly well; on the other hand, apart from the terminology and the
use of some methods (such as the ability to set a connection timeout) that make little sense in
a Saxon context, the API works equally well in an environment like Saxon where the XQuery processor
is invoked directly and runs within the same Java VM as the client application.</p>
<p>The samples directory in the issued saxon-resources download file includes a Java test application,
<b>XQJExamples.java</b>, which illustrates some of the possible ways of invoking Saxon using the XQJ interface.</p>
<p>Note that Saxon will generally only recognize its own implementation of XQJ interfaces. For example,
the interface <code>XQDynamicContext</code> includes a method <code>bindAtomicValue</code> that allows the value of a variable
or the context item to be supplied.
The type of the argument is <code>XQItem</code>: however, Saxon will only accept an <code>XQItem</code>
that was created by its own implementations of the factory methods in <code>XQDataFactory</code>.</p>
<p>Unlike JAXP interfaces, XQJ does not include an implementation-independent factory class. Instead,
you start the process by calling:</p>
<p class="command">new SaxonXQDataSource()</p>
<p>This constructor will create a new Configuration, which will be an <code>EnterpriseConfiguration</code> or
<code>ProfessionalConfiguration</code> if Saxon-EE or Saxon-PE is in use. As an alternative, there is also a constructor
that allows a specific pre-exising configuration to be used.</p>
<p>From the <code>XQDataSource</code> you can call <code>getConnection()</code> to get a connection,
and from the connection you can call <code>prepareExpression()</code> to compile a query. The resulting
<code>XQPreparedExpression</code> object has a method <code>executeQuery()</code> allowing the query
to be evaluated. The result of the query evaluation is an <code>XQSequence</code>, which acts as a cursor
or iterator: it has a <code>next()</code> method allowing you to change the current position, and a
<code>getItem()</code> method allowing you to retrieve the item at the current position. The result
of <code>getItem()</code> is an <code>XQItem</code> object, and this has methods allowing you to determine
the item type, and to convert the item into a suitable Java object or value.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="../update.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
