The Spring Framework

## org.springframework.jms.listener.adapter
Class MessageListenerAdapter

    java.lang.Object
      org.springframework.jms.listener.adapter.MessageListenerAdapter

All Implemented Interfaces:
  MessageListener, SessionAwareMessageListener

Direct Known Subclasses:
  MessageListenerAdapter102

    public class MessageListenerAdapter

extends Object
implements MessageListener, SessionAwareMessageListener

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.

NOTE: This class requires a JMS 1.1+ provider, because it builds on the domain-independent API. Use the `MessageListenerAdapter102` subclass for JMS 1.0.2 providers.

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` `(102)` 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 `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 `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 `TextMessages`. Notice how the return type of this method is `String`: This will result in the configured `MessageListenerAdapter` sending a `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.

Since:
  2.0
Author:
  Juergen Hoeller
See Also:
  `setDelegate(java.lang.Object)`, `setDefaultListenerMethod(java.lang.String)`, `setDefaultResponseDestination(javax.jms.Destination)`, `setMessageConverter(org.springframework.jms.support.converter.MessageConverter)`, `SimpleMessageConverter`, `SessionAwareMessageListener`, `AbstractMessageListenerContainer.setMessageListener(java.lang.Object)`

Field Summary
`protected Log` `logger` Logger available to subclasses
`static String` `ORIGINAL_DEFAULT_LISTENER_METHOD` Out-of-the-box value for the default listener method: "handleMessage".

Constructor Summary
`MessageListenerAdapter()` Create a new `MessageListenerAdapter` with default settings.
`MessageListenerAdapter(Object delegate)` Create a new `MessageListenerAdapter` for the given delegate.

Method Summary
`protected Object[]` `buildListenerArguments(Object extractedMessage)` Build an array of arguments to be passed into the target listener method.
`protected Message` `buildMessage(Session session, Object result)` Build a JMS message to be sent as response based on the given result object.
`protected Object` `extractMessage(Message message)` Extract the message body from the given JMS message.
`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.
`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.
`protected void` `handleListenerException(Throwable ex)` Handle the given exception that arose during listener execution.
`protected void` `handleResult(Object result, Message request, Session session)` Handle the given result object returned from the listener method, sending a response message back.
`protected void` `initDefaultStrategies()` Initialize the default implementations for the adapter's strategies.
`protected Object` `invokeListenerMethod(String methodName, Object[] arguments)` Invoke the specified listener method.
`void` `onMessage(Message message)` Standard JMS `MessageListener` entry point.
`void` `onMessage(Message message, Session session)` Spring `SessionAwareMessageListener` entry point.
`protected void` `postProcessProducer(MessageProducer producer, Message response)` Post-process the given message producer before using it to send the response.
`protected void` `postProcessResponse(Message request, Message response)` Post-process the given response message before it will be sent.
`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.
`protected void` `sendResponse(Session session, Destination destination, Message response)` Send the given response message to the given destination.
`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.

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

Field Detail

### ORIGINAL_DEFAULT_LISTENER_METHOD

    public static final String ORIGINAL_DEFAULT_LISTENER_METHOD

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

  See Also:
    Constant Field Values

### logger

    protected final Log logger

  Logger available to subclasses

Constructor Detail

### MessageListenerAdapter

    public MessageListenerAdapter()

  Create a new `MessageListenerAdapter` with default settings.

### MessageListenerAdapter

    public MessageListenerAdapter(Object delegate)

  Create a new `MessageListenerAdapter` for the given delegate.

  Parameters:
    `delegate` - the delegate object

Method Detail

### setDelegate

    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.

### getDelegate

    protected Object getDelegate()

  Return the target object to delegate message listening to.

### setDefaultListenerMethod

    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:
    `getListenerMethodName(javax.jms.Message, java.lang.Object)`

### getDefaultListenerMethod

    protected String getDefaultListenerMethod()

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

### setDefaultResponseDestination

    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:
    `setDefaultResponseQueueName(String)`, `setDefaultResponseTopicName(String)`, `getResponseDestination(javax.jms.Message, javax.jms.Message, javax.jms.Session)`

### setDefaultResponseQueueName

    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:
    `setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver)`, `setDefaultResponseDestination(javax.jms.Destination)`

### setDefaultResponseTopicName

    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:
    `setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver)`, `setDefaultResponseDestination(javax.jms.Destination)`

### setDestinationResolver

    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:
    `DynamicDestinationResolver`, `JndiDestinationResolver`

### getDestinationResolver

    protected DestinationResolver getDestinationResolver()

  Return the DestinationResolver for this adapter.

### setMessageConverter

    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 `BytesMessages`, `TextMessages` and `ObjectMessages`.

### getMessageConverter

    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.

### onMessage

    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.

  Specified by:
    `onMessage` in interface `MessageListener`
  Parameters:
    `message` - the incoming JMS message
  See Also:
    `handleListenerException(java.lang.Throwable)`, `onMessage(javax.jms.Message, javax.jms.Session)`

### onMessage

    public void onMessage(Message message,
                          Session session)
                   throws JMSException

  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.

  Specified by:
    `onMessage` in interface `SessionAwareMessageListener`
  Parameters:
    `message` - the incoming JMS message
    `session` - the JMS session to operate on
  Throws:
    `JMSException` - if thrown by JMS API methods

### initDefaultStrategies

    protected void initDefaultStrategies()

  Initialize the default implementations for the adapter's strategies.

  See Also:
    `setMessageConverter(org.springframework.jms.support.converter.MessageConverter)`, `SimpleMessageConverter`

### handleListenerException

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

### extractMessage

    protected Object extractMessage(Message message)
                             throws JMSException

  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:
    `JMSException` - if thrown by JMS API methods

### getListenerMethodName

    protected String getListenerMethodName(Message originalMessage,
                                           Object extractedMessage)
                                    throws JMSException

  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:
    `JMSException` - if thrown by JMS API methods
  See Also:
    `setDefaultListenerMethod(java.lang.String)`

### buildListenerArguments

    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)

### invokeListenerMethod

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

  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:
    `JMSException` - if thrown by JMS API methods
  See Also:
    `getListenerMethodName(javax.jms.Message, java.lang.Object)`, `buildListenerArguments(java.lang.Object)`

### handleResult

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

  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:
    `JMSException` - if thrown by JMS API methods
  See Also:
    `buildMessage(javax.jms.Session, java.lang.Object)`, `postProcessResponse(javax.jms.Message, javax.jms.Message)`, `getResponseDestination(javax.jms.Message, javax.jms.Message, javax.jms.Session)`, `sendResponse(javax.jms.Session, javax.jms.Destination, javax.jms.Message)`

### buildMessage

    protected Message buildMessage(Session session,
                                   Object result)
                            throws JMSException

  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:
    `JMSException` - if thrown by JMS API methods
  See Also:
    `setMessageConverter(org.springframework.jms.support.converter.MessageConverter)`

### postProcessResponse

    protected void postProcessResponse(Message request,
                                       Message response)
                                throws JMSException

  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:
    `JMSException` - if thrown by JMS API methods
  See Also:
    `Message.setJMSCorrelationID(java.lang.String)`

### getResponseDestination

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

  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:
    `JMSException` - if thrown by JMS API methods
    `InvalidDestinationException` - if no `Destination` can be determined
  See Also:
    `setDefaultResponseDestination(javax.jms.Destination)`, `Message.getJMSReplyTo()`

### resolveDefaultResponseDestination

    protected Destination resolveDefaultResponseDestination(Session session)
                                                     throws JMSException

  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:
    `JMSException` - if resolution failed
  See Also:
    `setDefaultResponseDestination(javax.jms.Destination)`, `setDefaultResponseQueueName(java.lang.String)`, `setDefaultResponseTopicName(java.lang.String)`, `setDestinationResolver(org.springframework.jms.support.destination.DestinationResolver)`

### sendResponse

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

  Send the given response message to the given destination.

  Parameters:
    `response` - the JMS message to send
    `destination` - the JMS destination to send to
    `session` - the JMS session to operate on
  Throws:
    `JMSException` - if thrown by JMS API methods
  See Also:
    `postProcessProducer(javax.jms.MessageProducer, javax.jms.Message)`, `Session.createProducer(javax.jms.Destination)`, `MessageProducer.send(javax.jms.Message)`

### postProcessProducer

    protected void postProcessProducer(MessageProducer producer,
                                       Message response)
                                throws JMSException

  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:
    `JMSException` - if thrown by JMS API methods

The Spring Framework

Copyright © 2002-2008 The Spring Framework.