Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.stc.connector.framework.jca.system
Class STCManagedConnection

    java.lang.Object
      com.stc.connector.framework.jca.system.STCManagedConnection

All Implemented Interfaces:
  javax.resource.spi.ManagedConnection, ManagedConnectionCallback, STCManagedMaster

public class STCManagedConnection
extends java.lang.Object
implements javax.resource.spi.ManagedConnection, ManagedConnectionCallback, STCManagedMaster

This class implements the ManagedConnection interface which represents a physical connection to the underlying EIS. 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. This class also implments the ManagedConnectionCallback interface so that the EwayConnection associated with the ManagedConnection can get services from the ManagedConnection.

Version:
  $Version$
Author:
  $Author: npiega $

Constructor Summary
`STCManagedConnection(STCManagedConnectionFactory mcf, javax.security.auth.Subject subject, STCPropertiesInfo cri)` No-args constructor needed so subclasses can use constructors with different signatures.

Method Summary
`void` | `addConnectionEventListener(javax.resource.spi.ConnectionEventListener connectionEventListener)` Adds a connection event listener to the ManagedConnection instance.
`void` | `addConnectionHandle(AssociateableHandle connHandle)` Adds a connection handle to the ManagedConnection instance.
`void` | `associateConnection(java.lang.Object obj)` 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` | `createMBean(java.lang.String mbeanClassName, java.lang.String mbeanName)` Creates the MBean
`void` | `destroy()` Destroys the physical connection to the underlying resource manager.
`java.lang.Object` | `getConnection(javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo cri)` Creates a new connection handle for the underlying physical connection represented by the ManagedConnection instance.
`int` | `getConnectionHandleCount()` Gets the current number active connection handles associated with an instance of ManagedConnection.
`EwayConnection` | `getEwayConnection()` Get the EwayConnection instance associated with the ManagedConnection instance.
`javax.resource.spi.LocalTransaction` | `getLocalTransaction()` Returns an javax.resource.spi.LocalTransaction instance.
`java.io.PrintWriter` | `getLogWriter()` Gets the log writer for this ManagedConnection instance.
`javax.resource.spi.ManagedConnection` | `getManagedConnection()` Get the ManagedConnection instance associated with the ManagedConnectionCallback instance.
`STCManagedConnectionFactory` | `getManagedConnectionFactory()` Get the ManagedConnectionFactory which created this instance of ManagedConnection.
`java.lang.Object` | `getMBean()` Getter for ManagedConnection's MBean
`javax.resource.spi.ManagedConnectionMetaData` | `getMetaData()` Gets the metadata information for this connection's underlying EIS resource manager instance.
`javax.transaction.xa.XAResource` | `getXAResource()` Returns an javax.transaction.xa.XAresource instance.
`boolean` | `matchConnection(javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo cri)` Determines whether this instance of the ManagedConnection matches the the connection request with the connection information in Subject and/or ConnectionRequestInfo.
`void` | `notifyConnectionEvent(javax.resource.spi.ConnectionEvent event)` Notify the ManagedConnection associated with the EwayConnection instance that a connection event had occurred.
`protected void` | `postDestroy()` Last chance to do anything else after the ManagedConnection is destroyed.
`protected void` | `preDestroy()` Performs any special operations before the ManagedConnection instance is destroyed.
`void` | `removeConnectionEventListener(javax.resource.spi.ConnectionEventListener connectionEventListener)` Removes a connection event listener from the ManagedConnection instance.
`void` | `removeConnectionHandle(AssociateableHandle connHandle)` Removes a connection handle from the ManagedConnection instance.
`void` | `setLogWriter(java.io.PrintWriter out)` Sets the log writer for this ManagedConnection instance.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### STCManagedConnection

    public STCManagedConnection(STCManagedConnectionFactory mcf,
                                javax.security.auth.Subject subject,
                                STCPropertiesInfo cri)
                         throws javax.resource.ResourceException

  No-args constructor needed so subclasses can use constructors with different signatures.

Parameters:
  `mcf` - DOCUMENT ME!
  `subject` - DOCUMENT ME!
  `cri` - DOCUMENT ME!
Throws:
  `javax.resource.ResourceException` - DOCUMENT ME!

Method Detail

### addConnectionEventListener

    public void addConnectionEventListener(javax.resource.spi.ConnectionEventListener connectionEventListener)

  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 ManagedConnection (for component-managed local transactions).

  Specified by:
    `addConnectionEventListener` in interface `javax.resource.spi.ManagedConnection`
  Parameters:
    `connectionEventListener` - An instance of ConnectionEventListener to register for event notifications.

### removeConnectionEventListener

    public void removeConnectionEventListener(javax.resource.spi.ConnectionEventListener connectionEventListener)

  Removes a connection event listener from the ManagedConnection instance.

  Specified by:
    `removeConnectionEventListener` in interface `javax.resource.spi.ManagedConnection`
  Parameters:
    `connectionEventListener` - An instance of ConnectionEventListener to uregister.

### addConnectionHandle

    public void addConnectionHandle(AssociateableHandle connHandle)

  Adds a connection handle to the ManagedConnection instance. The connection handle must be already associated with the ManagedConnection instance.

  Specified by:
    `addConnectionHandle` in interface `ManagedConnectionCallback`
  Parameters:
    `connHandle` - An connection handle which implements the AssociateableHandle.

### removeConnectionHandle

    public void removeConnectionHandle(AssociateableHandle connHandle)

  Removes a connection handle from the ManagedConnection instance. The connection handle must be removed from the ManagedConnection instance prior to associating itself to another ManagedConnection instance.

  Specified by:
    `removeConnectionHandle` in interface `ManagedConnectionCallback`
  Parameters:
    `connHandle` - An connection handle which implements the AssociateableHandle.

### getConnection

    public java.lang.Object getConnection(javax.security.auth.Subject subject,
                                          javax.resource.spi.ConnectionRequestInfo cri)
                                   throws javax.resource.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. A connection handle is tied to 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.

  Specified by:
    `getConnection` in interface `javax.resource.spi.ManagedConnection`
  Parameters:
    `subject` - The Subject provided by the container which can be used for reauthentication if the EIS supports reauthentication.
    `cri` - The ConnectionRequestInfo containing additional information which can be used for sign on.
  Returns:
    An opague connection handle Object instance which must implement AssociateableHandle.
  Throws:
    `javax.resource.ResourceException` - - generic exception if operation fails

### associateConnection

    public void associateConnection(java.lang.Object obj)
                             throws javax.resource.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. 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.

  Specified by:
    `associateConnection` in interface `javax.resource.spi.ManagedConnection`
  Parameters:
    `obj` - An opague connection handle Object instance which must implement AssociateableHandle.
  Throws:
    `javax.resource.ResourceException` - - Failed to associate the connection handle with this ManagedConnection instance

### cleanup

    public void cleanup()
                 throws javax.resource.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.

  Specified by:
    `cleanup` in interface `javax.resource.spi.ManagedConnection`
  Throws:
    `javax.resource.ResourceException` - - generic exception if operation fails

### destroy

    public void destroy()
                 throws javax.resource.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.

  Specified by:
    `destroy` in interface `javax.resource.spi.ManagedConnection`
  Throws:
    `javax.resource.ResourceException` - - generic exception if operation failed

### preDestroy

    protected void preDestroy()
                       throws javax.resource.ResourceException

  Performs any special operations before the ManagedConnection instance is destroyed.

  Throws:
    `javax.resource.ResourceException` - - generic exception if operation failed

### postDestroy

    protected void postDestroy()

  Last chance to do anything else after the ManagedConnection is destroyed.

### getLocalTransaction

    public javax.resource.spi.LocalTransaction getLocalTransaction()
                                                            throws javax.resource.ResourceException

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

  Specified by:
    `getLocalTransaction` in interface `javax.resource.spi.ManagedConnection`
  Returns:
    LocalTransaction instance
  Throws:
    `javax.resource.ResourceException` - - generic exception if operation fails

### getXAResource

    public javax.transaction.xa.XAResource getXAResource()
                                                  throws javax.resource.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.

  Specified by:
    `getXAResource` in interface `javax.resource.spi.ManagedConnection`
  Returns:
    XAResource instance
  Throws:
    `javax.resource.ResourceException` - - generic exception if operation fails

### getMetaData

    public javax.resource.spi.ManagedConnectionMetaData getMetaData()
                                                             throws javax.resource.ResourceException

  Gets the metadata information for this connection's underlying EIS resource manager instance. The ManagedConnectionMetaData interfacen provides information about the underlying EIS instance associated with the ManagedConenction instance.

  Specified by:
    `getMetaData` in interface `javax.resource.spi.ManagedConnection`
  Returns:
    ManagedConnectionMetaData instance
  Throws:
    `javax.resource.ResourceException` - - generic exception if operation fails

### getLogWriter

    public java.io.PrintWriter getLogWriter()
                                     throws javax.resource.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.

  Specified by:
    `getLogWriter` in interface `javax.resource.spi.ManagedConnection`
  Returns:
    Character output stream associated with this ManagedConnection instance
  Throws:
    `javax.resource.ResourceException` - DOCUMENT ME!

### setLogWriter

    public void setLogWriter(java.io.PrintWriter out)
                      throws javax.resource.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.

  Specified by:
    `setLogWriter` in interface `javax.resource.spi.ManagedConnection`
  Parameters:
    `out` - Character Output stream to be associated.
  Throws:
    `javax.resource.ResourceException` - DOCUMENT ME!

### notifyConnectionEvent

    public void notifyConnectionEvent(javax.resource.spi.ConnectionEvent event)

  Notify the ManagedConnection associated with the EwayConnection instance that a connection event had occurred.

  Specified by:
    `notifyConnectionEvent` in interface `ManagedConnectionCallback`
  Parameters:
    `event` - A ConnectionEvent instance containing the event that had occurred.

### getEwayConnection

    public EwayConnection getEwayConnection()

  Get the EwayConnection instance associated with the ManagedConnection instance.

  Specified by:
    `getEwayConnection` in interface `ManagedConnectionCallback`
  Returns:
    The instance of EwayConnection associated with the ManagedConnection instance.

### getManagedConnectionFactory

    public STCManagedConnectionFactory getManagedConnectionFactory()

  Get the ManagedConnectionFactory which created this instance of ManagedConnection.

  Returns:
    The instance of ManagedConnectionFactory which created this ManagedConnection instance.

### matchConnection

    public boolean matchConnection(javax.security.auth.Subject subject,
                                   javax.resource.spi.ConnectionRequestInfo cri)

  Determines whether this instance of the ManagedConnection matches the the connection request with the connection information in Subject and/or ConnectionRequestInfo.

  Parameters:
    `subject` - The Subject instance which holds the credentials for EIS signon.
    `cri` - The ConnectionRequestInfo instance which holds both EIS EIS signon information or general connection specific information. The ConnectionRequestInfo provided will contain the union of the properties from the client connection request properties, the ResourceAdapter properties, and the ManagedConnectionFactory properties.
  Returns:
    A boolean true if there is a connection match; false otherwise.

### getConnectionHandleCount

    public int getConnectionHandleCount()

  Gets the current number active connection handles associated with an instance of ManagedConnection.

  Specified by:
    `getConnectionHandleCount` in interface `ManagedConnectionCallback`
  Returns:
    The current number of active connection handles assoiciated with an instance of ManagedConnection;

### getManagedConnection

    public javax.resource.spi.ManagedConnection getManagedConnection()

  Get the ManagedConnection instance associated with the ManagedConnectionCallback instance.

  Specified by:
    `getManagedConnection` in interface `ManagedConnectionCallback`
  Returns:
    The instance of ManagedConnection associated with the ManagedConnection instance.

### getMBean

    public java.lang.Object getMBean()

  Getter for ManagedConnection's MBean

  Specified by:
    `getMBean` in interface `STCManagedMaster`
  Returns:
    MBean object associated with the managed connection

### createMBean

    public void createMBean(java.lang.String mbeanClassName,
                            java.lang.String mbeanName)
                     throws STCCreateMBeanException

  Creates the MBean

  Specified by:
    `createMBean` in interface `STCManagedMaster`
  Parameters:
    `mbeanClassName` - classname of MBean impl class
    `mbeanName` - name of MBean
  Throws:
    `STCCreateMBeanException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD