javax.resource API 1.7.1 · javax.resource.spi.ManagedConnection

Method Summary

Modifier and Type	Method and Description
public void	addConnectionEventListener(ConnectionEventListener a new ConnectionEventListener to be registered listener) Adds a connection event listener to the ManagedConnection instance.
public void	associateConnection(Object Application-level connection handle connection) Used typically by the container to change the association of an application-level connection handle with a ManagedConnection instance.
public void	cleanup() Application server calls this method to force any cleanup on the ManagedConnection instance.
public void	destroy() Destroys the physical connection to the underlying resource manager.
public Object	Returns: generic Object instance representing the connection handle. For CCI, the connection handle created by a ManagedConnection instance is of the type javax.resource.cci.Connection. getConnection(Subject security context as JAAS subject subject, ConnectionRequestInfo ConnectionRequestInfo instance cxRequestInfo) Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance.
public LocalTransaction	Returns: LocalTransaction instance getLocalTransaction() Returns an `javax.resource.spi.LocalTransaction` instance.
public PrintWriter	Returns: Character ourput stream associated with this Managed- Connection instance getLogWriter() Gets the log writer for this ManagedConnection instance.
public ManagedConnectionMetaData	Returns: ManagedConnectionMetaData instance getMetaData() Gets the metadata information for this connection's underlying EIS resource manager instance.
public XAResource	Returns: XAResource instance getXAResource() Returns an `javax.transaction.xa.XAresource` instance.
public void	removeConnectionEventListener(ConnectionEventListener already registered connection event listener to be removed listener) Removes an already registered connection event listener from the ManagedConnection instance.
public void	setLogWriter(PrintWriter Character Output stream to be associated out) Sets the log writer for this ManagedConnection instance.

Method Detail

addConnectionEventListener	back to summary
public void addConnectionEventListener(ConnectionEventListener listener) Adds a connection event listener to the ManagedConnection instance. The registered ConnectionEventListener instances are notified of connection close and error events, also of local transaction related events on the Managed Connection. Parameters listener:ConnectionEventListener a new ConnectionEventListener to be registered

addConnectionEventListener

back to summary

public void addConnectionEventListener(ConnectionEventListener listener)

Adds a connection event listener to the ManagedConnection instance.

The registered ConnectionEventListener instances are notified of connection close and error events, also of local transaction related events on the Managed Connection.

Parameters

listener:ConnectionEventListener: a new ConnectionEventListener to be registered

associateConnection back to summary

associateConnection	back to summary
public void associateConnection(Object connection) throws ResourceException Used typically by the container to change the association of an application-level connection handle with a ManagedConnection instance. The container should find the right ManagedConnection instance and call the associateConnection method. In order to set a Connection Handle as the active connection handle, the container may also use the `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. Parameters connection:Object Application-level connection handle Exceptions ResourceException: Failed to associate the connection handle with this ManagedConnection instance IllegalStateException: Illegal state for invoking this method ResourceAdapterInternalException: Resource adapter internal error condition

public void associateConnection(Object connection) throws ResourceException

Used typically by the container to change the association of an application-level connection handle with a ManagedConnection instance. The container should find the right ManagedConnection instance and call the associateConnection method. In order to set a Connection Handle as the active connection handle, the container may also use the 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.

Parameters

connection:Object: Application-level connection handle

Exceptions

ResourceException:: Failed to associate the connection handle with this ManagedConnection instance
IllegalStateException:: Illegal state for invoking this method
ResourceAdapterInternalException:: Resource adapter internal error condition

cleanup	back to summary
public void cleanup() throws ResourceException Application server calls this method to force any cleanup on the ManagedConnection instance. 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. Exceptions ResourceException: generic exception if operation fails ResourceAdapterInternalException: resource adapter internal error condition IllegalStateException: Illegal state for calling connection cleanup. Example - if a localtransaction is in progress that doesn't allow connection cleanup

cleanup

back to summary

public void cleanup() throws ResourceException

Application server calls this method to force any cleanup on the ManagedConnection instance.

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.

Exceptions

ResourceException:: generic exception if operation fails
ResourceAdapterInternalException:: resource adapter internal error condition
IllegalStateException:: Illegal state for calling connection cleanup. Example - if a localtransaction is in progress that doesn't allow connection cleanup

destroy	back to summary
public void destroy() throws ResourceException Destroys the physical connection to the underlying resource manager. 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. Exceptions ResourceException: generic exception if operation failed IllegalStateException: illegal state for destroying connection

destroy

back to summary

public void destroy() throws ResourceException

Destroys the physical connection to the underlying resource manager.

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.

Exceptions

ResourceException:: generic exception if operation failed
IllegalStateException:: illegal state for destroying connection

getConnection	back to summary
public Object getConnection(Subject subject, ConnectionRequestInfo cxRequestInfo) throws ResourceException Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance. This connection handle is used by the application code to refer to the underlying physical connection. This connection handle is associated with its ManagedConnection instance in a resource adapter implementation specific way. 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. Parameters subject:Subject security context as JAAS subject cxRequestInfo:ConnectionRequestInfo ConnectionRequestInfo instance Returns:Object generic Object instance representing the connection handle. For CCI, the connection handle created by a ManagedConnection instance is of the type javax.resource.cci.Connection. Exceptions ResourceException: generic exception if operation fails ResourceAdapterInternalException: resource adapter internal error condition SecurityException: security related error condition CommException: failed communication with EIS instance EISSystemException: internal error condition in EIS instance - used if EIS instance is involved in setting state of ManagedConnection

getConnection

back to summary

public Object getConnection(Subject subject, ConnectionRequestInfo cxRequestInfo) throws ResourceException

Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance. This connection handle is used by the application code to refer to the underlying physical connection. This connection handle is associated with its ManagedConnection instance in a resource adapter implementation specific way.

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.

Parameters

subject:Subject: security context as JAAS subject
cxRequestInfo:ConnectionRequestInfo: ConnectionRequestInfo instance

Returns:Object

generic Object instance representing the connection handle. For CCI, the connection handle created by a ManagedConnection instance is of the type javax.resource.cci.Connection.

Exceptions

ResourceException:: generic exception if operation fails
ResourceAdapterInternalException:: resource adapter internal error condition
SecurityException:: security related error condition
CommException:: failed communication with EIS instance
EISSystemException:: internal error condition in EIS instance - used if EIS instance is involved in setting state of ManagedConnection

getLocalTransaction back to summary

getLocalTransaction	back to summary
public LocalTransaction getLocalTransaction() throws ResourceException Returns an `javax.resource.spi.LocalTransaction` instance. The LocalTransaction interface is used by the container to manage local transactions for a RM instance. Returns:LocalTransaction LocalTransaction instance Exceptions ResourceException: generic exception if operation fails NotSupportedException: if the operation is not supported ResourceAdapterInternalException: resource adapter internal error condition

public LocalTransaction getLocalTransaction() throws ResourceException

Returns an javax.resource.spi.LocalTransaction instance. The LocalTransaction interface is used by the container to manage local transactions for a RM instance.

Returns:LocalTransaction

LocalTransaction instance

Exceptions

ResourceException:: generic exception if operation fails
NotSupportedException:: if the operation is not supported
ResourceAdapterInternalException:: resource adapter internal error condition

getLogWriter	back to summary
public PrintWriter getLogWriter() throws ResourceException Gets the log writer for this ManagedConnection instance. 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. Returns:PrintWriter Character ourput stream associated with this Managed- Connection instance Exceptions ResourceException: generic exception if operation fails

getLogWriter

back to summary

public PrintWriter getLogWriter() throws ResourceException

Gets the log writer for this ManagedConnection instance.

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.

Returns:PrintWriter

Character ourput stream associated with this Managed- Connection instance

Exceptions

ResourceException:: generic exception if operation fails

getMetaData

back to summary

public ManagedConnectionMetaData 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.

Returns:ManagedConnectionMetaData

ManagedConnectionMetaData instance

Exceptions

ResourceException:: generic exception if operation fails
NotSupportedException:: if the operation is not supported

getXAResource back to summary

getXAResource	back to summary
public XAResource getXAResource() throws ResourceException Returns an `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. Returns:XAResource XAResource instance Exceptions ResourceException: generic exception if operation fails NotSupportedException: if the operation is not supported ResourceAdapterInternalException: resource adapter internal error condition

public XAResource getXAResource() throws ResourceException

Returns an 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.

Returns:XAResource

XAResource instance

Exceptions

ResourceException:: generic exception if operation fails
NotSupportedException:: if the operation is not supported
ResourceAdapterInternalException:: resource adapter internal error condition

removeConnectionEventListener	back to summary
public void removeConnectionEventListener(ConnectionEventListener listener) Removes an already registered connection event listener from the ManagedConnection instance. Parameters listener:ConnectionEventListener already registered connection event listener to be removed

removeConnectionEventListener

back to summary

public void removeConnectionEventListener(ConnectionEventListener listener)

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

Parameters

listener:ConnectionEventListener: already registered connection event listener to be removed

setLogWriter	back to summary
public void setLogWriter(PrintWriter out) throws ResourceException Sets the log writer for this ManagedConnection instance. 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. Parameters out:PrintWriter Character Output stream to be associated Exceptions ResourceException: generic exception if operation fails ResourceAdapterInternalException: resource adapter related error condition

setLogWriter

back to summary

public void setLogWriter(PrintWriter out) throws ResourceException

Sets the log writer for this ManagedConnection instance.

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.

Parameters

out:PrintWriter: Character Output stream to be associated

Exceptions

ResourceException:: generic exception if operation fails
ResourceAdapterInternalException:: resource adapter related error condition

public Interface ManagedConnection

Method Summary

Method Detail