0
# Messaging Templates
1

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

4
## Capabilities
5

6
### Core Template Interfaces
7

8
Interfaces defining common messaging operations patterns.
9

10
```java { .api }
11
/**
12
 * Operations for sending messages to a destination.
13
 */
14
public interface MessageSendingOperations<D> {
15
    /**
16
     * Send a message to the given destination.
17
     */
18
    void send(D destination, Message<?> message);
19
    
20
    /**
21
     * Convert the given Object to serialized form, possibly using a MessageConverter,
22
     * wrap it as a message and send it to the given destination.
23
     */
24
    void send(D destination, Object payload);
25
    
26
    /**
27
     * Convert the given Object to serialized form, possibly using a MessageConverter,
28
     * wrap it as a message with the given headers and send it to the given destination.
29
     */
30
    void send(D destination, Object payload, Map<String, Object> headers);
31
    
32
    /**
33
     * Convert the given Object to serialized form, possibly using a MessageConverter,
34
     * wrap it as a message, apply the given post processor, and send the resulting
35
     * message to the given destination.
36
     */
37
    void send(D destination, Object payload, @Nullable MessagePostProcessor postProcessor);
38
    
39
    /**
40
     * Convert the given Object to serialized form, possibly using a MessageConverter,
41
     * wrap it as a message with the given headers, apply the given post processor,
42
     * and send the resulting message to the given destination.
43
     */
44
    void send(D destination, Object payload, @Nullable Map<String, Object> headers,
45
              @Nullable MessagePostProcessor postProcessor);
46
}
47

48
/**
49
 * Operations for receiving messages from a destination.
50
 */
51
public interface MessageReceivingOperations<D> {
52
    /**
53
     * Receive a message from the given destination.
54
     */
55
    @Nullable
56
    Message<?> receive(D destination);
57
    
58
    /**
59
     * Receive a message from the given destination and convert its payload to the specified target class.
60
     */
61
    @Nullable
62
    <T> T receiveAndConvert(D destination, Class<T> targetClass);
63
}
64

65
/**
66
 * Operations for sending messages with a request-reply pattern.
67
 */
68
public interface MessageRequestReplyOperations<D> {
69
    /**
70
     * Send a request message and receive a reply.
71
     */
72
    @Nullable
73
    Message<?> sendAndReceive(D destination, Message<?> requestMessage);
74
    
75
    /**
76
     * Convert the given request Object to serialized form, possibly using a MessageConverter,
77
     * send it as a Message to the given destination, receive the reply and convert its body
78
     * of the specified target class.
79
     */
80
    @Nullable
81
    <T> T convertSendAndReceive(D destination, Object request, Class<T> targetClass);
82
    
83
    /**
84
     * Convert the given request Object to serialized form, possibly using a MessageConverter,
85
     * send it as a Message with the given headers to the specified destination, receive 
86
     * the reply and convert its body of the specified target class.
87
     */
88
    @Nullable
89
    <T> T convertSendAndReceive(D destination, Object request, @Nullable Map<String, Object> headers,
90
                               Class<T> targetClass);
91
    
92
    /**
93
     * Convert the given request Object to serialized form, possibly using a MessageConverter,
94
     * send it as a Message to the given destination, receive the reply and convert its body
95
     * of the specified target class.
96
     */
97
    @Nullable
98
    <T> T convertSendAndReceive(D destination, Object request, Class<T> targetClass,
99
                               @Nullable MessagePostProcessor requestPostProcessor);
100
    
101
    /**
102
     * Convert the given request Object to serialized form, possibly using a MessageConverter,
103
     * send it as a Message with the given headers to the specified destination, apply the
104
     * given post processor to the request message, receive the reply and convert its body
105
     * of the specified target class.
106
     */
107
    @Nullable
108
    <T> T convertSendAndReceive(D destination, Object request, @Nullable Map<String, Object> headers,
109
                               Class<T> targetClass, @Nullable MessagePostProcessor requestPostProcessor);
110
}
111
```
112

113
### Generic Messaging Template
114

115
Main implementation providing high-level messaging operations.
116

117
```java { .api }
118
/**
119
 * A messaging template that resolves destination names to MessageChannels to send and receive messages from.
120
 * Extends AbstractDestinationResolvingMessagingTemplate which provides destination resolution capabilities.
121
 */
122
public class GenericMessagingTemplate extends AbstractDestinationResolvingMessagingTemplate<MessageChannel>
123
        implements BeanFactoryAware {
124
    
125
    /**
126
     * Create a new GenericMessagingTemplate with no default channel.
127
     */
128
    public GenericMessagingTemplate();
129
    
130
    /**
131
     * Create a new GenericMessagingTemplate with the given default channel.
132
     */
133
    public GenericMessagingTemplate(@Nullable MessageChannel defaultChannel);
134
    
135
    /**
136
     * Set the default channel to send messages to.
137
     */
138
    public void setDefaultDestination(@Nullable String defaultDestination);
139
    
140
    /**
141
     * Return the configured default destination.
142
     */
143
    @Nullable
144
    public String getDefaultDestination();
145
    
146
    /**
147
     * Set the MessageChannel to use by default when no destination is specified.
148
     */
149
    public void setDefaultSendChannel(@Nullable MessageChannel defaultSendChannel);
150
    
151
    /**
152
     * Return the default MessageChannel to send to.
153
     */
154
    @Nullable  
155
    public MessageChannel getDefaultSendChannel();
156
    
157
    /**
158
     * Set the MessageChannel to use by default when no destination is specified for receive operations.
159
     */
160
    public void setDefaultReceiveChannel(@Nullable PollableChannel defaultReceiveChannel);
161
    
162
    /**
163
     * Return the default PollableChannel to receive from.
164
     */
165
    @Nullable
166
    public PollableChannel getDefaultReceiveChannel();
167
    
168
    /**
169
     * Set the timeout for receive operations.
170
     */
171
    public void setReceiveTimeout(long receiveTimeout);
172
    
173
    /**
174
     * Return the receive timeout.
175
     */
176
    public long getReceiveTimeout();
177
    
178
    /**
179
     * Set the timeout for send operations.
180
     */
181
    public void setSendTimeout(long sendTimeout);  
182
    
183
    /**
184
     * Return the send timeout.
185
     */
186
    public long getSendTimeout();
187
}
188
```
189

190
### Abstract Messaging Template
191

192
Base class for messaging template implementations.
193

194
```java { .api }
195
/**
196
 * Abstract base class for messaging template implementations.
197
 */
198
public abstract class AbstractMessagingTemplate<D> implements MessageSendingOperations<D>,
199
        MessageReceivingOperations<D>, MessageRequestReplyOperations<D> {
200
    
201
    /**
202
     * Set the MessageConverter to use for converting between Objects and Messages.
203
     */
204
    public void setMessageConverter(MessageConverter messageConverter);
205
    
206
    /**
207
     * Return the configured MessageConverter.
208
     */
209
    public MessageConverter getMessageConverter();
210
    
211
    /**
212
     * Set the DestinationResolver to use for resolving destinations by name.
213
     */
214
    public void setDestinationResolver(@Nullable DestinationResolver<D> destinationResolver);
215
    
216
    /**
217
     * Return the configured DestinationResolver.
218
     */
219
    @Nullable
220
    public DestinationResolver<D> getDestinationResolver();
221
    
222
    /**
223
     * Resolve the given destination name to a destination.
224
     */
225
    protected D resolveDestination(String destinationName);
226
    
227
    /**
228
     * Actually send the given Message to the specified destination.
229
     */
230
    protected abstract void doSend(D destination, Message<?> message);
231
    
232
    /**
233
     * Actually receive a Message from the specified destination.
234
     */
235
    @Nullable
236
    protected abstract Message<?> doReceive(D destination);
237
    
238
    /**
239
     * Actually send the request Message and receive a reply from the specified destination.
240
     */
241
    @Nullable
242
    protected abstract Message<?> doSendAndReceive(D destination, Message<?> requestMessage);
243
}
244
```
245

246
### Destination Resolution
247

248
Interfaces and implementations for resolving destination names to actual destinations.
249

250
```java { .api }
251
/**
252
 * Strategy for resolving a destination name to a destination.
253
 */
254
public interface DestinationResolver<D> {
255
    /**
256
     * Resolve the given destination name.
257
     */
258
    D resolveDestination(String name) throws DestinationResolutionException;
259
}
260

261
/**
262
 * A DestinationResolver that resolves a destination name to a MessageChannel retrieved
263
 * from a BeanFactory.
264
 */
265
public class BeanFactoryMessageChannelDestinationResolver implements DestinationResolver<MessageChannel> {
266
    
267
    /**
268
     * Create a new instance with the given BeanFactory.
269
     */
270
    public BeanFactoryMessageChannelDestinationResolver(BeanFactory beanFactory);
271
    
272
    /**
273
     * Return the BeanFactory that this resolver uses to lookup destinations.
274
     */
275
    public BeanFactory getBeanFactory();
276
    
277
    /**
278
     * Resolve the given destination name to a MessageChannel.
279
     */
280
    @Override
281
    public MessageChannel resolveDestination(String name) throws DestinationResolutionException;
282
}
283

284
/**
285
 * A caching decorator for DestinationResolver implementations.
286
 */
287
public class CachingDestinationResolverProxy<D> implements DestinationResolver<D> {
288
    
289
    /**
290
     * Create a new CachingDestinationResolverProxy.
291
     */
292
    public CachingDestinationResolverProxy(DestinationResolver<D> targetResolver);
293
    
294
    /**
295
     * Return the target DestinationResolver that this proxy delegates to.
296
     */
297
    public DestinationResolver<D> getTargetResolver();
298
    
299
    /**
300
     * Resolve the given destination name, caching the result.
301
     */
302
    @Override
303
    public D resolveDestination(String name) throws DestinationResolutionException;
304
}
305
```
306

307
### Message Post Processing
308

309
Interface for post-processing messages after creation.
310

311
```java { .api }
312
/**
313
 * A contract for processing a Message after it has been created, either returning
314
 * a modified (effectively new) message or returning the same message.
315
 */
316
@FunctionalInterface
317
public interface MessagePostProcessor {
318
    /**
319
     * Apply this post-processor to the given message.
320
     */
321
    Message<?> postProcessMessage(Message<?> message);
322
}
323
```
324

325
### Template Exceptions
326

327
Exception thrown when destination resolution fails.
328

329
```java { .api }
330
/**
331
 * Thrown by a DestinationResolver when it cannot resolve a destination name.
332
 */
333
public class DestinationResolutionException extends MessagingException {
334
    
335
    public DestinationResolutionException(String description);
336
    
337
    public DestinationResolutionException(String description, Throwable cause);
338
}
339
```
340

341
### SIMP Messaging Template
342

343
Template specialized for SIMP (Simple Messaging Protocol) operations.
344

345
```java { .api }
346
/**
347
 * An implementation of SimpMessageSendingOperations.
348
 */
349
public class SimpMessagingTemplate extends AbstractMessageSendingTemplate<String>
350
        implements SimpMessageSendingOperations {
351
    
352
    /**
353
     * Create a new SimpMessagingTemplate instance.
354
     */
355
    public SimpMessagingTemplate(MessageChannel messageChannel);
356
    
357
    /**
358
     * Set the prefix to add to user destinations.
359
     */
360
    public void setUserDestinationPrefix(String prefix);
361
    
362
    /**
363
     * Return the configured user destination prefix.
364
     */
365
    public String getUserDestinationPrefix();
366
    
367
    /**
368
     * Convert the given Object to serialized form, possibly using a MessageConverter,
369
     * and send as a message to the specified user.
370
     */
371
    @Override
372
    public void convertAndSendToUser(String user, String destination, Object payload);
373
    
374
    /**
375
     * Convert the given Object to serialized form, possibly using a MessageConverter,
376
     * and send as a message with the given headers to the specified user.
377
     */
378
    @Override
379
    public void convertAndSendToUser(String user, String destination, Object payload,
380
                                   @Nullable Map<String, Object> headers);
381
    
382
    /**
383
     * Convert the given Object to serialized form, possibly using a MessageConverter,
384
     * and send as a message to the specified user with post-processing.
385
     */
386
    @Override
387
    public void convertAndSendToUser(String user, String destination, Object payload,
388
                                   @Nullable MessagePostProcessor postProcessor);
389
    
390
    /**
391
     * Convert the given Object to serialized form, possibly using a MessageConverter,
392
     * and send as a message with headers to the specified user with post-processing.
393
     */
394
    @Override
395
    public void convertAndSendToUser(String user, String destination, Object payload,
396
                                   @Nullable Map<String, Object> headers,
397
                                   @Nullable MessagePostProcessor postProcessor);
398
}
399
```
400

401
**Usage Examples:**
402

403
```java
404
import org.springframework.messaging.core.GenericMessagingTemplate;
405
import org.springframework.messaging.support.MessageBuilder;
406
import org.springframework.messaging.converter.MappingJackson2MessageConverter;
407

408
// Template setup
409
GenericMessagingTemplate template = new GenericMessagingTemplate();
410
template.setMessageConverter(new MappingJackson2MessageConverter());
411
template.setDefaultSendChannel(getDefaultChannel());
412
template.setSendTimeout(10000); // 10 seconds
413

414
// Simple sending
415
template.send("orders", MessageBuilder.withPayload("New Order").build());
416

417
// Send with payload conversion
418
Order order = new Order("123", "Product A", 100.0);
419
template.send("orders", order);
420

421
// Send with headers
422
Map<String, Object> headers = new HashMap<>();
423
headers.put("priority", "high");
424
headers.put("type", "order");
425
template.send("orders", order, headers);
426

427
// Send with post-processing
428
template.send("orders", order, message -> {
429
    return MessageBuilder.fromMessage(message)
430
        .setHeader("timestamp", System.currentTimeMillis())
431
        .build();
432
});
433

434
// Request-reply operations
435
String response = template.convertSendAndReceive("requests", "getData", String.class);
436

437
// Request-reply with headers and timeout
438
Map<String, Object> requestHeaders = Map.of("timeout", "5000");
439
Order orderResponse = template.convertSendAndReceive("orders", order, requestHeaders, 
440
                                                   Order.class);
441

442
// Receive operations (requires PollableChannel)
443
template.setDefaultReceiveChannel(getPollableChannel());
444
template.setReceiveTimeout(5000);
445
Message<?> received = template.receive("notifications");
446
String notification = template.receiveAndConvert("notifications", String.class);
447

448
// Destination resolution
449
BeanFactoryMessageChannelDestinationResolver resolver = 
450
    new BeanFactoryMessageChannelDestinationResolver(applicationContext);
451
template.setDestinationResolver(resolver);
452

453
// SIMP template for user-specific messaging
454
SimpMessagingTemplate simpTemplate = new SimpMessagingTemplate(brokerChannel);
455
simpTemplate.convertAndSendToUser("john", "/queue/notifications", 
456
                                 "You have a new message");
457

458
// Send to user with headers
459
Map<String, Object> userHeaders = Map.of("priority", "urgent");
460
simpTemplate.convertAndSendToUser("john", "/queue/alerts", "System maintenance",
461
                                 userHeaders);
462
```