This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Framework 7.0.9!

Annotated Controllers

Applications can use annotated @Controller classes to handle messages from clients. Such classes can declare @MessageMapping, @SubscribeMapping, and @ExceptionHandler methods, as described in the following topics:

@MessageMapping
@SubscribeMapping
@MessageExceptionHandler

`@MessageMapping`

You can use @MessageMapping to annotate methods that route messages based on their destination. It is supported at the method level as well as at the type level. At the type level, @MessageMapping is used to express shared mappings across all methods in a controller.

By default, the mapping values are Ant-style path patterns (for example /thing*, /thing/**), including support for template variables (for example, /thing/{id}). The values can be referenced through @DestinationVariable method arguments. Applications can also switch to a dot-separated destination convention for mappings, as explained in Dots as Separators.

Supported Method Arguments

The following table describes the method arguments:

Method argument Description

Method argument	Description
`Message`	For access to the complete message.
`MessageHeaders`	For access to the headers within the `Message`.
`MessageHeaderAccessor`, `SimpMessageHeaderAccessor`, and `StompHeaderAccessor`	For access to the headers through typed accessor methods.
`@Payload`	For access to the payload of the message, converted (for example, from JSON) by a configured `MessageConverter`. The presence of this annotation is not required since it is, by default, assumed if no other argument is matched. You can annotate payload arguments with `@jakarta.validation.Valid` or Spring’s `@Validated`, to have the payload arguments be automatically validated.
`@Header`	For access to a specific header value — along with type conversion using an `org.springframework.core.convert.converter.Converter`, if necessary.
`@Headers`	For access to all headers in the message. This argument must be assignable to `java.util.Map`.
`@DestinationVariable`	For access to template variables extracted from the message destination. Values are converted to the declared method argument type as necessary.
`java.security.Principal`	Reflects the user logged in at the time of the WebSocket HTTP handshake.

Message

For access to the complete message.

MessageHeaders

For access to the headers within the Message.

MessageHeaderAccessor, SimpMessageHeaderAccessor, and StompHeaderAccessor

For access to the headers through typed accessor methods.

@Payload

For access to the payload of the message, converted (for example, from JSON) by a configured MessageConverter.

The presence of this annotation is not required since it is, by default, assumed if no other argument is matched.

You can annotate payload arguments with @jakarta.validation.Valid or Spring’s @Validated, to have the payload arguments be automatically validated.

@Header

For access to a specific header value — along with type conversion using an org.springframework.core.convert.converter.Converter, if necessary.

@Headers

For access to all headers in the message. This argument must be assignable to java.util.Map.

@DestinationVariable

For access to template variables extracted from the message destination. Values are converted to the declared method argument type as necessary.

java.security.Principal

Reflects the user logged in at the time of the WebSocket HTTP handshake.

Return Values

By default, the return value from a @MessageMapping method is serialized to a payload through a matching MessageConverter and sent as a Message to the brokerChannel, from where it is broadcast to subscribers. The destination of the outbound message is the same as that of the inbound message but prefixed with /topic.

You can use the @SendTo and