org.springframework.jms.listener.adapter

## Class MessageListenerAdapter

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

- All Implemented Interfaces:
    MessageListener, SessionAwareMessageListener<Message>, SubscriptionNameProvider

      public class MessageListenerAdapter
      extends AbstractAdaptableMessageListener
      implements SubscriptionNameProvider

  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 of 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 `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 attendant 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)`, `AbstractAdaptableMessageListener.setDefaultResponseDestination(javax.jms.Destination)`, `AbstractAdaptableMessageListener.setMessageConverter(org.springframework.jms.support.converter.MessageConverter)`, `SimpleMessageConverter`, `SessionAwareMessageListener`, `AbstractMessageListenerContainer.setMessageListener(java.lang.Object)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `ORIGINAL_DEFAULT_LISTENER_METHOD` Out-of-the-box value for the default listener method: "handleMessage".

    - ### Fields inherited from class org.springframework.jms.listener.adapter.AbstractAdaptableMessageListener

      `logger`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object[]` | `buildListenerArguments(Object extractedMessage)` Build an array of arguments to be passed into the target listener method.
    `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 String` | `getListenerMethodName(Message originalMessage, Object extractedMessage)` Determine the name of the listener method that is supposed to handle the given message.
    `String` | `getSubscriptionName()` Determine the subscription name for this message listener object.
    `protected Object` | `invokeListenerMethod(String methodName, Object[] arguments)` Invoke the specified listener method.
    `void` | `onMessage(Message message, Session session)` Spring `SessionAwareMessageListener` 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` | `setDelegate(Object delegate)` Set a target object to delegate message listening to.

    - ### Methods inherited from class org.springframework.jms.listener.adapter.AbstractAdaptableMessageListener

      `buildMessage, extractMessage, getDestinationResolver, getMessageConverter, getMessagingMessageConverter, getResponseDestination, getResponseQosSettings, handleListenerException, handleResult, onMessage, postProcessProducer, postProcessResponse, preProcessResponse, resolveDefaultResponseDestination, sendResponse, setDefaultResponseDestination, setDefaultResponseQueueName, setDefaultResponseTopicName, setDestinationResolver, setHeaderMapper, setMessageConverter, setResponseQosSettings`

    - ### 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

  - ### 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.

    - #### onMessage

          public void onMessage(Message message,
                                @Nullable
                                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<Message>`
      Specified by:
        `onMessage` in class `AbstractAdaptableMessageListener`
      Parameters:
        `message` - the incoming JMS message
        `session` - the JMS session to operate on
      Throws:
        `JMSException` - if thrown by JMS API methods

    - #### getSubscriptionName

          public String getSubscriptionName()

      Description copied from interface: `SubscriptionNameProvider`
      Determine the subscription name for this message listener object.
      Specified by:
        `getSubscriptionName` in interface `SubscriptionNameProvider`

    - #### 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

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