org.springframework.messaging.simp

## Class SimpMessagingTemplate

- java.lang.Object
- - org.springframework.messaging.core.AbstractMessageSendingTemplate<String>
  - - org.springframework.messaging.simp.SimpMessagingTemplate

- All Implemented Interfaces:
    MessageSendingOperations<String>, SimpMessageSendingOperations

      public class SimpMessagingTemplate
      extends AbstractMessageSendingTemplate<String>
      implements SimpMessageSendingOperations

  An implementation of `SimpMessageSendingOperations`.

  Also provides methods for sending messages to a user. See `UserDestinationResolver` for more on user destinations.

  Since:
    4.0
  Author:
    Rossen Stoyanchev

- - ### Field Summary

    - ### Fields inherited from class org.springframework.messaging.core.AbstractMessageSendingTemplate

      `CONVERSION_HINT_HEADER, logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpMessagingTemplate(MessageChannel messageChannel)` Create a new `SimpMessagingTemplate` instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `convertAndSendToUser(String user, String destination, Object payload)` Send a message to the given user.
    `void` | `convertAndSendToUser(String user, String destination, Object payload, Map<String,Object> headers)` Send a message to the given user.
    `void` | `convertAndSendToUser(String user, String destination, Object payload, Map<String,Object> headers, MessagePostProcessor postProcessor)` Send a message to the given user.
    `void` | `convertAndSendToUser(String user, String destination, Object payload, MessagePostProcessor postProcessor)` Send a message to the given user.
    `protected void` | `doSend(String destination, Message<?> message)`
    `MessageHeaderInitializer` | `getHeaderInitializer()` Return the configured header initializer.
    `MessageChannel` | `getMessageChannel()` Return the configured message channel.
    `long` | `getSendTimeout()` Return the configured send timeout (in milliseconds).
    `String` | `getUserDestinationPrefix()` Return the configured user destination prefix.
    `protected Map<String,Object>` | `processHeadersToSend(Map<String,Object> headers)` Creates a new map and puts the given headers under the key `NATIVE_HEADERS NATIVE_HEADERS NATIVE_HEADERS`.
    `void` | `send(Message<?> message)` If the headers of the given message already contain a `SimpMessageHeaderAccessor#DESTINATION_HEADER` then the message is sent without further changes.
    `void` | `setHeaderInitializer(MessageHeaderInitializer headerInitializer)` Configure a `MessageHeaderInitializer` to apply to the headers of all messages created through the `SimpMessagingTemplate`.
    `void` | `setSendTimeout(long sendTimeout)` Specify the timeout value to use for send operations (in milliseconds).
    `void` | `setUserDestinationPrefix(String prefix)` Configure the prefix to use for destinations targeting a specific user.

    - ### Methods inherited from class org.springframework.messaging.core.AbstractMessageSendingTemplate

      `convertAndSend, convertAndSend, convertAndSend, convertAndSend, convertAndSend, convertAndSend, doConvert, getDefaultDestination, getMessageConverter, getRequiredDefaultDestination, send, setDefaultDestination, setMessageConverter`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.springframework.messaging.core.MessageSendingOperations

      `convertAndSend, convertAndSend, convertAndSend, convertAndSend, convertAndSend, convertAndSend, send`

- - ### Constructor Detail

    - #### SimpMessagingTemplate

          public SimpMessagingTemplate(MessageChannel messageChannel)

      Create a new `SimpMessagingTemplate` instance.
      Parameters:
        `messageChannel` - the message channel (never `null`)

  - ### Method Detail

    - #### getMessageChannel

          public MessageChannel getMessageChannel()

      Return the configured message channel.

    - #### setUserDestinationPrefix

          public void setUserDestinationPrefix(String prefix)

      Configure the prefix to use for destinations targeting a specific user.

      The default value is "/user/".

      See Also:
        `UserDestinationMessageHandler`

    - #### getUserDestinationPrefix

          public String getUserDestinationPrefix()

      Return the configured user destination prefix.

    - #### setSendTimeout

          public void setSendTimeout(long sendTimeout)

      Specify the timeout value to use for send operations (in milliseconds).

    - #### getSendTimeout

          public long getSendTimeout()

      Return the configured send timeout (in milliseconds).

    - #### setHeaderInitializer

          public void setHeaderInitializer(@Nullable
                                           MessageHeaderInitializer headerInitializer)

      Configure a `MessageHeaderInitializer` to apply to the headers of all messages created through the `SimpMessagingTemplate`.

      By default, this property is not set.

    - #### getHeaderInitializer

          @Nullable
          public MessageHeaderInitializer getHeaderInitializer()

      Return the configured header initializer.

    - #### send

          public void send(Message<?> message)

      If the headers of the given message already contain a `SimpMessageHeaderAccessor#DESTINATION_HEADER` then the message is sent without further changes.

      If a destination header is not already present ,the message is sent to the configured `defaultDestination` or an exception an `IllegalStateException` is raised if that isn't configured.

      Specified by:
        `send` in interface `MessageSendingOperations<String>`
      Overrides:
        `send` in class `AbstractMessageSendingTemplate<String>`
      Parameters:
        `message` - the message to send (never `null`)

    - #### doSend

          protected void doSend(String destination,
                                Message<?> message)

      Specified by:
        `doSend` in class `AbstractMessageSendingTemplate<String>`

    - #### convertAndSendToUser

          public void convertAndSendToUser(String user,
                                           String destination,
                                           Object payload)
                                    throws MessagingException

      Description copied from interface: `SimpMessageSendingOperations`
      Send a message to the given user.
      Specified by:
        `convertAndSendToUser` in interface `SimpMessageSendingOperations`
      Parameters:
        `user` - the user that should receive the message.
        `destination` - the destination to send the message to.
        `payload` - the payload to send
      Throws:
        `MessagingException`

    - #### convertAndSendToUser

          public void convertAndSendToUser(String user,
                                           String destination,
                                           Object payload,
                                           @Nullable
                                           Map<String,Object> headers)
                                    throws MessagingException

      Description copied from interface: `SimpMessageSendingOperations`
      Send a message to the given user.

      By default headers are interpreted as native headers (e.g. STOMP) and are saved under a special key in the resulting Spring `Message`. In effect when the message leaves the application, the provided headers are included with it and delivered to the destination (e.g. the STOMP client or broker).

      If the map already contains the key `"nativeHeaders"` or was prepared with `SimpMessageHeaderAccessor` then the headers are used directly. A common expected case is providing a content type (to influence the message conversion) and native headers. This may be done as follows:

           SimpMessageHeaderAccessor accessor = SimpMessageHeaderAccessor.create();
           accessor.setContentType(MimeTypeUtils.TEXT_PLAIN);
           accessor.setNativeHeader("foo", "bar");
           accessor.setLeaveMutable(true);
           MessageHeaders headers = accessor.getMessageHeaders();
           messagingTemplate.convertAndSendToUser(user, destination, payload, headers);

      Note: if the `MessageHeaders` are mutable as in the above example, implementations of this interface should take notice and update the headers in the same instance (rather than copy or re-create it) and then set it immutable before sending the final message.

      Specified by:
        `convertAndSendToUser` in interface `SimpMessageSendingOperations`
      Parameters:
        `user` - the user that should receive the message (must not be `null`)
        `destination` - the destination to send the message to (must not be `null`)
        `payload` - the payload to send (may be `null`)
        `headers` - the message headers (may be `null`)
      Throws:
        `MessagingException`

    - #### convertAndSendToUser

          public void convertAndSendToUser(String user,
                                           String destination,
                                           Object payload,
                                           @Nullable
                                           MessagePostProcessor postProcessor)
                                    throws MessagingException

      Description copied from interface: `SimpMessageSendingOperations`
      Send a message to the given user.
      Specified by:
        `convertAndSendToUser` in interface `SimpMessageSendingOperations`
      Parameters:
        `user` - the user that should receive the message (must not be `null`)
        `destination` - the destination to send the message to (must not be `null`)
        `payload` - the payload to send (may be `null`)
        `postProcessor` - a postProcessor to post-process or modify the created message
      Throws:
        `MessagingException`

    - #### convertAndSendToUser

          public void convertAndSendToUser(String user,
                                           String destination,
                                           Object payload,
                                           @Nullable
                                           Map<String,Object> headers,
                                           @Nullable
                                           MessagePostProcessor postProcessor)
                                    throws MessagingException

      Description copied from interface: `SimpMessageSendingOperations`
      Send a message to the given user.

      See `MessageSendingOperations.convertAndSend(Object, Object, java.util.Map)` for important notes regarding the input headers.

      Specified by:
        `convertAndSendToUser` in interface `SimpMessageSendingOperations`
      Parameters:
        `user` - the user that should receive the message
        `destination` - the destination to send the message to
        `payload` - the payload to send
        `headers` - the message headers
        `postProcessor` - a postProcessor to post-process or modify the created message
      Throws:
        `MessagingException`

    - #### processHeadersToSend

          protected Map<String,Object> processHeadersToSend(@Nullable
                                                            Map<String,Object> headers)

      Creates a new map and puts the given headers under the key `NATIVE_HEADERS NATIVE_HEADERS NATIVE_HEADERS`. effectively treats the input header map as headers to be sent out to the destination.

      However if the given headers already contain the key `NATIVE_HEADERS NATIVE_HEADERS` then the same headers instance is returned without changes.

      Also if the given headers were prepared and obtained with `MessageHeaderAccessor.getMessageHeaders()` then the same headers instance is also returned without changes.

      Overrides:
        `processHeadersToSend` in class `AbstractMessageSendingTemplate<String>`
      Parameters:
        `headers` - the headers to send (or `null` if none)
      Returns:
        the actual headers to send (or `null` if none)