<init>

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 org.springframework.messaging.simp.annotation.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 org.springframework.messaging.converter.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 org.springframework.validation.annotation.Validated) will be subject to JSR-303 validation.
• Header-annotated method arguments to extract a specific header value along with type conversion with a org.springframework.core.convert.converter.Converter if necessary.
• Headers-annotated argument that must also be assignable to java.util.Map for getting access to all headers.
• org.springframework.messaging.MessageHeaders arguments for getting access to all headers.
• org.springframework.messaging.support.MessageHeaderAccessor or with STOMP over WebSocket support also sub-classes such as org.springframework.messaging.simp.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.
• java.security.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 org.springframework.util.concurrent.ListenableFuture return type or a corresponding JDK 8 java.util.concurrent.CompletableFuture / java.util.concurrent.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 org.springframework.messaging.simp.annotation.SendToUser annotation to have the message directed to a specific user if connected. The return value is converted with a org.springframework.messaging.converter.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.

Author
Rossen Stoyanchev

Since
4.0

See Also
org.springframework.messaging.simp.annotation.support.SimpAnnotationMethodMessageHandler