com.bea.adapter.spi
Class AbstractManagedConnection

java.lang.Object
  |
  +--com.bea.adapter.spi.AbstractManagedConnection

public abstract class AbstractManagedConnection

extends java.lang.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.

Author:

Copyright © 2000, 2001 BEA Systems, Inc. All Rights Reserved.

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(java.lang.Object connectionHandle) Adds an application-level connection handle to the collection maintained by this ManagedConnection.
void	associateConnection(java.lang.Object connection) Used by the container to change the association of an application-level connection handle with a ManagedConnection instance.
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(javax.security.auth.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 javax.transaction.xa.XAResource	createXAResource() Creates the XA resource if supported.
void	destroy() Destroys the physical connection to the underlying EIS.
protected void	destroyConnectionHandle(java.lang.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(java.lang.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(java.lang.Exception exception) Notifies all registered listeners of a connection error.
void	fireConnectionHandleClosedEvent(java.lang.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.
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.
java.io.PrintWriter	getLogWriter()
javax.resource.spi.ManagedConnectionMetaData	getMetaData() Gets the metadata information for this connection's underlying EIS resource manager instance.
java.lang.Object	getPhysicalConnection() A ManagedConnection object is typically a wrapper around an object that is native to the EIS's external API.
javax.transaction.xa.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(java.lang.Object connectionHandle) Removes connectionHandle from the set of application-level connection handles that is managed by this instance.
void	setLogWriter(java.io.PrintWriter out) Adds out as a runtime destination to the ILogger for this instance.
void	setPhysicalConnection(java.lang.Object obj) A convenience method that allows an adapter developer to save an object that represents the underlying physical connection to the EIS.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

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(java.lang.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(java.lang.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(java.lang.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.

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.

createXAResource

protected javax.transaction.xa.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.

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

destroyConnectionHandle

protected void destroyConnectionHandle(java.lang.Object obj)
                                throws java.lang.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.

destroyPhysicalConnection

protected void destroyPhysicalConnection(java.lang.Object obj)
                                  throws java.lang.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.

doAdditionalCleanup

protected void doAdditionalCleanup()
                            throws java.lang.Exception

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

fireConnectionErrorOccurredEvent

public void fireConnectionErrorOccurredEvent(java.lang.Exception exception)

Notifies all registered listeners of a connection error.

fireConnectionHandleClosedEvent

public void fireConnectionHandleClosedEvent(java.lang.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.

Specified by:

getLocalTransaction in interface javax.resource.spi.ManagedConnection

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 java.io.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.

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

getPhysicalConnection

public java.lang.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(java.lang.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 javax.transaction.xa.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(java.io.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

toString

public java.lang.String toString()

Returns:

a string representation of this object.

Overrides:

toString in class java.lang.Object

compareCredentials

public boolean compareCredentials(javax.security.auth.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