0
# Spring Messaging
1

2
Spring Messaging provides a comprehensive messaging abstraction layer for enterprise applications, enabling developers to work with various messaging protocols and systems through a unified API. It includes support for core messaging concepts, message conversion capabilities, reactive messaging patterns, STOMP protocol support for WebSocket communication, RSocket integration, and annotation-based message handling.
3

4
## Package Information
5

6
- **Package Name**: org.springframework:spring-messaging
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven pom.xml:
10
  ```xml
11
  <dependency>
12
    <groupId>org.springframework</groupId>
13
    <artifactId>spring-messaging</artifactId>
14
    <version>5.3.39</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
// Core messaging interfaces
22
import org.springframework.messaging.Message;
23
import org.springframework.messaging.MessageChannel;
24
import org.springframework.messaging.MessageHandler;
25
import org.springframework.messaging.MessageHeaders;
26

27
// Template for high-level operations
28
import org.springframework.messaging.core.GenericMessagingTemplate;
29

30
// Message building
31
import org.springframework.messaging.support.MessageBuilder;
32

33
// Annotation-based handling
34
import org.springframework.messaging.handler.annotation.MessageMapping;
35
import org.springframework.messaging.handler.annotation.Payload;
36
import org.springframework.messaging.handler.annotation.Header;
37
```
38

39
## Basic Usage
40

41
```java
42
import org.springframework.messaging.Message;
43
import org.springframework.messaging.MessageChannel;
44
import org.springframework.messaging.support.MessageBuilder;
45
import org.springframework.messaging.support.GenericMessage;
46

47
// Create a message
48
Message<String> message = MessageBuilder
49
    .withPayload("Hello, World!")
50
    .setHeader("type", "greeting")
51
    .build();
52

53
// Send message through a channel
54
MessageChannel channel = getMessageChannel(); // obtain channel
55
boolean sent = channel.send(message);
56

57
// Handle messages with annotation-based approach
58
@Component
59
public class MessageHandler {
60
    
61
    @MessageMapping("/greetings")
62
    public void handleGreeting(@Payload String message, 
63
                              @Header("type") String messageType) {
64
        System.out.println("Received " + messageType + ": " + message);
65
    }
66
}
67
```
68

69
## Architecture
70

71
Spring Messaging is built around several key architectural patterns:
72

73
- **Message Abstraction**: Core `Message<T>` interface representing typed messages with headers
74
- **Channel Pattern**: `MessageChannel` abstraction for message transport with interceptor support
75
- **Template Pattern**: High-level `GenericMessagingTemplate` for common messaging operations
76
- **Annotation-Driven**: Rich annotation support (`@MessageMapping`, `@Payload`, etc.) for declarative handling
77
- **Protocol Support**: Dedicated implementations for STOMP, SIMP, and RSocket protocols
78
- **Conversion Framework**: Pluggable message converters for different data formats (JSON, XML, Protocol Buffers)
79
- **Reactive Integration**: Full reactive streams support with `ReactiveMessageHandler`
80

81
## Capabilities
82

83
### Core Messaging
84

85
Foundation messaging interfaces and classes providing the basic abstractions for message handling, channels, and core operations.
86

87
```java { .api }
88
// Core message interface
89
public interface Message<T> {
90
    T getPayload();
91
    MessageHeaders getHeaders();
92
}
93

94
// Channel for sending messages
95
@FunctionalInterface
96
public interface MessageChannel {
97
    boolean send(Message<?> message);
98
    boolean send(Message<?> message, long timeout);
99
}
100

101
// Handler for processing messages
102
@FunctionalInterface
103
public interface MessageHandler {
104
    void handleMessage(Message<?> message) throws MessagingException;
105
}
106
```
107

108
[Core Messaging](./core-messaging.md)
109

110
### Message Conversion
111

112
Comprehensive message conversion framework supporting multiple data formats including JSON, XML, Protocol Buffers, and custom conversions with pluggable converter architecture.
113

114
```java { .api }
115
public interface MessageConverter {
116
    Object fromMessage(Message<?> message, Class<?> targetClass);
117
    Message<?> toMessage(Object payload, @Nullable MessageHeaders headers);
118
}
119

120
public class MappingJackson2MessageConverter extends AbstractMessageConverter {
121
    // JSON message conversion using Jackson
122
}
123
```
124

125
[Message Conversion](./message-conversion.md)
126

127
### Annotation-Based Handling
128

129
Declarative message handling using annotations for mapping messages to handler methods, extracting payloads and headers, and defining response destinations.
130

131
```java { .api }
132
@Target({ElementType.TYPE, ElementType.METHOD})
133
@Retention(RetentionPolicy.RUNTIME)
134
public @interface MessageMapping {
135
    String[] value() default {};
136
}
137

138
@Target(ElementType.PARAMETER)
139
@Retention(RetentionPolicy.RUNTIME) 
140
public @interface Payload {
141
    String value() default "";
142
    boolean required() default true;
143
}
144
```
145

146
[Annotation-Based Handling](./annotation-handling.md)
147

148
### STOMP and WebSocket Support
149

150
Complete STOMP (Simple Text Oriented Messaging Protocol) implementation for WebSocket-based messaging with session management, subscription handling, and broker relay capabilities.
151

152
```java { .api }
153
public interface StompSession {
154
    StompSession.Subscription subscribe(String destination, StompFrameHandler handler);
155
    void send(String destination, Object payload);
156
    void disconnect();
157
}
158

159
public class StompBrokerRelayMessageHandler extends AbstractBrokerMessageHandler {
160
    // Relay messages to external STOMP broker
161
}
162
```
163

164
[STOMP and WebSocket Support](./stomp-websocket.md)
165

166
### RSocket Integration
167

168
RSocket protocol support for reactive, binary messaging with backpressure handling, request-response patterns, and reactive streams integration.
169

170
```java { .api }
171
public interface RSocketRequester {
172
    RequestSpec route(String route);
173
    
174
    interface RequestSpec {
175
        ResponseSpec data(Object data);
176
        Mono<Void> send();
177
        Mono<Object> retrieveMono(Class<?> elementType);
178
        Flux<Object> retrieveFlux(Class<?> elementType);
179
    }
180
}
181
```
182

183
[RSocket Integration](./rsocket-integration.md)
184

185
### Messaging Templates and Operations
186

187
High-level template classes providing convenient APIs for common messaging operations including sending, receiving, and request-reply patterns with destination resolution.
188

189
```java { .api }
190
public interface MessageSendingOperations<D> {
191
    void send(D destination, Message<?> message);
192
    void send(D destination, Object payload);
193
    void send(D destination, Object payload, Map<String, Object> headers);
194
}
195

196
public class GenericMessagingTemplate extends AbstractMessagingTemplate<String> {
197
    // High-level messaging operations
198
}
199
```
200

201
[Messaging Templates](./messaging-templates.md)
202

203
## Types
204

205
Core types used across the messaging framework:
206

207
```java { .api }
208
public final class MessageHeaders implements Map<String, Object>, Serializable {
209
    public static final String ID = "id";
210
    public static final String TIMESTAMP = "timestamp";
211
    
212
    public Object get(Object key);
213
    public boolean containsKey(Object key);
214
    // Map interface methods...
215
}
216

217
public class MessagingException extends RuntimeException {
218
    public MessagingException(String description);
219
    public MessagingException(Message<?> failedMessage);
220
    public Message<?> getFailedMessage();
221
}
222
```