Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.bea.adapter.spi
Class AbstractManagedConnection

    java.lang.Object
      com.bea.adapter.spi.AbstractManagedConnection

All Implemented Interfaces:
  javax.resource.spi.ManagedConnection

public abstract class AbstractManagedConnection
extends Object
implements javax.resource.spi.ManagedConnection

Provides functionality that is common across resource adapters for implementing the `ManagedConnection` interface. A `ManagedConnection` represents a physical connection to an underlying EIS. The creation of a `ManagedConnection` instance typically results in the allocation of EIS and resource adapter resources.

Constructor Summary
`protected` | `AbstractManagedConnection(AbstractManagedConnectionFactory myFactory, LogContext logContext, boolean bSupportsXAResource, boolean bSupportsLocalTransactions)` Initializes the base class components provided by this class for concrete ManagedConnections.

Method Summary
`void` | `addConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)` Adds a connection event listener to this `ManagedConnection` instance.
`void` | `addConnectionHandle(Object connectionHandle)` Adds an application-level connection handle to the collection maintained by this `ManagedConnection`.
`void` | `associateConnection(Object connection)` Used by the container to change the association of an application-level connection handle with a ManagedConnection instance.
`boolean` | `checkConnection()` Check to see if this managed connection is alive, and if not fire a ConnectionErrorOccurred event.
`protected void` | `checkIfDestroyed()` Checks to see if the client has already called the "destroy" on this instance.
`void` | `cleanup()` Application server calls this to force any cleanup on the `ManagedConnection` instance.
`boolean` | `compareCredentials(Subject subject, javax.resource.spi.ConnectionRequestInfo info)` This method is invoked when the ManagedConnectionFactory is attempting to match this connection with a connection request for the ConnectionManager.
`protected javax.resource.spi.LocalTransaction` | `createLocalTransaction()` Returns a LocalTransaction.
`protected abstract javax.resource.spi.ManagedConnectionMetaData` | `createMetaData()` Returns an object that provides information about the underlying EIS instance associated with "this" ManagedConnection instance.
`protected XAResource` | `createXAResource()` Creates the XA resource if supported.
`void` | `destroy()` Destroys the physical connection to the underlying EIS.
`protected void` | `destroyConnectionHandle(Object obj)` This method gets invoked by the cleanup method to allow any clean-up of resources held by this instance for a particular connection handle.
`protected void` | `destroyPhysicalConnection(Object obj)` This method gets invoked by the destroy method to allow destruction of resources held by this instance for a particular physical connection to the EIS.
`protected void` | `doAdditionalCleanup()` This method gets invoked by the cleanup method to allow any clean-up of additional resources held by this instance
`void` | `fireConnectionErrorOccurredEvent(Exception exception)` Notifies all registered listeners of a connection error.
`void` | `fireConnectionHandleClosedEvent(Object connectionHandle)` Notifies all registered listeners that a connection was closed.
`void` | `fireLocalTransactionCommittedEvent()` Notifies all registered listeners that a transaction was committed.
`void` | `fireLocalTransactionRolledBackEvent()` Notifies all registered listeners that a transaction was rolled back.
`void` | `fireLocalTransactionStartedEvent()` Notifies all registered listeners that a transaction was started.
`AbstractManagedConnectionFactory` | `getFactory()`
`javax.resource.spi.LocalTransaction` | `getLocalTransaction()` Returns a LocalTransaction that is tied to the EIS connection represented by this ManagedConnection.
`javax.resource.spi.LocalTransaction` | `getLocalTransaction(boolean notify)` Returns a LocalTransaction that is tied to the EIS connection represented by this ManagedConnection.
`LogContext` | `getLogContext()` Retrieves an object that determines the logging configuration for this instance in the logging framework.
`ILogger` | `getLogger()` Retrieves an object used to log information to.
`PrintWriter` | `getLogWriter()`
`javax.resource.spi.ManagedConnectionMetaData` | `getMetaData()` Gets the metadata information for this connection's underlying EIS resource manager instance.
`Object` | `getPhysicalConnection()` A ManagedConnection object is typically a wrapper around an object that is native to the EIS's external API.
`XAResource` | `getXAResource()`
`boolean` | `isBusy()`
`boolean` | `isDestroyed()`
`protected void` | `notifyListenersOfEvent(javax.resource.spi.ConnectionEvent event)` Notifies all currently registered listeners of a connection event
`void` | `removeConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)` Removes an already registered connection event listener from the ManagedConnection instance.
`void` | `removeConnectionHandle(Object connectionHandle)` Removes `connectionHandle` from the set of application-level connection handles that is managed by this instance.
`void` | `setLogWriter(PrintWriter out)` Adds `out` as a runtime destination to the ILogger for this instance.
`void` | `setPhysicalConnection(Object obj)` A convenience method that allows an adapter developer to save an object that represents the underlying physical connection to the EIS.
`String` | `toString()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface javax.resource.spi.ManagedConnection
`getConnection`

Constructor Detail

### AbstractManagedConnection

    protected AbstractManagedConnection(AbstractManagedConnectionFactory myFactory,
                                        LogContext logContext,
                                        boolean bSupportsXAResource,
                                        boolean bSupportsLocalTransactions)
                                 throws javax.resource.ResourceException

  Initializes the base class components provided by this class for concrete ManagedConnections.

Parameters:
  `myFactory` - - the factory that instantiated this
  `logContext` - - an object that provides access to an `ILogger` instance for logging.
  `bSupportsXAResource` - - a flag to indicate if the resource adapter implements XAResource to provide support for transaction management.
  `bSupportsLocalTransactions` - - a flag to indicate if the resource adapter supports local transactions.
Throws:
  `javax.resource.ResourceException` - - an exceptional condition was encountered while attempting to initialize this instance; either there was a null parameter or failed to get metadata.

Method Detail

### checkConnection

    public boolean checkConnection()

  Check to see if this managed connection is alive, and if not fire a ConnectionErrorOccurred event. This method should not throw any exceptions, but rather simply return false if any connection related event occurs when trying to verify the connection. This method is used in the matching process. The default implementation of this method just returns true. Subclasses should override this method to physically check the connection to see if it can still support communication to the EIS. If the connection is found to be dead, the overridden method should send a ConnectionErrorOccurred event to its connection listeners.

### isBusy

    public boolean isBusy()

  Returns:
    true if this instance has any open application-level connection handles; false otherwise. This method is employed during the matching process.

### addConnectionEventListener

    public void addConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)

  Adds a connection event listener to this `ManagedConnection` instance.

  Specified by:
    `addConnectionEventListener` in interface `javax.resource.spi.ManagedConnection`
  Parameters:
    `listener` - - enables the application server to get notifications related to the state of this `ManagedConnection` instance. The application server uses these notifications to manage connection pooling, transactions, cleanup connections, and handle any error conditions.

### removeConnectionEventListener

    public void removeConnectionEventListener(javax.resource.spi.ConnectionEventListener listener)

  Removes an already registered connection event listener from the ManagedConnection instance.

  Specified by:
    `removeConnectionEventListener` in interface `javax.resource.spi.ManagedConnection`

### addConnectionHandle

    public void addConnectionHandle(Object connectionHandle)

  Adds an application-level connection handle to the collection maintained by this `ManagedConnection`. An application server can call `getConnection` multiple times, thus multiple connection handles can exist concurrently for a single instance.

  Parameters:
    `connectionHandle` - - represents an application-level connection handle to the EIS.

### removeConnectionHandle

    public void removeConnectionHandle(Object connectionHandle)

  Removes `connectionHandle` from the set of application-level connection handles that is managed by this instance. There can be more than one application-level connection handles associated with a ManagedConnection instance.

### associateConnection

    public void associateConnection(Object connection)
                             throws javax.resource.ResourceException

  Used by the container to change the association of an application-level connection handle with a ManagedConnection instance. This assumes `connection` is an instance of `com.bea.adapter.cci.AbstractConnection`. Adapter developers should override this if their connection object does not extend `com.bea.adapter.cci.AbstractConnection`.

  Specified by:
    `associateConnection` in interface `javax.resource.spi.ManagedConnection`
  Parameters:
    `connection` - - the application-level connection handle
  Throws:
    `javax.resource.ResourceException` - - an exceptional condition was encountered while attempting to associate an application-level connection handle with this instance.

### checkIfDestroyed

    protected void checkIfDestroyed()
                             throws javax.resource.spi.IllegalStateException

  Checks to see if the client has already called the "destroy" on this instance.

  Throws:
    `javax.resource.spi.IllegalStateException` - - the destoy has already been called on this instance.

### cleanup

    public void cleanup()
                 throws javax.resource.ResourceException

  Application server calls this to force any cleanup on the `ManagedConnection` instance. This might include any transaction or security state associated with the connection. This method does NOT close the undelying physical connection to the EIS, use `destroy` for that.

  Specified by:
    `cleanup` in interface `javax.resource.spi.ManagedConnection`
  Throws:
    `javax.resource.ResourceException` - - an exceptional condition was encountered while cleaning up the connection handles associated with this instance.

### createLocalTransaction

    protected javax.resource.spi.LocalTransaction createLocalTransaction()
                                                                  throws javax.resource.ResourceException

  Returns a LocalTransaction. Adapter developers should over-ride this method to instantiate the correct type of LocalTransaction implementation for their adapter. The base class implementation should never actually be called...it only gets called if a developer states that this implementation supports local tx but does not override this method.

  Throws:
    `javax.resource.ResourceException`

### createMetaData

    protected abstract javax.resource.spi.ManagedConnectionMetaData createMetaData()
                                                                            throws javax.resource.ResourceException

  Returns an object that provides information about the underlying EIS instance associated with "this" ManagedConnection instance. This is called after the physical connection to the EIS is obtained. Since obtaining a physical connection is EIS specific, this is abstract.

  Throws:
    `javax.resource.ResourceException`

### createXAResource

    protected XAResource createXAResource()
                                   throws javax.resource.ResourceException

  Creates the XA resource if supported. This method simplifies the work needed to provide an XA resource. Adapter developers are guaranteed that this method will not be invoked unless "this" actually supports XAResource. Adapter developers should override this method to provide the XAResource in an adapter specific manner. Currently returns null. Allows adapter developer to benefit from logging, sanity checking, creating an I18N ResourceException, etc.

  Throws:
    `javax.resource.ResourceException`

### destroy

    public void destroy()
                 throws javax.resource.ResourceException

  Destroys the physical connection to the underlying EIS.

  Specified by:
    `destroy` in interface `javax.resource.spi.ManagedConnection`
  Throws:
    `javax.resource.ResourceException`

### destroyConnectionHandle

    protected void destroyConnectionHandle(Object obj)
                                    throws Exception

  This method gets invoked by the cleanup method to allow any clean-up of resources held by this instance for a particular connection handle.

  Throws:
    `Exception`

### destroyPhysicalConnection

    protected void destroyPhysicalConnection(Object obj)
                                      throws Exception

  This method gets invoked by the destroy method to allow destruction of resources held by this instance for a particular physical connection to the EIS.

  Throws:
    `Exception`

### doAdditionalCleanup

    protected void doAdditionalCleanup()
                                throws Exception

  This method gets invoked by the cleanup method to allow any clean-up of additional resources held by this instance

  Throws:
    `Exception`

### fireConnectionErrorOccurredEvent

    public void fireConnectionErrorOccurredEvent(Exception exception)

  Notifies all registered listeners of a connection error.

### fireConnectionHandleClosedEvent

    public void fireConnectionHandleClosedEvent(Object connectionHandle)

  Notifies all registered listeners that a connection was closed.

### fireLocalTransactionCommittedEvent

    public void fireLocalTransactionCommittedEvent()

  Notifies all registered listeners that a transaction was committed.

### fireLocalTransactionRolledBackEvent

    public void fireLocalTransactionRolledBackEvent()

  Notifies all registered listeners that a transaction was rolled back.

### fireLocalTransactionStartedEvent

    public void fireLocalTransactionStartedEvent()

  Notifies all registered listeners that a transaction was started.

### getFactory

    public AbstractManagedConnectionFactory getFactory()

  Returns:
    the ManagedConnectionFactory implementation for this object.

### getLocalTransaction

    public javax.resource.spi.LocalTransaction getLocalTransaction()
                                                            throws javax.resource.ResourceException

  Returns a LocalTransaction that is tied to the EIS connection represented by this ManagedConnection. If the adapter's LocalTransaction object is a subclass of AbstractLocalTransaction, the returned object will have local TX event notifications disabled (as per the JCA 1.0 spec). If you require these notifications to be enabled (you are managing the local TX directly as an application component) you should call getLocalTransaction(true).

  Specified by:
    `getLocalTransaction` in interface `javax.resource.spi.ManagedConnection`
  Throws:
    `javax.resource.ResourceException` - if the adapter does not support local transactions

### getLocalTransaction

    public javax.resource.spi.LocalTransaction getLocalTransaction(boolean notify)
                                                            throws javax.resource.ResourceException

  Returns a LocalTransaction that is tied to the EIS connection represented by this ManagedConnection. This method is generally called from the ADK's AbstractConnection object to obtain a LocalTransaction that will do notifications on LocalTransaction demarcation calls (begin, commit, etc.)

  Parameters:
    `notify` - Indicates whether the returned LocalTransaction object should notify listeners of connection events or not. When obtaining a LocalTransaction object from the client connection handle, JCA 1.0 says notifications should be sent, but if obtaining the object from the managed connection directly, no notifications should be sent (because the latter case indicates a container managed transaction).
  Throws:
    `javax.resource.ResourceException` - if the adapter does not support local transactions

### getLogContext

    public LogContext getLogContext()

  Retrieves an object that determines the logging configuration for this instance in the logging framework.

  Returns:
    an object that determines the logging configuration for this instance.

### getLogger

    public ILogger getLogger()

  Retrieves an object used to log information to. This uses the adapter's logical name to determine its logger. Adapter developers can override this to return a logger that is not based solely on the supplied logging context.

  Returns:
    an object used to log information to.

### getLogWriter

    public PrintWriter getLogWriter()
                             throws javax.resource.ResourceException

  Specified by:
    `getLogWriter` in interface `javax.resource.spi.ManagedConnection`
  Returns:
    a PrintWriter interface to the logging framework used by the ADK.
  Throws:
    `javax.resource.ResourceException`

### getMetaData

    public javax.resource.spi.ManagedConnectionMetaData getMetaData()
                                                             throws javax.resource.ResourceException

  Gets the metadata information for this connection's underlying EIS resource manager instance.

  Specified by:
    `getMetaData` in interface `javax.resource.spi.ManagedConnection`
  Throws:
    `javax.resource.ResourceException`

### getPhysicalConnection

    public Object getPhysicalConnection()
                                 throws javax.resource.ResourceException

  A ManagedConnection object is typically a wrapper around an object that is native to the EIS's external API. This is a convenience method that allows the retrieval of the underlying EIS connection object.

  Throws:
    `javax.resource.ResourceException` - if the physical connection has not been set for this instance, using the setPhysicalConnection method.

### setPhysicalConnection

    public void setPhysicalConnection(Object obj)
                               throws javax.resource.ResourceException

  A convenience method that allows an adapter developer to save an object that represents the underlying physical connection to the EIS. It is a common design pattern that a ManagedConnection implementation encapsulates another type of object that is needed to establish connectivity to the underlying EIS. For example, a JDBC based resource adapter's ManagedConnection implementation would probably use the java.sql.Connection object as the physical connection.

  Throws:
    `javax.resource.ResourceException` - if `obj` is null.

### getXAResource

    public XAResource getXAResource()
                             throws javax.resource.ResourceException

  Specified by:
    `getXAResource` in interface `javax.resource.spi.ManagedConnection`
  Returns:
    an XAResource for this EIS connection
  Throws:
    `javax.resource.ResourceException` - if the resource adapter does not support XA.

### isDestroyed

    public boolean isDestroyed()

  Returns:
    true if the destroy method has already been invoked for this instance.

### notifyListenersOfEvent

    protected void notifyListenersOfEvent(javax.resource.spi.ConnectionEvent event)

  Notifies all currently registered listeners of a connection event

  Parameters:
    `event` - - the connection event

### setLogWriter

    public void setLogWriter(PrintWriter out)
                      throws javax.resource.ResourceException

  Adds `out` as a runtime destination to the ILogger for this instance.

  Specified by:
    `setLogWriter` in interface `javax.resource.spi.ManagedConnection`
  Throws:
    `javax.resource.ResourceException`

### toString

    public String toString()

  Returns:
    a string representation of this object.

### compareCredentials

    public boolean compareCredentials(Subject subject,
                                      javax.resource.spi.ConnectionRequestInfo info)
                               throws javax.resource.ResourceException

  This method is invoked when the ManagedConnectionFactory is attempting to match this connection with a connection request for the ConnectionManager. Currently, this method extracts a PasswordCredential from the supplied Subject / ConnectionRequestInfo parameters. If both are null, this method returns true because it has already been established that the ManagedConnectionFactory for this instance is correct. If either the Subject or the ConnectionRequestInfo are not null, then this method returns false. Adapter developers should override this method if they expect the Subject or the ConnectionRequestInfo objects to be non-null

  Throws:
    `javax.resource.ResourceException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD