MessageHeaderAccessor

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 {@link #getMessageHeaders()} provides access to the underlying, fully-prepared {@link MessageHeaders} that can then be used as-is (i.e. without copying) to create a single message as follows:

<pre class="code"> MessageHeaderAccessor accessor = new MessageHeaderAccessor(); accessor.setHeader("foo", "bar"); Message message = MessageHelper.createMessage("payload", accessor.getMessageHeaders()); </pre>

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

<pre class="code"> MessageHeaderAccessor accessor = new MessageHeaderAccessor(); accessor.setHeader("foo", "bar"); accessor.setLeaveMutable(true); Message message = MessageHelper.createMessage("payload", accessor.getMessageHeaders());

// later on in the same thread...

MessageHeaderAccessor accessor = MessageHeaderAccessor.getAccessor(message); accessor.setHeader("bar", "baz"); accessor.setImmutable(); </pre>

The method {@link #toMap()} returns a copy of the underlying headers. It can be used to prepare multiple messages from the same {@code MessageHeaderAccessor} instance: <pre class="code"> 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(); </pre>

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 {@code MessageHeaderAccessor} per message:

<pre class="code"> MessageHeaderAccessor accessor1 = new MessageHeaderAccessor(); accessor.set("foo", "bar1"); Message message1 = MessageHelper.createMessage("payload", accessor1.getMessageHeaders());

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

MessageHeaderAccessor accessor3 = new MessageHeaderAccessor(); accessor.set("foo", "bar3"); Message message3 = MessageHelper.createMessage("payload", accessor3.getMessageHeaders()); </pre>

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

@author Rossen Stoyanchev @author Juergen Hoeller @since 4.0

class MessageHeaderAccessor {

enum Charset DEFAULT_CHARSET;

this();

this(MessageBase message);

MessageHeaderAccessor createAccessor(MessageBase message);

void setLeaveMutable(bool leaveMutable);

void setImmutable();

bool isMutable();

void setModified(bool modified);

bool isModified();

void setEnableTimestamp(bool enableTimestamp);

void setIdGenerator(IdGenerator idGenerator);

MessageHeaders getMessageHeaders();

MessageHeaders toMessageHeaders();

Map!(string, Object) toMap();

Object getHeader(string headerName);

T getHeaderAs(string headerName);

void setHeader(string name, T value);

void setHeader(string name, Object value);

void verifyType(string headerName, Object headerValue);

void setHeaderIfAbsent(string name, Object value);

void removeHeader(string headerName);

void removeHeaders(string[] headerPatterns);

void copyHeaders(Map!(string, Object) headersToCopy);

void copyHeadersIfAbsent(Map!(string, Object) headersToCopy);

bool isReadOnly(string headerName);

UUID getId();

Long getTimestamp();

void setContentType(MimeType contentType);

MimeType getContentType();

void setReplyChannelName(string replyChannelName);

void setReplyChannel(MessageChannel replyChannel);

Object getReplyChannel();

void setErrorChannelName(string errorChannelName);

void setErrorChannel(MessageChannel errorChannel);

Object getErrorChannel();

string getShortLogMessage(Object payload);

string getDetailedLogMessage(Object payload);

string getShortPayloadLogMessage(Object payload);

string getDetailedPayloadLogMessage(Object payload);

bool isReadableContentType();

string toString();

static T getAccessor(MessageBase message);

static T getAccessor(MessageHeaders messageHeaders);

static MessageHeaderAccessor getMutableAccessor(MessageBase message);

}

Constructors

this this(): A constructor to create new headers.
this this(MessageBase message): A constructor accepting the headers of an existing message to copy. @param message a message to copy the headers from, or {@code null} if none

Members

Functions

copyHeaders void copyHeaders(Map!(string, Object) headersToCopy): Copy the name-value pairs from the provided Map. This operation will overwrite any existing values. Use {@link #copyHeadersIfAbsent(Map)} to avoid overwriting values.
copyHeadersIfAbsent void copyHeadersIfAbsent(Map!(string, Object) headersToCopy): Copy the name-value pairs from the provided Map. This operation will not overwrite any existing values.
createAccessor MessageHeaderAccessor createAccessor(MessageBase message): Build a 'nested' accessor for the given message. @param message the message to build a new accessor for @return the nested accessor (typically a specific subclass)
getContentType MimeType getContentType(): Undocumented in source. Be warned that the author may not have intended to support it.
getDetailedLogMessage string getDetailedLogMessage(Object payload): Return a more detailed message for logging purposes. @param payload the payload that corresponds to the headers. @return the message
getDetailedPayloadLogMessage string getDetailedPayloadLogMessage(Object payload): Undocumented in source. Be warned that the author may not have intended to support it.
getErrorChannel Object getErrorChannel(): Undocumented in source. Be warned that the author may not have intended to support it.
getHeader Object getHeader(string headerName): Retrieve the value for the header with the given name. @param headerName the name of the header @return the associated value, or {@code null} if none found
getHeaderAs T getHeaderAs(string headerName): Undocumented in source. Be warned that the author may not have intended to support it.
getId UUID getId(): Undocumented in source. Be warned that the author may not have intended to support it.
getMessageHeaders MessageHeaders getMessageHeaders(): Return the underlying {@code MessageHeaders} instance. Unless {@link #setLeaveMutable()} was set to {@code true}, after this call, the headers are immutable and this accessor can no longer modify them. This method always returns the same {@code MessageHeaders} instance if invoked multiples times. To obtain a copy of the underlying headers, use {@link #toMessageHeaders()} or {@link #toMap()} instead. @since 4.1
getReplyChannel Object getReplyChannel(): Undocumented in source. Be warned that the author may not have intended to support it.
getShortLogMessage string getShortLogMessage(Object payload): Return a concise message for logging purposes. @param payload the payload that corresponds to the headers. @return the message
getShortPayloadLogMessage string getShortPayloadLogMessage(Object payload): Undocumented in source. Be warned that the author may not have intended to support it.
getTimestamp Long getTimestamp(): Undocumented in source. Be warned that the author may not have intended to support it.
isModified bool isModified(): Check whether the underlying message headers have been marked as modified. @return {@code true} if the flag has been set, {@code false} otherwise
isMutable bool isMutable(): Whether the underlying headers can still be modified. @since 4.1
isReadOnly bool isReadOnly(string headerName): Undocumented in source. Be warned that the author may not have intended to support it.
isReadableContentType bool isReadableContentType(): Undocumented in source. Be warned that the author may not have intended to support it.
removeHeader void removeHeader(string headerName): Remove the value for the given header name.
removeHeaders 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".
setContentType void setContentType(MimeType contentType): Undocumented in source. Be warned that the author may not have intended to support it.
setEnableTimestamp void setEnableTimestamp(bool enableTimestamp): A package private mechanism to enables the automatic addition of the {@link hunt.stomp.MessageHeaders#TIMESTAMP} header. By default, this property is set to {@code false}. @see IdTimestampMessageHeaderInitializer
setErrorChannel void setErrorChannel(MessageChannel errorChannel): Undocumented in source. Be warned that the author may not have intended to support it.
setErrorChannelName void setErrorChannelName(string errorChannelName): Undocumented in source. Be warned that the author may not have intended to support it.
setHeader void setHeader(string name, T value): Undocumented in source. Be warned that the author may not have intended to support it.
setHeader void setHeader(string name, Object value): Set the value for the given header name. If the provided value is {@code null}, the header will be removed.
setHeaderIfAbsent 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.
setIdGenerator void setIdGenerator(IdGenerator idGenerator): A package-private mechanism to configure the IdGenerator strategy to use. By default this property is not set in which case the default IdGenerator in {@link hunt.stomp.MessageHeaders} is used. @see IdTimestampMessageHeaderInitializer
setImmutable void setImmutable(): By default when {@link #getMessageHeaders()} is called, {@code "this"} {@code MessageHeaderAccessor} instance can no longer be used to modify the underlying message headers. However if {@link #setLeaveMutable()} is used, this method is necessary to indicate explicitly when the {@code MessageHeaders} instance should no longer be modified. @since 4.1
setLeaveMutable void setLeaveMutable(bool leaveMutable): By default when {@link #getMessageHeaders()} is called, {@code "this"} {@code MessageHeaderAccessor} instance can no longer be used to modify the underlying message headers and the returned {@code MessageHeaders} is immutable. However when this is set to {@code true}, the returned (underlying) {@code MessageHeaders} instance remains mutable. To make further modifications continue to use the same accessor instance or re-obtain it via: {@link MessageHeaderAccessor#getAccessor(Message, Class) MessageHeaderAccessor.getAccessor(Message, Class)} When modifications are complete use {@link #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 {@code false}. @since 4.1
setModified void setModified(bool modified): Mark the underlying message headers as modified. @param modified typically {@code true}, or {@code false} to reset the flag @since 4.1
setReplyChannel void setReplyChannel(MessageChannel replyChannel): Undocumented in source. Be warned that the author may not have intended to support it.
setReplyChannelName void setReplyChannelName(string replyChannelName): Undocumented in source. Be warned that the author may not have intended to support it.
toMap Map!(string, Object) toMap(): Return a copy of the underlying header values as a plain {@link 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.
toMessageHeaders MessageHeaders toMessageHeaders(): Return a copy of the underlying header values as a {@link 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
toString string toString(): Undocumented in source. Be warned that the author may not have intended to support it.
verifyType void verifyType(string headerName, Object headerValue): Undocumented in source. Be warned that the author may not have intended to support it.

Static functions

getAccessor T getAccessor(MessageBase message): Return the original {@code MessageHeaderAccessor} used to create the headers of the given {@code Message}, or {@code 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. @param message the message to get an accessor for @param requiredType the required accessor type (or {@code null} for any) @return an accessor instance of the specified type, or {@code null} if none @since 4.1
getAccessor T getAccessor(MessageHeaders messageHeaders): A variation of {@link #getAccessor(hunt.stomp.Message, Class)} with a {@code MessageHeaders} instance instead of a {@code Message}. This is for cases when a full message may not have been created yet. @param messageHeaders the message headers to get an accessor for @param requiredType the required accessor type (or {@code null} for any) @return an accessor instance of the specified type, or {@code null} if none @since 4.1
getMutableAccessor MessageHeaderAccessor getMutableAccessor(MessageBase message): Return a mutable {@code 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 {@code MessageHeaderAccessor} instance. This is for cases where a header needs to be updated in generic code while preserving the accessor type for downstream processing. @return an accessor of the required type (never {@code null}) @since 4.1

Variables

DEFAULT_CHARSET enum Charset DEFAULT_CHARSET;: The default charset used for headers.