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: A handle is 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 that do not involve the database are sometimes allowed on inactive handles even if they do not support implicit reactivation.

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

    An isClosed request on an inactive handle should return false, as the handle might still be used when it is reassociated.

    Because this interface is meant to be implemented by the handle, which is directly accessible by the application. It might be dangerous to all the application to invoke certain methods directly (for example, reassociate). A special key parameter is added to these methods to keep the application from accessing them. The handle implementation can 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 can be ignored.

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      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()
      Deprecated. 
      this method is no longer used and will be removed in a future release.
    • Method Detail

      • dissociate

        void dissociate()
                        throws javax.resource.ResourceException

        Transitions the Connection handle to the INACTIVE state. Retrieves and stores all information needed for reassociation. This method can close all child objects of the connection instead of saving their states. A reserved handle might 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

        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

        int getState()
        Returns:
        the current handle state, as defined in WSJdbcObject.
      • isReserved

        boolean isReserved()
        Returns:
        true if the handle is reserved for reassociation with its current ManagedConnection, otherwise false.
      • reassociate

        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

        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 that are also associated with the ManagedConnection, or associated with underlying objects of the ManagedConnection, to be left open across reassociations. Use this method only when you are assured that the handle will always be reassociated back to its original ManagedConnection.

        Reserved handles must 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.
      • getCRI

        javax.resource.spi.ConnectionRequestInfo getCRI()

        Get the ConnectionRequestInfo object associated with this connection. When a managed connection is associated with a Reassociatable, their ConnectionRequestInfo might be different. Therefore, managed connection's ConnectionRequestInfo must 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
        Since:
        WAS 5.0.2
      • supportsImplicitReactivation

        boolean supportsImplicitReactivation()
        Deprecated. this method is no longer used and will be removed in a future release.

        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.

        Returns:
        true if the handle supports implicit reactivation, otherwise false.
IBM WebSphere Application ServerTM
Release 9.0