@Target(value={TYPE,METHOD})
@Retention(value=RUNTIME)
@Documented
public @interface MessageMapping
Message
onto message-handling methods by matching
to the message destination. This annotation can also be used on the type-level in
which case it defines a common destination prefix or pattern for all method-level
annotations including method-level
@SubscribeMapping
annotations.
Handler methods which are annotated with this annotation are allowed to have flexible signatures. They may have arguments of the following types, in arbitrary order:
Message
to get access to the complete message being processed.Payload
-annotated method arguments to extract the payload of
a message and optionally convert it using a
MessageConverter
.
The presence of the annotation is not required since it is assumed by default
for method arguments that are not annotated. Payload method arguments annotated
with Validation annotations (like
Validated
) will be subject to
JSR-303 validation.Header
-annotated method arguments to extract a specific
header value along with type conversion with a
Converter
if necessary.Headers
-annotated argument that must also be assignable to
Map
for getting access to all headers.MessageHeaders
arguments for
getting access to all headers.MessageHeaderAccessor
or
with STOMP over WebSocket support also sub-classes such as
SimpMessageHeaderAccessor
for convenient access to all method arguments.DestinationVariable
-annotated arguments for access to template
variable values extracted from the message destination (e.g. /hotels/{hotel}).
Variable values will be converted to the declared method argument type.Principal
method arguments are supported with
STOMP over WebSocket messages. It reflects the user logged in to the
WebSocket session on which the message was received. Regular HTTP-based
authentication (e.g. Spring Security based) can be used to secure the
HTTP handshake that initiates WebSocket sessions.A return value will get wrapped as a message and sent to a default response
destination or to a custom destination specified with an @SendTo
method-level annotation. Such a response may also be provided asynchronously
via a ListenableFuture
return type
or a corresponding JDK 8 CompletableFuture
/
CompletionStage
handle.
An @SendTo
annotation is not strictly required — by default
the message will be sent to the same destination as the incoming message but with
an additional prefix ("/topic"
by default). It is also possible to use the
SendToUser
annotation to
have the message directed to a specific user if connected. The return value is
converted with a MessageConverter
.
NOTE: When using controller interfaces (e.g. for AOP proxying),
make sure to consistently put all your mapping annotations - such as
@MessageMapping
and @SubscribeMapping
- on
the controller interface rather than on the implementation class.
SimpAnnotationMethodMessageHandler
Modifier and Type | Optional Element and Description |
---|---|
java.lang.String[] |
value
Destination-based mapping expressed by this annotation.
|
public abstract java.lang.String[] value
For STOMP over WebSocket messages: this is the destination of the
STOMP message (e.g. "/positions"
). Ant-style path patterns
(e.g. "/price.stock.*"
) and path template variables (e.g.
"/price.stock.{ticker}"
) are also supported.