A connection handle is a representation of a physical connection.
To use a backend resource (such as a relational database) in WebSphere Application Server you must get a connection to that resource. When you call the getConnection() method, you get a connection handle returned. The handle is not the physical connection. The physical connection is managed by the connection manager.
There are two significant configurations that affect how connection handles are used and how they behave. The first is the res-sharing-scope, which is defined by the resource-reference used to look up the DataSource or Connection Factory. This property tells the connection manager whether or not you can share this connection.
The following code segment shows the cached connection pattern.
Connection conn = ds.getConnection(); ut.begin(); conn.prepareStatement("....."); --> Connection runs in global transaction mode ... ut.commit(); conn.prepareStatement("....."); ---> Connection still valid but runs in autoCommit(True); ...
Related concepts
Resource adapter
Connection factory
Data sources
Connection pooling
Unshareable and shareable connections
Isolation level and resource reference
Some characteristics of connection handles retrieved with a res-sharing-scope of unshareable are described in the following sections.
The possible benefits of unshared connections
The possible drawbacks of unshared connections
In the same scenario, but with a shared connection, deadlock does not occur because all the work is done on the same connection. It is worth noting that when writing code that uses shared connections, you use a strategy that calls for multiple work items to be performed on the same connection, possibly within the same transaction. If you decide to use an unshareable connection, you must set the maximum connections property on the connection factory or data source correctly. An exception might occur for waiting connection requests if you exceed the maximum connections value, and unshareable connections are not being closed before the connection wait time-out is exceeded.
Some characteristics of connection handles that are retrieved with a res-sharing-scope of shareable are described in the following sections.
The possible benefits of shared connections
If the cached handle pattern is used, then the next time the handle is used within a new sharing scope, the application server run time ensures that the handle is reassociated with a managed connection that is appropriate for the current sharing scope, and has the same properties with which the handle was originally retrieved. Remember that it is not appropriate to change properties on a shareable connection. If properties are changed, other components that share the same connection might experience unexpected behavior. Futhermore, when using cached handles, the value of the changed property might not be remembered across sharing scopes.
The possible drawbacks of shared connections
Not all resource adapters have this limitation; it occurs only in certain implementations. The WebSphere Relational Resource Adapter (RRA) does not have this limitation. Any data source used through the RRA does not have this limitation. If you encounter a resource adapter with this limitation you can work around it by serializing your access to the managed connection. If you always close your connection handle before getting another (or close your handle before calling code that gets another handle), and before returning from a method, you can allow two pieces of code to share the same managed connection. You simply cannot use the connection for both events at the same time.
In WebSphere Application Server Version 5.0, the Java 2 Platform, Enterprise Edition (J2EE) Connector (J2C) connection manager implemented smart handle support. This technology enables allocation of a connection handle to an application while the managed connection associated with that connection handle is used by other applications (assuming that the connection is not being used by the original application). This concept is part of the J2EE Connector Architecture (JCA) 1.5 specification. (You can find it in the JCA 1.5 specification document in the section entitled "Lazy Connection Association Optimization.") Smart handle support introduces use a method on the ConnectionManager object, the LazyAssociatableConnectionManager() method , and a new marker interface, the DissociatableManagedConnection class. You must configure the provider of the resource adapter to make this functionality available in your environment. (In the case of the RRA, WebSphere Application Server itself is the provider.) The following code snippet shows how to include smart handle support:
package javax.resource.spi; import javax.resource.ResourceException; interface LazyAssociatableConnectionManager { // application server void associateConnection( Object connection, ManagedConnectionFactory mcf, ConnectionRequestInfo info) throws ResourceException; } interface DissociatableManagedConnection { // resource adapter void dissociateConnections() throws ResourceException; }
This DissociatableManagedConnection interface introduces another state to the Connection object: inactive. A Connection can now be active, closed, and inactive. The connection object enters the inactive state when a corresponding ManagedConnection object is cleaned up. The connection stays inactive until an application component attempts to re-use it. Then the resource adapter calls back to the connection manager to re-associate the connection with an active ManagedConnection object.