public interface ManagedConnection
A ManagedConnection instance provides access to a pair of
interfaces: javax.transaction.xa.XAResource
and
javax.resource.spi.LocalTransaction
.
XAResource
interface is used by the transaction
manager to associate and dissociate a transaction with the underlying
EIS resource manager instance and to perform two-phase commit
protocol. The ManagedConnection interface is not directly used
by the transaction manager. More details on the XAResource
interface are described in the JTA specification.
The LocalTransaction interface is used by the application server to manage local transactions.
ManagedConnectionFactory
,
XAResource
,
LocalTransaction
Modifier and Type | Method and Description |
---|---|
void |
addConnectionEventListener(ConnectionEventListener listener)
Adds a connection event listener to the ManagedConnection
instance.
|
void |
associateConnection(Object connection)
Used by the container to change the association of an
application-level connection handle with a ManagedConneciton
instance.
|
void |
cleanup()
Application server calls this method to force any cleanup on the
ManagedConnection instance.
|
void |
destroy()
Destroys the physical connection to the underlying resource manager.
|
Object |
getConnection(Subject subject,
ConnectionRequestInfo cxRequestInfo)
Creates a new connection handle for the underlying physical connection
represented by the ManagedConnection instance.
|
LocalTransaction |
getLocalTransaction()
Returns an
javax.resource.spi.LocalTransaction instance. |
PrintWriter |
getLogWriter()
Gets the log writer for this ManagedConnection instance.
|
ManagedConnectionMetaData |
getMetaData()
Gets the metadata information for this connection's underlying
EIS resource manager instance.
|
XAResource |
getXAResource()
Returns an
javax.transaction.xa.XAresource instance. |
void |
removeConnectionEventListener(ConnectionEventListener listener)
Removes an already registered connection event listener from the
ManagedConnection instance.
|
void |
setLogWriter(PrintWriter out)
Sets the log writer for this ManagedConnection instance.
|
Object getConnection(Subject subject, ConnectionRequestInfo cxRequestInfo) throws ResourceException
The ManagedConnection uses the Subject and additional ConnectionRequest Info (which is specific to resource adapter and opaque to application server) to set the state of the physical connection.
subject
- security context as JAAS subjectcxRequestInfo
- ConnectionRequestInfo instanceResourceException
- generic exception if operation failsResourceAdapterInternalException
- resource adapter internal error conditionSecurityException
- security related error conditionCommException
- failed communication with EIS instanceEISSystemException
- internal error condition in EIS instance
- used if EIS instance is involved in
setting state of ManagedConnectionvoid destroy() throws ResourceException
To manage the size of the connection pool, an application server can explictly call ManagedConnection.destroy to destroy a physical connection. A resource adapter should destroy all allocated system resources for this ManagedConnection instance when the method destroy is called.
ResourceException
- generic exception if operation failedIllegalStateException
- illegal state for destroying connectionvoid cleanup() throws ResourceException
The method ManagedConnection.cleanup initiates a cleanup of the any client-specific state as maintained by a ManagedConnection instance. The cleanup should invalidate all connection handles that had been created using this ManagedConnection instance. Any attempt by an application component to use the connection handle after cleanup of the underlying ManagedConnection should result in an exception.
The cleanup of ManagedConnection is always driven by an application server. An application server should not invoke ManagedConnection.cleanup when there is an uncompleted transaction (associated with a ManagedConnection instance) in progress.
The invocation of ManagedConnection.cleanup method on an already cleaned-up connection should not throw an exception.
The cleanup of ManagedConnection instance resets its client specific state and prepares the connection to be put back in to a connection pool. The cleanup method should not cause resource adapter to close the physical pipe and reclaim system resources associated with the physical connection.
ResourceException
- generic exception if operation failsResourceAdapterInternalException
- resource adapter internal error conditionIllegalStateException
- Illegal state for calling connection
cleanup. Example - if a localtransaction
is in progress that doesn't allow
connection cleanupvoid associateConnection(Object connection) throws ResourceException
associateConnection
method to set the same ManagedConnection
associated
with the Connection handle.
The resource adapter is required to implement the associateConnection method. The method implementation for a ManagedConnection should dissociate the connection handle (passed as a parameter) from its currently associated ManagedConnection and associate the new connection handle with itself.
connection
- Application-level connection handleResourceException
- Failed to associate the connection
handle with this ManagedConnection
instanceIllegalStateException
- Illegal state for invoking this
methodResourceAdapterInternalException
- Resource adapter internal error
conditionvoid addConnectionEventListener(ConnectionEventListener listener)
The registered ConnectionEventListener instances are notified of connection close and error events, also of local transaction related events on the Managed Connection.
listener
- a new ConnectionEventListener to be registeredvoid removeConnectionEventListener(ConnectionEventListener listener)
listener
- already registered connection event listener to be
removedXAResource getXAResource() throws ResourceException
javax.transaction.xa.XAresource
instance.
An application server enlists this XAResource instance with the
Transaction Manager if the ManagedConnection instance is being used
in a JTA transaction that is being coordinated by the Transaction
Manager.ResourceException
- generic exception if operation failsNotSupportedException
- if the operation is not supportedResourceAdapterInternalException
- resource adapter internal error conditionLocalTransaction getLocalTransaction() throws ResourceException
javax.resource.spi.LocalTransaction
instance.
The LocalTransaction interface is used by the container to manage
local transactions for a RM instance.ResourceException
- generic exception if operation failsNotSupportedException
- if the operation is not supportedResourceAdapterInternalException
- resource adapter internal error conditionManagedConnectionMetaData getMetaData() throws ResourceException
Gets the metadata information for this connection's underlying EIS resource manager instance. The ManagedConnectionMetaData interface provides information about the underlying EIS instance associated with the ManagedConenction instance.
ResourceException
- generic exception if operation failsNotSupportedException
- if the operation is not supportedvoid setLogWriter(PrintWriter out) throws ResourceException
The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. Application Server manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements.
When a ManagedConnection object is initially created, the default log writer associated with this instance is obtained from the ManagedConnectionFactory. An application server can set a log writer specific to this ManagedConnection to log/trace this instance using setLogWriter method.
out
- Character Output stream to be associatedResourceException
- generic exception if operation failsResourceAdapterInternalException
- resource adapter related error conditionPrintWriter getLogWriter() throws ResourceException
The log writer is a character output stream to which all logging and tracing messages for this ManagedConnection instance will be printed. ConnectionManager manages the association of output stream with the ManagedConnection instance based on the connection pooling requirements.
The Log writer associated with a ManagedConnection instance can be one set as default from the ManagedConnectionFactory (that created this connection) or one set specifically for this instance by the application server.
ResourceException
- generic exception if operation failsCopyright © 2019 JBoss by Red Hat. All rights reserved.