public class

MessageListenerAdapter

extends Object
implements SessionAwareMessageListener<M extends Message> SubscriptionNameProvider
java.lang.Object
   ↳ org.springframework.jms.listener.adapter.MessageListenerAdapter
Known Direct Subclasses

Class Overview

Message listener adapter that delegates the handling of messages to target listener methods via reflection, with flexible message type conversion. Allows listener methods to operate on message content types, completely independent from the JMS API.

By default, the content of incoming JMS messages gets extracted before being passed into the target listener method, to let the target method operate on message content types such as String or byte array instead of the raw Message. Message type conversion is delegated to a Spring JMS MessageConverter. By default, a SimpleMessageConverter will be used. (If you do not want such automatic message conversion taking place, then be sure to set the MessageConverter to null.)

If a target listener method returns a non-null object (typically of a message content type such as String or byte array), it will get wrapped in a JMS Message and sent to the response destination (either the JMS "reply-to" destination or a #setDefaultResponseDestination(javax.jms.Destination) specified default destination).

Note: The sending of response messages is only available when using the SessionAwareMessageListener entry point (typically through a Spring message listener container). Usage as standard JMS MessageListener does not support the generation of response messages.

Find below some examples of method signatures compliant with this adapter class. This first example handles all Message types and gets passed the contents of each Message type as an argument. No Message will be sent back as all of these methods return void. 

public interface MessageContentsDelegate {
    void handleMessage(String text);
    void handleMessage(Map map);
    void handleMessage(byte[] bytes);
    void handleMessage(Serializable obj);
 }
This next example handles all Message types and gets passed the actual (raw) Message as an argument. Again, no Message will be sent back as all of these methods return void. 
public interface RawMessageDelegate {
    void handleMessage(TextMessage message);
    void handleMessage(MapMessage message);
    void handleMessage(BytesMessage message);
    void handleMessage(ObjectMessage message);
 }
This next example illustrates a Message delegate that just consumes the String contents of javax.jms.TextMessage TextMessages. Notice also how the name of the Message handling method is different from the original (this will have to be configured in the attandant bean definition). Again, no Message will be sent back as the method returns void. 
public interface TextMessageContentDelegate {
    void onMessage(String text);
 }
This final example illustrates a Message delegate that just consumes the String contents of javax.jms.TextMessage TextMessages. Notice how the return type of this method is String: This will result in the configured MessageListenerAdapter sending a javax.jms.TextMessage in response. 
public interface ResponsiveTextMessageContentDelegate {
    String handleMessage(String text);
 }
For further examples and discussion please do refer to the Spring reference documentation which describes this class (and it's attendant XML configuration) in detail.

See Also

Summary

Constants
String ORIGINAL_DEFAULT_LISTENER_METHOD Out-of-the-box value for the default listener method: "handleMessage".
Fields
protected final Log logger Logger available to subclasses
Public Constructors
MessageListenerAdapter()
Create a new MessageListenerAdapter with default settings.
MessageListenerAdapter(Object delegate)
Create a new MessageListenerAdapter for the given delegate.
Public Methods
String getSubscriptionName()
Determine the subscription name for this message listener object.
void onMessage(Message message, Session session)
Spring SessionAwareMessageListener entry point.
void onMessage(Message message)
Standard JMS MessageListener entry point.
void setDefaultListenerMethod(String defaultListenerMethod)
Specify the name of the default listener method to delegate to, for the case where no specific listener method has been determined.
void setDefaultResponseDestination(Destination destination)
Set the default destination to send response messages to.
void setDefaultResponseQueueName(String destinationName)
Set the name of the default response queue to send response messages to.
void setDefaultResponseTopicName(String destinationName)
Set the name of the default response topic to send response messages to.
void setDelegate(Object delegate)
Set a target object to delegate message listening to.
void setDestinationResolver(DestinationResolver destinationResolver)
Set the DestinationResolver that should be used to resolve response destination names for this adapter.
void setMessageConverter(MessageConverter messageConverter)
Set the converter that will convert incoming JMS messages to listener method arguments, and objects returned from listener methods back to JMS messages.
Protected Methods
Object[] buildListenerArguments(Object extractedMessage)
Build an array of arguments to be passed into the target listener method.
Message buildMessage(Session session, Object result)
Build a JMS message to be sent as response based on the given result object.
Object extractMessage(Message message)
Extract the message body from the given JMS message.
String getDefaultListenerMethod()
Return the name of the default listener method to delegate to.
Object getDelegate()
Return the target object to delegate message listening to.
DestinationResolver getDestinationResolver()
Return the DestinationResolver for this adapter.
String getListenerMethodName(Message originalMessage, Object extractedMessage)
Determine the name of the listener method that is supposed to handle the given message.
MessageConverter getMessageConverter()
Return the converter that will convert incoming JMS messages to listener method arguments, and objects returned from listener methods back to JMS messages.
Destination getResponseDestination(Message request, Message response, Session session)
Determine a response destination for the given message.
void handleListenerException(Throwable ex)
Handle the given exception that arose during listener execution.
void handleResult(Object result, Message request, Session session)
Handle the given result object returned from the listener method, sending a response message back.
void initDefaultStrategies()
Initialize the default implementations for the adapter's strategies.
Object invokeListenerMethod(String methodName, Object[] arguments)
Invoke the specified listener method.
void postProcessProducer(MessageProducer producer, Message response)
Post-process the given message producer before using it to send the response.
void postProcessResponse(Message request, Message response)
Post-process the given response message before it will be sent.
Destination resolveDefaultResponseDestination(Session session)
Resolve the default response destination into a JMS Destination, using this accessor's DestinationResolver in case of a destination name.
void sendResponse(Session session, Destination destination, Message response)
Send the given response message to the given destination.
[Expand]
Inherited Methods
From class java.lang.Object
From interface org.springframework.jms.listener.SessionAwareMessageListener
From interface org.springframework.jms.listener.SubscriptionNameProvider

Constants

public static final String ORIGINAL_DEFAULT_LISTENER_METHOD

Out-of-the-box value for the default listener method: "handleMessage".

Constant Value: "handleMessage"

Fields

protected final Log logger

Logger available to subclasses

Public Constructors

public MessageListenerAdapter ()

Create a new MessageListenerAdapter with default settings.

public MessageListenerAdapter (Object delegate)

Create a new MessageListenerAdapter for the given delegate.

Parameters
delegate the delegate object

Public Methods

public String getSubscriptionName ()

Determine the subscription name for this message listener object.

public void onMessage (Message message, Session session)

Spring SessionAwareMessageListener entry point.

Delegates the message to the target listener method, with appropriate conversion of the message argument. If the target method returns a non-null object, wrap in a JMS message and send it back.

Parameters
message the incoming JMS message
session the JMS session to operate on
Throws
if thrown by JMS API methods
JMSException

public void onMessage (Message message)

Standard JMS MessageListener entry point.

Delegates the message to the target listener method, with appropriate conversion of the message argument. In case of an exception, the handleListenerException(Throwable) method will be invoked.

Note: Does not support sending response messages based on result objects returned from listener methods. Use the SessionAwareMessageListener entry point (typically through a Spring message listener container) for handling result objects as well.

Parameters
message the incoming JMS message
See Also

public void setDefaultListenerMethod (String defaultListenerMethod)

Specify the name of the default listener method to delegate to, for the case where no specific listener method has been determined. Out-of-the-box value is "handleMessage".

See Also

public void setDefaultResponseDestination (Destination destination)

Set the default destination to send response messages to. This will be applied in case of a request message that does not carry a "JMSReplyTo" field.

Response destinations are only relevant for listener methods that return result objects, which will be wrapped in a response message and sent to a response destination.

Alternatively, specify a "defaultResponseQueueName" or "defaultResponseTopicName", to be dynamically resolved via the DestinationResolver.

See Also

public void setDefaultResponseQueueName (String destinationName)

Set the name of the default response queue to send response messages to. This will be applied in case of a request message that does not carry a "JMSReplyTo" field.

Alternatively, specify a JMS Destination object as "defaultResponseDestination".

See Also

public void setDefaultResponseTopicName (String destinationName)

Set the name of the default response topic to send response messages to. This will be applied in case of a request message that does not carry a "JMSReplyTo" field.

Alternatively, specify a JMS Destination object as "defaultResponseDestination".

See Also

public void setDelegate (Object delegate)

Set a target object to delegate message listening to. Specified listener methods have to be present on this target object.

If no explicit delegate object has been specified, listener methods are expected to present on this adapter instance, that is, on a custom subclass of this adapter, defining listener methods.

public void setDestinationResolver (DestinationResolver destinationResolver)

Set the DestinationResolver that should be used to resolve response destination names for this adapter.

The default resolver is a DynamicDestinationResolver. Specify a JndiDestinationResolver for resolving destination names as JNDI locations.

See Also

public void setMessageConverter (MessageConverter messageConverter)

Set the converter that will convert incoming JMS messages to listener method arguments, and objects returned from listener methods back to JMS messages.

The default converter is a SimpleMessageConverter, which is able to handle javax.jms.BytesMessage BytesMessages, javax.jms.TextMessage TextMessages and javax.jms.ObjectMessage ObjectMessages.

Protected Methods

protected Object[] buildListenerArguments (Object extractedMessage)

Build an array of arguments to be passed into the target listener method. Allows for multiple method arguments to be built from a single message object.

The default implementation builds an array with the given message object as sole element. This means that the extracted message will always be passed into a single method argument, even if it is an array, with the target method having a corresponding single argument of the array's type declared.

This can be overridden to treat special message content such as arrays differently, for example passing in each element of the message array as distinct method argument.

Parameters
extractedMessage the content of the message
Returns
  • the array of arguments to be passed into the listener method (each element of the array corresponding to a distinct method argument)

protected Message buildMessage (Session session, Object result)

Build a JMS message to be sent as response based on the given result object.

Parameters
session the JMS Session to operate on
result the content of the message, as returned from the listener method
Returns
  • the JMS Message (never null)
Throws
if thrown by JMS API methods
JMSException
See Also

protected Object extractMessage (Message message)

Extract the message body from the given JMS message.

Parameters
message the JMS Message
Returns
  • the content of the message, to be passed into the listener method as argument
Throws
if thrown by JMS API methods
JMSException

protected String getDefaultListenerMethod ()

Return the name of the default listener method to delegate to.

protected Object getDelegate ()

Return the target object to delegate message listening to.

protected DestinationResolver getDestinationResolver ()

Return the DestinationResolver for this adapter.

protected String getListenerMethodName (Message originalMessage, Object extractedMessage)

Determine the name of the listener method that is supposed to handle the given message.

The default implementation simply returns the configured default listener method, if any.

Parameters
originalMessage the JMS request message
extractedMessage the converted JMS request message, to be passed into the listener method as argument
Returns
  • the name of the listener method (never null)
Throws
if thrown by JMS API methods
JMSException
See Also

protected MessageConverter getMessageConverter ()

Return the converter that will convert incoming JMS messages to listener method arguments, and objects returned from listener methods back to JMS messages.

protected Destination getResponseDestination (Message request, Message response, Session session)

Determine a response destination for the given message.

The default implementation first checks the JMS Reply-To Destination of the supplied request; if that is not null it is returned; if it is null, then the configured default response destination is returned; if this too is null, then an InvalidDestinationException is thrown.

Parameters
request the original incoming JMS message
response the outgoing JMS message about to be sent
session the JMS Session to operate on
Returns
  • the response destination (never null)
Throws
if thrown by JMS API methods
if no Destination can be determined
JMSException
See Also

protected void handleListenerException (Throwable ex)

Handle the given exception that arose during listener execution. The default implementation logs the exception at error level.

This method only applies when used as standard JMS MessageListener. In case of the Spring SessionAwareMessageListener mechanism, exceptions get handled by the caller instead.

Parameters
ex the exception to handle
See Also
  • #onMessage(javax.jms.Message)

protected void handleResult (Object result, Message request, Session session)

Handle the given result object returned from the listener method, sending a response message back.

Parameters
result the result object to handle (never null)
request the original request message
session the JMS Session to operate on (may be null)
Throws
if thrown by JMS API methods
JMSException
See Also

protected void initDefaultStrategies ()

Initialize the default implementations for the adapter's strategies.

See Also

protected Object invokeListenerMethod (String methodName, Object[] arguments)

Invoke the specified listener method.

Parameters
methodName the name of the listener method
arguments the message arguments to be passed in
Returns
  • the result returned from the listener method
Throws
if thrown by JMS API methods
JMSException
See Also

protected void postProcessProducer (MessageProducer producer, Message response)

Post-process the given message producer before using it to send the response.

The default implementation is empty.

Parameters
producer the JMS message producer that will be used to send the message
response the outgoing JMS message about to be sent
Throws
if thrown by JMS API methods
JMSException

protected void postProcessResponse (Message request, Message response)

Post-process the given response message before it will be sent.

The default implementation sets the response's correlation id to the request message's correlation id, if any; otherwise to the request message id.

Parameters
request the original incoming JMS message
response the outgoing JMS message about to be sent
Throws
if thrown by JMS API methods
JMSException
See Also
  • javax.jms.Message#setJMSCorrelationID

protected Destination resolveDefaultResponseDestination (Session session)

Resolve the default response destination into a JMS Destination, using this accessor's DestinationResolver in case of a destination name.

Returns
  • the located Destination
Throws
if resolution failed
JMSException
See Also

protected void sendResponse (Session session, Destination destination, Message response)

Send the given response message to the given destination.

Parameters
session the JMS session to operate on
destination the JMS destination to send to
response the JMS message to send
Throws
if thrown by JMS API methods
JMSException
See Also