com.softwareag.tamino.db.api.connection
Interface TConnection

All Known Subinterfaces:
TDarkConnection
All Known Implementing Classes:
TConnectionImpl, TPooledConnection

public interface TConnection

The TConnection interface represents a connection to a Tamino database. In a normal J2SE environment you can obtain a TConnection instance by one of the factory methods of the TConnectionFactory class. In a J2EE environment it is recommended to obtain a TConnection instance by means of the TaminoDataSource class of the Tamino Resource Adapter. An instance of the TaminoDataSource factory class can be obtained through a JNDI lookup.
A TConnection instance in turn is a factory for accessors such as TXMLAccessor, TNonXMLAccessor and TStreamAccessor. Each accessor is bound to the connection through which it was created.
You can use a TConnection in different transaction modes:

TConnection also provides access to session parameters which define the behaviour of Tamino when dealing with concurrent access of data. The session parameters are: You can get and set their values through their setter and getter methods. A null value of such a parameter indicates that the Tamino default value is being used. You can also use the null value in a setter method to indicate you want the default Tamino parameter setting.
Note:the previous API version returned an explicit default value. This has changed!)

You may change the value of such a parameter at any time but when that value will become effective depends on the transaction mode and the type of command.

In addition you may also set a subset of the session parameters on the level of an accessor. Their setting is immediate (i.e. will have effect starting with the next command issued) but only effects the commands issued using the accessor for which the parameter was set.

Version:
$Revision: 1.51 $
Author:
Marcus Schreyer

Field Summary
static long DEFAULT_TIMEOUT
          This value indicates to use Tamino default values for the timeout parameters.
 
Method Summary
 void close()
          Closes the TConnection instance.
 TIsolationDegree getIsolationDegree()
          Gets the isolation degree.
 java.util.Locale getLocale()
          Gets Locale
 TLockMode getLockMode()
          Gets the lock mode.
 TLockwaitMode getLockwaitMode()
          Gets the current lockwait mode.
 long getMaximumTransactionDuration()
          Gets the maximum transaction duration in seconds.

Note:
This method retrieves the servers default value, when this duration has not been set to a specific value (unequal to TConnection.DEFAULT_TIMEOUT)!
 long getNonActivityTimeout()
          Gets the nonActivity timeout in seconds.

Note:
This method retrieves the servers default value, when this timeout has not been set to a specific value (unequal to TConnection.DEFAULT_TIMEOUT)!
 int getSocketTimeout()
           
 TTransaction getTransaction()
          Gets the current active transaction instance.
 boolean isActive()
          Indicates whether the session associated with the TConnection instance is active
 boolean isClosed()
          Indicates whether the TConnection instance is closed or not.
 TAdministrationAccessor newAdministrationAccessor()
          Creates a TAdministrationAccessor instance that is bound to this connection.
 TNonXMLObjectAccessor newNonXMLObjectAccessor(TAccessLocation accessLocation)
          Creates a TNonXMLObjectAccessor instance that is bound to this connection.
 TSchemaDefinition2Accessor newSchemaDefinition2Accessor(java.lang.Object xmlObjectModel)
          Creates a TSchemaDefinition2Accessor instance that is bound to this connection.
 TSchemaDefinition3Accessor newSchemaDefinition3Accessor(java.lang.Object xmlObjectModel)
          Creates a TSchemaDefinition3Accessor instance that is bound to this connection.
 TStreamAccessor newStreamAccessor(TAccessLocation accessLocation)
          Creates a TStreamAccessor instance that is bound to this connection.
 TSystemAccessor newSystemAccessor()
          Creates a TSystemAccessor instance that is bound to this connection.
 TXMLObjectAccessor newXMLObjectAccessor(TAccessLocation accessLocation, java.lang.Object xmlObjectModel)
          Creates a TXMLObjectAccessor instance that is bound to this connection.
 TPreparedXQuery prepareQuery(java.lang.String expression)
          Creates a TPreparedXQuery instance that is bound to this connection.
 void reset()
          Resets the TConnection instance to its initial state.
 void setGroups(java.lang.String groups)
          Sets the groups for the current user.
 void setIsolationDegree(TIsolationDegree isolationDegree)
          Sets the isolation degree.
 void setLockMode(TLockMode lockMode)
          Sets the lock mode.
 void setLockwaitMode(TLockwaitMode lockwaitMode)
          Sets the lockwait mode for a transaction.
 void setMaximumTransactionDuration(long maximumTransactionDuration)
          Sets the maximum transaction duration in seconds.
 void setNonActivityTimeout(long nonActivityTimeout)
          Sets the nonActivity timeout in seconds.
 void setSocketTimeout(int timeout)
           
 void useAutoCommitMode()
          Signals the TConnection connection to switch to autocommit mode.
 TGlobalTransaction useGlobalTransactionMode(TGlobalTransactionSpecifier globalTransactionSpecifier)
          Tells the connection to use and participate in a global transaction with the given isolation level and lockwait mode.
 TLocalTransaction useLocalTransactionMode()
          Signals the TConnection connection to switch to local transaction moode.
 boolean usesAutoCommitMode()
          Indicates whether the TConnection instance is in autocommit mode or not.
 boolean usesGlobalTransactionMode()
          Indicates whether the TConnection instance is in global transaction mode or not.
 boolean usesLocalTransactionMode()
          Indicates whether the TConnection instance is in local transaction mode or not.
 

Field Detail

DEFAULT_TIMEOUT

static final long DEFAULT_TIMEOUT
This value indicates to use Tamino default values for the timeout parameters.

See Also:
Constant Field Values
Method Detail

newStreamAccessor

TStreamAccessor newStreamAccessor(TAccessLocation accessLocation)
Creates a TStreamAccessor instance that is bound to this connection. You can use a TStreamAccessor instance for low level stream access to documents stored in Tamino.

Parameters:
accessLocation - the TAccessLocation instance specifying the location for the accessor.
Returns:
TStreamAccessor a stream accessor instance bound to this connection.

newNonXMLObjectAccessor

TNonXMLObjectAccessor newNonXMLObjectAccessor(TAccessLocation accessLocation)
Creates a TNonXMLObjectAccessor instance that is bound to this connection. You can use a TNonXMLObjectAccessor instance for access to non-XML documents stored in Tamino.

Parameters:
accessLocation - the TAccessLocation instance specifying the location for the accessor.
Returns:
TNonXMLObjectAccessor a non-XML object accessor bound to this connection.

newXMLObjectAccessor

TXMLObjectAccessor newXMLObjectAccessor(TAccessLocation accessLocation,
                                        java.lang.Object xmlObjectModel)
Creates a TXMLObjectAccessor instance that is bound to this connection. You can use a TXMLObjectAccessor instance for access to XML documents stored in Tamino. The xmlObjectModel parameter has to be an instance of TXMLObjectModel. The xmlObjectModel parameter determines the object model that the accessor will use. The object model used determines the type and format of the XML documents passed to and from the Tamino database.

Parameters:
accessLocation - the TAccessLocation instance specifying the location for the accessor.
xmlObjectModel - an instance of TXMLObjectModel indicating the object model to be used for the accessor.
Returns:
TXMLObjectAccessor an XML object accessor bound to this connection.

newSchemaDefinition2Accessor

TSchemaDefinition2Accessor newSchemaDefinition2Accessor(java.lang.Object xmlObjectModel)
Creates a TSchemaDefinition2Accessor instance that is bound to this connection. You can use a TSchemaDefinition2Accessor instance for access to TSD2 schemas stored in Tamino. The xmlObjectModel parameter has to be an instance of TXMLObjectModel.

Parameters:
xmlObjectModel - an instance of TXMLObjectModel indicating the object model to be used for the accessor.
Returns:
TSchemaDefinition2Accessor a TSD2 schema accessor bound to this connection.

newSchemaDefinition3Accessor

TSchemaDefinition3Accessor newSchemaDefinition3Accessor(java.lang.Object xmlObjectModel)
Creates a TSchemaDefinition3Accessor instance that is bound to this connection. You can use a TSchemaDefinition3Accessor instance for access to TSD3 schemas stored in Tamino. The xmlObjectModel parameter has to be an instance of TXMLObjectModel.

Parameters:
xmlObjectModel - an instance of TXMLObjectModel indicating the object model to be used for the accessor.
Returns:
TSchemaDefinition3Accessor a TSD3 schema accessor bound to this connection.

newSystemAccessor

TSystemAccessor newSystemAccessor()
Creates a TSystemAccessor instance that is bound to this connection. You can use a TSystemAccessor instance for access system information of Tamino and the Tamino API.

Returns:
TSystemAccessor a system accessor bound to this connection.

newAdministrationAccessor

TAdministrationAccessor newAdministrationAccessor()
Creates a TAdministrationAccessor instance that is bound to this connection. You can use a TAdministrationAccessor instance for executing administrative commands on Tamino.

Returns:
TSystemAccessor a system accessor bound to this connection.

useAutoCommitMode

void useAutoCommitMode()
                       throws TTransactionModeChangeException
Signals the TConnection connection to switch to autocommit mode. In autocommit mode, all access operations performed on accessors bound to the TConnection instance are executed and committed as individual transactions. If the TConnection instance is currently in local transaction mode, the local transaction is rolled back and the associated TLocalTransaction instance is released and no longer be used.
Note that you can not use this method for a TConnection obtained through the Tamino Resource Adapter in managed scenarios.

Throws:
TTransactionModeChangeException - signals an error while attempting to change the transaction mode from local to autocommit.

usesAutoCommitMode

boolean usesAutoCommitMode()
Indicates whether the TConnection instance is in autocommit mode or not.

Returns:
true if the TConnection instance is in autocommit mode, false otherwise.

useLocalTransactionMode

TLocalTransaction useLocalTransactionMode()
                                          throws TTransactionModeChangeException
Signals the TConnection connection to switch to local transaction moode. In local transaction mode, access operations are performed together in a transactionon and are committed or rolled back as a unit. A TLocalTransaction instance is returned so that you can perform a commit or rollback on the local transaction. The TConnection instance remains in local transaction mode until it is switched back into autocommit mode.
Note that you can not use this method for a TConnection obtained through the Tamino Resource Adapter in managed scenarios.

Returns:
a TLocalTransaction instance that you can use for commit/rollback.
Throws:
TTransactionModeChangeException - signals an error while attempting to change the transaction mode from autocommit to local.

usesLocalTransactionMode

boolean usesLocalTransactionMode()
Indicates whether the TConnection instance is in local transaction mode or not.

Returns:
true if the TConnection instance is in local transaction mode, false otherwise.

useGlobalTransactionMode

TGlobalTransaction useGlobalTransactionMode(TGlobalTransactionSpecifier globalTransactionSpecifier)
                                            throws TTransactionModeChangeException
Tells the connection to use and participate in a global transaction with the given isolation level and lockwait mode.

Parameters:
globalTransactionSpecifier - the global transaction identifier. Should be originated by transaction controller.
Returns:
a TGlobalTransaction instance that can be used for the global transaction.
Throws:
TTransactionModeChangeException

usesGlobalTransactionMode

boolean usesGlobalTransactionMode()
Indicates whether the TConnection instance is in global transaction mode or not.

Returns:
true if the TConnection instance is in global transaction mode, false otherwise.

getTransaction

TTransaction getTransaction()
Gets the current active transaction instance. Since not every transaction mode has a transaction instance, this method may return null.

In a J2SE environment this method returns an instance of TLocalTransaction if the connection is in local transaction mode, otherwise null (i.e. if the connection is in auto commit mode.

In a J2EE environment is the TConnection instance was obtained through the Tamino Resource Adapter it will always return null.

Returns:
the current transaction instance, or null if no transaction instance is available.

reset

void reset()
           throws TTransactionModeChangeException
Resets the TConnection instance to its initial state.

In a J2SE environment, there is a distinction between non-pooled connections and pooled connections.
If no connection pool is used and the TConnection instance is in autocommit mode all session parameters like lockwait mode and isolation level are set to the Tamino defaults. If no connection pool is used and the TConnection instance is in local transaction mode the connection is switched to auto commit mode. This implies that the underlying Taino session is disconnected which in turn implies that the current transaction is committed.
If a connection pool is used that has been configured to pool physical Tamino connections, none of the session parameters are reset as they are properties of the pool and are immutable.

In a J2EE environment if the TConnection instance was obtained through the Tamino Resource Adapter, all session parameters are reset to their Tamino default settings.

Throws:
TTransactionModeChangeException - signals an error while attempting to change the transaction mode from local to autocommit.

setLockwaitMode

void setLockwaitMode(TLockwaitMode lockwaitMode)
Sets the lockwait mode for a transaction. The lockwait mode correponds to the _lockwait session parameter of Tamino. If set before invoking useLocalTransactionMode(), the Tamino default for the _lockwaitMode session parameter is overwritten. If set later, the setting has no effect unless the connection is switched back to autocommit mode and useLocalTransactionMode() is onvoked anew (setting a new default for a new Tamino session).
Note that for pooled connections obtained from a connection pool configured to pool Tamino physical connections, the invocation of this method has no effect. The default value is set once and for all for all connections in a pool when the pool is created.

Parameters:
lockwaitMode - the lockwait mode to be set, 'null' for Tamino default.

getLockwaitMode

TLockwaitMode getLockwaitMode()
Gets the current lockwait mode. The lockwait mode correponds to the _lockwait session parameter of Tamino. A 'null' value represents the Tamino default.

Returns:
the lockwait mode. Returns 'null' if no lockwait mode is specified.

setIsolationDegree

void setIsolationDegree(TIsolationDegree isolationDegree)
Sets the isolation degree. The isolation degree correponds to the _isolationLevel session parameter of Tamino. If set before invoking useLocalTransactionMode(), the Tamino default for the _isolationLevel session parameter is overwritten. If set later, the value set here is passed on to Tamino with every first command of a transaction. In autocommit mode this means with every command as each command triggers a transaction implicitly.

Parameters:
isolationDegree - the isolation degree to be set, 'null' for Tamino default.

getIsolationDegree

TIsolationDegree getIsolationDegree()
Gets the isolation degree. The isolation degree correponds to the _isolationLevel session parameter of Tamino. A 'null' value represents the Tamino default.

Returns:
the isolation degree. Returns 'null' if no isolation degree is specified.

setLockMode

void setLockMode(TLockMode lockMode)
Sets the lock mode. The isolation degree correponds to the _lockMode session parameter of Tamino. If set before invoking useLocalTransactionMode(), the Tamino default for the _lockMode session parameter is overwritten. If set later, the setting has no effect unless the connection is switched back to autocommit mode and useLocalTransactionMode() is onvoked anew (setting a new default for a new Tamino session).
Note that for pooled connections obtained from a connection pool which configured to pool Tamino physical connections, the invocation of this method has no effect. The default value is set once and for all for all connections in a pool when the pool is created.

Parameters:
lockMode - the lock mode to be set, 'null' for Tamino default.

getLockMode

TLockMode getLockMode()
Gets the lock mode. The isolation degree correponds to the _lockMode session parameter of Tamino. A 'null' value represents the Tamino default.

Returns:
the lock mode. Returns 'null' if no lock mode is specified.

setNonActivityTimeout

void setNonActivityTimeout(long nonActivityTimeout)
Sets the nonActivity timeout in seconds. If set before invoking useLocalTransactionMode(), the Tamino default for the _nonActivityTimeout session parameter is overwritten. If set later, the setting has no effect unless the connection is switched back to autocommit mode and useLocalTransactionMode() is invoked anew (setting a new default for a new Tamino session).
Note that for pooled connections obtained frlom a connection pool which configured to pool Tamino physical connections, the invocation of this method has no effect. The default value is set once and for all connections in a pool when the pool is created.

Parameters:
nonActivityTimeout - the transaction nonActivity timeout in seconds be set, TConnection.DEFAULT_TIMEOUT for Tamino default.

getNonActivityTimeout

long getNonActivityTimeout()
Gets the nonActivity timeout in seconds.

Note:
This method retrieves the servers default value, when this timeout has not been set to a specific value (unequal to TConnection.DEFAULT_TIMEOUT)!

Returns:
the transaction nonActivity timeout in seconds.

setMaximumTransactionDuration

void setMaximumTransactionDuration(long maximumTransactionDuration)
Sets the maximum transaction duration in seconds. If set before invoking useLocalTransactionMode(), the Tamino default for the _maximumTransactionDuration session parameter is overwritten. If set later, the setting has no effect unless the connection is switched back to autocommit mode and useLocalTransactionMode() is onvoked anew (setting a new default for a new Tamino session).
Note that for pooled connections obtained frlom a connection pool which configured to pool Tamino physical connections, the invocation of this method has no effect. The default value is set once and for all for all connections in a pool when the pool is created.

Parameters:
maximumTransactionDuration - the maximum transaction duration in seconds in seconds be set, TConnection.DEFAULT_TIMEOUT for Tamino default.

getMaximumTransactionDuration

long getMaximumTransactionDuration()
Gets the maximum transaction duration in seconds.

Note:
This method retrieves the servers default value, when this duration has not been set to a specific value (unequal to TConnection.DEFAULT_TIMEOUT)!

Returns:
the maximum transaction duration in seconds.

setGroups

void setGroups(java.lang.String groups)
Sets the groups for the current user. This has to be set before invoking useLocalTransactionMode().

Parameters:
groups - the groups for the current user

close

void close()
           throws TConnectionCloseException
Closes the TConnection instance. This TConnection instance can no longer be used afterwards.

In a J2SE environment if no connection pool is used the underlying session with Tamino is closed as well. Before closing the connection, the transaction mode is changed to autocommit. This implies that if the TConnection instance was in local transaction mode, the local transaction is committed.
If a connection pool is used which was configured to pool physical Tamino connections, the underlying session with Tamino is NOT closed. However, if there is an open transaction, a commit is issued against Tamino committed the current transaction.

In a J2EE environment if the TConnection instance was obtained through the Tamino Resource Adapter, the underlying session with Tamino is NOT closed. Instead the connection is returned to the connection pool managed by the J2EE application server and is ready for re-use.

Throws:
TConnectionCloseException - due to problems (such as database access) during the the closure of the connection.

isClosed

boolean isClosed()
Indicates whether the TConnection instance is closed or not.

Returns:
true if the TConnection instance is closed, false otherwise.

isActive

boolean isActive()
Indicates whether the session associated with the TConnection instance is active

Returns:
true if the session is valid, false otherwise

prepareQuery

TPreparedXQuery prepareQuery(java.lang.String expression)
Creates a TPreparedXQuery instance that is bound to this connection. You can use a TPreparedXQuery instance for seperate compilation and execution of XQueries.

Returns:
TPreparedXQuery a prepared XQuery bound to this connection.

getLocale

java.util.Locale getLocale()
Gets Locale

Returns:
Locale.

setSocketTimeout

void setSocketTimeout(int timeout)

getSocketTimeout

int getSocketTimeout()


Copyright (c) 2013 Software AG. All Rights Reserved.