com.atomikos.jms.extra

Class MessageDrivenContainer

java.lang.Object

com.atomikos.jms.extra.MessageDrivenContainer

public class MessageDrivenContainer
extends Object

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()

Method Summary

Methods

Modifier and Type	Method and Description
AtomikosConnectionFactoryBean	getAtomikosConnectionFactoryBean()
boolean	getDaemonThreads() Tests whether threads are daemon threads.
javax.jms.Destination	getDestination() Gets the destination.
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.
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.
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.
String	getUser() Get the user for connecting, or null if the default user should be used.
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(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(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(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(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(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(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

setClientID

public void setClientID(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 String getDestinationName()

Gets the destination name.

Returns:

The name, or null if not set.

setDestinationName

public void setDestinationName(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 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(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(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 String getMessageSelector()

Get the message selector (if any)

Returns:

The selector, or null if none.

setMessageSelector

public void setMessageSelector(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 String getSubscriberName()

Gets the subscriber name (for durable subscribers).

Returns:

The name, or null if not set (no durable subscriber).

setSubscriberName

public void setSubscriberName(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 -