| /* |
| * The contents of this file are subject to the terms |
| * of the Common Development and Distribution License |
| * (the License). You may not use this file except in |
| * compliance with the License. |
| * |
| * You can obtain a copy of the license at |
| * https://glassfish.dev.java.net/public/CDDLv1.0.html or |
| * glassfish/bootstrap/legal/CDDLv1.0.txt. |
| * See the License for the specific language governing |
| * permissions and limitations under the License. |
| * |
| * When distributing Covered Code, include this CDDL |
| * Header Notice in each file and include the License file |
| * at glassfish/bootstrap/legal/CDDLv1.0.txt. |
| * If applicable, add the following below the CDDL Header, |
| * with the fields enclosed by brackets [] replaced by |
| * you own identifying information: |
| * "Portions Copyrighted [year] [name of copyright owner]" |
| * |
| * Copyright 2006 Sun Microsystems, Inc. All rights reserved. |
| */ |
| |
| 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. This connection handle is associated with 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; |
| } |
