Skip to content

Commit 4cbaaa3

Browse files
bclozelbclozel
committed
Move Servlet HTTP Message Conversion to its own section
Closes gh-33063
1 parent e622555 commit 4cbaaa3

File tree

4 files changed

+98
-63
lines changed

4 files changed

+98
-63
lines changed

‎framework-docs/modules/ROOT/nav.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,7 @@
248248
**** xref:web/webmvc/mvc-servlet/multipart.adoc[]
249249
**** xref:web/webmvc/mvc-servlet/logging.adoc[]
250250
*** xref:web/webmvc/filters.adoc[]
251+
*** xref:web/webmvc/message-converters.adoc[]
251252
*** xref:web/webmvc/mvc-controller.adoc[]
252253
**** xref:web/webmvc/mvc-controller/ann.adoc[]
253254
**** xref:web/webmvc/mvc-controller/ann-requestmapping.adoc[]

‎framework-docs/modules/ROOT/pages/integration/rest-clients.adoc

+1-62
Original file line numberDiff line numberDiff line change
@@ -366,68 +366,7 @@ val result = restClient.get()
366366
[[rest-message-conversion]]
367367
=== HTTP Message Conversion
368368

369-
[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs[See equivalent in the Reactive stack]#
370-
371-
The `spring-web` module contains the `HttpMessageConverter` interface for reading and writing the body of HTTP requests and responses through `InputStream` and `OutputStream`.
372-
`HttpMessageConverter` instances are used on the client side (for example, in the `RestClient`) and on the server side (for example, in Spring MVC REST controllers).
373-
374-
Concrete implementations for the main media (MIME) types are provided in the framework and are, by default, registered with the `RestClient` and `RestTemplate` on the client side and with `RequestMappingHandlerAdapter` on the server side (see xref:web/webmvc/mvc-config/message-converters.adoc[Configuring Message Converters]).
375-
376-
Several implementations of `HttpMessageConverter` are described below.
377-
Refer to the {spring-framework-api}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list.
378-
For all converters, a default media type is used, but you can override it by setting the `supportedMediaTypes` property.
379-
380-
[[rest-message-converters-tbl]]
381-
.HttpMessageConverter Implementations
382-
[cols="1,3"]
383-
|===
384-
| MessageConverter | Description
385-
386-
| `StringHttpMessageConverter`
387-
| An `HttpMessageConverter` implementation that can read and write `String` instances from the HTTP request and response.
388-
By default, this converter supports all text media types(`text/{asterisk}`) and writes with a `Content-Type` of `text/plain`.
389-
390-
| `FormHttpMessageConverter`
391-
| An `HttpMessageConverter` implementation that can read and write form data from the HTTP request and response.
392-
By default, this converter reads and writes the `application/x-www-form-urlencoded` media type.
393-
Form data is read from and written into a `MultiValueMap<String, String>`.
394-
The converter can also write (but not read) multipart data read from a `MultiValueMap<String, Object>`.
395-
By default, `multipart/form-data` is supported.
396-
Additional multipart subtypes can be supported for writing form data.
397-
Consult the javadoc for `FormHttpMessageConverter` for further details.
398-
399-
| `ByteArrayHttpMessageConverter`
400-
| An `HttpMessageConverter` implementation that can read and write byte arrays from the HTTP request and response.
401-
By default, this converter supports all media types (`{asterisk}/{asterisk}`) and writes with a `Content-Type` of `application/octet-stream`.
402-
You can override this by setting the `supportedMediaTypes` property and overriding `getContentType(byte[])`.
403-
404-
| `MarshallingHttpMessageConverter`
405-
| An `HttpMessageConverter` implementation that can read and write XML by using Spring's `Marshaller` and `Unmarshaller` abstractions from the `org.springframework.oxm` package.
406-
This converter requires a `Marshaller` and `Unmarshaller` before it can be used.
407-
You can inject these through constructor or bean properties.
408-
By default, this converter supports `text/xml` and `application/xml`.
409-
410-
| `MappingJackson2HttpMessageConverter`
411-
| An `HttpMessageConverter` implementation that can read and write JSON by using Jackson's `ObjectMapper`.
412-
You can customize JSON mapping as needed through the use of Jackson's provided annotations.
413-
When you need further control (for cases where custom JSON serializers/deserializers need to be provided for specific types), you can inject a custom `ObjectMapper` through the `ObjectMapper` property.
414-
By default, this converter supports `application/json`.
415-
416-
| `MappingJackson2XmlHttpMessageConverter`
417-
| An `HttpMessageConverter` implementation that can read and write XML by using {jackson-github-org}/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`.
418-
You can customize XML mapping as needed through the use of JAXB or Jackson's provided annotations.
419-
When you need further control (for cases where custom XML serializers/deserializers need to be provided for specific types), you can inject a custom `XmlMapper` through the `ObjectMapper` property.
420-
By default, this converter supports `application/xml`.
421-
422-
| `SourceHttpMessageConverter`
423-
| An `HttpMessageConverter` implementation that can read and write `javax.xml.transform.Source` from the HTTP request and response.
424-
Only `DOMSource`, `SAXSource`, and `StreamSource` are supported.
425-
By default, this converter supports `text/xml` and `application/xml`.
426-
427-
|===
428-
429-
By default, `RestClient` and `RestTemplate` register all built-in message converters, depending on the availability of underlying libraries on the classpath.
430-
You can also set the message converters to use explicitly, by using the `messageConverters()` method on the `RestClient` builder, or via the `messageConverters` property of `RestTemplate`.
369+
xref:web/webmvc/message-converters.adoc#message-converters[See the supported HTTP message converters in the dedicated section].
431370

432371
==== Jackson JSON Views
433372

‎framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc

+13-1
Original file line numberDiff line numberDiff line change
@@ -453,7 +453,7 @@ The following table describes the available `WebExceptionHandler` implementation
453453

454454
[[webflux-codecs]]
455455
== Codecs
456-
[.small]#xref:integration/rest-clients.adoc#rest-message-conversion[See equivalent in the Servlet stack]#
456+
[.small]#xref:web/webmvc/message-converters.adoc#message-converters[See equivalent in the Servlet stack]#
457457

458458
The `spring-web` and `spring-core` modules provide support for serializing and
459459
deserializing byte content to and from higher level objects through non-blocking I/O with
@@ -562,6 +562,18 @@ for repeated, map-like access to parts, or otherwise rely on the
562562
`SynchronossPartHttpMessageReader` for a one-time access to `Flux<Part>`.
563563

564564

565+
[[webflux-codecs-protobuf]]
566+
=== Protocol Buffers
567+
568+
`ProtobufEncoder` and `ProtobufDecoder` supporting decoding and encoding "application/x-protobuf", "application/octet-stream"
569+
and "application/vnd.google.protobuf" content for `com.google.protobuf.Message` types. They also support stream of values
570+
if content is received/sent with the "delimited" parameter along the content type (like "application/x-protobuf;delimited=true").
571+
This requires the "com.google.protobuf:protobuf-java" library, version 3.29 and higher.
572+
573+
The `ProtobufJsonDecoder` and `ProtobufJsonEncoder` variants support reading and writing JSON documents to and from Protobuf messages.
574+
They require the "com.google.protobuf:protobuf-java-util" dependency. Note, the JSON variants do not support reading stream of messages,
575+
see the {spring-framework-api}/http/codec/protobuf/ProtobufJsonDecoder.html[javadoc of `ProtobufJsonDecoder`] for more details.
576+
565577
[[webflux-codecs-limits]]
566578
=== Limits
567579

‎framework-docs/modules/ROOT/pages/web/webmvc/message-converters.adoc

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
[[message-converters]]
2+
= HTTP Message Conversion
3+
4+
[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs[See equivalent in the Reactive stack]#
5+
6+
The `spring-web` module contains the `HttpMessageConverter` interface for reading and writing the body of HTTP requests and responses through `InputStream` and `OutputStream`.
7+
`HttpMessageConverter` instances are used on the client side (for example, in the `RestClient`) and on the server side (for example, in Spring MVC REST controllers).
8+
9+
Concrete implementations for the main media (MIME) types are provided in the framework and are, by default, registered with the `RestClient` and `RestTemplate` on the client side and with `RequestMappingHandlerAdapter` on the server side (see xref:web/webmvc/mvc-config/message-converters.adoc[Configuring Message Converters]).
10+
11+
Several implementations of `HttpMessageConverter` are described below.
12+
Refer to the {spring-framework-api}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list.
13+
For all converters, a default media type is used, but you can override it by setting the `supportedMediaTypes` property.
14+
15+
[[rest-message-converters-tbl]]
16+
.HttpMessageConverter Implementations
17+
[cols="1,3"]
18+
|===
19+
| MessageConverter | Description
20+
21+
| `StringHttpMessageConverter`
22+
| An `HttpMessageConverter` implementation that can read and write `String` instances from the HTTP request and response.
23+
By default, this converter supports all text media types(`text/{asterisk}`) and writes with a `Content-Type` of `text/plain`.
24+
25+
| `FormHttpMessageConverter`
26+
| An `HttpMessageConverter` implementation that can read and write form data from the HTTP request and response.
27+
By default, this converter reads and writes the `application/x-www-form-urlencoded` media type.
28+
Form data is read from and written into a `MultiValueMap<String, String>`.
29+
The converter can also write (but not read) multipart data read from a `MultiValueMap<String, Object>`.
30+
By default, `multipart/form-data` is supported.
31+
Additional multipart subtypes can be supported for writing form data.
32+
Consult the javadoc for `FormHttpMessageConverter` for further details.
33+
34+
| `ByteArrayHttpMessageConverter`
35+
| An `HttpMessageConverter` implementation that can read and write byte arrays from the HTTP request and response.
36+
By default, this converter supports all media types (`{asterisk}/{asterisk}`) and writes with a `Content-Type` of `application/octet-stream`.
37+
You can override this by setting the `supportedMediaTypes` property and overriding `getContentType(byte[])`.
38+
39+
| `MarshallingHttpMessageConverter`
40+
| An `HttpMessageConverter` implementation that can read and write XML by using Spring's `Marshaller` and `Unmarshaller` abstractions from the `org.springframework.oxm` package.
41+
This converter requires a `Marshaller` and `Unmarshaller` before it can be used.
42+
You can inject these through constructor or bean properties.
43+
By default, this converter supports `text/xml` and `application/xml`.
44+
45+
| `MappingJackson2HttpMessageConverter`
46+
| An `HttpMessageConverter` implementation that can read and write JSON by using Jackson's `ObjectMapper`.
47+
You can customize JSON mapping as needed through the use of Jackson's provided annotations.
48+
When you need further control (for cases where custom JSON serializers/deserializers need to be provided for specific types), you can inject a custom `ObjectMapper` through the `ObjectMapper` property.
49+
By default, this converter supports `application/json`. This requires the `com.fasterxml.jackson.core:jackson-databind` dependency.
50+
51+
| `MappingJackson2XmlHttpMessageConverter`
52+
| An `HttpMessageConverter` implementation that can read and write XML by using {jackson-github-org}/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`.
53+
You can customize XML mapping as needed through the use of JAXB or Jackson's provided annotations.
54+
When you need further control (for cases where custom XML serializers/deserializers need to be provided for specific types), you can inject a custom `XmlMapper` through the `ObjectMapper` property.
55+
By default, this converter supports `application/xml`. This requires the `com.fasterxml.jackson.dataformat:jackson-dataformat-xml` dependency.
56+
57+
| `MappingJackson2CborHttpMessageConverter`
58+
| `com.fasterxml.jackson.dataformat:jackson-dataformat-cbor`
59+
60+
| `SourceHttpMessageConverter`
61+
| An `HttpMessageConverter` implementation that can read and write `javax.xml.transform.Source` from the HTTP request and response.
62+
Only `DOMSource`, `SAXSource`, and `StreamSource` are supported.
63+
By default, this converter supports `text/xml` and `application/xml`.
64+
65+
| `GsonHttpMessageConverter`
66+
| An `HttpMessageConverter` implementation that can read and write JSON by using "Google Gson".
67+
This requires the `com.google.code.gson:gson` dependency.
68+
69+
| `JsonbHttpMessageConverter`
70+
| An `HttpMessageConverter` implementation that can read and write JSON by using the Jakarta Json Bind API.
71+
This requires the `jakarta.json.bind:jakarta.json.bind-api` dependency and an implementation available.
72+
73+
| `ProtobufHttpMessageConverter`
74+
| An `HttpMessageConverter` implementation that can read and write Protobuf messages in binary format with the `"application/x-protobuf"`
75+
content type. This requires the `com.google.protobuf:protobuf-java` dependency.
76+
77+
| `ProtobufJsonFormatHttpMessageConverter`
78+
| An `HttpMessageConverter` implementation that can read and write JSON documents to and from Protobuf messages.
79+
This requires the `com.google.protobuf:protobuf-java-util` dependency.
80+
81+
|===
82+
83+

0 commit comments

Comments
 (0)