Xquery API for Java™ (XQJ) 1.0 Specification Version 0.9 (JSR 225 Public Draft Specification) May 21, 2007
Total Page:16
File Type:pdf, Size:1020Kb
XQuery API for Java™ (XQJ) 1.0 Specification Version 0.9 (JSR 225 Public Draft Specification) May 21, 2007 Spec Lead: Jim Melton Oracle Editor: Marc Van Cappellen DataDirect Technologies This document is the Public Draft Specification of the XQuery API for Java™ (XQJ) 1.0. It describes the current state of the XQuery API for Java™ (XQJ), and is subject to possibly changes and should not be considered to be in any way final. Comments on this specification should be sent to [email protected]. Copyright © 2003, 2006, 2007, Oracle. All rights reserved. Java™ is a registered trademark of Sun Microsystems, Inc. http://www.sun.com JSR 225 Public Draft Specification – Version 0.9 SPECIFICATION LICENSE Oracle USA (the “Spec Lead”) for the XQuery API for Java specification (the “Specification”) hereby grant a perpetual, non-exclusive, worldwide, fully paid-up, royalty-free, irrevocable (except as explicitly set forth below) license to copy and display the Specification, in any medium without fee or royalty, provided that you include the following on ALL copies, or portions thereof, that you make: 1. A link or URL to the Specification at this location: __________. 2. The copyright notice as shown herein. In addition, to the extent that an implementation of the Specification would be considered a derivative work under applicable law requiring a license grant from the holder of the copyright in the Specification, the Spec Lead grants a copyright license solely for the purpose of making and/or distributing an implementation of the Specification that: (a) except for the RI code licensed from Oracle under the RI License, does not include or otherwise make any use of the RI; (b) fully implements the Specification including all of its required interfaces and functionality; (c) does not modify, subset, superset or otherwise extend those public class or interface declarations whose names begin with “java;” and (d) passes the TCK. The Spec Lead also agrees, upon request, to grant a perpetual, non-exclusive, worldwide, non sub-licensable, non-transferable, royalty-free fully paid-up license, for the sole purposes of making, having made, using, selling and offering for sale, implementations of the Specification that meet the requirements of (a) - (d) above, under those respective patent claims that they own, or have the authority to license, for which there is no technically feasible way of avoiding infringement in the course of implementing the Specification (“Necessary Patent Claims”). The licenses and agreement to license set forth above are conditional upon licensee’s offering a license, on fair, reasonable and non-discriminatory terms to Necessary Patent Claims that they own or have the authority to license to make, have made, use, sell and offer for sale, implementations of the Specification that meet the requirements of (a) - (d) above, to all other licensees to the Specification who agree to offer a similar license and not initiating any claim that either Specification Lead, has, in the course of performing its responsibilities as the Specification Lead, induced any other entity to infringe the licensee’s patent rights. THE SPECIFICATION IS PROVIDED "AS IS," AND THE SPEC LEAD AND ANY OTHER AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON- INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY PATENTS (INCLUDING, JSR 225 Public Draft Specification Page 2 of 106 May 21, 2007 JSR 225 Public Draft Specification – Version 0.9 WITHOUT LIMITATION, PATENTS OF THE SPECIFICATION LEADS), COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. THE SPEC LEAD AND ANY OTHER AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SPECIFICATION OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF. The name and trademarks of the Spec Lead or any other Authors may NOT be used in any manner, including advertising or publicity pertaining to the Specification or its contents without specific, written prior permission. Title to copyright in the Specification will at all times remain with the Authors. No other rights are granted by implication, estoppel or otherwise. JSR 225 Public Draft Specification Page 3 of 106 May 21, 2007 JSR 225 Public Draft Specification – Version 0.9 Table of Contents Table of Contents................................................................................................................ 4 1 Introduction................................................................................................................. 8 1.1 Getting Started with XQJ.................................................................................... 8 1.2 Definitions........................................................................................................... 9 1.3 Platforms............................................................................................................. 9 1.4 Target Audience.................................................................................................. 9 1.5 Submitting Feedback .......................................................................................... 9 1.6 Acknowledgements............................................................................................. 9 2 Goals and Non-Goals................................................................................................ 11 2.1 Goals ................................................................................................................. 11 2.2 Non-Goals......................................................................................................... 11 3 Compliance ............................................................................................................... 13 3.1 Definitions......................................................................................................... 13 3.2 Guidelines and Requirements ........................................................................... 13 3.3 XQJ 1.0 Compliance......................................................................................... 14 4 Overview................................................................................................................... 16 4.1 Establishing a Connection................................................................................. 16 4.2 Executing Queries and Retrieving Results ....................................................... 17 4.3 Introductory Examples...................................................................................... 18 4.3.1 Example – One-time execution of an XQuery Expression....................... 18 4.3.2 Example – Binding a value to an external variable .................................. 19 4.3.3 Example – Multiple Executions with Different Input Values .................. 19 4.3.4 Example – Binding a value to the context item ........................................ 20 4.3.5 Example – Retrieving results from an XQuery......................................... 22 4.3.6 Example – Using a Result Sequence as Input........................................... 23 4.3.7 Example – Making the Result available after closing the Connection ..... 24 4.3.8 Example – Error Handling........................................................................ 25 5 Classes and Interfaces............................................................................................... 27 6 Exceptions................................................................................................................. 30 6.1.1 Navigating XQExceptions ........................................................................ 30 6.1.2 The XQException class............................................................................. 31 6.1.3 The XQQueryException class................................................................... 32 6.1.4 The XQCancelledException class............................................................. 32 6.1.5 Serializing XQException objects.............................................................. 33 7 DataSources .............................................................................................................. 34 7.1 XQDataSource Properties................................................................................. 34 7.2 Creating an XQDataSource and XQConnection............................................... 35 7.3 Application Portability...................................................................................... 35 7.4 The JNDI API and Application Portability....................................................... 36 8 Connections............................................................................................................... 38 8.1 Creating an XQConnection............................................................................... 38 8.2 Using an XQConnection................................................................................... 39 8.3 Interacting with JDBC Connections ................................................................. 39 9 Static Contexts .......................................................................................................... 41 JSR 225 Public Draft Specification Page 4 of 106 May 21, 2007 JSR 225 Public Draft Specification – Version 0.9 9.1 XQStaticContext..............................................................................................