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.
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.
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.
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.
The prepared query has now been simplified.
declare variable $y:string as xs:string external for $q in input()/DataTypes[string=$y:string] return $q
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);
A connection can now be created by specifying a locale. See the
Javadoc of
TConnectionFactory for further details.
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.
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.
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());
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();
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.
xmlAccessor.setScrollType(TScroll.NO); TResponse result = streamAccessor.query(query, 5);
streamAccessor.setScrollType(TScroll.NO); TInputStream inputStream = streamAccessor.openCursor(TQuery.newInstance(docType), 1, 5);
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.
// Get Accessor object to execute requests. TXMLObjectAccessor accessor = connection.newXMLObjectAccessor( TAccessLocation.newInstance(COLLECTION), TDOMObjectModel.getInstance()); // Set maximum request duration in seconds. accessor.setMaximumRequestDuration(2);
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.
/*
* 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.
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.
// 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);
The Tamino API for Java now supports multiple or cyclic schema DEFINE and UNDEFINE operations.
//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);
//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");
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:
represents the current behavior (this is the default);
specifies the new behavior;
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.
TQuery query = new TQuery("Account");
query.setQuerySearchMode(TQuerySearchMode.APPROXIMATE);
TResponse response = accessor.query(query);
It is possible to specify a domain when creating a
TConnection instance.
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.
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.
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.
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.
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.
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.
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.
The Tamino API for Java comes with the Xerces V2.5.0 Java XML parser.
The Tamino API for Java comes with JDOM 1.0.
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
);.
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.
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.
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().