Release Notes

This document contains an overview of the features of the Tamino API for Java that have been introduced or modified since the original release with Tamino V.3.1.

Binary Compatibility

All programs that ran under version 4.1 should run under version 8.x, with the following exception:

  • Exceptions have introduced a new parameter (Locale) in their constructors.

Global Transactions

Version 8.x supports global transactions using the two-phase commit (2PC) concept. In order to use this feature, call the overloaded useGlobalTransactionMode() method of the TConnection interface.

Secured Database Connections

Version 8.x supports secure database connections, which can be created with the help of security tokens. The factory class TConnectionFactory has an overloaded method newConnection() that accepts SecurityTokens as parameter. In order to use this feature, the file cstUtils.jar must be added to the execution classpath. This file is normally located in $INODIR\$INOVERS\SDK\TaminoAPI4J\lib.

Prepared XQuery

The prepared query has now been simplified.

Old style:
declare variable $y:string as xs:string external for $q in
  input()/DataTypes[string=$y:string] return $q
New style:
declare variable $y as xs:string external for $q in
  input()/DataTypes[string=$y] return $q

The following code sample shows typical usage:

// Get tamino connection, use local transaction mode
connection = getConnection();
connection.useLocalTransactionMode();
		
// Get XML object accessor 			
accessor = connection.newXMLObjectAccessor();

// Prepare XQuery using connection object
TPreparedXQuery query = connection.prepareQuery("declare variable $y as xs:string external for $q in
 input()/DataTypes[string=$y] return $q");
// Bind external variables
query.bindString(new QName("y"),"String");

// Execute prepared XQuery
TResponse response = accessor.xquery(query);

Support for Internationalization and Localization

A connection can now be created by specifying a locale. See the Javadoc of TConnectionFactory for further details.

Exceptions

All exception classes that are inherited from TException can use Local to specify internationalized messages. The class hierarchy of the TException interface can be found at javadoc/JavaTaminoAPI/com/softwareag/tamino/db/api/common/TException.html

Note:
Existing programs that were written to run with earlier versions of Tamino and throw exceptions in their code or custom exceptions derived directly or indirectly from TException will cause compilation errors if used with Tamino version 8.x.

Use of New Serialization Pragma

With version 4.4, Tamino enables you to customize the presentation of the result of an XQuery. With this new facility Tamino XQuery can manage both first-rate database querying and front-end publishing in a single step, thus making the handling of XML data even easier and faster than ever. The output of such an XQuery was always serialized using a standardized response wrapper.

The TXMLObjectAccessor will handle wrapped or unwrapped XML results and TNonXMLObjectAccessor will handle nonXML results. In order to find out whether a query will return wrapped or unwrapped XML data, the accessor must know the serialization specification. The serialization specification can be specified as a part of an XQuery expression, or it can be set using setter methods of TXQuery class.

Code Sample

Retrieve response as plain text

TXMLObjectAccessor accessor = connection.newXMLObjectAccessor( 
TAccessLocation.newInstance(COLLECTION), TDOMObjectModel.getInstance() );
TXQuery xquery = new TXQuery("for $q in input()/Account return $q");
xquery.setOutputMethod(TOutputMethod.TEXT);
TResponse response = accessor.xquery(xquery);
System.out.println("Response as a STRING -->" + response.getQueryContentAsString());

OR

TXMLObjectAccessor accessor = connection.newXMLObjectAccessor( 
TAccessLocation.newInstance(COLLECTION), TDOMObjectModel.getInstance() );
TXQuery xquery = new TXQuery("{?serialization method='text' media-type='text/plain'?}for $q in
input()/Account return $q");
TResponse response = accessor.xquery(xquery);
System.out.println("Response as a STRING -->" + response.getQueryContentAsString());

Retrieve response as nonXML document

TNonXMLObjectAccessor accessor = connection.newNonXMLObjectAccessor( 
TAccessLocation.newInstance(COLLECTION));
TXQuery xquery = new TXQuery("declare namespace tf = 
\"http://namespaces.softwareag.com/tamino/TaminoFunction\" " + 
"declare namespace ino= \"http://namespaces.softwareag.com/tamino/response2\" " + 
"input()/ino:nonXML[tf:getInoId(.)=5]/..");
xquery.setOutputMethod(TOutputMethod.INODOCUMENT);
TResponse response = accessor.xquery(xquery);
//Get inputStream from response.
TInputStream inputStream = response.getQueryContentAsStream();

Use of Cursor Parameter _scroll

Until the previous release, the _scroll parameter had always been set to "yes", even if the user did not intend to move backward in a cursor. The current implementation optionally enables a user to set the _scroll parameter to "no", in order to gain better performance.

Code Sample

Using XML Accessor

xmlAccessor.setScrollType(TScroll.NO);
TResponse result = streamAccessor.query(query, 5);

Using Stream Accessor

streamAccessor.setScrollType(TScroll.NO);
TInputStream inputStream = streamAccessor.openCursor(TQuery.newInstance(docType), 1, 5);

Use of _maximumrequestduration Parameter

In Tamino, the response time of a single request depends on a number of factors, e.g. the presence of indexes, locks of concurrent transactions, amount of data to be searched or sorted, etc. Thus, an application can be blocked for a considerable time because a single request takes quite some time. In particular, similar requests might have performed well in the past. Often, such a situation is resolved only by timeouts e.g. in the HTTP layer or the transaction timeout in Tamino. On the other hand, a user might issue a request that – intentionally or unintentionally – consumes a lot of Tamino resources and blocks other requests.

Until now the XML maximum query duration property was available with Tamino. But this property is applicable for XQuery and X-Query only. A new parameter, _maximumrequestduration, has been introduced to limit the maximum elapsed time for all requests to a database.

Code Sample

// Get Accessor object to execute requests.
TXMLObjectAccessor accessor = connection.newXMLObjectAccessor(
		TAccessLocation.newInstance(COLLECTION), TDOMObjectModel.getInstance());

// Set maximum request duration in seconds.
accessor.setMaximumRequestDuration(2);

Cancel Requests

Currently it is not possible to stop requests sent to Tamino through the Tamino API for Java. Once started, a query executes (i.e., consumes CPU cycles, main memory, and I/O capacity) until all results are delivered or until an error condition occurs. The user has no chance to cancel a long running request (and thus stop resource consumption).

In the current version of Tamino, the server provides this feature. Application-owned requests can be cancelled using the Tamino API for Java.

Code Sample

/*
 * In order to cancel any request, it is required to set as cancellable. 
 * It is recommended to set the client application name for ease of tracing / debugging.
 */
accessor.setCanBeCancelled(true);
accessor.setApplicationName("myApplication");
//Execute requests (XQuery, X-Query, process, define etc) using accessor
//... ...

/* In order to cancel above request, client application need to call cancelRequests()
 * on same accessor object concurrently.
 */
accessor.cancelRequests();

// Note that cancelRequests() will cancel all active requests issued using same accessor object.

Xquery Prepare and Execute

In order to separate the compilation of an XQuery from its execution, Tamino 4.4 provides an interface for preparing and executing queries. Two new commands have been introduced: _prepare and _execute.

To support this feature in Tamino API for Java , the class com.softwareag.tamino.db.api.accessor.TPreparedXQuery has been implemented.

The lifetime of a prepared query is determined by a connection (session). Therefore the TConnection interface provides a factory method for creating an instance of TPreparedXQuery. Note that a prepared query can only be used in the context of a session. This means that LocalTransactionMode must be used when working with prepared queries. A prepared query can be executed using an XML object accessor.

In order to pass parameters to a query, XQuery provides external variables. An external variable gets its value from the evaluation context (client application). The Tamino API for Java provides several external variable binding APIs.

Code Sample

// Get tamino connection, use local transaction mode
connection = getConnection();
connection.useLocalTransactionMode();

// Get XML object accessor 			
accessor = connection.newXMLObjectAccessor();

// Prepare XQuery using connection object
TPreparedXQuery query = connection.prepareQuery("declare variable $y:string as xs:string external for $q in
 input()/DataTypes[string=$y:string] return $q");
// Bind external variables
query.bindString(new QName("http://www.softwareag.com","y","string"),"String");

// Execute prepared XQuery
TResponse response = accessor.xquery(query);

User Schema with Cyclic Imports

The Tamino API for Java now supports multiple or cyclic schema DEFINE and UNDEFINE operations.

Code Sample

Define Schema Cluster

//Get Tamino connection and schema definition accessor
TConnection connection = connectionFactory.newConnection(URI);
tsd3Accessor = connection.newSchemaDefinition3Accessor(TDOMObjectModel.getInstance());	
//create schema documents as TXMLObjects
TXMLObject[] schemaObjects = new TXMLObject[2];
schemaObjects[0] = schemaObject1;
schemaObjects[1] = schemaObject2;
//define schema cluster
tsd3Accessor.define(schemaObjects);

Undefine Schema Cluster

//Get Tamino connection and schema definition accessor
TConnection connection = connectionFactory.newConnection(URI);
tsd3Accessor = connection.newSchemaDefinition3Accessor(TDOMObjectModel.getInstance());	
//create undefined items
TUndefineItem[] undefineItems = new TUndefineItem[2];
undefineItems[0] = new TUndefineItem("collectionName","schema1name");

Weaker Locking on Long-Lasting Index Access

A new parameter has been introduced in Tamino 4.4 to support weaker locking on long-lasting index access operations: 

_QUERYSEARCHMODE={"approximative"|"accurate"|"nonserialized"}

Where:

"accurate"

represents the current behavior (this is the default);

"approximative"

specifies the new behavior;

"nonserialized"

is similar to mode approximative, but omits post-processing.

In order to support this feature in the Tamino API for Java, the new class TQuerySearchMode is introduced to represent the _QUERYSEARCHMODE parameter value.

The TQuery class represents the XQuery expression that is to be executed. To the send parameter _QUERYSEARCHMODE with XQuery, the following getter/setter APIs have been added in the TQuery class:

setQuerySearchMode(TQuerySearchMode mode)
TQuerySearchMode getQuerySearchMode()

You can find detailed information about the query search mode in the X-Machine Programming documentation.

Code Sample

TQuery query = new TQuery("Account");
query.setQuerySearchMode(TQuerySearchMode.APPROXIMATE);
TResponse response = accessor.query(query);

Domain Authentication

It is possible to specify a domain when creating a TConnection instance.

Isolation Levels

The Tamino XML Server uses an enhanced locking algorithm, providing several isolation levels. Each isolation level has different effects on parallel transactions. The interface TConnection in the package com.softwareag.tamino.db.api.connection provides access to the transactional parameters which define the behavior of Tamino when dealing with concurrent access of data. The parameters are:

LockwaitMode
IsolationLevel
LockMode
IsolationDegree

Additionally, a subset of the transactional parameters may also be defined with the accessors. For detailed information, see the Javadoc reference section in the online documentation.

Tip:
The previous API version returned default values if the transactional parameters were not changed explicitly. Now null values indicate the Tamino default values.

Schema definition

Methods in the interfaces TSchemaDefinition3Accessor and TStreamAccessor in the package com.softwareag.tamino.db.api.accessor allow you to specify a TDefineMode. This permits definition of a schema with validation. For detailed information, see the Javadoc reference section in the online documentation.

Explain Query

The class TQueryBuilder offers methods to build a TQuery instance for an "explain" query. It can be used to retrieve information about query execution for analysis and optimization.

Query Count

The interface TXMLObjectIterator in the package com.softwareag.tamino.db.api.objectModel has additional methods to get the total number of resulting objects for a query issued to the Tamino XML Server. This query count is only available for queries that have been issued using the query method, specifying a quantity (i.e. when the Tamino cursoring mechanism is being used). The Tamino XML Server only returns a query count if the calculation does not require the creation of the result set as a whole. In other words, Tamino XML Server only returns a query count if it is not expensive to calculate.

Tamino XQuery

The Tamino API for Java supports two query languages: Tamino X-Query and Tamino XQuery (note the hyphen).

XQuery is supported by the new classes TXQuery and TXQueryBuilder in the package com.softwareag.tamino.db.api.accessor. XQueries can be executed in the interfaces TXMLObjectAccessor and TStreamAccessor.

X-Query, the former query language of the Tamino XML Server, can still be used, e.g. for migration purposes.

Retry Handler

If a request to the Tamino XML Server fails, a retry handler will retry the request. In the case of a transaction timeout (session lost), the retry handler will set up a new session to the Tamino XML Server and associate it with the TConnection object. This is only possible if the last successful command was commit or rollback. For all other failures, the retry handler will retry the request up to 10 times, with an increasing time interval between successive retries.

You can disable retries by calling TPreference.getInstance().setUseRetryHandler(false) in the package com.softwareag.tamino.db.api.common.

Tip:
If you create a new connection from the TConnectionFactory to determine whether a database is available, you should disable the retry handler before doing so. Failure to do so results in a long waiting time if the database is inaccessible.

Pre- and Postconditions

The exceptions TPreconditionViolation and TPostconditionViolation in the package com.softwareag.tamino.db.api.common are no longer part of the API. It is not recommended to catch pre- and postcondition violations thrown by the API in client components. Nevertheless, the API components may still throw runtime exceptions in the case of a contract violation.

Xerces V2.5.0

The Tamino API for Java comes with the Xerces V2.5.0 Java XML parser.

JDOM 1.0

The Tamino API for Java comes with JDOM 1.0.

General Entities

Previous versions of this API set the Apache-Xerces-specific feature http://apache.org/xml/features/nonvalidating/load-external.dtd. This feature simplified the parsing of XML documents, because the DTD was not searched and therefore no problems arose if the DTD did not exist or was non accessible. However, this caused general entities to be lost; they were neither translated nor kept.

In the current version of the API, the parser by default attempts to translate general entities.

If you want to maintain compatibility with older versions of the API, set the preference property: TPreference.getInstance().setUseApacheLoadExternalDTD( false );.

XML Documents: Encoding Information

The encoding information stored in the database currently gets lost. For TXMLObjectAccessor, this is because the underlying SAX parsers ignore the encoding information. For the TStreamAccessor implementation, this happens because no encoding information is recognized.

Connection Pooling

The Tamino API for Java offers the possibility to pool physical Tamino connections. For more information, see the reference documentation of the class TConnectionPoolManager in the package com.softwareag.tamino.db.api.connection.

List Databases

The Tamino API for Java offers the possibility to retrieve the list of available databases for a given Tamino XML Server. For more information, see the reference documentation of the class TConnectionFactory in the package com.softwareag.tamino.db.api.connection and in particular the methods getDatabases().