XQuery API for Java

XQuery API for Java (XQJ)
Company type	Java API
Industry	Software, XML data processing
Founded	June 24, 2009; 17 years ago
Headquarters	N/A
Products	Java API for XQuery execution

XQuery API for Java (XQJ) represents the official Java API aligned with the W3C XQuery 1.0 standard.

XQJ allows Java programmers to run XQuery statements on XML data repositories, including XML database platforms, thereby reducing dependency on specific vendors. It provides an interface to interact with the XQuery Data Model and is architected similarly to the JDBC API, making it particularly effective for server-side XML databases. The API facilitates binding Java objects to XQuery commands, which enhances security by mitigating risks of injection attacks, and supports executing multiple XQuery statements within atomic transaction boundaries.

History and implementation

Created through the Java Community Process as part of JSR 225, XQJ was supported by leading technology firms such as Oracle, IBM, BEA Systems, Software AG, Intel, Nokia, and DataDirect. The initial release, version 1.0, was published on June 24, 2009, accompanied by comprehensive JavaDocs, a reference implementation, and a Technology Compatibility Kit (TCK) to verify vendor adherence.

The API’s classes are contained within the Java package javax.xml.xquery.

There has been no visible progress toward extending XQJ to accommodate newer versions of XQuery (3.0 or 3.1), including features such as functions, arrays, or maps.

Functionality

XQJ supports multiple implementations that can coexist within a single application environment.

Through XQJ connections, users can create and execute various XQuery expressions, including those involving updates and full-text searches. These expressions are represented by:

XQExpression – submits the query to the processor upon each execution.
XQPreparedExpression – stores the compiled expression for efficient reuse.

XQuery queries produce sequences of XDM items accessible via the XQResultSequence interface. Developers can iterate through individual XDM items, each carrying type metadata such as , , or atomic types like and . This type information is available through XQItemType.

Atomic items in XQuery can be converted into Java primitive types using methods from XQItemAccessor, such as getByte() and getFloat(). Both single items and sequences can be serialized into DOM, SAX, StAX formats or generic IO streams, enabling seamless integration with Java’s XML processing tools.

Basic example

The following snippet demonstrates how to establish a connection with an XML database, execute an XQuery expression, process the returned data in Java, and close the connection to free resources.

<syntaxhighlight lang="java"> // Establish connection to XML database XQConnection conn = vendorDataSource.getConnection("myUser", "myPassword");

XQExpression expr = conn.createExpression(); // Prepare reusable XQuery expression

XQResultSequence result = expr.executeQuery(

 "for $n in fn:collection('catalog')//item " +
 "return fn:data($n/name)"); // Perform XQuery execution

// Process each result item while (result.next()) {

   System.out.println("Product name: " + result.getItemAsString(null));

}

conn.close(); // Close connection and release resources </syntaxhighlight>

Assigning a value to an external variable

The following illustration demonstrates how a Java value can be linked to an external variable within an XQuery expression, provided that the connection is established:

<syntaxhighlight lang="java"> XQExpression expr = conn.createExpression();

// XQuery statement String es = "declare variable $x as xs:integer external;" +

           " for $n in fn:collection('catalog')//item" +
           " where $n/price <= $x" +
           " return fn:data($n/name)";

// Attach the integer 21 to the external variable named x expr.bindInt(new QName("x"), 21, null);

// Run the XQuery XQResultSequence result = expr.executeQuery(es);

// Iterate through the results while (result.next()) {

   // Handle each result ...

} </syntaxhighlight>

Standard data type correspondence

The XQJ 1.0 standard specifies default conversion guidelines between Java and XQuery data types when no explicit type is provided. These mappings are largely consistent with those found in JAXB.

Java to XQuery Default Data Type Mapping
Java Data Type	Corresponding Default XQuery Data Type(s)
<syntaxhighlight lang="text" class="" style="" inline="1">boolean</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:boolean</syntaxhighlight>
<syntaxhighlight lang="text" class="" style="" inline="1">byte</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:byte</syntaxhighlight>
<syntaxhighlight lang="text" class="" style="" inline="1">byte[]</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:hexBinary</syntaxhighlight>
<syntaxhighlight lang="text" class="" style="" inline="1">double</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:double</syntaxhighlight>
<syntaxhighlight lang="text" class="" style="" inline="1">float</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:float</syntaxhighlight>
<syntaxhighlight lang="text" class="" style="" inline="1">int</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:int</syntaxhighlight>
<syntaxhighlight lang="text" class="" style="" inline="1">long</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:long</syntaxhighlight>
<syntaxhighlight lang="text" class="" style="" inline="1">short</syntaxhighlight>	<syntaxhighlight lang="text" class="" style="" inline="1">xs:short</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:boolean</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:byte</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:float</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:double</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:int</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:long</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:short</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:string</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:decimal</syntaxhighlight>
Template:Javadoc:SE	<syntaxhighlight lang="text" class="" style="" inline="1">xs:integer</syntaxhighlight>

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type (continued)	Corresponding Default XQuery Data Type(s)

Java Data Type	Corresponding Default XQuery Data Type(s)

|- rowspan="3" | || when the Duration instance represents xs:dayTimeDuration |- || when the Duration instance represents xs:yearMonthDuration |- || when the Duration instance represents xs:duration |- rowspan="8" | || when the XMLGregorianCalendar instance corresponds to xs:date |- || when the XMLGregorianCalendar instance corresponds to xs:dateTime |- || when the XMLGregorianCalendar instance corresponds to xs:gDay |- || when the XMLGregorianCalendar instance corresponds to xs:gMonth |- || when the XMLGregorianCalendar instance corresponds to xs:gMonthDay |- || when the XMLGregorianCalendar instance corresponds to xs:gYear |- || when the XMLGregorianCalendar instance corresponds to xs:gYearMonth |- || when the XMLGregorianCalendar instance corresponds to xs:time |-

|| |-

|| |- |}

Native XML databases

Several Native XML Databases provide implementations of the XQuery API for Java (XQJ), including:

Relational databases

DataDirect offers XQJ adapters for various relational database systems by converting XQuery statements into SQL and adapting SQL results for XQJ consumption. Supported databases include:

Non-database implementations

Certain non-database XQuery engines feature an XQJ interface, generally designed to query XML data stored in memory. These include:

Saxon XSLT and XQuery processor
Zorba
MXQuery
Oracle XQuery Processor

License

The specification license authorizes free reproduction provided copyright notices are preserved and permits the development and distribution of fully conforming implementations without modifying or extending the interfaces, as well as passing compatibility tests.

This licensing model has generated debate. Some argue whether implementing a published specification requires a copyright license. Additionally, the prohibition on extensions or modifications means it does not qualify as an open source license under the Open Source Definition, prompting discussions about whether XQJ implementations can be genuinely classified as open source.

The reference implementation is made available under a conventional BSD-style open source license.

External links