Login
Login

XQuery API for Java

{{Short description|Application programming interface}}

{{Use dmy dates|date=August 2015}}

{{Infobox software

|name = XQJ

|logo =

|caption =

|developer = Java Community Process

|latest release version = 1.0

|latest release date = {{Start date|df=yes|2009|06|24}}

|latest preview version =

|latest preview date =

|operating_system =

|genre = Data Access API

|license =

|website = [http://jcp.org/en/jsr/detail?id=225 JSR 225: XQuery API for Java]

}}

File:XQJ-Architecture.svg

XQuery API for Java (XQJ) refers to the common Java API for the W3C XQuery 1.0 specification.

The XQJ API enables Java programmers to execute XQuery against an XML data source (e.g. an XML database) while reducing or eliminating vendor lock in.

The XQJ API provides Java developers with an interface to the XQuery Data Model.[http://www.w3.org/TR/xpath-datamodel/ XQuery 1.0 and XPath 2.0 Data Model (XDM)] Its design is similar to the JDBC API which has a client/server feel and as such lends itself well to Server-based XML Databases and less well to client-side XQuery processors, although the "connection" part is a very minor part of the entire API. Users of the XQJ API can bind Java values to XQuery expressions, preventing code injection attacks.[http://www.cfoster.net/articles/xqj-tutorial/binding-java-variables.xml Binding Java Variables] Also, multiple XQuery expressions can be executed as part of an atomic transaction.

History and implementation

The XQuery API for Java was developed at the Java Community Process as JSR 225. It had some big technology backers such as Oracle,Querying XML: XQuery, XPath, and SQL/XML in context - Jim Melton and Stephen Buxton. {{ISBN|978-1558607118}}[http://www.sigmod.org/publications/sigmod-record/0912/p07.article.cappellen.pdf XQJ - XQuery Java API is Completed, Marc Van Cappellen, Zhen Hua Liu, Jim Melton and Maxim Orgiyan] {{webarchive |url=https://web.archive.org/web/20120728102540/http://www.sigmod.org/publications/sigmod-record/0912/p07.article.cappellen.pdf |date=28 July 2012 }}[http://xml.coverpages.org/ni2003-06-12-b.html IBM and Oracle Submit XQuery API for Java (XQJ) Java Specification Request.][http://www.sigmod.org/publications/sigmod-record/0406/JimAndrew.pdf An Early Look at XQuery API for Java (XQJ) - Andrew Eisenberg, IBM and Jim Melton, Oracle] {{webarchive |url=https://web.archive.org/web/20120728091917/http://www.sigmod.org/publications/sigmod-record/0406/JimAndrew.pdf |date=28 July 2012 }} IBM, BEA Systems,[http://www.cfoster.net/pdf/reference/10.1.1.92.2337.pdf#page=17 The BEA Streaming XQuery Processor] Software AG,[http://documentation.softwareag.com/webmethods/wmsuites/wmsuite8-2_ga/CentraSite/8-2-SP1_CentraSite/dg-xqj/overview.htm XQJ Interface for Tamino Native XML Database] {{webarchive |url=https://web.archive.org/web/20130530022516/http://documentation.softwareag.com/webmethods/wmsuites/wmsuite8-2_ga/CentraSite/8-2-SP1_CentraSite/dg-xqj/overview.htm |date=30 May 2013 }} Intel, Nokia and DataDirect.

Version 1.0 of the XQuery API for Java Specification was released on June 24, 2009,[http://jcp.org/aboutJava/communityprocess/final/jsr225/index.html JSR-000225 XQuery API for Java (Final Release)] along with JavaDocs, a reference implementation and a TCK (Technology Compatibility Kit) which implementing vendors must conform to.

The XQJ classes are contained in the Java package [http://xqj.net/javadoc/ javax.xml.xquery]

There is no (visible) activity to create a version of XQJ that provides support for XQuery 3.0 or 3.1, for example by providing Java bindings for additions to the data model such as functions, arrays, or maps.

Functionality

XQJ allows multiple implementations to exist and be used by the same application.

XQJ connections support creating and executing XQuery expressions. Expressions may be updatingXQuery Update Facility and may include full text searches.[http://www.w3.org/TR/xpath-full-text-10/ XQuery Full Text] XQJ represents XQuery expressions using one of the following classes:

  • [http://xqj.net/javadoc/javax/xml/xquery/XQExpression.html XQExpression] – the expression is sent to the XQuery processor every time.
  • [http://xqj.net/javadoc/javax/xml/xquery/XQPreparedExpression.html XQPreparedExpression] – the expression is cached and the execution path is pre-determined allowing it to be executed multiple times in an efficient manner.

XQuery expressions return a result sequence of XDM items which in XQJ are represented through the [http://xqj.net/javadoc/javax/xml/xquery/XQResultSequence.html XQResultSequence] interface. The programmer can use an [http://xqj.net/javadoc/javax/xml/xquery/XQResultSequence.html XQResultSequence] to walk over individual XDM items in the result sequence. Each item in the sequence has XDM type information associated with it, such as its node type e.g. {{code|element()}}, {{code|document-node()}} or an XDM atomic type such as {{code|xs:string}}, {{code|xs:integer}} or {{code|xs:dateTime}}. XDM type information in XQJ can be retrieved via the [http://xqj.net/javadoc/javax/xml/xquery/XQItemType.html XQItemType] interface.

Atomic XQuery items can be easily cast to Java primitives via [http://xqj.net/javadoc/javax/xml/xquery/XQItemAccessor.html XQItemAccessor] methods such as [http://xqj.net/javadoc/javax/xml/xquery/XQItemAccessor.html#getByte() getByte()] and [http://xqj.net/javadoc/javax/xml/xquery/XQItemAccessor.html#getFloat() getFloat()]. Also XQuery items and sequences can be serialized to DOM {{Javadoc:SE|org/w3c/dom|Node|module=java.xml}}, SAX {{Javadoc:SE|org/xml/sax|ContentHandler|module=java.xml}}, StAX {{Javadoc:SE|javax/xml/stream|XMLStreamReader|module=java.xml}} and the generic IO {{Javadoc:SE|java/io|Reader}} and {{Javadoc:SE|java/io|InputStream}} classes.

Examples

=Basic example=

The following example illustrates creating a connection to an XML Database, submitting an XQuery expression, then processing the results in Java. Once all of the results have been processed, the connection is closed to free up all resources associated with it.

// Create a new connection to an XML database

XQConnection conn = vendorDataSource.getConnection("myUser", "myPassword");

XQExpression expr = conn.createExpression(); // Create a reusable XQuery Expression object

XQResultSequence result = expr.executeQuery(

"for $n in fn:collection('catalog')//item " +

"return fn:data($n/name)"); // execute an XQuery expression

// Process the result sequence iteratively

while (result.next()) {

// Print the current item in the sequence

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

}

// Free all resources created by the connection

conn.close();

=Binding a value to an external variable=

The following example illustrates how a Java value can be bound to an external variable in an XQuery expression.

Assume that the connection {{code|conn}} already exists:

XQExpression expr = conn.createExpression();

// The XQuery expression to be executed

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)";

// Bind a value (21) to an external variable with the QName x

expr.bindInt(new QName("x"), 21, null);

// Execute the XQuery expression

XQResultSequence result = expr.executeQuery(es);

// Process the result (sequence) iteratively

while (result.next()) {

// Process the result ...

}

Default data type mapping

Mapping between Java and XQuery data types is largely flexible, however the XQJ 1.0 specification does have default mapping rules mapping data types when they are not specified by the user. These mapping rules bear great similarities to the mapping rules found in JAXB.

The following table illustrates the default mapping rules for when binding Java values to external variables in XQuery expressions.

class="wikitable"

|+ Default conversion rules when mapping from Java data types to XQuery data types

Java Datatype

! Default XQuery Data Type(s)

{{code|boolean}}

| {{code|xs:boolean}}

{{code|byte}}

| {{code|xs:byte}}

{{code|byte[]}}

| {{code|xs:hexBinary}}

{{code|double}}

| {{code|xs:double}}

{{code|float}}

| {{code|xs:float}}

{{code|int}}

| {{code|xs:int}}

{{code|long}}

| {{code|xs:long}}

{{code|short}}

| {{code|xs:short}}

{{Javadoc:SE|java/lang|Boolean}}

| {{code|xs:boolean}}

{{Javadoc:SE|java/lang|Byte}}

| {{code|xs:byte}}

{{Javadoc:SE|java/lang|Float}}

| {{code|xs:float}}

{{Javadoc:SE|java/lang|Double}}

| {{code|xs:double}}

{{Javadoc:SE|java/lang|Integer}}

| {{code|xs:int}}

{{Javadoc:SE|java/lang|Long}}

| {{code|xs:long}}

{{Javadoc:SE|java/lang|Short}}

| {{code|xs:short}}

{{Javadoc:SE|java/lang|String}}

| {{code|xs:string}}

{{Javadoc:SE|java/math|BigDecimal}}

| {{code|xs:decimal}}

{{Javadoc:SE|java/math|BigInteger}}

| {{code|xs:integer}}

rowspan="3"| {{Javadoc:SE|javax/xml/datatype|Duration|module=java.xml}}

| {{code|xs:dayTimeDuration}} if the {{code|Duration}} Object's state is {{code|xs:dayTimeDuration}}

{{code|xs:yearMonthDuration}} if the {{code|Duration}} Object's state is {{code|xs:yearMonthDuration}}
{{code|xs:duration}} if the {{code|Duration}} Object's state is {{code|xs:duration}}
rowspan="8"| {{Javadoc:SE|javax/xml/datatype|XMLGregorianCalendar|module=java.xml}}

| {{code|xs:date}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:date}}

{{code|xs:dateTime}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:dateTime}}
{{code|xs:gDay}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:gDay}}
{{code|xs:gMonth}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:gMonth}}
{{code|xs:gMonthDay}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:gMonthDay}}
{{code|xs:gYear}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:gYear}}
{{code|xs:gYearMonth}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:gYearMonth}}
{{code|xs:time}} if the {{code|XMLGregorianCalendar}} Object's state is {{code|xs:time}}
{{Javadoc:SE|javax/xml/namespace|QName|module=java.xml}}

| {{code|xs:QName}}

{{Javadoc:SE|org/w3c/dom|Document|module=java.xml}}

| {{code|document-node(element(*, xs:untyped))}}

{{Javadoc:SE|org/w3c/dom|DocumentFragment|module=java.xml}}

| {{code|document-node(element(*, xs:untyped))}}

{{Javadoc:SE|org/w3c/dom|Element|module=java.xml}}

| {{code|element(*, xs:untyped)}}

{{Javadoc:SE|org/w3c/dom|Attr|module=java.xml}}

| {{code|attribute(*, xs:untypedAtomic)}}

{{Javadoc:SE|org/w3c/dom|Comment|module=java.xml}}

| {{code|comment()}}

{{Javadoc:SE|org/w3c/dom|ProcessingInstruction|module=java.xml}}

| {{code|processing-instruction()}}

{{Javadoc:SE|org/w3c/dom|Text|module=java.xml}}

| {{code|text()}}

Known implementations

=Native XML databases=

The following is a list of Native XML Databases which are known to have XQuery API for Java implementations.

  • MarkLogic[http://xqj.net/marklogic MarkLogic XQJ API]
  • eXist[http://xqj.net/exist eXist XQJ API]
  • BaseX[http://xqj.net/basex BaseX XQJ API]
  • Sedna[http://xqj.net/sedna Sedna XQJ API]
  • Oracle [http://www.oracle.com/technetwork/database-features/xmldb/overview/index.html XDB][http://docs.oracle.com/cd/E16655_01/appdev.121/e17604/adx_j_xqjxdb.htm#ADXDK136 Oracle XML DB Support for XQJ]
  • Tamino[https://archive.today/20130914203527/http://documentation.softwareag.com/webmethods/wmsuites/wmsuite8-2_ga/CentraSite/8-2-SP1_CentraSite/dg-xqj/working_xqjdriver.htm Software AG - Working with the CentraSite XQJ Interface]
  • TigerLogic

=Relational databases=

DataDirect provide XQJ adapters for relational databases, by translating XQuery code into SQL on the fly, then converting SQL result sets into a format suitable for XQJ to process further. The following is a couple of known implementations.

=Non-database implementations=

The following is a list of non-database XQuery processors which provide an XQuery API for Java interface (typically allowing query against documents parsed from XML in filestore, and held in memory as DOM or similar trees).

  • Saxon XSLT and XQuery processor
  • Zorba[https://archive.today/20130210145706/http://www.zorba-xquery.com/html/entry/2012/06/14/Zorba_25 Zorba 2.5 ships with a long awaited XQJ binding, 14 June 2012]
  • MXQuery
  • Oracle XQuery Processor [http://docs.oracle.com/cd/E16655_01/appdev.121/e17604/adx_j_xqj.htm#ADXDK99930 Oracle XML Developer's Kit (XDK) provides a standalone XQuery 1.0 processor for use by Java applications.]

License

The specification is marked as "Copyright © 2003, 2006 - 2009 Oracle. All rights reserved."

The specification contains two separate licenses: a "specification license" and a "reference implementation license".

The specification license allows free copying of the specification provided that copyright notices are retained; it also grants a license to create and distribute an implementation of the

specification provided that it fully implements the entire specification, that it does not modify or extend any interfaces, and that it passes the compatibility tests.

This provision has caused some controversy. Firstly, it is not universally accepted that implementing a published specification is something that requires a license (that is, that copyright law would disallow this in the absence of a license).{{cite web|url=http://rosenlaw.com/wp-content/uploads/Open-Standards.pdf |title=Open Standards|access-date=2023-09-07}}{{cite web |url=http://www.groklaw.net/articlebasic.php?story=20120221094600287 |title=Groklaw - Oracle v. Google - Understanding the Copyright Issue with API Specifications |website=www.groklaw.net |url-status=dead |archive-url=https://web.archive.org/web/20120505083130/http://www.groklaw.net/articlebasic.php?story=20120221094600287 |archive-date=2012-05-05}} Secondly, the license does not meet the criteria to qualify as an open source license (see Open Source Definition), because of the ban on making extensions and modifications. This has led some open source enthusiasts to challenge whether XQJ implementations can ever be considered truly open source.

The license for the reference implementation is a fairly conventional BSD-style open source license.

References

{{reflist}}

External links

  • [http://xqj.net/javadoc/ Javadoc for XQJ]
  • [http://www.cfoster.net/articles/xqj-tutorial/ XQJ Tutorial]
  • [http://archive.xmlprague.cz/2012/files/xmlprague-2012-proceedings.pdf#page=197 Building Bridges from Java to XQuery, Charles Foster. XML Prague 2012] ([http://prezi.com/lviyahwtaxge/building-bridges-from-java-to-xquery/ Prezi Presentation])
  • [http://www.balisage.net/Proceedings/vol5/html/Rennau01/BalisageVol5-Rennau01.html Java Integration of XQuery, Hans-Jürgen Rennau. Balisage 2010]
  • [http://wiki.orbeon.com/forms/doc/developer-guide/processors-xquery-generator#TOC-XQuery-processor-implementations Orbeon Forms using XQJ]
  • [https://github.com/SpringSource/spring-integration-extensions/tree/master/spring-integration-xquery Spring Integration XQuery Support]
  • [https://github.com/fancellu/xqs XQS: XQuery for Scala (Sits on top of XQJ)]
  • [https://ligasgr.github.io/intellij-xquery/ IntelliJ XQuery Support plugin]

Category:Java APIs

Category:Java specification requests

Category:XML data access

Category:Java API for XML

Category:Database APIs