A ManagedConnection object is always in one of three states: DoesNotExist, InFreePool, or InUse.
Before a connection is created, it must be in the DoesNotExist state. After a connection is created, it can be in either the InUse or the InFreePool state, depending on whether it is allocated to an application.
InFreePool > InUse:
getConnection AND
freeConnectionAvailable AND
NOT(shareableConnectionAvailable)
Condition | Description |
---|---|
ageTimeoutExpired | Connection is older then its ageTimeout value. |
close | Application calls close method on the Connection object. |
fatalErrorNotification | A connection has just experienced a fatal error. |
freeConnectionAvailable | A connection with matching properties is available in the free pool. |
getConnection | Application calls getConnection method on a data source or connection factory object. |
markedStale | Connection is marked as stale, typically in response to a fatal error notification. |
noOtherReferences | There is only one connection handle to the managed connection, and the Transaction Service is not holding a reference to the managed connection. |
noTx | No transaction is in force. |
poolSizeGTMin | Connection pool size is greater than the minimum pool size (minimum number of connections) |
poolSizeLTMax | Pool size is less than the maximum pool size (maximum number of connections) |
shareableConnectionAvailable | The getConnection() request is for a shareable connection, and one with matching properties is in use and available to share. |
TxEnds | The transaction has ended. |
unshareableConnectionRequest | The getConnection() request is for an unshareable connection. |
unusedTimeoutExpired | Connection is in the free pool and not in use past its unused timeout value. |
DoesNotExist
getConnection AND NOT(freeConnectionAvailable) AND poolSizeLTMax AND (NOT(shareableConnectionAvailable) OR unshareableConnectionRequest)
All connections begin in the DoesNotExist state and are only created when the application requests a connection. The pool grows from 0 to the maximum number of connections as applications request new connections. The pool is not created with the minimum number of connections when the server starts.
If the request is for a sharable connection and a connection with the same sharing properties is already in use by the application, the connection is shared by two or more requests for a connection. In this case, a new connection is not created. For users of the JDBC API these sharing properties are most often userid/password and transaction context; for users of the Resource Adapter Common Client Interface (CCI) they are typically ConnectionSpec, Subject, and transaction context.
InFreePool
InFreePool>InUse: getConnection AND freeConnectionAvailable AND (unshareableConnectionRequest OR NOT(shareableConnectionAvailable))
Any connection request that a connection from the free pool can fulfill does not result in a new connection to the database. Therefore, if there is never more than one connection used at a time from the pool by any number of applications, the pool never grows beyond a size of one. This number can be less than the minimum number of connections specified for the pool. One way that a pool grows to the minimum number of connections is if the application has multiple concurrent requests for connections that must result in a newly created connection.
InUse
InUse>InUse: getConnection AND ShareableConnectionAvailable
This transition indicates that if an application requests a shareable connection (getConnection) with the same sharing properties as a connection that is already in use (ShareableConnectionAvailable), the existing connection is shared.
InUse>InFreePool: (close AND noOtherReferences AND NoTx AND UnshareableConnection) OR (ShareableConnection AND TxEnds)
When the application calls close() on a connection, it is returning the connection to the pool of free connections; it is not closing the connection to the data store. When the application calls close() on a currently shared connection, the connection is not returned to the free pool. Only after the application drops the last reference to the connection, and the transaction is over, is the connection returned to the pool. Applications using unsharable connections must take care to close connections in a timely manner. Failure to do so can starve out the connection pool, making it impossible for any application running on the server to get a connection.
When the application calls close() on a connection enlisted in a transaction, the connection is not returned to the free pool. Because the transaction manager must also hold a reference to the connection object, the connection cannot return to the free pool until the transaction ends. Once a connection is enlisted in a transaction, you cannot use it in any other transaction by any other application until after the transaction is complete.
InUse>DoesNotExist: close AND markedStale AND NoTx AND noOtherReferences
This transition states that if the application calls close() on the connection and the connection is marked as stale during the pool cleansing step (markedStale), the connection object closes to the data store and is not returned to the pool.
Finally, you can close connections to the data store and remove them from the pool.