MessageHeaderAccessor (Spring Framework 5.1.14.RELEASE API)

java.lang.Object
- org.springframework.messaging.support.MessageHeaderAccessor

Direct Known Subclasses:: NativeMessageHeaderAccessor

public class MessageHeaderAccessor
extends Object

A base for classes providing strongly typed getters and setters as well as behavior around specific categories of headers (e.g. STOMP headers). Supports creating new headers, modifying existing headers (when still mutable), or copying and modifying existing headers.

The method getMessageHeaders() provides access to the underlying, fully-prepared MessageHeaders that can then be used as-is (i.e. without copying) to create a single message as follows:

 MessageHeaderAccessor accessor = new MessageHeaderAccessor();
 accessor.setHeader("foo", "bar");
 Message message = MessageBuilder.createMessage("payload", accessor.getMessageHeaders());

After the above, by default the MessageHeaderAccessor becomes immutable. However it is possible to leave it mutable for further initialization in the same thread, for example:

 MessageHeaderAccessor accessor = new MessageHeaderAccessor();
 accessor.setHeader("foo", "bar");
 accessor.setLeaveMutable(true);
 Message message = MessageBuilder.createMessage("payload", accessor.getMessageHeaders());

 // later on in the same thread...

 MessageHeaderAccessor accessor = MessageHeaderAccessor.getAccessor(message);
 accessor.setHeader("bar", "baz");
 accessor.setImmutable();

The method toMap() returns a copy of the underlying headers. It can be used to prepare multiple messages from the same MessageHeaderAccessor instance:

 MessageHeaderAccessor accessor = new MessageHeaderAccessor();
 MessageBuilder builder = MessageBuilder.withPayload("payload").setHeaders(accessor);

 accessor.setHeader("foo", "bar1");
 Message message1 = builder.build();

 accessor.setHeader("foo", "bar2");
 Message message2 = builder.build();

 accessor.setHeader("foo", "bar3");
 Message  message3 = builder.build();

However note that with the above style, the header accessor is shared and cannot be re-obtained later on. Alternatively it is also possible to create one MessageHeaderAccessor per message:

 MessageHeaderAccessor accessor1 = new MessageHeaderAccessor();
 accessor.set("foo", "bar1");
 Message message1 = MessageBuilder.createMessage("payload", accessor1.getMessageHeaders());

 MessageHeaderAccessor accessor2 = new MessageHeaderAccessor();
 accessor.set("foo", "bar2");
 Message message2 = MessageBuilder.createMessage("payload", accessor2.getMessageHeaders());

 MessageHeaderAccessor accessor3 = new MessageHeaderAccessor();
 accessor.set("foo", "bar3");
 Message message3 = MessageBuilder.createMessage("payload", accessor3.getMessageHeaders());

Note that the above examples aim to demonstrate the general idea of using header accessors. The most likely usage however is through subclasses.

Since:: 4.0
Author:: Rossen Stoyanchev, Juergen Hoeller

Field Summary

Fields
Modifier and Type Field and Description

static Charset DEFAULT_CHARSET
The default charset used for headers.

Fields
Modifier and Type	Field and Description
`static Charset`	`DEFAULT_CHARSET` The default charset used for headers.

Constructor Summary

Constructors
Constructor and Description
`MessageHeaderAccessor()` A constructor to create new headers.
`MessageHeaderAccessor(Message<?> message)` A constructor accepting the headers of an existing message to copy.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`copyHeaders(Map<String,?> headersToCopy)` Copy the name-value pairs from the provided Map.
`void`	`copyHeadersIfAbsent(Map<String,?> headersToCopy)` Copy the name-value pairs from the provided Map.
`protected MessageHeaderAccessor`	`createAccessor(Message<?> message)` Build a 'nested' accessor for the given message.
`static <T extends MessageHeaderAccessor> T`	`getAccessor(Message<?> message, Class<T> requiredType)` Return the original `MessageHeaderAccessor` used to create the headers of the given `Message`, or `null` if that's not available or if its type does not match the required type.
`static <T extends MessageHeaderAccessor> T`	`getAccessor(MessageHeaders messageHeaders, Class<T> requiredType)` A variation of `getAccessor(org.springframework.messaging.Message, Class)` with a `MessageHeaders` instance instead of a `Message`.
`MimeType`	`getContentType()`
`String`	`getDetailedLogMessage(Object payload)` Return a more detailed message for logging purposes.
`protected String`	`getDetailedPayloadLogMessage(Object payload)`
`Object`	`getErrorChannel()`
`Object`	`getHeader(String headerName)` Retrieve the value for the header with the given name.
`UUID`	`getId()`
`MessageHeaders`	`getMessageHeaders()` Return the underlying `MessageHeaders` instance.
`static MessageHeaderAccessor`	`getMutableAccessor(Message<?> message)` Return a mutable `MessageHeaderAccessor` for the given message attempting to match the type of accessor used to create the message headers, or otherwise wrapping the message with a `MessageHeaderAccessor` instance.
`Object`	`getReplyChannel()`
`String`	`getShortLogMessage(Object payload)` Return a concise message for logging purposes.
`protected String`	`getShortPayloadLogMessage(Object payload)`
`Long`	`getTimestamp()`
`boolean`	`isModified()` Check whether the underlying message headers have been marked as modified.
`boolean`	`isMutable()` Whether the underlying headers can still be modified.
`protected boolean`	`isReadableContentType()`
`protected boolean`	`isReadOnly(String headerName)`
`void`	`removeHeader(String headerName)` Remove the value for the given header name.
`void`	`removeHeaders(String... headerPatterns)` Removes all headers provided via array of 'headerPatterns'.
`void`	`setContentType(MimeType contentType)`
`void`	`setErrorChannel(MessageChannel errorChannel)`
`void`	`setErrorChannelName(String errorChannelName)`
`void`	`setHeader(String name, Object value)` Set the value for the given header name.
`void`	`setHeaderIfAbsent(String name, Object value)` Set the value for the given header name only if the header name is not already associated with a value.
`void`	`setImmutable()` By default when `getMessageHeaders()` is called, `"this"` `MessageHeaderAccessor` instance can no longer be used to modify the underlying message headers.
`void`	`setLeaveMutable(boolean leaveMutable)` By default when `getMessageHeaders()` is called, `"this"` `MessageHeaderAccessor` instance can no longer be used to modify the underlying message headers and the returned `MessageHeaders` is immutable.
`protected void`	`setModified(boolean modified)` Mark the underlying message headers as modified.
`void`	`setReplyChannel(MessageChannel replyChannel)`
`void`	`setReplyChannelName(String replyChannelName)`
`Map<String,Object>`	`toMap()` Return a copy of the underlying header values as a plain `Map` object.
`MessageHeaders`	`toMessageHeaders()` Return a copy of the underlying header values as a `MessageHeaders` object.
`String`	`toString()`
`protected void`	`verifyType(String headerName, Object headerValue)`

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

- Field Detail
  - DEFAULT_CHARSET
```
public static final Charset DEFAULT_CHARSET
```
    The default charset used for headers.
- Constructor Detail
  - MessageHeaderAccessor
```
public MessageHeaderAccessor()
```
    A constructor to create new headers.
  - MessageHeaderAccessor
```
public MessageHeaderAccessor(@Nullable
                             Message<?> message)
```
    A constructor accepting the headers of an existing message to copy.
    
    Parameters:
    
    message - a message to copy the headers from, or null if none
- Method Detail
  - createAccessor
```
protected MessageHeaderAccessor createAccessor(Message<?> message)
```
    Build a 'nested' accessor for the given message.
    
    Parameters:
    
    message - the message to build a new accessor for
    
    Returns:
    
    the nested accessor (typically a specific subclass)
  - setLeaveMutable
```
public void setLeaveMutable(boolean leaveMutable)
```
    By default when getMessageHeaders() is called, "this" MessageHeaderAccessor instance can no longer be used to modify the underlying message headers and the returned MessageHeaders is immutable.
    However when this is set to true, the returned (underlying) MessageHeaders instance remains mutable. To make further modifications continue to use the same accessor instance or re-obtain it via:
    MessageHeaderAccessor.getAccessor(Message, Class)
    When modifications are complete use setImmutable() to prevent further changes. The intended use case for this mechanism is initialization of a Message within a single thread.
    By default this is set to false.
    
    Since:
    
    4.1
  - setImmutable
```
public void setImmutable()
```
    By default when getMessageHeaders() is called, "this" MessageHeaderAccessor instance can no longer be used to modify the underlying message headers. However if setLeaveMutable(boolean) is used, this method is necessary to indicate explicitly when the MessageHeaders instance should no longer be modified.
    
    Since:
    
    4.1
  - isMutable
```
public boolean isMutable()
```
    Whether the underlying headers can still be modified.
    
    Since:
    
    4.1
  - setModified
```
protected void setModified(boolean modified)
```
    Mark the underlying message headers as modified.
    
    Parameters:
    
    modified - typically true, or false to reset the flag
    
    Since:
    
    4.1
  - isModified
```
public boolean isModified()
```
    Check whether the underlying message headers have been marked as modified.
    
    Returns:
    
    true if the flag has been set, false otherwise
  - getMessageHeaders
```
public MessageHeaders getMessageHeaders()
```
    Return the underlying MessageHeaders instance.
    Unless setLeaveMutable(boolean) was set to true, after this call, the headers are immutable and this accessor can no longer modify them.
    This method always returns the same MessageHeaders instance if invoked multiples times. To obtain a copy of the underlying headers, use toMessageHeaders() or toMap() instead.
    
    Since:
    
    4.1
  - toMessageHeaders
```
public MessageHeaders toMessageHeaders()
```
    Return a copy of the underlying header values as a MessageHeaders object.
    This method can be invoked many times, with modifications in between where each new call returns a fresh copy of the current header values.
    
    Since:
    
    4.1
  - toMap
```
public Map<String,Object> toMap()
```
    Return a copy of the underlying header values as a plain Map object.
    This method can be invoked many times, with modifications in between where each new call returns a fresh copy of the current header values.
  - getHeader
```
@Nullable
public Object getHeader(String headerName)
```
    Retrieve the value for the header with the given name.
    
    Parameters:
    
    headerName - the name of the header
    
    Returns:
    
    the associated value, or null if none found
  - setHeader
```
public void setHeader(String name,
                      @Nullable
                      Object value)
```
    Set the value for the given header name.
    If the provided value is null, the header will be removed.
  - verifyType
```
protected void verifyType(@Nullable
                          String headerName,
                          @Nullable
                          Object headerValue)
```
  - setHeaderIfAbsent
```
public void setHeaderIfAbsent(String name,
                              Object value)
```
    Set the value for the given header name only if the header name is not already associated with a value.
  - removeHeader
```
public void removeHeader(String headerName)
```
    Remove the value for the given header name.
  - removeHeaders
```
public void removeHeaders(String... headerPatterns)
```
    Removes all headers provided via array of 'headerPatterns'.
    As the name suggests, array may contain simple matching patterns for header names. Supported pattern styles are: "xxx*", "*xxx", "*xxx*" and "xxx*yyy".
  - copyHeaders
```
public void 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.
  - copyHeadersIfAbsent
```
public void copyHeadersIfAbsent(@Nullable
                                Map<String,?> headersToCopy)
```
    Copy the name-value pairs from the provided Map.
    This operation will not overwrite any existing values.
  - isReadOnly
```
protected boolean isReadOnly(String headerName)
```
  - getId
```
@Nullable
public UUID getId()
```
  - getTimestamp
```
@Nullable
public Long getTimestamp()
```
  - setContentType
```
public void setContentType(MimeType contentType)
```
  - getContentType
```
@Nullable
public MimeType getContentType()
```
  - setReplyChannelName
```
public void setReplyChannelName(String replyChannelName)
```
  - setReplyChannel
```
public void setReplyChannel(MessageChannel replyChannel)
```
  - getReplyChannel
```
@Nullable
public Object getReplyChannel()
```
  - setErrorChannelName
```
public void setErrorChannelName(String errorChannelName)
```
  - setErrorChannel
```
public void setErrorChannel(MessageChannel errorChannel)
```
  - getErrorChannel
```
@Nullable
public Object getErrorChannel()
```
  - getShortLogMessage
```
public String getShortLogMessage(Object payload)
```
    Return a concise message for logging purposes.
    
    Parameters:
    
    payload - the payload that corresponds to the headers.
    
    Returns:
    
    the message
  - getDetailedLogMessage
```
public String getDetailedLogMessage(@Nullable
                                    Object payload)
```
    Return a more detailed message for logging purposes.
    
    Parameters:
    
    payload - the payload that corresponds to the headers.
    
    Returns:
    
    the message
  - getShortPayloadLogMessage
```
protected String getShortPayloadLogMessage(Object payload)
```
  - getDetailedPayloadLogMessage
```
protected String getDetailedPayloadLogMessage(@Nullable
                                              Object payload)
```
  - isReadableContentType
```
protected boolean isReadableContentType()
```
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getAccessor
```
@Nullable
public static <T extends MessageHeaderAccessor> T getAccessor(Message<?> message,
                                                                        @Nullable
                                                                        Class<T> requiredType)
```
    Return the original MessageHeaderAccessor used to create the headers of the given Message, or null if that's not available or if its type does not match the required type.
    This is for cases where the existence of an accessor is strongly expected (followed up with an assertion) or where an accessor will be created otherwise.
    
    Parameters:
    
    message - the message to get an accessor for
    
    requiredType - the required accessor type (or null for any)
    
    Returns:
    
    an accessor instance of the specified type, or null if none
    
    Since:
    
    4.1
  - getAccessor
```
@Nullable
public static <T extends MessageHeaderAccessor> T getAccessor(MessageHeaders messageHeaders,
                                                                        @Nullable
                                                                        Class<T> requiredType)
```
    A variation of getAccessor(org.springframework.messaging.Message, Class) with a MessageHeaders instance instead of a Message.
    This is for cases when a full message may not have been created yet.
    
    Parameters:
    
    messageHeaders - the message headers to get an accessor for
    
    requiredType - the required accessor type (or null for any)
    
    Returns:
    
    an accessor instance of the specified type, or null if none
    
    Since:
    
    4.1
  - getMutableAccessor
```
public static MessageHeaderAccessor getMutableAccessor(Message<?> message)
```
    Return a mutable MessageHeaderAccessor for the given message attempting to match the type of accessor used to create the message headers, or otherwise wrapping the message with a MessageHeaderAccessor instance.
    This is for cases where a header needs to be updated in generic code while preserving the accessor type for downstream processing.
    
    Returns:
    
    an accessor of the required type (never null)
    
    Since:
    
    4.1

Class MessageHeaderAccessor

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CHARSET

Constructor Detail

MessageHeaderAccessor

MessageHeaderAccessor

Method Detail

createAccessor

setLeaveMutable

setImmutable

isMutable

setModified

isModified

getMessageHeaders

toMessageHeaders

toMap

getHeader

setHeader

verifyType

setHeaderIfAbsent

removeHeader

removeHeaders

copyHeaders

copyHeadersIfAbsent

isReadOnly

getId

getTimestamp

setContentType

getContentType

setReplyChannelName

setReplyChannel

getReplyChannel

setErrorChannelName

setErrorChannel

getErrorChannel

getShortLogMessage

getDetailedLogMessage

getShortPayloadLogMessage

getDetailedPayloadLogMessage

isReadableContentType

toString

getAccessor

getAccessor

getMutableAccessor