<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="changes" page="intro91" subpage="xqj91"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: XQJ (XQuery API for Java)</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: XQJ (XQuery API for Java)"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>XQJ (XQuery API for Java)</h1>
<p>Saxon's implementation of XQJ has been brought into line with the 1.0 "final draft" released on 20 Nov 2007.
The final draft includes a set of compatibility tests, and Saxon now passes all these tests, with the exception
of four tests whose results have been queried as they appear inconsistent with the documentation.</p>
<p>This change means that the XQJ interfaces now have their proper package names (<code>javax.xml.query.*</code>
in place of <code>net.sf.saxon.javax.xml.query.*</code>, and applications will need to be updated accordingly.
The interfaces together with the implementation classes are in the JAR file saxon9-xqj.jar .</p>
<p>To pass the test suite, quite a few changes were necessary, but few of these will affect applications. Many of them
concern the error behaviour when null arguments are passed to methods, or when operations are attempted on a connection that
has been closed - neither of which are things that real applications are likely to do.</p>
<p>One more noticeable change is that the rules for processing a forwards-only sequence are now strictly enforced. These
rules prevent you accessing the same item in the result of a query more than once, unless you save a local copy using
the <code>getItem()</code> method.</p>
<p>As required by the licensing conditions for XQJ, a
<a class="bodylink" href="../../conformance/xqj.xml">conformance statement</a> is provided.</p>
<p>The XQJ implementation now allows a Java object to be supplied as an "external object", whose instance methods
can be invoked as external functions within the query. TestL in the sample application <code>XQJExamples.java</code> provides an
illustration of how to do this. It is necessary to create an <code>XQItemType</code> representing the type of the
item: this will always have a name whose URI is <code>http://saxon.sf.net/java-type</code> and whose local name
is the qualified name of the Java class. The standard XQJ method <code>createItemFromObject()</code> will recognize a
type name in this form and handle the object accordingly.</p>
<p>A number of named properties have been implemented to allow Saxon's behavior to be configured via the
<code>setProperty()</code> method of <code>XQDataSource</code>; for details see the Javadoc of the
Saxon implementation class <code>SaxonXQDataSource</code>. For configuration settings that are not in this
list, <code>SaxonXQDataSource</code> provides a method <code>getConfiguration()</code> that allows access
to the underlying <code>Configuration</code> object.</p>
<p>A Saxon-specific method has been added to the <code>SaxonXQConnection</code> class, which is Saxon's
implementation of <code>XQConnection</code>. The method <code>copyPreparedExpression()</code> allows an
<code>XQPreparedExpression</code> created under one connection to be copied to a different connection. This
makes it much easier to compile a query once and run in concurrently in multiple threads, a facility that is
notoriously absent from the XQJ specification. When a prepared expression is copied in this way, the compiled code
of the query and the static context are shared between the two copies, but each copy has its own dynamic
context (for query parameters and suchlike).</p>
<p>There have been changes to the implementation of XQJ methods involving input or delivery of results using
the Stax <code>XMLStreamReader</code> interface. These methods are now implemented using the "pull events"
mechanism introduced in Saxon 9.0, replacing the older <code>PullProvider</code> interface.</p>
<p>A new <code>EventIterator</code> is available for use in the event-pull pipeline, namely <code>NamespaceMaintainer</code>.
This maintains the namespace context (it acts as a <code>NamespaceResolver</code>). This is used by XQJ when delivering
results in the form of a StAX <code>XMLStreamReader</code>, underpinning the methods on the <code>XMLStreamReader</code>
interface that allow namespace prefixes to be resolved.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="s9api91.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
