com.ibm.websphere.rsadapter
Interface Reassociateable

All Superinterfaces:

HandleStates

public interface Reassociateable

extends HandleStates

Enables a Connection handle to support handle reassociation.

The process of reassociation involves the following: The handle may be dissociated with its underlying database connection and placed in an inactive state. It may later be reassociated, which returns the handle to an active state. If implicit reactivation is enabled, any operation on an inactive handle will trigger a dynamic request for reassociation with the underlying connection. Otherwise, any operations to the database on an inactive handle are considered an error. Operations which do not involve the database may be allowed on inactive handles even if they do not support implicit reactivation.

Inactive handles may be closed, as usual, after which they are no longer useable.

An isClosed request on an inactive handle should return false, as the handle may still be used (once it is reassociated).

Because this interface is meant to be implemented by the handle, which is directly accessible by the application, a special key parameter is added to certain methods which it might be dangerous to allow the application to invoke directly, such as reassociate. The handle implementation may choose to restrict access to these methods using the key since the key is not available to application code. The handle implementation is not required to restrict access in this manner, in which case the key parameter may simply be ignored.

Fields inherited from interface com.ibm.websphere.rsadapter.HandleStates

ACTIVE, CLOSED, INACTIVE, STATE_STRINGS

Method Summary

void	dissociate() Transitions the Connection handle to the INACTIVE state.
javax.resource.spi.ConnectionRequestInfo	getCRI() Get the ConnectionRequestInfo object associated with this connection.
javax.resource.spi.ManagedConnection	getManagedConnection(java.lang.Object key) Retrieve the ManagedConnection this Connection handle is currently associated with.
int	getState()
boolean	isReserved()
void	reassociate(javax.resource.spi.ManagedConnection mc, java.sql.Connection connImplObject, java.lang.Object key) Reassociates this Connection handle with a new ManagedConnection and underlying connection and reestablishes all saved states.
void	reserve(java.lang.Object key) Reserve this Connection handle for reassociation only with its current ManagedConnection.
boolean	supportsImplicitReactivation() Indicates whether the handle supports implicit reactivation.

Method Detail

dissociate

public void dissociate()
                throws javax.resource.ResourceException

Transitions the Connection handle to the INACTIVE state. Retrieves and stores all information needed for reassociation. This method may close all child objects of the connection instead of saving their states. A reserved handle may be dissociated, in which case the handle must lose its reserved status.

Throws:

javax.resource.ResourceException - if the Connection handle is closed or a fatal error occurs on dissociation.

getManagedConnection

public javax.resource.spi.ManagedConnection getManagedConnection(java.lang.Object key)
                                                          throws javax.resource.ResourceException

Retrieve the ManagedConnection this Connection handle is currently associated with.

Parameters:

key - a special key that must be provided to invoke this method.

Returns:

the ManagedConnection, or null if not associated.

Throws:

javax.resource.ResourceException - if an incorrect key is supplied.

getState

public int getState()

Returns:

the current handle state, as defined in WSJdbcObject.

isReserved

public boolean isReserved()

Returns:

true if the handle is reserved for reassociation with its current ManagedConnection, otherwise false.

reassociate

public void reassociate(javax.resource.spi.ManagedConnection mc,
                        java.sql.Connection connImplObject,
                        java.lang.Object key)
                 throws javax.resource.ResourceException

Reassociates this Connection handle with a new ManagedConnection and underlying connection and reestablishes all saved states. It is an error to reassociate a handle which is not in the inactive state.

Parameters:

mc - the new ManagedConnection to associate this handle with.

connImplObject - the new underlying JDBC Connection object to associate this handle with.

key - a special key that must be provided to invoke this method.

Throws:

javax.resource.ResourceException - if an incorrect key is supplied, if the handle is not ready for reassociation, or if an error occurs during the reassociation.

reserve

public void reserve(java.lang.Object key)
             throws javax.resource.ResourceException

Reserve this Connection handle for reassociation only with its current ManagedConnection. This optimization allows child objects of the handle also associated with the ManagedConnection (or associated with underlying objects of the ManagedConnection) to be left open across reassociations. This method should only be used when the guarantee can be made that the handle will always be reassociated back to its original ManagedConnection.

Reserved handles should always be placed in the INACTIVE state. The handle loses its reserved status when either of the following occur,

• The handle is explicitly dissociated.
• A reassociation request is made for the handle to reassociate with its current ManagedConnection.

Parameters:

key - a special key that must be provided to invoke this method.

Throws:

javax.resource.ResourceException - if an incorrect key is supplied or if the handle may not be reserved from its current state.

supportsImplicitReactivation

public boolean supportsImplicitReactivation()

Indicates whether the handle supports implicit reactivation. Implicit reactivation means that an inactive connection handle will implicitly request reassociation when used. For example, if the handle state is inactive and a createStatement operation is requested, the handle will implicitly reassociate with a new underlying connection and continue the operation.

getCRI

public javax.resource.spi.ConnectionRequestInfo getCRI()

Get the ConnectionRequestInfo object associated with this connection. When a managed connection is associated with a Reassociatable, their ConnectionRequestInfo may be different. Therefore, managed connection's ConnectionRequestInfo should be updated with the ConnectionRequestInfo from the Reassociatable. This method is used for managed connection to get the ConnectionRequestInfo from the Reassociatable.

Returns:

the ConnectionRequestInfo object