com.softwareag.tamino.db.api.connection
Class TPooledConnection

java.lang.Object
  extended by com.softwareag.tamino.db.api.connection.TPooledConnection
All Implemented Interfaces:
TConnection

public class TPooledConnection
extends java.lang.Object
implements TConnection

This class is a wrapper around one or two Connections, overriding the close method to just inform the pool that it's available for reuse again, and the isClosed method to return the state of the wrapper instead of the Connection.

Version:
$Revision: 1.15 $
Author:
Marcus Schreyer

Field Summary
 
Fields inherited from interface com.softwareag.tamino.db.api.connection.TConnection
DEFAULT_TIMEOUT
 
Constructor Summary
TPooledConnection(TDarkConnection genericConnection, TConnectionPool pool)
          Create a TPooledConnection instance with a single wrapped connection which will be used for both auto commit and local transaction mode.
TPooledConnection(TDarkConnection autoCommitConnection, TDarkConnection localTransactionConnection, TConnectionPool pool)
          Create a TPooledConnection instance with two wrapped connections each used for different transaction modes.
 
Method Summary
 void close()
          Closes the connection to Tamino.
 java.lang.String getDatabaseURI()
          Return the database URI as a string.
 int getFailedReconnects()
          Method getFailedReconnects
 TIsolationDegree getIsolationDegree()
          Gets the isolation degree.
 java.util.Locale getLocale()
          Gets the locale.
 TLockMode getLockMode()
          Gets the lock mode.
 TLockwaitMode getLockwaitMode()
          Gets the current lockwait mode A 'null' value represents the Tamino default.
 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 getReconnects()
          Method getReconnects
 int getSocketTimeout()
           
 TTransaction getTransaction()
          Gets the current active transaction instance.
 void invalidate(TAccessor accessor)
          Removes the given accessor from the TPooledConnection
 boolean isActive()
          Indicates whether the session associated with the TConnection instance is active
 boolean isClosed()
          Indicates if the connection is closed.
 TAdministrationAccessor newAdministrationAccessor()
          Creates a new TAdministrationAccessor object that is bound to this connection.
 TNonXMLObjectAccessor newNonXMLObjectAccessor(TAccessLocation accessLocation)
          Creates a new TNonXMLObjectAccessor instance that is bound to this connection.
 TSchemaDefinition2Accessor newSchemaDefinition2Accessor(java.lang.Object xmlObjectModel)
          Creates a new TSchemaDefinition2Accessor instance that is bound to this connection.
 TSchemaDefinition3Accessor newSchemaDefinition3Accessor(java.lang.Object xmlObjectModel)
          Creates a new TSchemaDefinition3Accessor object that is bound to this connection.
 TStreamAccessor newStreamAccessor(TAccessLocation accessLocation)
          Creates a new TXMLStreamAccessor instance that is bound to this connection.
 TSystemAccessor newSystemAccessor()
          Creates a new TSystemAccessor object that is bound to this connection.
 TXMLObjectAccessor newXMLObjectAccessor(TAccessLocation accessLocation, java.lang.Object xmlObjectModel)
          Creates a new 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 connection to its initial state.
 void setFirstCallPending(boolean flag)
          Indicates whether the pooled connection is already in use or not.
 void setGroups(java.lang.String groups)
          Sets the groups for the current user.
 void setIsolationDegree(TIsolationDegree isolationDegree)
          Sets the isolation degree.
 void setLocale(java.util.Locale locale)
          Sets the locale.
 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()
          Tells the connection to use autocommit mode.
 TGlobalTransaction useGlobalTransactionMode(TGlobalTransactionSpecifier globalTransactionId)
          Tells the connection to use and participate in a global transaction with the given isolation level and lockwait mode.
 TLocalTransaction useLocalTransactionMode()
          Tells the connection to use a local transaction with the given isolation level and lockwait mode.
 boolean usesAutoCommitMode()
          Indicates if currently an autocommit transaction mode is used.
 boolean usesGlobalTransactionMode()
          Indicates whether the TConnection instance is in global transaction mode or not.
 boolean usesLocalTransactionMode()
          Indicates if currently a local transaction mode is used.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TPooledConnection

public TPooledConnection(TDarkConnection genericConnection,
                         TConnectionPool pool)
Create a TPooledConnection instance with a single wrapped connection which will be used for both auto commit and local transaction mode.

Parameters:
genericConnection - the wrapped connection instance
pool - the connection pool this wrapper belongs to

TPooledConnection

public TPooledConnection(TDarkConnection autoCommitConnection,
                         TDarkConnection localTransactionConnection,
                         TConnectionPool pool)
Create a TPooledConnection instance with two wrapped connections each used for different transaction modes.

Parameters:
autoCommitConnection - the wrapped auto commit connection instance
localTransactionConnection - the wrapped local transaction mode instance
pool - the connection pool this wrapper belongs to
Method Detail

getFailedReconnects

public int getFailedReconnects()
Method getFailedReconnects

Returns:
an int

getReconnects

public int getReconnects()
Method getReconnects

Returns:
an int

setFirstCallPending

public void setFirstCallPending(boolean flag)
Indicates whether the pooled connection is already in use or not. It is importantn to know that the first call is pending, because that is the time where it should checked whether the underlying Tamino session might have been dropped by Tamino and a reconnect needs to be made.

Parameters:
flag - a boolean indicating whether the first call is pending or not.

setLocale

public void setLocale(java.util.Locale locale)
Sets the locale.


getLocale

public java.util.Locale getLocale()
Gets the locale.

Specified by:
getLocale in interface TConnection
Returns:
the locale.

newNonXMLObjectAccessor

public TNonXMLObjectAccessor newNonXMLObjectAccessor(TAccessLocation accessLocation)
Creates a new TNonXMLObjectAccessor instance that is bound to this connection.

Specified by:
newNonXMLObjectAccessor in interface TConnection
Parameters:
accessLocation - the TAccessLocation instance specifying the location for the accessor.
Returns:
TNonXMLObjectAccessor object that is associated with this conneciton connection.

newXMLObjectAccessor

public TXMLObjectAccessor newXMLObjectAccessor(TAccessLocation accessLocation,
                                               java.lang.Object xmlObjectModel)
Creates a new TXMLObjectAccessor instance that is bound to this connection. The instantiated TXMLObjectAccessor is parametrized with the given xmlObjectModel which has to implement the operations defined within TXMLObjectModel.

Specified by:
newXMLObjectAccessor in interface TConnection
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 object that is associated with this conneciton connection.

newStreamAccessor

public TStreamAccessor newStreamAccessor(TAccessLocation accessLocation)
Creates a new TXMLStreamAccessor instance that is bound to this connection. A TXMLStreamAccessor can be used for low level stream access on Tamino.

Specified by:
newStreamAccessor in interface TConnection
Parameters:
accessLocation - the TAccessLocation instance specifying the location for the accessor.
Returns:
TXMLStreamAccessor object that is associated with this conneciton.

newSchemaDefinition2Accessor

public TSchemaDefinition2Accessor newSchemaDefinition2Accessor(java.lang.Object xmlObjectModel)
Creates a new TSchemaDefinition2Accessor instance that is bound to this connection. The instantiated TSchemaDefinition2Accessor is parametrized with the given xmlObjectModel which has to implement the operations defined within TXMLObjectModel.

Specified by:
newSchemaDefinition2Accessor in interface TConnection
Parameters:
xmlObjectModel - an instance of TXMLObjectModel indicating the object model to be used for the accessor.
Returns:
TSchemaDefinition2Accessor the object that is associated with this conneciton.

newSchemaDefinition3Accessor

public TSchemaDefinition3Accessor newSchemaDefinition3Accessor(java.lang.Object xmlObjectModel)
Creates a new TSchemaDefinition3Accessor object that is bound to this connection. The instantiated TSchemaDefinition3Accessor is parametrized with the given xmlObjectModel which has to implement the operations defined within TXMLObjectModel.

Specified by:
newSchemaDefinition3Accessor in interface TConnection
Parameters:
xmlObjectModel - an instance of TXMLObjectModel indicating the object model to be used for the accessor.
Returns:
TSchemaDefinition3Accessor the object that is associated with this conneciton.

newSystemAccessor

public TSystemAccessor newSystemAccessor()
Creates a new TSystemAccessor object that is bound to this connection.

Specified by:
newSystemAccessor in interface TConnection
Returns:
TSystemAccessor the object that is associated with this conneciton.

newAdministrationAccessor

public TAdministrationAccessor newAdministrationAccessor()
Creates a new TAdministrationAccessor object that is bound to this connection.

Specified by:
newAdministrationAccessor in interface TConnection
Returns:
TAdministrationAccessor the object that is associated with this conneciton.

useAutoCommitMode

public void useAutoCommitMode()
                       throws TTransactionModeChangeException
Tells the connection to use autocommit mode. If a connection is in autocommit mode, then all access operations performed on associated TAccessor instances will be executed and committed as individual transactions. If the connection is currently in the local transactin mode, then the current local transaction is rolled back and the relevant TLocalTransaction instance is released and cannot be used any longer.

Specified by:
useAutoCommitMode in interface TConnection
Throws:
TTransactionModeChangeException - due to a problem during changing the transaction mode (e.g. from local to autocommit).

usesAutoCommitMode

public boolean usesAutoCommitMode()
Indicates if currently an autocommit transaction mode is used.

Specified by:
usesAutoCommitMode in interface TConnection
Returns:
true if an autocommit transaction mode is currently in use, false otherwise.

useLocalTransactionMode

public TLocalTransaction useLocalTransactionMode()
                                          throws TTransactionModeChangeException
Tells the connection to use a local transaction with the given isolation level and lockwait mode. A TLocalTransaction instance is handed back so that the client can perform commit/rollback on the local transaction. The connection resides in the local transaction mode until the TLocalTransaction instance is released on the connection.

Specified by:
useLocalTransactionMode in interface TConnection
Returns:
a TLocalTransaction instance that can be used for commit/rollback.
Throws:
TTransactionModeChangeException - due to a problem during changing the transaction mode (e.g. from autocommit to local).

usesLocalTransactionMode

public boolean usesLocalTransactionMode()
Indicates if currently a local transaction mode is used.

Specified by:
usesLocalTransactionMode in interface TConnection
Returns:
true if a local transaction is currently in use, false otherwise.

useGlobalTransactionMode

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

Specified by:
useGlobalTransactionMode in interface TConnection
Parameters:
globalTransactionId - 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

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

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

getTransaction

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

Specified by:
getTransaction in interface TConnection
Returns:
the current transaction instance, or null if no transaction instance is required for this mode.

reset

public void reset()
           throws TTransactionModeChangeException
Resets the connection to its initial state. When the connection is in auto commit mode the connection sets the lockwait mode and isolation level to the Tamino defaults. When the connection is in local transaction mode the the current transaction is rolled back and the connection is switched to auto commit mode.

Specified by:
reset in interface TConnection
Throws:
TTransactionModeChangeException - due to a problem during reseting the transaction mode to auto commit.

setLockwaitMode

public void setLockwaitMode(TLockwaitMode lockwaitMode)
Sets the lockwait mode for a transaction. For a pool which only pools TConnection objects, this setting is passed on the to the underlying TConnection object. For a pool which pools physical Tamino connections, nothing is set, as all properties are set once for the pool and they are immutable.

Specified by:
setLockwaitMode in interface TConnection
Parameters:
lockwaitMode - the lockwait mode to be set, 'null' for Tamino default.

getLockwaitMode

public TLockwaitMode getLockwaitMode()
Gets the current lockwait mode A 'null' value represents the Tamino default.

Specified by:
getLockwaitMode in interface TConnection
Returns:
the lockwait mode. Returns 'null' if no lockwait mode is specified.

setIsolationDegree

public void setIsolationDegree(TIsolationDegree isolationDegree)
Sets the isolation degree. For a pool which only pools TConnection objects, this setting is passed on the to the underlying TConnection object. For a pool which pools physical Tamino connections, nothing is set, as all properties are set once for the pool and they are immutable.

Specified by:
setIsolationDegree in interface TConnection
Parameters:
isolationDegree - the isolation degree to be set, 'null' for Tamino default.

getIsolationDegree

public TIsolationDegree getIsolationDegree()
Gets the isolation degree. A 'null' value represents the Tamino default.

Specified by:
getIsolationDegree in interface TConnection
Returns:
the isolation degree. Returns 'null' if no isolation degree is specified.

setLockMode

public void setLockMode(TLockMode lockMode)
Sets the lock mode. For a pool which only pools TConnection objects, this setting is passed on the to the underlying TConnection object. For a pool which pools physical Tamino connections, nothing is set, as all properties are set once for the pool and they are immutable.

Specified by:
setLockMode in interface TConnection
Parameters:
lockMode - the lock mode to be set, 'null' for Tamino default.

getLockMode

public TLockMode getLockMode()
Gets the lock mode. A 'null' value represents the Tamino default.

Specified by:
getLockMode in interface TConnection
Returns:
the lock mode. Returns 'null' if no lock mode is specified.

setNonActivityTimeout

public void setNonActivityTimeout(long nonActivityTimeout)
Sets the nonActivity timeout in seconds. For a pool which only pools TConnection objects, this setting is passed on the to the underlying TConnection object. For a pool which pools physical Tamino connections, nothing is set, as all properties are set once for the pool and they are immutable.

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

getNonActivityTimeout

public 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)!

Specified by:
getNonActivityTimeout in interface TConnection
Returns:
the transaction nonActivity timeout in seconds.

setMaximumTransactionDuration

public void setMaximumTransactionDuration(long maximumTransactionDuration)
Sets the maximum transaction duration in seconds. For a pool which only pools TConnection objects, this setting is passed on the to the underlying TConnection object. For a pool which pools physical Tamino connections, nothing is set, as all properties are set once for the pool and they are immutable.

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

getMaximumTransactionDuration

public 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)!

Specified by:
getMaximumTransactionDuration in interface TConnection
Returns:
the maximum transaction duration in seconds.

setGroups

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

Specified by:
setGroups in interface TConnection
Parameters:
groups - the groups for the current user

close

public void close()
           throws TConnectionCloseException
Closes the connection to Tamino. As a result any internal resources needed for the connections with Tamino are closed. This connection instance can afterwards no longer be used. In case there is still an open transaction, the tranasction is committed. This behaviour is consistent with the behaviour of a close() of a normal, non-pooled, connection. T�n that case a close() leads to a disconnect which in Tamino leads to a commit.

Specified by:
close in interface TConnection
Throws:
TConnectionCloseException - due to problems (such as database access) during closing the connection.

invalidate

public void invalidate(TAccessor accessor)
Removes the given accessor from the TPooledConnection

Parameters:
accessor -

isClosed

public boolean isClosed()
Indicates if the connection is closed.

Specified by:
isClosed in interface TConnection
Returns:
true if connection is closed, false otherwise.

getDatabaseURI

public java.lang.String getDatabaseURI()
Return the database URI as a string.

Returns:
the database URI.

prepareQuery

public 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.

Specified by:
prepareQuery in interface TConnection
Returns:
TPreparedXQuery a prepared XQuery bound to this connection.

isActive

public boolean isActive()
Description copied from interface: TConnection
Indicates whether the session associated with the TConnection instance is active

Specified by:
isActive in interface TConnection
Returns:
true if the session is valid, false otherwise

getSocketTimeout

public int getSocketTimeout()
Specified by:
getSocketTimeout in interface TConnection

setSocketTimeout

public void setSocketTimeout(int timeout)
Specified by:
setSocketTimeout in interface TConnection


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