org.springframework.messaging.support

## Class MessageBuilder<T>

- java.lang.Object
- - org.springframework.messaging.support.MessageBuilder<T>

- Type Parameters:
    `T` - the message payload type

      public final class MessageBuilder<T>
      extends Object

  A builder for creating a `GenericMessage` (or `ErrorMessage` if the payload is of type `Throwable`).
  Since:
    4.0
  Author:
    Arjen Poutsma, Mark Fisher, Rossen Stoyanchev
  See Also:
    `GenericMessage`, `ErrorMessage`

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Message<T>` | `build()`
    `MessageBuilder<T>` | `copyHeaders(Map<String,?> headersToCopy)` Copy the name-value pairs from the provided Map.
    `MessageBuilder<T>` | `copyHeadersIfAbsent(Map<String,?> headersToCopy)` Copy the name-value pairs from the provided Map.
    `static <T> Message<T>` | `createMessage(T payload, MessageHeaders messageHeaders)` A shortcut factory method for creating a message with the given payload and `MessageHeaders`.
    `static <T> MessageBuilder<T>` | `fromMessage(Message<T> message)` Create a builder for a new `Message` instance pre-populated with all the headers copied from the provided message.
    `MessageBuilder<T>` | `removeHeader(String headerName)` Remove the value for the given header name.
    `MessageBuilder<T>` | `removeHeaders(String... headerPatterns)` Removes all headers provided via array of 'headerPatterns'.
    `MessageBuilder<T>` | `setErrorChannel(MessageChannel errorChannel)`
    `MessageBuilder<T>` | `setErrorChannelName(String errorChannelName)`
    `MessageBuilder<T>` | `setHeader(String headerName, Object headerValue)` Set the value for the given header name.
    `MessageBuilder<T>` | `setHeaderIfAbsent(String headerName, Object headerValue)` Set the value for the given header name only if the header name is not already associated with a value.
    `MessageBuilder<T>` | `setHeaders(MessageHeaderAccessor accessor)` Set the message headers to use by providing a `MessageHeaderAccessor`.
    `MessageBuilder<T>` | `setReplyChannel(MessageChannel replyChannel)`
    `MessageBuilder<T>` | `setReplyChannelName(String replyChannelName)`
    `static <T> MessageBuilder<T>` | `withPayload(T payload)` Create a new builder for a message with the given payload.

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

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

- - ### Method Detail

    - #### setHeaders

          public MessageBuilder<T> setHeaders(MessageHeaderAccessor accessor)

      Set the message headers to use by providing a `MessageHeaderAccessor`.
      Parameters:
        `accessor` - the headers to use

    - #### setHeader

          public MessageBuilder<T> setHeader(String headerName,
                                             @Nullable
                                             Object headerValue)

      Set the value for the given header name. If the provided value is `null`, the header will be removed.

    - #### setHeaderIfAbsent

          public MessageBuilder<T> setHeaderIfAbsent(String headerName,
                                                     Object headerValue)

      Set the value for the given header name only if the header name is not already associated with a value.

    - #### removeHeaders

          public MessageBuilder<T> removeHeaders(String... headerPatterns)

      Removes all headers provided via array of 'headerPatterns'. As the name suggests the array may contain simple matching patterns for header names. Supported pattern styles are: "xxx*", "*xxx", "*xxx*" and "xxx*yyy".

    - #### removeHeader

          public MessageBuilder<T> removeHeader(String headerName)

      Remove the value for the given header name.

    - #### copyHeaders

          public MessageBuilder<T> copyHeaders(@Nullable
                                               Map<String,?> headersToCopy)

      Copy the name-value pairs from the provided Map. This operation will overwrite any existing values. Use `copyHeadersIfAbsent(Map)` to avoid overwriting values. Note that the 'id' and 'timestamp' header values will never be overwritten.

    - #### copyHeadersIfAbsent

          public MessageBuilder<T> copyHeadersIfAbsent(@Nullable
                                                       Map<String,?> headersToCopy)

      Copy the name-value pairs from the provided Map. This operation will not overwrite any existing values.

    - #### setReplyChannel

          public MessageBuilder<T> setReplyChannel(MessageChannel replyChannel)

    - #### setReplyChannelName

          public MessageBuilder<T> setReplyChannelName(String replyChannelName)

    - #### setErrorChannel

          public MessageBuilder<T> setErrorChannel(MessageChannel errorChannel)

    - #### setErrorChannelName

          public MessageBuilder<T> setErrorChannelName(String errorChannelName)

    - #### build

          public Message<T> build()

    - #### fromMessage

          public static <T> MessageBuilder<T> fromMessage(Message<T> message)

      Create a builder for a new `Message` instance pre-populated with all the headers copied from the provided message. The payload of the provided Message will also be used as the payload for the new message.

      If the provided message is an `ErrorMessage`, the `originalMessage` it contains, will be passed on to new instance.

      Parameters:
        `message` - the Message from which the payload and all headers will be copied

    - #### withPayload

          public static <T> MessageBuilder<T> withPayload(T payload)

      Create a new builder for a message with the given payload.
      Parameters:
        `payload` - the payload

    - #### createMessage

          public static <T> Message<T> createMessage(T payload,
                                                     MessageHeaders messageHeaders)

      A shortcut factory method for creating a message with the given payload and `MessageHeaders`.

      Note: the given `MessageHeaders` instance is used directly in the new message, i.e. it is not copied.

      Parameters:
        `payload` - the payload to use (never `null`)
        `messageHeaders` - the headers to use (never `null`)
      Returns:
        the created message
      Since:
        4.1