MessageDrivenContainer (Transactions JMS 5.0.8 API)

java.lang.Object
- com.atomikos.jms.extra.MessageDrivenContainer

All Implemented Interfaces:

OrderedLifecycleComponent
```
public class MessageDrivenContainer
extends java.lang.Object
implements OrderedLifecycleComponent
```
A message-driven container for asynchronously receiving JMS messages from a topic or queue, within a managed JTA transaction context. Upon start, an instance of this class will create a number of concurrent sessions that listen for incoming messages on the same destination. MessageListener instances should be thread-safe if the pool size is larger than one. Note: in general, after start() any changed properties are only effective on the next start() event.
IMPORTANT: the transactional behaviour guarantees redelivery after failures. As a side-effect, this can lead to so-called poison messages: messages whose processing repeatedly fails due to some recurring error (for instance, a primary key violation in the database, a NullPointerException, ...). Poison messages are problematic because they can prevent other messages from being processed, and block the system. To avoid poison messages, make sure that your MessageListener implementation only throws a RuntimeException when the problem is transient. In that case, the system will perform rollback and the message will be redelivered facing a clean system state. All non-transient errors (i.e., those that happen each time a message is delivered) indicate problems at the application level and should be dealt with by writing better application code.

Constructor Summary

Constructors
Constructor and Description

MessageDrivenContainer()

Constructors
Constructor and Description
`MessageDrivenContainer()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()`
`protected com.atomikos.jms.extra.MessageConsumerSession`	`createSession()`
`AtomikosConnectionFactoryBean`	`getAtomikosConnectionFactoryBean()`
`boolean`	`getDaemonThreads()` Tests whether threads are daemon threads.
`javax.jms.Destination`	`getDestination()` Gets the destination.
`java.lang.String`	`getDestinationName()` Gets the destination name.
`javax.jms.ExceptionListener`	`getExceptionListener()` Gets the exception listener (if any).
`javax.jms.MessageListener`	`getMessageListener()` Get the message listener if any.
`java.lang.String`	`getMessageSelector()` Get the message selector (if any)
`protected boolean`	`getNoLocal()`
`boolean`	`getNotifyListenerOnClose()` Getter to check whether the listener is notified on close.
`int`	`getPoolSize()` Get the size of the pool.
`int`	`getReceiveTimeout()` Gets the receive timeout in seconds.
`java.lang.String`	`getSubscriberName()` Gets the subscriber name (for durable subscribers).
`int`	`getTransactionTimeout()` Get the transaction timeout.
`boolean`	`getUnsubscribeOnClose()` Getter to test if unsubscribe should be called on close.
`java.lang.String`	`getUser()` Get the user for connecting, or null if the default user should be used.
`void`	`init()`
`boolean`	`isNoLocal()` Test if this instance will receive sends from the same connection.
`void`	`setAtomikosConnectionFactoryBean(AtomikosConnectionFactoryBean bean)` Sets the connection factory to use.
`void`	`setClientID(java.lang.String clientID)` Sets the clientID for durable subscriptions.
`void`	`setDaemonThreads(boolean value)` Sets whether threads should be daemon threads or not (optional).
`void`	`setDestination(javax.jms.Destination dest)` Sets the JMS destination to listen on (required unless the destinationName is set instead).
`void`	`setDestinationName(java.lang.String destinationName)` Sets the JMS provider-specific destination name (required unless the destination is set directly).
`void`	`setExceptionListener(javax.jms.ExceptionListener exceptionListener)` Sets the exception listener (optional).
`void`	`setMessageListener(javax.jms.MessageListener listener)` Set the message listener to use (required).
`void`	`setMessageSelector(java.lang.String selector)` Set the message selector to use (optional).
`void`	`setNoLocal(boolean noLocal)` Sets whether or not this topic should receive sends from the same connection (optional).
`void`	`setNotifyListenerOnClose(boolean b)` Set whether the listener should be notified of close events on the pool (optional).
`void`	`setPassword(java.lang.String string)` Set the password if explicit authentication is needed (optional).
`void`	`setPoolSize(int size)` Sets the size of the session pool (optional).
`void`	`setReceiveTimeout(int seconds)` Sets the receive timeout in seconds, i.e.
`void`	`setSubscriberName(java.lang.String subscriberName)` Sets the name to use for durable subscriptions (optional).
`void`	`setTransactionTimeout(int seconds)` Set the transaction timeout in seconds (optional).
`void`	`setUnsubscribeOnClose(boolean b)` Sets whether unsubscribe should be done at closing time (optional).
`void`	`setUser(java.lang.String string)` Set the user to use for explicit authentication (optional).
`void`	`start()` Start listening for messages.
`void`	`stop()` Stop listening for messages.

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

- Constructor Detail
  - MessageDrivenContainer
```
public MessageDrivenContainer()
```
- Method Detail
  - createSession
```
protected com.atomikos.jms.extra.MessageConsumerSession createSession()
```
  - setClientID
```
public void setClientID(java.lang.String clientID)
```
    Sets the clientID for durable subscriptions. Optional.
    
    Parameters:
    
    clientID -
  - setAtomikosConnectionFactoryBean
```
public void setAtomikosConnectionFactoryBean(AtomikosConnectionFactoryBean bean)
```
    Sets the connection factory to use. Required.
    
    Parameters:
    
    bean -
  - getAtomikosConnectionFactoryBean
```
public AtomikosConnectionFactoryBean getAtomikosConnectionFactoryBean()
```
  - getDestination
```
public javax.jms.Destination getDestination()
```
    Gets the destination.
    
    Returns:
    
    The destination, or null if not set.
  - setDestination
```
public void setDestination(javax.jms.Destination dest)
```
    Sets the JMS destination to listen on (required unless the destinationName is set instead).
    
    Parameters:
    
    dest -
  - getDestinationName
```
public java.lang.String getDestinationName()
```
    Gets the destination name.
    
    Returns:
    
    The name, or null if not set.
  - setDestinationName
```
public void setDestinationName(java.lang.String destinationName)
```
    Sets the JMS provider-specific destination name (required unless the destination is set directly).
    
    Parameters:
    
    destinationName -
  - setDaemonThreads
```
public void setDaemonThreads(boolean value)
```
    Sets whether threads should be daemon threads or not (optional). Default is false.
    
    Parameters:
    
    value - If true then threads will be daemon threads.
  - getDaemonThreads
```
public boolean getDaemonThreads()
```
    Tests whether threads are daemon threads.
    
    Returns:
    
    True if threads are deamons.
  - getMessageListener
```
public javax.jms.MessageListener getMessageListener()
```
    Get the message listener if any.
    
    Returns:
  - getTransactionTimeout
```
public int getTransactionTimeout()
```
    Get the transaction timeout.
    
    Returns:
  - getUser
```
public java.lang.String getUser()
```
    Get the user for connecting, or null if the default user should be used.
    
    Returns:
  - setMessageListener
```
public void setMessageListener(javax.jms.MessageListener listener)
```
    Set the message listener to use (required). The same instance will be used for each session in the pool, meaning that instances need to be thread-safe. Only one listener is allowed at a time. Call this method with a null argument to unset the listener.
    
    Parameters:
    
    listener -
  - setPassword
```
public void setPassword(java.lang.String string)
```
    Set the password if explicit authentication is needed (optional). You need to set this if the user is also set.
    
    Parameters:
    
    string -
  - setTransactionTimeout
```
public void setTransactionTimeout(int seconds)
```
    Set the transaction timeout in seconds (optional).
    
    Parameters:
    
    seconds -
  - setUser
```
public void setUser(java.lang.String string)
```
    Set the user to use for explicit authentication (optional). Don't set this property if you want to use the default authentication.
    
    Parameters:
    
    string -
  - getMessageSelector
```
public java.lang.String getMessageSelector()
```
    Get the message selector (if any)
    
    Returns:
    
    The selector, or null if none.
  - setMessageSelector
```
public void setMessageSelector(java.lang.String selector)
```
    Set the message selector to use (optional).
    
    Parameters:
    
    selector -
  - getPoolSize
```
public int getPoolSize()
```
    Get the size of the pool.
    
    Returns:
  - setPoolSize
```
public void setPoolSize(int size)
```
    Sets the size of the session pool (optional). Default is 1.
    
    Parameters:
    
    size -
  - getExceptionListener
```
public javax.jms.ExceptionListener getExceptionListener()
```
    Gets the exception listener (if any).
    
    Returns:
    
    Null if no ExceptionListener was set.
  - setExceptionListener
```
public void setExceptionListener(javax.jms.ExceptionListener exceptionListener)
```
    Sets the exception listener (optional). The listener will be notified of connection-level JMS errors.
    
    Parameters:
    
    exceptionListener -
  - isNoLocal
```
public boolean isNoLocal()
```
    Test if this instance will receive sends from the same connection.
    
    Returns:
  - setNoLocal
```
public void setNoLocal(boolean noLocal)
```
    Sets whether or not this topic should receive sends from the same connection (optional).
    
    Parameters:
    
    noLocal -
  - getSubscriberName
```
public java.lang.String getSubscriberName()
```
    Gets the subscriber name (for durable subscribers).
    
    Returns:
    
    The name, or null if not set (no durable subscriber).
  - setSubscriberName
```
public void setSubscriberName(java.lang.String subscriberName)
```
    Sets the name to use for durable subscriptions (optional).
    Note: this name will be appended with a suffix to ensure uniqueness among instances in the pool. Otherwise, the JMS back-end would see multiple instances subscribing with the same name - an error.
    
    Parameters:
    
    subscriberName -
  - getNoLocal
```
protected boolean getNoLocal()
```
  - start
```
public void start()
           throws javax.jms.JMSException
```
    Start listening for messages.
    
    Throws:
    
    javax.jms.JMSException
  - stop
```
public void stop()
```
    Stop listening for messages. If notifyListenerOnClose is set then calling this method will notify the listener by calling its onMessage method with a null argument (and also without transaction context). This method will wait for all active receive operations to unblock, which may take up to receiveTimeout seconds per active thread.
  - getNotifyListenerOnClose
```
public boolean getNotifyListenerOnClose()
```
    Getter to check whether the listener is notified on close.
    
    Returns:
  - setNotifyListenerOnClose
```
public void setNotifyListenerOnClose(boolean b)
```
    Set whether the listener should be notified of close events on the pool (optional). Default is false.
    
    Parameters:
    
    b - If true, then the listener will receive a null message if the pool is closed.
  - setUnsubscribeOnClose
```
public void setUnsubscribeOnClose(boolean b)
```
    Sets whether unsubscribe should be done at closing time (optional). Default is false.
    
    Parameters:
    
    b - If true, then unsubscribe will be done at closing time. This only applies to durable subscribers (i.e., cases where subscriberName is set).
  - getUnsubscribeOnClose
```
public boolean getUnsubscribeOnClose()
```
    Getter to test if unsubscribe should be called on close.
  - getReceiveTimeout
```
public int getReceiveTimeout()
```
    Gets the receive timeout in seconds.
    
    Returns:
  - setReceiveTimeout
```
public void setReceiveTimeout(int seconds)
```
    Sets the receive timeout in seconds, i.e. the number of seconds to wait for incoming messages in the message listener thread's event loop. This property is optional and defaults to half the transactionTimeout, but typically this should be lower because the time required to shutdown (stop) this container will be bound by this value multiplied by the number of threads (as indicated by poolSize).
    
    Parameters:
    
    seconds -
  - close
```
public void close()
           throws java.lang.Exception
```
    Specified by:
    
    close in interface OrderedLifecycleComponent
    
    Throws:
    
    java.lang.Exception
  - init
```
public void init()
          throws java.lang.Exception
```
    Specified by:
    
    init in interface OrderedLifecycleComponent
    
    Throws:
    
    java.lang.Exception

Class MessageDrivenContainer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MessageDrivenContainer

Method Detail

createSession

setClientID

setAtomikosConnectionFactoryBean

getAtomikosConnectionFactoryBean

getDestination

setDestination

getDestinationName

setDestinationName

setDaemonThreads

getDaemonThreads

getMessageListener

getTransactionTimeout

getUser

setMessageListener

setPassword

setTransactionTimeout

setUser

getMessageSelector

setMessageSelector

getPoolSize

setPoolSize

getExceptionListener

setExceptionListener

isNoLocal

setNoLocal

getSubscriberName

setSubscriberName

getNoLocal

start

stop

getNotifyListenerOnClose

setNotifyListenerOnClose

setUnsubscribeOnClose

getUnsubscribeOnClose

getReceiveTimeout

setReceiveTimeout

close

init