File	Doc	Category	Size	Date	Package
ManagedConnection.java	API Doc	Glassfish v2 API	13297	Fri May 04 22:35:36 BST 2007	javax.resource.spi

ManagedConnection

Fields Summary

Constructors Summary

Methods 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. param listener a new ConnectionEventListener to be registered
public void	associateConnection(java.lang.Object connection) Used by the container to change the association of an application-level connection handle with a ManagedConneciton instance. The container should find the right ManagedConnection instance and call the associateConnection method. 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. param connection Application-level connection handle throws ResourceException Failed to associate the connection handle with this ManagedConnection instance throws IllegalStateException Illegal state for invoking this method throws ResourceAdapterInternalException Resource adapter internal error condition
public void	cleanup() 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. throws ResourceException generic exception if operation fails throws ResourceAdapterInternalException resource adapter internal error condition throws IllegalStateException Illegal state for calling connection cleanup. Example - if a localtransaction is in progress that doesn't allow connection cleanup
public void	destroy() 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. throws ResourceException generic exception if operation failed throws IllegalStateException illegal state for destroying connection
public java.lang.Object	getConnection(javax.security.auth.Subject subject, ConnectionRequestInfo cxRequestInfo) 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. param subject security context as JAAS subject param cxRequestInfo ConnectionRequestInfo instance return 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. throws ResourceException generic exception if operation fails throws ResourceAdapterInternalException resource adapter internal error condition throws SecurityException security related error condition throws CommException failed communication with EIS instance throws EISSystemException internal error condition in EIS instance - used if EIS instance is involved in setting state of ManagedConnection
public LocalTransaction	getLocalTransaction() Returns an javax.resource.spi.LocalTransaction instance. The LocalTransaction interface is used by the container to manage local transactions for a RM instance. return LocalTransaction instance throws ResourceException generic exception if operation fails throws NotSupportedException if the operation is not supported throws ResourceAdapterInternalException resource adapter internal error condition
public java.io.PrintWriter	getLogWriter() 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. return Character ourput stream associated with this Managed- Connection instance throws ResourceException generic exception if operation fails
public ManagedConnectionMetaData	getMetaData() 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. return ManagedConnectionMetaData instance throws ResourceException generic exception if operation fails throws NotSupportedException if the operation is not supported
public javax.transaction.xa.XAResource	getXAResource() 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. return XAResource instance throws ResourceException generic exception if operation fails throws NotSupportedException if the operation is not supported throws ResourceAdapterInternalException resource adapter internal error condition
public void	removeConnectionEventListener(ConnectionEventListener listener) Removes an already registered connection event listener from the ManagedConnection instance. param listener already registered connection event listener to be removed
public void	setLogWriter(java.io.PrintWriter out) 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. param out Character Output stream to be associated throws ResourceException generic exception if operation fails throws ResourceAdapterInternalException resource adapter related error condition