org.springframework.messaging.handler.annotation

Annotation Type MessageMapping

@Target(value={TYPE,METHOD})
 @Retention(value=RUNTIME)
 @Documented
public @interface MessageMapping

Annotation for mapping a 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.

STOMP over WebSocket

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.

Since:

4.0

Author:

Rossen Stoyanchev

See Also:

SimpAnnotationMethodMessageHandler

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String[]	value Destination-based mapping expressed by this annotation.

Element Detail

value

public abstract String[] value

Destination-based mapping expressed by this annotation.

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.

Default:

{}