Package org.springframework.messaging.handler.annotation

Annotation Interface MessageMapping

@Target({TYPE,METHOD}) @Retention(RUNTIME) @Documented @Reflective(MessageMappingReflectiveProcessor.class) public @interface MessageMapping
Annotation for mapping a Message onto a message-handling method by matching the declared patterns to a destination extracted from the message. The annotation is supported at the type-level too, as a way of declaring a pattern prefix (or prefixes) across all class methods.

@MessageMapping methods support the following arguments:

  • @Payload method argument to extract the payload of a message and have it de-serialized to the declared target type. @Payload arguments may also be annotated with Validation annotations such as @Validated and will then have JSR-303 validation applied. Keep in mind the annotation is not required to be present as it is assumed by default for arguments not handled otherwise.
  • @DestinationVariable method argument for access to template variable values extracted from the message destination, e.g. /hotels/{hotel}. Variable values may also be converted from String to the declared method argument type, if needed.
  • @Header method argument to extract a specific message header value and have a Converter applied to it to convert the value to the declared target type.
  • @Headers method argument that is also assignable to Map for access to all headers.
  • MessageHeaders method argument for access to all headers.
  • MessageHeaderAccessor method argument for access to all headers. In some processing scenarios, like STOMP over WebSocket, this may also be a specialization such as SimpMessageHeaderAccessor.
  • Message<T> for access to body and headers with the body de-serialized if necessary to match the declared type.
  • Principal method arguments are supported in some processing scenarios such as STOMP over WebSocket. It reflects the authenticated user.

Return value handling depends on the processing scenario:

  • STOMP over WebSocket -- the value is turned into a message and sent to a default response destination or to a custom destination specified with an @SendTo or @SendToUser annotation.
  • RSocket -- the response is used to reply to the stream request.

Specializations of this annotation include @SubscribeMapping (e.g. STOMP subscriptions) and @ConnectMapping (e.g. RSocket connections). Both narrow the primary mapping further and also match against the message type. Both can be combined with a type-level @MessageMapping that declares a common pattern prefix (or prefixes).

For further details on the use of this annotation in different contexts, see the following sections of the Spring Framework reference:

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:

  • Optional Element Summary

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

  • Element Details

    • value

      String[] value
      Destination-based mapping expressed by this annotation.

      For STOMP over WebSocket messages this is AntPathMatcher-style patterns matched against the STOMP destination of the message.

      for RSocket this is either AntPathMatcher or PathPattern based pattern, depending on which is configured, matched to the route of the stream request.

      If no patterns are configured, the mapping matches all destinations.

      Default:
      {}