Centrasite XQJ Interface This Document Applies to Soalink Cookbook V8.0 Version 8.0 2008-12-17 and to All Subsequent Releases

Version 8.0 2008-12-17 The CentraSite XQJ Interface This document applies to SOALink Cookbook v8.0 Version 8.0 2008-12-17 and to all subsequent releases.

Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.

The name Software AG and/or all Software AG product names are either trademarks or registered trademarks of Software AG. Other company and product names mentioned herein may be trademarks of their respective owners. The CentraSite XQJ Interface CentraSite XQJ Interface

Table of Contents

CentraSite XQJ Interface ...... 1 CentraSite XQJ Interface ...... 1 What is XQJ? ...... 2 What is XQJ? ...... 2 Features of the CentraSite XQJ Interface ...... 2 Working with the CentraSite XQJ Interface ...... 3 Working with the CentraSite XQJ Interface ...... 3 Establishing an XQConnection ...... 3 Creating an XQExpression ...... 5 Executing an XQuery ...... 5 Binding External Variables ...... 7 Executing a Prepared Expression ...... 7 Updating a Database Using XQJ ...... 8 Inserting a Document in the CentraSite Registry/Repository ...... 8 Working with an XQCachedSequence ...... 8 XQDataSource Properties ...... 11 XQDataSource Properties ...... 11 Tracing ...... 13 Tracing ...... 13

Draft: 17 Dec 2008 16:37 i

The CentraSite XQJ Interface CentraSite XQJ Interface

CentraSite XQJ Interface

You can use XQJ, the XQuery API for Java™, for processing XML and for data integration applications. This document introduces the CentraSite implementation of XQJ and its features. It explains how to use the API and provides examples for each type of task.

The reader of the document should be an experienced Java programmer.

This document covers the following topics.

What is XQJ? Introduces the XQuery API for Java and explains its features Working with the CentraSite XQJ Describes various tasks you can perform with XQJ Interface XQDataSource Properties Lists and explains all datasource properties Tracing Provides details of Log4J Javadoc: dataAPI Javadoc of the API for writing CentraSite XQJ interfaces Messages and Codes: XQJ messages Messages and codes listed

Draft: 17 Dec 2008 16:37 1 What is XQJ? The CentraSite XQJ Interface

What is XQJ?

XQJ, the XQuery API for Java, is based on XQuery, a query language promulgated by the W3C that can operate both on physical XML documents, and also on virtual XML documents that have been derived from data sources such as relational or object databases. XQJ is a powerful new API standard developed as per JSR 225 (Java Specification Requirement 225) for invoking XQuery expressions against virtually any XML or relational database and processing query results. XQJ makes the full power of the XQuery language available to Java applications. You can programmatically process the results in your Java code in a JDBC-like manner. XQJ is to XQuery what JDBC is to SQL.

The XQJ standard specifies a number of Java interfaces. The CentraSite XQJ interface implements the functionality defined by these interfaces, and thus makes XQJ available to the application.

Note: Beside its standard functionality, CentraSite offers an implementation of an early draft of the upcoming XQJ specification (JSR 225). The CentraSite XQJ interface is an implementation of an interim XQJ specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP. As a member of the XQJ Expert Group, Software AG is in the best position to keep this interface in sync with the latest released versions of the specification.

Features of the CentraSite XQJ Interface

The CentraSite XQJ interface supports:

Prepared XQueries

The submission of queries to the CentraSite registry/repository

XQuery updates

Transaction control (commit, rollback)

User authentication prior to connecting to the database

Variable binding to parameterize queries

Handling registry/repository errors and warnings

The creation and execution of cached sequences and items

Different models for accessing data in the CentraSite registry/repository (DOM, SAX, and StAX streams)

2 Draft: 17 Dec 2008 16:37 The CentraSite XQJ Interface Working with the CentraSite XQJ Interface

Working with the CentraSite XQJ Interface

You can use the CentraSite XQJ interface to perform the following tasks:

Establishing an XQConnection

Creating an XQExpression

Executing an XQuery

Binding External Variables

Executing a Prepared Expression

Updating a Database Using XQJ

Inserting a Document in the CentraSite Registry/Repository

Working with an XQCachedSequence

Establishing an XQConnection

An XQConnection object represents a connection to the data source (i.e. registry/repository database in this context) using the CentraSite XQJ interface. This is the first and a very important step.

To establish a connection to the database

1. Set up property values to connect to the datasource, which is the CentraSite registry/repository in this case. You must specify the following property values:

com.softwareag.tamino.xqj.dbUri

Convention: http://{pcname}/tamino/{databasename}

com.softwareag.tamino.xqj.defaultCollection

To learn more about properties, refer to the section Datasource Properties

2. Specify the fetch size parameter value to retrieve and view the query result in manageable portions from the server.

3. After specifying the datasource properties, invoke the get Connection() method to get the XQConnection object from the datasource. You may establish single or multiple connections to the datasource using this method.

4. Once the connection has been established, you can use it to create:

Draft: 17 Dec 2008 16:37 3 Working with the CentraSite XQJ Interface The CentraSite XQJ Interface

XQExpression objects

XQPreparedExpression objects

XQCachedItem objects

XQCachedSequence objects

5. Finally, invoke the XQConnection.close() method to close the connection to the datasource.

Example

1. /* A connection is always created from a datasource */

XQDataSourceImpl dataSource = new XQDataSourceImpl();

2. /* Set property values for establishing a connection to the CentraSite registry/repository. This can be done in any of the following ways */

Set the properties for the datasource using the setProperty() method;

Load the properties from a file.

3. /* Set the URI of the CentraSite registry/repository. In this example, "DBURI" is a string that indicates the address of the database */

dataSource.setProperty("com.softwareag.tamino.xqj.dbUri", DBURI);

4. /* Set the user ID and password to establish a connection to the CentraSite registry/repository */

dataSource.setProperty("javax.xml.xquery.property.UserName", username); dataSource.setProperty("javax.xml.xquery.property.Password ", password);

5. /* Set the default collection within the CentraSite registry/repository that you will use to query on. In this example, "COLLECTION" is a string that indicates the said property */

dataSource.setProperty("com.softwareag.tamino.xqj.defaultCollection", COLLECTION);

6. /* Set the fetch size i.e., the number of records to be retrieved. This property only has to be set when querying or updating a database query*/

dataSource.setProperty("com.softwareag.tamino.xqj.fetchSize","2");

/ * Specify the connection properties in a separate file and load the properties from the file as mentioned below */

Properties properties = new Properties(); properties.load(new FileInputStream("E:/xqj.properties")); dataSource.setProperties(properties);

7. /*Get the XQConnection from the dataSource */

XQConnection connection = dataSource.getConnection();

4 Draft: 17 Dec 2008 16:37 The CentraSite XQJ Interface Working with the CentraSite XQJ Interface

8. /*Commit and close the XQConnection once you have completed working with it */

connection.commit(); connection.close();

Creating an XQExpression

Once the connection to the registry/repository has been established, the next stage is to create and execute an XQExpression. This is an important step to execute any method using the CentraSite XQJ interface.

To create an XQExpression

1. Connect to the registry/repository.

2. Create the XQExpression object from the XQConnection object. The XQExpression is used to invoke several other methods to perform various tasks using the CentraSite XQJ interface. You may create more than one XQExpression from a single connection if required.

Example

/*Create XQExpression from XQConnection to execute an XQuery.*/ XQExpression expression = connection.createExpression();

Executing an XQuery

The steps below explain the procedure to create and execute an XQuery.

To create and execute an XQuery

1. Invoke the executeQuery() method to return an XQResultSequence.

2. The XQResultSequence represents the XQuery result. Retrieve the query result and read/print it in XML format. The query result sequence is displayed item by item. Using XQJ, it is possible to get the result sequence in DOM, SAX and StAX formats.

3. Invoke the XQConnection.close() method to close the connection to the registry/repository.

Example

/*Instance of the query string*/ String xquery = "for $b in input()/book return $b/title"; /*Execute the above XQuery String which returns a XQResultSequence*/ XQResultSequence xqResultSequence = expression.executeQuery(xquery);

Note: You cannot scroll the XQResultSequences backwards.

Draft: 17 Dec 2008 16:37 5 Working with the CentraSite XQJ Interface The CentraSite XQJ Interface

/*Iterating the XQResultSequence*/ XMLStreamReader reader = null; StringWriter sw = null; While(xqResultSequence.next()) { reader = xqResultSequence.getXMLStreamReader(); /*Iterate the XML StreamReader using StAX APIs*/ } connection.commit(); connection.close();

Example using the getInt() method

The getInt() method returns an integer value of the XQResultSequence.

/*Instance of the XQuery String*/ String xquery =" for $b in input()/bib/book return xs:int($b/@year) "; /*This query on execution will return the year as an integer value*/ XQResultSequence xqResultSequence = expression.executeQuery(xquery); xqResultSequence.next(); int I = xqResultSequence.getInt();

Example using the getString() method

The getString() method returns a string of the XQResultSequence.

/*Instance of the XQuery String*/ String xquery = "for $p in input()/book return xs:string($p/title)"; XQResultSequence xqResultSequence = expression.executeQuery(xquery);

/*This query on execution will return the title as a String*/ xqResultSequence.next(); String str = xqResultSequence.getString ();

Example using the getNode() method

The getNode() method returns a DOM node of the XQResultSequence.

/*Instance of the XQuery String*/ String xquery = "for $q in input()/bib/book return $q"; XQResultSequence xqResultSequence = expression.executeQuery("); xqResultSequence.next(); Node node = result.getNode();

Example using the writeSAX() method

The writeSAX() method writes an item in the XQResultSequence to the SAX stream.

Note: The item currently referred to must be an atomic value that can be cast to a string or a node other than an attribute.

6 Draft: 17 Dec 2008 16:37 The CentraSite XQJ Interface Working with the CentraSite XQJ Interface

xqResultSequence.next(); StringWriter sw = new StringWriter(); /*Provide a org.xml.sax.ContentHandler, which is saxhandler in our case*/

XQSAXTextEventHandler saxhandler = new XQSAXTextEventHandler(sw); resultSequence.writeSAX(saxhandler); System.out.println(sw);

Binding External Variables

An external variable is a type of variable that can be dynamically added to the query by declaring the variable in the query. The value of the variable can be set externally and added to the pre-set variable while executing the XQuery. The externally-bound variables can be set within a normal XQuery expression or an XQuery PreparedExpression.

Example

String xquery = "declare variable $year as xs:int external" + "for $q in input()/bib/book where $q/@year > $year return $q" ;

XQExpression expression = connection.createExpression(); expression.bindInt(new QName("year"),1993); XQResultSequence xqResultSequence = expression.executeQuery(xquery);

Executing a Prepared Expression

When an XQuery is executed, the query is parsed before it is executed. However, it is possible to avoid repeating the procedure every time the XQuery is used. XQJ simplifies the procedure and enables queries to be prepared once and executed multiple times.

To execute a prepared expression

1. Create an XQPreparedExpression.

2. You can now set values for bound variables.

3. Invoke the executeQuery() method to execute the prepared expression. This returns the XQResultSequence.

4. The ResultSequence represents the XQuery result. Retrieve the query result and read/print it in XML format. The query result sequence is displayed item by item. Using XQJ, it is possible to get the result sequence in DOM, SAX and StAX formats.

5. Invoke the XQConnection.close() method to close the connection to the registry/repository.

Example

/*Binding variables in Prepared Expressions*/ String pQuery = "declare variable $int as xs:int external" + "for $q in input()/bib/book where $q/@year = $int return $q"; XQPreparedExpression preparedExpression = conn.prepareExpression(pQuery); /*Bind the appropriate value to the prepared expression using the matching binding API provided.*/

Draft: 17 Dec 2008 16:37 7 Working with the CentraSite XQJ Interface The CentraSite XQJ Interface

Using bindInt() to bind an int value to the prepared expression preparedExpression.bindInt(new QName("int"), 1994); XQResultSequence xqResultSequence = preparedExpression.executeQuery();

Executing an XQPreparedExpression using the bindNode()

XQExpression expression = connection.createExpression(); XQResultSequence xqResultSequence = expression.executeQuery("for $q in input()/bib/book where $q/@year = 1994 return $q/title"); xqResultSequence.next(); /*Get a node from the result sequence retrieved above*/ Node node = xqResultSequence.getNode(); /*PreparedQuery*/ String pquery = "declare variable $node external " + "for $q in input()/bib/book where $q/title = $node return $q"; XQPreparedExpression prepared = connection.prepareExpression(pQuery); /*Bind the above retrieved node to the prepared query*/ prepared.bindNode(new QName("node"), node); XQResultSequence preparedResult = prepared.executeQuery();

Updating a Database Using XQJ

Using the CentraSite XQJ interface, you can update the registry/repository. This feature is a Software AG specific extension of XQJ.

To update an XQuery

1. Specify the string or the reader object containing the update XQuery

2. Invoke the executeUpdate() method on the expression

Example

String updateQuery = "update for $q in input()/bib/book where $q/@year = 1994" + "do replace $q/title with XQJ from SoftwareAG "; XQResultSequence xqResultSequence = ((XQExpressionImpl)expression).executeUpdate(updateQuery); // execute update

Inserting a Document in the CentraSite Registry/Repository

This feature is a Software AG specific extension of XQJ.

To insert a document in the CentraSite Registry/Repository

1. Specify the XML instance to be inserted as a string or the reader object.

2. Execute the executeInsert () method in XQExpression to insert a document.

Example

String insertStr = ""; (XQExpressionImpl)expression).executeInsert(insertStr);

Working with an XQCachedSequence

An XQCachedSequence represents a sequence of XQCachedItems that outlives the XQConnection. An XQCachedSequence enables inserting and removing items and sequences.

8 Draft: 17 Dec 2008 16:37 The CentraSite XQJ Interface Working with the CentraSite XQJ Interface

To creating an XQCachedSequence

1. Invoke the createCachedSequence() method on XQConnection that returns an XQCachedSequence which is independent of the XQConnection.

2. You can create sequence types and Item types and insert them in the CachedSequence. The example below illustrates the procedure.

Examples Creating a CachedSequence

XQCachedSequence cachedSequence = connection.createCachedSequence(); /*The XQItemType interface is used to represent the type information of an item type as described in the XQuery.*/ Create an itemType for the item that is to be inserted as follows: XQItemType itemType = connection.createItemType(XQItemType.XQITEMTYPE_ATOMIC, null, new QName("http://www.w3.org/2001/XMLSchema", "int", "xs"), false); /*Insert an item into the Cached Sequence with the above created XQItemType*/ cachedSequence.insertInt(1, itemType);

Retrieving an Integer value from a CachedSequence using getInt() cachedSequence.next(); int value = cachedSequence.getInt();

Inserting a XQResultSequence into a CachedSequence

String query = "for $q in input()/bib/book where $q/@year = 1994 return $q"; XQExpression expression = connection.createExpression(); XQResultSequence resultSequence = expression.executeQuery(query);

XQCachedSequence cachedSequence = connection.createCachedSequence(); /*Insert the above resultSequence into the cachedSequence*/ cached.insertSequence(result);

Creating a CachedItem from another XQItem

XQResultSequence resultSequence = expression.executeQuery("for $q in input()/bib/book return $q"); resultSequence.next();

XQItem item = result.getItem(); XQCachedItem cachedItem = connection.createItem(item);

The following snippet explains the use of getString () method

XQItemType xqItemType = connection.createItemType(XQItemType.XQITEMTYPE_ATOMIC, null, new QName("http://www.w3.org/2001/XMLSchema", "string", "xs"), false); cachedSequence.insertString("TestString", xqItemType); cachedSequence.next(); String str = xqResultSequence.getString ();

Using insertItem() to insert an XQItem in the CachedSequence

String query = "for $q in input()/bib/book where $q/@year = 1994 return $q"; XQResultSequence xqResultSequence = expression.executeQuery(query); xqResultSequence.next();

XQItem item = xqResultSequence.getItem(); cachedSequence.insertItem(m_item);

Draft: 17 Dec 2008 16:37 9 Working with the CentraSite XQJ Interface The CentraSite XQJ Interface

The following snippet explains the getItem() method cachedSequence.next(); XQCachedItem cachedItem = (XQCachedItem) cachedSequence.getItem();

10 Draft: 17 Dec 2008 16:37 The CentraSite XQJ Interface XQDataSource Properties

XQDataSource Properties

The following datasource properties must be specified to connect to the CentraSite registry/repository. The table lists all properties and their descriptions.

Property Description com.softwareag.tamino.xqj.dbUri Mandatory. Indicates the URI of the database to which the user is connecting. This information is mandatory to connect to the datasource, which is the CentraSite registry/repository in this context. com.softwareag.tamino.xqj.defaultCollection Mandatory. Specifies the name of the collection in the registry/repository that the user will access to query, update, or insert a document. javax.xml.xquery.property.UserName Unique user ID for connecting to the registry/repository. javax.xml.xquery.property.Password The password for the specified user ID. javax.xml.xquery.property.MaxConnections Indicates the maximum number of open connections that can be established from the datasource. com.softwareag.tamino.xqj.isolationLevel Together with the _lockMode parameter, this parameter specifies the way in which two or more transactions in a session context can access the same data simultaneously. The isolation level can be set to "None". com.softwareag.tamino.xqj.lockMode Together with the _isolationLevel parameter, this parameter specifies the way in which two or more transactions in a session context can access the same data simultaneously. com.softwareag.tamino.xqj.lockWait Specifies the action to be taken if data is not accessible to the current transaction because another transaction has used the _isolationLevel or _lockMode parameter to restrict access to the data.

Draft: 17 Dec 2008 16:37 11 XQDataSource Properties The CentraSite XQJ Interface

com.softwareag.tamino.xqj.fetchSize Determines the number of records to be retrieved at a time for display. This property accepts an integer value. com.softwareag.tamino.xqj.sensitive The parameter _sensitive is required when opening a cursor with _xquery. Legal values are "no" and "vague". If you specify "_sensitive=no", an insensitive cursor is opened. This means that the query is calculated on a fixed input when the cursor is opened, and thus the result sequence remains unchanged as long as the cursor is active. If you specify "_sensitive=vague", a vague cursor is opened. The query is calculated on an input that takes modification operations of parallel transactions into account. Thus, the result sequence can vary during the lifetime of the cursor if documents that match the original query criteria are inserted, updated or deleted in the meantime. com.softwareag.tamino.xqj.nonactivityTimeout Specifies the non-activity timeout in seconds.

12 Draft: 17 Dec 2008 16:37 The CentraSite XQJ Interface Tracing

Tracing

XQJ uses the popular log4j API to trace the measured values. log4j is an open source project developed by the Apache Software Foundation as a logging package for Java. It allows the developer to control the output of log statements with arbitrary granularity. It is fully configurable at runtime using external configuration files. This documentation does not describe the log4j API. The latest log4j version and documentation can be found at http://logging.apache.org/log4j/index.html.

The log4j environment is typically configured when the application is initialized. The preferred way is by reading a configuration file. Please see the log4j documentation for further information.

The log4j logger used by XQJ for measuring operation duration is named com.softwareag.tamino.db.api.loggin.

Draft: 17 Dec 2008 16:37 13