-
- /*
- * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
- * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
- */
-
- package javax.resource.spi;
-
- import javax.security.auth.Subject;
- import javax.transaction.xa.XAResource;
- import javax.resource.ResourceException;
-
- /** ManagedConnection instance represents a physical connection
- * to the underlying EIS.
- *
- * <p>A ManagedConnection instance provides access to a pair of
- * interfaces: <code>javax.transaction.xa.XAResource</code> and
- * <code>javax.resource.spi.LocalTransaction</code>.
- *
- * <p><code> XAResource</code> 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.
- *
- * <p>The LocalTransaction interface is used by the application server
- * to manage local transactions.
- *
- * @version 0.5
- * @author Rahul Sharma
- * @see javax.resource.spi.ManagedConnectionFactory
- * @see javax.transaction.xa.XAResource
- * @see javax.resource.spi.LocalTransaction
- **/
-
- public interface ManagedConnection {
-
- /** 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. A connection handle is tied to its ManagedConnection instance
- * in a resource adapter implementation specific way.</P>
- *
- * <P>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.</p>
- *
- * @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
- Object getConnection(Subject subject,
- ConnectionRequestInfo cxRequestInfo)
- throws ResourceException;
-
- /** Destroys the physical connection to the underlying resource manager.
- *
- * <p>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
- void destroy() throws ResourceException;
-
- /** Application server calls this method to force any cleanup on the
- * ManagedConnection instance.
- *
- * <p>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.
- *
- * <p>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.
-
- * <p>The invocation of ManagedConnection.cleanup method on an already
- * cleaned-up connection should not throw an exception.
- *
- * <p>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 cleanup() throws ResourceException;
-
- /** 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.
- *
- * <p>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 associateConnection(Object connection)
- throws ResourceException;
-
-
-
- /** Adds a connection event listener to the ManagedConnection
- * instance.
- *
- * <p>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 addConnectionEventListener(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 removeConnectionEventListener(
- ConnectionEventListener listener);
-
- /** Returns an <code>javax.transaction.xa.XAresource</code> 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
- XAResource getXAResource() throws ResourceException;
-
- /** Returns an <code>javax.resource.spi.LocalTransaction</code> 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
- LocalTransaction getLocalTransaction() throws ResourceException;
-
- /** <p>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
- ManagedConnectionMetaData getMetaData() throws ResourceException;
-
- /** Sets the log writer for this ManagedConnection instance.
- *
- * <p>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.</p>
- *
- * <p>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.</p>
- *
- * @param out Character Output stream to be associated
- *
- * @throws ResourceException generic exception if operation fails
- * @throws ResourceAdapterInternalException
- * resource adapter related error condition
- **/
- public
- void setLogWriter(java.io.PrintWriter out) throws ResourceException;
-
- /** Gets the log writer for this ManagedConnection instance.
- *
- * <p>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.</p>
- *
- * <p>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.</p>
- *
- * @return Character ourput stream associated with this Managed-
- * Connection instance
- *
- * @throws ResourceException generic exception if operation fails
- **/
- public
- java.io.PrintWriter getLogWriter() throws ResourceException;
- }