JmsManagedConnection (Red Hat JBoss Enterprise Application Platform 6.4.19.GA public API)

java.lang.Object
- org.jboss.resource.adapter.jms.JmsManagedConnection

All Implemented Interfaces:

ExceptionListener, ManagedConnection
```
public class JmsManagedConnection
extends Object
implements ManagedConnection, ExceptionListener
```
Managed Connection, manages one or more JMS sessions.

Every ManagedConnection will have a physical JMSConnection under the hood. This may leave out several session, as specifyed in 5.5.4 Multiple Connection Handles. Thread safe semantics is provided

Hm. If we are to follow the example in 6.11 this will not work. We would have to use the SAME session. This means we will have to guard against concurrent access. We use a stack, and only allowes the handle at the top of the stack to do things.

As to transactions we some fairly hairy alternatives to handle: XA - we get an XA. We may now only do transaction through the XAResource, since a XASession MUST throw exceptions in commit etc. But since XA support implies LocatTransaction support, we will have to use the XAResource in the LocalTransaction class. LocalTx - we get a normal session. The LocalTransaction will then work against the normal session api.

An invokation of JMS MAY BE DONE in none transacted context. What do we do then? How much should we leave to the user???

One possible solution is to use transactions any way, but under the hood. If not LocalTransaction or XA has been aquired by the container, we have to do the commit in send and publish. (CHECK is the container required to get a XA every time it uses a managed connection? No its is not, only at creation!)

Does this mean that a session one time may be used in a transacted env, and another time in a not transacted.

Maybe we could have this simple rule:

If a user is going to use non trans:
- mark that i ra deployment descr
- Use a JmsProviderAdapter with non XA factorys
- Mark session as non transacted (this defeats the purpose of specifying
- trans attrinbutes in deploy descr NOT GOOD
From the JMS tutorial: "When you create a session in an enterprise bean, the container ignores the arguments you specify, because it manages all transactional properties for enterprise beans."

And further: "You do not specify a message acknowledgment mode when you create a message-driven bean that uses container-managed transactions. The container handles acknowledgment automatically."

On Session or Connection:
From Tutorial: "A JMS API resource is a JMS API connection or a JMS API session." But in the J2EE spec only connection is considered a resource.

Not resolved: connectionErrorOccurred: it is verry hard to know from the exceptions thrown if it is a connection error. Should we register an ExceptionListener and mark al handles as errounous? And then let them send the event and throw an exception?
Author:

Peter Antman., Jason Dillon, Adrian Brock

Constructor Summary

Constructors
Constructor and Description
`JmsManagedConnection(JmsManagedConnectionFactory mcf, ConnectionRequestInfo info, String user, String pwd)` Create a `JmsManagedConnection`.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addConnectionEventListener(ConnectionEventListener l)` Add a connection event listener.
`void`	`associateConnection(Object obj)` Move a handler from one mc to this one.
`void`	`cleanup()` Cleans up, from the spec - The cleanup of ManagedConnection instance resets its client specific state.
`Connection`	`createConnection(Object factory, String username, String password)` Create a connection from the given factory.
`void`	`destroy()` Destroy the physical connection.
`Object`	`getConnection(Subject subject, ConnectionRequestInfo info)` Get the physical connection handler.
`protected ConnectionRequestInfo`	`getInfo()` Get the request info for this connection.
`LocalTransaction`	`getLocalTransaction()` Get the location transaction for the connection.
`PrintWriter`	`getLogWriter()` Get the log writer for this connection.
`protected JmsManagedConnectionFactory`	`getManagedConnectionFactory()` Get the connection factory for this connection.
`ManagedConnectionMetaData`	`getMetaData()` Get the meta data for the connection.
`protected Session`	`getSession()` Get the session for this connection.
`protected String`	`getUserName()` Get the user name for this connection.
`XAResource`	`getXAResource()` Get the XAResource for the connection.
`protected void`	`lock()`
`void`	`onException(JMSException exception)` Notifies user of a JMS exception.
`void`	`removeConnectionEventListener(ConnectionEventListener l)` Remove a connection event listener.
`protected void`	`removeHandle(JmsSession handle)` Remove a handle from the handle map.
`protected void`	`sendEvent(ConnectionEvent event)` Send an event.
`void`	`setLogWriter(PrintWriter out)` Set the log writer for this connection.
`protected void`	`tryLock()`
`protected void`	`unlock()`

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

- Constructor Detail
  - JmsManagedConnection
```
public JmsManagedConnection(JmsManagedConnectionFactory mcf,
                    ConnectionRequestInfo info,
                    String user,
                    String pwd)
                     throws ResourceException
```
    Create a JmsManagedConnection.
    
    Parameters:
    mcf -
    info -
    user -
    pwd -
    
    Throws:
    
    ResourceException
- Method Detail
  - getConnection
```
public Object getConnection(Subject subject,
                   ConnectionRequestInfo info)
                     throws ResourceException
```
    Get the physical connection handler. This bummer will be called in two situations:
    1. When a new mc has bean created and a connection is needed
    2. When an mc has been fetched from the pool (returned in match*)
    It may also be called multiple time without a cleanup, to support connection sharing.
    Specified by:
    
    getConnection in interface ManagedConnection
    
    Parameters:
    subject -
    info -
    
    Returns:
    A new connection object.
    
    Throws:
    
    ResourceException
    
    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
  - destroy
```
public void destroy()
             throws ResourceException
```
    Destroy the physical connection.
    
    Specified by:
    
    destroy in interface ManagedConnection
    
    Throws:
    
    ResourceException - Could not property close the session and connection.
  - cleanup
```
public void cleanup()
             throws ResourceException
```
    Cleans up, from the spec - The cleanup of ManagedConnection instance resets its client specific state. Does that mean that authentication should be redone. FIXME
    
    Specified by:
    
    cleanup in interface ManagedConnection
    
    Throws:
    
    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
  - associateConnection
```
public void associateConnection(Object obj)
                         throws ResourceException
```
    Move a handler from one mc to this one.
    
    Specified by:
    
    associateConnection in interface ManagedConnection
    
    Parameters:
    obj - An object of type JmsSession.
    
    Throws:
    
    ResourceException - Failed to associate connection.
    
    IllegalStateException - ManagedConnection in an illegal state.
  - lock
```
protected void lock()
```
  - tryLock
```
protected void tryLock()
                throws JMSException
```
    Throws:
    
    JMSException
  - unlock
```
protected void unlock()
```
  - addConnectionEventListener
```
public void addConnectionEventListener(ConnectionEventListener l)
```
    Add a connection event listener.
    
    Specified by:
    
    addConnectionEventListener in interface ManagedConnection
    
    Parameters:
    l - The connection event listener to be added.
  - removeConnectionEventListener
```
public void removeConnectionEventListener(ConnectionEventListener l)
```
    Remove a connection event listener.
    
    Specified by:
    
    removeConnectionEventListener in interface ManagedConnection
    
    Parameters:
    l - The connection event listener to be removed.
  - getXAResource
```
public XAResource getXAResource()
                         throws ResourceException
```
    Get the XAResource for the connection.
    
    Specified by:
    
    getXAResource in interface ManagedConnection
    
    Returns:
    The XAResource for the connection.
    
    Throws:
    
    ResourceException - XA transaction not supported
  - getLocalTransaction
```
public LocalTransaction getLocalTransaction()
                                     throws ResourceException
```
    Get the location transaction for the connection.
    
    Specified by:
    
    getLocalTransaction in interface ManagedConnection
    
    Returns:
    The local transaction for the connection.
    
    Throws:
    
    ResourceException
    
    NotSupportedException - if the operation is not supported
    
    ResourceAdapterInternalException - resource adapter internal error condition
  - getMetaData
```
public ManagedConnectionMetaData getMetaData()
                                      throws ResourceException
```
    Get the meta data for the connection.
    
    Specified by:
    
    getMetaData in interface ManagedConnection
    
    Returns:
    The meta data for the connection.
    
    Throws:
    
    ResourceException
    
    IllegalStateException - ManagedConnection already destroyed.
    
    NotSupportedException - if the operation is not supported
  - setLogWriter
```
public void setLogWriter(PrintWriter out)
                  throws ResourceException
```
    Set the log writer for this connection.
    
    Specified by:
    
    setLogWriter in interface ManagedConnection
    
    Parameters:
    out - The log writer for this connection.
    
    Throws:
    
    ResourceException
    
    ResourceAdapterInternalException - resource adapter related error condition
  - getLogWriter
```
public PrintWriter getLogWriter()
                         throws ResourceException
```
    Get the log writer for this connection.
    
    Specified by:
    
    getLogWriter in interface ManagedConnection
    
    Returns:
    Always null
    
    Throws:
    
    ResourceException - generic exception if operation fails
  - onException
```
public void onException(JMSException exception)
```
    Description copied from interface: ExceptionListener
    
    Notifies user of a JMS exception.
    
    Specified by:
    
    onException in interface ExceptionListener
    
    Parameters:
    exception - the JMS exception
  - getSession
```
protected Session getSession()
```
    Get the session for this connection.
    
    Returns:
    Either a topic or queue connection.
  - sendEvent
```
protected void sendEvent(ConnectionEvent event)
```
    Send an event.
    
    Parameters:
    event - The event to send.
  - removeHandle
```
protected void removeHandle(JmsSession handle)
```
    Remove a handle from the handle map.
    
    Parameters:
    handle - The handle to remove.
  - getInfo
```
protected ConnectionRequestInfo getInfo()
```
    Get the request info for this connection.
    
    Returns:
    The request info for this connection.
  - getManagedConnectionFactory
```
protected JmsManagedConnectionFactory getManagedConnectionFactory()
```
    Get the connection factory for this connection.
    
    Returns:
    The connection factory for this connection.
  - getUserName
```
protected String getUserName()
```
    Get the user name for this connection.
    
    Returns:
    The user name for this connection.
  - createConnection
```
public Connection createConnection(Object factory,
                          String username,
                          String password)
                            throws JMSException
```
    Create a connection from the given factory. An XA connection will be created if possible.
    
    Parameters:
    factory - An object that implements ConnectionFactory, XAQConnectionFactory
    username - The username to use or null for no user.
    password - The password for the given username or null if no username was specified.
    
    Returns:
    A connection.
    
    Throws:
    
    JMSException - Failed to create connection.
    
    IllegalArgumentException - Factory is null or invalid.

Class JmsManagedConnection

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

JmsManagedConnection

Method Detail

getConnection

destroy

cleanup

associateConnection

lock

tryLock

unlock

addConnectionEventListener

removeConnectionEventListener

getXAResource

getLocalTransaction

getMetaData

setLogWriter

getLogWriter

onException

getSession

sendEvent

removeHandle

getInfo

getManagedConnectionFactory

getUserName

createConnection