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

java.lang.Object
  extended by com.softwareag.tamino.db.api.connection.TConnectionPoolManager

public class TConnectionPoolManager
extends java.lang.Object

TConnectionPoolManager manages one or more pools of connections. Two types of connection pools exist. One type only pools TConnection Java objects, the other also pools the underlying Tamino physical connections. The first variant of the connection pool only remains there for upward compatibility reasons. It is strongly recommended to use the second variant including the pooling of Tamino physical connections. This kind of pooling can significanlty improve the performance of an application.
You can obtain pooled connections from a specific pool from the manager by invoking TConnectionPoolManager.getConnection(). Once a pooled connection is no longer used, you must return it to the pool by closing it.

The connection pool manager waits timeOut seconds for a connection to be returned to the pool when all connections of a pool are in use and the maximum limit (MaxConnections) of connections is already reached. If the timeOut is elapsed and still no connection is available, an exception will be thrown. Note that by setting the timeOut to 0, an exception will be thrown immediately.

This class implements the singleton pattern, i.e. there is always only one instance of this class available.

It is recommended to configure connection pools by invoking the addConnectionPool() method which requires a TConnectionPoolDescriptor object describing the properties of the pool and its connections. This method also guarantess that Tamino physical connections are pooled. When configuring such a pool it is important to realize that all connections managed by that pool have the the same values for all session parameters, like lock mode, transaction timeout, etc. These paremeters are only set once based on their setting in the TConnectionPoolDescriptor used t create the pool. Only the _isolationLevel parameter may be overwritten by using the setIsolationDegree() method immediately after a getConnection and before its first usage.

For upward compatibility reasons you can still also configure the TConnectionPoolManager in the following ways:
If you want to ensure that the connection pool manager does not contain any "statical" initialization, call TConnectionPoolManager.release() before adding connection pools programmatically.

Version:
$Revision: 1.28 $
Author:
Marcus Schreyer

Method Summary
 boolean addConnectionPool(java.lang.String poolName, java.lang.String databaseURI, java.lang.String user, java.lang.String password, int maxConnections, int initConnections, int timeOut)
          Add a connection pool to the list of managed pools.
 boolean addConnectionPool(java.lang.String poolName, java.lang.String databaseURI, java.lang.String user, java.lang.String password, int maxConnections, int initConnections, int timeOut, java.util.Locale locale)
          Add a connection pool to the list of managed pools.
 boolean addConnectionPool(java.lang.String poolName, java.lang.String databaseURI, java.lang.String domain, java.lang.String user, java.lang.String password, int maxConnections, int initConnections, int timeOut)
          Add a connection pool to the list of managed pools.
 boolean addConnectionPool(java.lang.String poolName, java.lang.String databaseURI, java.lang.String domain, java.lang.String user, java.lang.String password, int maxConnections, int initConnections, int timeOut, java.util.Locale locale)
          Add a connection pool to the list of managed pools.
 boolean addConnectionPool(java.lang.String poolName, TConnectionPoolDescriptor descriptor)
          Adds a connection pool to the list of managed pools.
 boolean addConnectionPool(java.lang.String poolName, TConnectionPoolDescriptor descriptor, java.util.Locale locale)
          Adds a connection pool to the list of managed pools.
 void addConnectionPools(java.io.InputStream inputStream)
          Deprecated. Please use the following methods instead:
  • addConnectionPool( String poolName, String databaseURI, String domain, String user, String password, int maxConnections, int initConnections, int timeOut )
  • addConnectionPool( String poolName, String databaseURI, String user, String password, int maxConnections, int initConnections, int timeOut )
  • addConnectionPool( String poolName, TConnectionPoolDescriptor descriptor )
 TConnection getConnection(java.lang.String poolName)
          Gets a pooled connection for the given pool.
static TConnectionPoolManager getInstance()
          Gets the singleton TConnectionPoolManager instance.
 java.util.Iterator<java.lang.String> getPoolNames()
          Gets the pool names of all managed pools as an iterator.
 TConnectionPoolStatistics getStatistics(java.lang.String poolName)
          Delivers statistical information on a connection pool
 boolean hasPool(java.lang.String poolName)
          Indicates if the pool with the given name exist.
 boolean isEmpty()
          Indicates if the pool manager contains any pools or none.
 void release()
          Release all pools from the pool manager.
 void release(java.lang.String poolName)
          Release the specified pool from the pool manager.
 java.lang.String toString()
          Writes the statistics for all managed pools into a String.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getInstance

public static TConnectionPoolManager getInstance()
                                          throws TConnectionNotAvailableException
Gets the singleton TConnectionPoolManager instance.

Returns:
the singleton instance TConnectionPoolManager.
Throws:
TConnectionNotAvailableException

getConnection

public TConnection getConnection(java.lang.String poolName)
                          throws TConnectionNotAvailableException
Gets a pooled connection for the given pool. If none is available, a TConnectionNotAvailableException is thrown.

Parameters:
poolName - a pool name managed by the connection pool manager.
Returns:
a pooled TConnection instance.
Throws:
TConnectionNotAvailableException - if no more connection is available from the specified pool.

release

public void release()
Release all pools from the pool manager. Once you have called this method the pool manager no longer has any pools and you can no longer obtain any pooled connections except that pools will be added programmatically via addConnectionPool(..).


release

public void release(java.lang.String poolName)
Release the specified pool from the pool manager. Once you have called this method the pool manager no longer has this pool and you can no longer obtain any pooled connections except that pools will be added programmatically via addConnectionPool(..).

Parameters:
poolName - the name of the pool to release.

getPoolNames

public java.util.Iterator<java.lang.String> getPoolNames()
Gets the pool names of all managed pools as an iterator.

Returns:
an Iterator instance that can be used to iterate over the pool names as strings.

hasPool

public boolean hasPool(java.lang.String poolName)
Indicates if the pool with the given name exist.

Returns:
true if given pool exist, false otherwise.

getStatistics

public TConnectionPoolStatistics getStatistics(java.lang.String poolName)
Delivers statistical information on a connection pool

Returns:
a TConnectionPoolStatistics object containing the statistical information.

addConnectionPool

public boolean addConnectionPool(java.lang.String poolName,
                                 TConnectionPoolDescriptor descriptor)
                          throws TServerNotAvailableException
Adds a connection pool to the list of managed pools. The physical connections in a pool created via this method will automatically be reconnected if a Tamino nonActivity timeout threatens to have deleted the physical connection. All connections in the pool have the same properties (user, password, Tamino URI, session parameters, etc.) and these properties are immutable. It is only possible to override the _isolationLevel parameter by using the setIsolationDegree() method for the usage of the connection, once it is put back into the pool it falls back to its original setting.

Parameters:
poolName - the name of the pool (identification)
descriptor - a TConnectionPoolDescriptor object describing the properties of the pool and its connections.
Returns:
return true on successful add, false if the pool already exists
Throws:
TServerNotAvailableException

addConnectionPool

public boolean addConnectionPool(java.lang.String poolName,
                                 java.lang.String databaseURI,
                                 java.lang.String user,
                                 java.lang.String password,
                                 int maxConnections,
                                 int initConnections,
                                 int timeOut)
                          throws TServerNotAvailableException
Add a connection pool to the list of managed pools. A pool created via this method only pools Java objects and does not pool physical Tamino connections.
The usage of this method is no longer recommended.

Parameters:
poolName - the name of the pool (identification)
databaseURI - the database URI
user - the user identification
password - the password
maxConnections - the number of maximum connections this pool can handle
initConnections - the initial number of connections this pool can handle
timeOut - this pools timeout value (seconds) the manager waits for connections to be retrieved from the pool.
Returns:
return true on successful add, false if the pool already exists
Throws:
TServerNotAvailableException

addConnectionPool

public boolean addConnectionPool(java.lang.String poolName,
                                 java.lang.String databaseURI,
                                 java.lang.String domain,
                                 java.lang.String user,
                                 java.lang.String password,
                                 int maxConnections,
                                 int initConnections,
                                 int timeOut)
                          throws TServerNotAvailableException
Add a connection pool to the list of managed pools. A pool created via this method only pools Java objects and does not pool physical Tamino connections.
The usage of this method is no longer recommended.

Parameters:
poolName - the name of the pool (identification)
databaseURI - the database URI
domain - the domain identification
user - the user identification
password - the password
maxConnections - the number of maximum connections this pool can handle
initConnections - the initial number of connections this pool can handle
timeOut - this pools timeout value (seconds) the manager waits for connections to be retrieved from the pool.
Returns:
return true on successful add, false if the pool already exists
Throws:
TServerNotAvailableException

addConnectionPools

public void addConnectionPools(java.io.InputStream inputStream)
                        throws TConnectionNotAvailableException
Deprecated. Please use the following methods instead:
  • addConnectionPool( String poolName, String databaseURI, String domain, String user, String password, int maxConnections, int initConnections, int timeOut )
  • addConnectionPool( String poolName, String databaseURI, String user, String password, int maxConnections, int initConnections, int timeOut )
  • addConnectionPool( String poolName, TConnectionPoolDescriptor descriptor )

Add connection pools to the list of managed pools. If a pool already exists it will not overridden. The pools created via this method only pool Java objects and does not pool physical Tamino connections.
The usage of this method is no longer recommended.

Parameters:
inputStream - the pool definition xml stream.
Throws:
TConnectionNotAvailableException

addConnectionPool

public boolean addConnectionPool(java.lang.String poolName,
                                 TConnectionPoolDescriptor descriptor,
                                 java.util.Locale locale)
                          throws TServerNotAvailableException
Adds a connection pool to the list of managed pools. The physical connections in a pool created via this method will automatically be reconnected if a Tamino nonActivity timeout threatens to have deleted the physical connection. All connections in the pool have the same properties (user, password, Tamino URI, session parameters, etc.) and these properties are immutable. It is only possible to override the _isolationLevel parameter by using the setIsolationDegree() method for the usage of the connection, once it is put back into the pool it falls back to its original setting.

Parameters:
poolName - the name of the pool (identification)
descriptor - a TConnectionPoolDescriptor object describing the properties of the pool and its connections.
Returns:
return true on successful add, false if the pool already exists
Throws:
TServerNotAvailableException

addConnectionPool

public boolean addConnectionPool(java.lang.String poolName,
                                 java.lang.String databaseURI,
                                 java.lang.String user,
                                 java.lang.String password,
                                 int maxConnections,
                                 int initConnections,
                                 int timeOut,
                                 java.util.Locale locale)
                          throws TServerNotAvailableException
Add a connection pool to the list of managed pools. A pool created via this method only pools Java objects and does not pool physical Tamino connections.
The usage of this method is no longer recommended.

Parameters:
poolName - the name of the pool (identification)
databaseURI - the database URI
user - the user identification
password - the password
maxConnections - the number of maximum connections this pool can handle
initConnections - the initial number of connections this pool can handle
timeOut - this pools timeout value (seconds) the manager waits for connections to be retrieved from the pool.
Returns:
return true on successful add, false if the pool already exists
Throws:
TServerNotAvailableException

addConnectionPool

public boolean addConnectionPool(java.lang.String poolName,
                                 java.lang.String databaseURI,
                                 java.lang.String domain,
                                 java.lang.String user,
                                 java.lang.String password,
                                 int maxConnections,
                                 int initConnections,
                                 int timeOut,
                                 java.util.Locale locale)
                          throws TServerNotAvailableException
Add a connection pool to the list of managed pools. A pool created via this method only pools Java objects and does not pool physical Tamino connections.
The usage of this method is no longer recommended.

Parameters:
poolName - the name of the pool (identification)
databaseURI - the database URI
domain - the domain identification
user - the user identification
password - the password
maxConnections - the number of maximum connections this pool can handle
initConnections - the initial number of connections this pool can handle
timeOut - this pools timeout value (seconds) the manager waits for connections to be retrieved from the pool.
Returns:
return true on successful add, false if the pool already exists
Throws:
TServerNotAvailableException

isEmpty

public boolean isEmpty()
Indicates if the pool manager contains any pools or none.

Returns:
true if given the pool manager is empty, false otherwise.

toString

public java.lang.String toString()
Writes the statistics for all managed pools into a String.

Overrides:
toString in class java.lang.Object
Returns:
a String with the statistics for all managed pools.


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