spring-projects/spring-framework

spring-messaging

Active contributors: rstoyanchev, Juergen Hoeller, Sébastien Deleuze

Purpose

spring-messaging is the generic messaging abstraction that underpins Spring's STOMP-over-WebSocket support, Spring's RSocket integration, the integration with JMS / AMQP / Kafka adapters, and Spring Cloud Stream's binder model. It defines Message<T>, MessageHandler, MessageChannel, the @MessageMapping annotation family, and the converter and routing infrastructure.

Directory layout

spring-messaging/
└── src/main/java/org/springframework/messaging/
    ├── Message.java
    ├── MessageChannel.java
    ├── MessageHandler.java
    ├── MessageHeaders.java
    ├── converter/                                  # MessageConverter (JSON, XML, Smile, …)
    ├── core/                                       # AbstractMessagingTemplate
    ├── handler/                                    # @MessageMapping infrastructure
    │   └── annotation/
    ├── rsocket/                                    # RSocket support
    ├── simp/                                       # STOMP / pub-sub specifics
    │   ├── annotation/                             # @SubscribeMapping, @SendTo
    │   ├── broker/                                 # SimpleBrokerMessageHandler
    │   ├── stomp/                                  # STOMP encoders/decoders
    │   └── …
    ├── support/                                    # ChannelInterceptor, GenericMessage
    └── tcp/                                        # Reactive TCP for STOMP brokers

Key abstractions

Type	File	Role
`Message<T>`	`spring-messaging/src/main/java/org/springframework/messaging/Message.java`	Generic message: payload + headers
`MessageHeaders`	`spring-messaging/src/main/java/org/springframework/messaging/MessageHeaders.java`	Immutable, typed-key header map
`MessageChannel`	`spring-messaging/src/main/java/org/springframework/messaging/MessageChannel.java`	Interface a handler can send to
`MessageHandler`	`spring-messaging/src/main/java/org/springframework/messaging/MessageHandler.java`	Receives messages from a channel
`MessageConverter`	`spring-messaging/src/main/java/org/springframework/messaging/converter/MessageConverter.java`	Object ↔ message body
`@MessageMapping` / `@SubscribeMapping` / `@SendTo`	`spring-messaging/src/main/java/org/springframework/messaging/handler/annotation/`	Annotation-based routing
`SimpAnnotationMethodMessageHandler`	`spring-messaging/src/main/java/org/springframework/messaging/simp/annotation/support/SimpAnnotationMethodMessageHandler.java`	Dispatcher for STOMP `@MessageMapping`
`SimpleBrokerMessageHandler`	`spring-messaging/src/main/java/org/springframework/messaging/simp/broker/SimpleBrokerMessageHandler.java`	In-memory pub-sub broker

How it works

Generic message flow

graph LR
    Source -->|"send"| Channel[MessageChannel]
    Channel --> Interceptors[ChannelInterceptors]
    Interceptors --> Handler[MessageHandler]
    Handler -->|"convert"| Converter[MessageConverter]
    Converter --> App[@MessageMapping method]

MessageChannel is a fundamental abstraction — pub-sub, point-to-point, executor-backed, and reactive variants are all implementations.

STOMP routing

sequenceDiagram
    participant WS as WebSocket transport
    participant Stomp as StompSubProtocolHandler
    participant CSI as ClientInboundChannel
    participant Disp as SimpAnnotationMethodMessageHandler
    participant App as @MessageMapping method
    participant Broker as SimpleBrokerMessageHandler
    WS->>Stomp: STOMP frame
    Stomp->>CSI: Message<byte[]>
    CSI->>Disp: route by destination ("/app/...")
    Disp->>App: invoke handler
    App-->>Disp: return value
    Disp->>Broker: relay to subscribers ("@SendTo /topic/news")
    Broker->>WS: STOMP MESSAGE frame

The same routing model is reused for RSocket: @MessageMapping methods serve both transports.

`MessageConverter`

Like HttpMessageConverter for HTTP, MessageConverter is the marshalling layer. Implementations: MappingJackson2MessageConverter, KotlinSerializationJsonMessageConverter, MarshallingMessageConverter, StringMessageConverter, …

Integration points

Used by:
- spring-websocket — STOMP transport
- spring-jms — MessageConverter for JMS payloads
- Spring AMQP, Spring Kafka — STOMP/RabbitMQ/Kafka bindings
- Spring Integration — channels and endpoints
- RSocket — @MessageMapping over RSocket frames
Reactive variant — Many channel/handler interfaces have reactive versions (ReactiveMessageChannel, ReactiveMessageHandler).

Entry points for modification

New transport — Implement a MessageHandler that consumes from your transport and a MessageChannel that sends back to it.
New annotation routing target — Subclass AbstractMethodMessageHandler for a custom dispatcher (RSocket and STOMP both do this).
Custom converter — Implement MessageConverter for a new payload format.