0
# Message Conversion
1

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

4
## Capabilities
5

6
### Core Conversion Interface
7

8
Base interface for converting between typed objects and messages.
9

10
```java { .api }
11
/**
12
 * A converter to turn the payload of a Message from serialized form to a typed
13
 * Object and vice versa.
14
 */
15
public interface MessageConverter {
16
    /**
17
     * Convert the payload of a Message from a serialized form to a typed Object.
18
     * @param message the input message
19
     * @param targetClass the target class for conversion
20
     * @return the result of conversion, or null if the converter cannot perform the conversion
21
     */
22
    @Nullable
23
    Object fromMessage(Message<?> message, Class<?> targetClass);
24
    
25
    /**
26
     * Create a Message whose payload is the result of converting the given payload Object to serialized form.
27
     * @param payload the Object to convert
28
     * @param headers optional headers for the message (may be null)
29
     * @return the new message, or null if the converter does not support the Object type
30
     */
31
    @Nullable  
32
    Message<?> toMessage(Object payload, @Nullable MessageHeaders headers);
33
}
34

35
/**
36
 * An extended MessageConverter that also supports conversion hints and MIME type resolution.
37
 */
38
public interface SmartMessageConverter extends MessageConverter {
39
    /**
40
     * A variant of fromMessage with conversion hints.
41
     */
42
    @Nullable
43
    Object fromMessage(Message<?> message, Class<?> targetClass, @Nullable Object conversionHint);
44
    
45
    /**
46
     * A variant of toMessage with conversion hints.
47
     */
48
    @Nullable
49
    Message<?> toMessage(Object payload, @Nullable MessageHeaders headers, @Nullable Object conversionHint);
50
}
51
```
52

53
### JSON Converters
54

55
Converters for JSON serialization using popular JSON libraries.
56

57
```java { .api }
58
/**
59
 * A MessageConverter that uses Jackson to convert messages to and from JSON.
60
 */
61
public class MappingJackson2MessageConverter extends AbstractMessageConverter {
62
    
63
    public MappingJackson2MessageConverter();
64
    
65
    public MappingJackson2MessageConverter(MimeType... supportedMimeTypes);
66
    
67
    /**
68
     * Set the ObjectMapper for this converter.
69
     */
70
    public void setObjectMapper(ObjectMapper objectMapper);
71
    
72
    /**
73
     * Return the ObjectMapper for this converter.
74
     */
75
    public ObjectMapper getObjectMapper();
76
    
77
    /**
78
     * Specify whether to use default typing when JSON content is empty or only contains whitespace.
79
     */
80
    public void setSerializeTypingOnEmpty(boolean serializeTypingOnEmpty);
81
}
82

83
/**
84
 * A MessageConverter that uses Google Gson to convert messages to and from JSON.
85
 */
86
public class GsonMessageConverter extends AbstractMessageConverter {
87
    
88
    public GsonMessageConverter();
89
    
90
    public GsonMessageConverter(MimeType... supportedMimeTypes);
91
    
92
    /**
93
     * Set the Gson instance to use.
94
     */
95
    public void setGson(Gson gson);
96
    
97
    /**
98
     * Return the configured Gson instance.
99
     */
100
    public Gson getGson();
101
}
102

103
/**
104
 * A MessageConverter that uses JSON-B (JSR 367) to convert messages to and from JSON.
105
 */
106
public class JsonbMessageConverter extends AbstractMessageConverter {
107
    
108
    public JsonbMessageConverter();
109
    
110
    public JsonbMessageConverter(MimeType... supportedMimeTypes);
111
    
112
    /**
113
     * Set the Jsonb instance to use.
114
     */
115
    public void setJsonb(Jsonb jsonb);
116
    
117
    /**
118
     * Return the configured Jsonb instance.
119
     */
120
    public Jsonb getJsonb();
121
}
122
```
123

124
### Protocol Buffers Support
125

126
Message converter for Google Protocol Buffers serialization.
127

128
```java { .api }
129
/**
130
 * A MessageConverter that reads and writes com.google.protobuf.Messages using Google Protocol Buffers.
131
 */
132
public class ProtobufMessageConverter extends AbstractMessageConverter {
133
    
134
    public ProtobufMessageConverter();
135
    
136
    public ProtobufMessageConverter(ExtensionRegistry extensionRegistry);
137
    
138
    /**
139
     * Set the ExtensionRegistry instance to use for parsing.
140
     */
141
    public void setExtensionRegistry(ExtensionRegistry extensionRegistry);
142
    
143
    /**
144
     * Return the configured ExtensionRegistry.
145
     */
146
    public ExtensionRegistry getExtensionRegistry();
147
}
148
```
149

150
### Basic Type Converters
151

152
Converters for common Java types and byte arrays.
153

154
```java { .api }
155
/**
156
 * A simple MessageConverter that converts Strings and byte arrays.
157
 */
158
public class SimpleMessageConverter implements MessageConverter {
159
    
160
    public SimpleMessageConverter();
161
}
162

163
/**  
164
 * A MessageConverter that converts Strings to and from byte arrays.
165
 */
166
public class StringMessageConverter extends AbstractMessageConverter {
167
    
168
    public StringMessageConverter();
169
    
170
    public StringMessageConverter(Charset defaultCharset);
171
    
172
    /**
173
     * Set the default charset to use when converting to bytes.
174
     */
175
    public void setDefaultCharset(Charset defaultCharset);
176
    
177
    /**
178
     * Return the default charset.
179
     */
180
    public Charset getDefaultCharset();
181
}
182

183
/**
184
 * A MessageConverter that supports byte arrays.
185
 */  
186
public class ByteArrayMessageConverter extends AbstractMessageConverter {
187
    
188
    public ByteArrayMessageConverter();
189
}
190
```
191

192
### Composite and Generic Converters
193

194
Converters that delegate to multiple converters or use Spring's conversion service.
195

196
```java { .api }
197
/**
198
 * A MessageConverter that delegates to a list of registered converters.
199
 */
200
public class CompositeMessageConverter implements SmartMessageConverter {
201
    
202
    public CompositeMessageConverter(List<MessageConverter> converters);
203
    
204
    /**
205
     * Return the underlying list of delegate converters.
206
     */
207
    public List<MessageConverter> getConverters();
208
}
209

210
/**
211
 * A MessageConverter that uses Spring's ConversionService for type conversion.
212
 */
213
public class GenericMessageConverter implements SmartMessageConverter {
214
    
215
    public GenericMessageConverter();
216
    
217
    public GenericMessageConverter(ConversionService conversionService);
218
    
219
    /**
220
     * Set the ConversionService to use.
221
     */
222
    public void setConversionService(ConversionService conversionService);
223
    
224
    /**
225
     * Return the configured ConversionService.
226
     */
227
    public ConversionService getConversionService();
228
}
229
```
230

231
### Content Type Resolution
232

233
Interface and implementation for resolving content types from messages.
234

235
```java { .api }
236
/**
237
 * A contract for resolving the content type of a message.
238
 */
239
public interface ContentTypeResolver {
240
    /**
241
     * Determine the MimeType of a message from the given MessageHeaders.
242
     */
243
    @Nullable
244
    MimeType resolve(@Nullable MessageHeaders headers);
245
}
246

247
/**
248
 * A default ContentTypeResolver that checks the MessageHeaders.CONTENT_TYPE header.
249
 */
250
public class DefaultContentTypeResolver implements ContentTypeResolver {
251
    
252
    public DefaultContentTypeResolver();
253
    
254
    /**
255
     * Set the default MIME type to use when no content type header is present.
256
     */
257
    public void setDefaultMimeType(MimeType defaultMimeType);
258
    
259
    /**
260
     * Return the default MIME type.
261
     */
262
    @Nullable
263
    public MimeType getDefaultMimeType();
264
}
265
```
266

267
### Conversion Exceptions
268

269
Exception thrown when message conversion fails.
270

271
```java { .api }
272
/**
273
 * An exception raised by MessageConverter implementations when message conversion fails.
274
 */
275
public class MessageConversionException extends MessagingException {
276
    
277
    public MessageConversionException(String description);
278
    
279
    public MessageConversionException(String description, Throwable cause);
280
    
281
    public MessageConversionException(Message<?> failedMessage, String description);
282
    
283
    public MessageConversionException(Message<?> failedMessage, String description, Throwable cause);
284
}
285
```
286

287
**Usage Examples:**
288

289
```java
290
import org.springframework.messaging.converter.*;
291
import org.springframework.messaging.support.MessageBuilder;
292
import org.springframework.util.MimeType;
293

294
// JSON conversion with Jackson
295
MappingJackson2MessageConverter jsonConverter = new MappingJackson2MessageConverter();
296

297
// Convert object to message
298
Person person = new Person("John", "Doe", 30);
299
Message<?> message = jsonConverter.toMessage(person, null);
300

301
// Convert message back to object
302
Person converted = (Person) jsonConverter.fromMessage(message, Person.class);
303

304
// Composite converter with multiple formats
305
List<MessageConverter> converters = Arrays.asList(
306
    new MappingJackson2MessageConverter(),
307
    new StringMessageConverter(),
308
    new ByteArrayMessageConverter()
309
);
310
CompositeMessageConverter composite = new CompositeMessageConverter(converters);
311

312
// String conversion with charset
313
StringMessageConverter stringConverter = new StringMessageConverter(StandardCharsets.UTF_8);
314
Message<?> stringMessage = stringConverter.toMessage("Hello World", null);
315

316
// Protocol Buffers conversion
317
ProtobufMessageConverter protobufConverter = new ProtobufMessageConverter();
318
// Requires protobuf-generated classes
319
// Message<?> protoMessage = protobufConverter.toMessage(myProtoObject, null);
320

321
// Content type resolution
322
DefaultContentTypeResolver resolver = new DefaultContentTypeResolver();
323
resolver.setDefaultMimeType(MimeType.valueOf("application/json"));
324
MimeType contentType = resolver.resolve(message.getHeaders());
325
```