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