From 4cbaaa3b1d1badf01891f77d7df14ea0c10b1214 Mon Sep 17 00:00:00 2001 From: Brian Clozel Date: Wed, 19 Jun 2024 15:45:16 +0200 Subject: [PATCH] Move Servlet HTTP Message Conversion to its own section Closes gh-33063 --- framework-docs/modules/ROOT/nav.adoc | 1 + .../ROOT/pages/integration/rest-clients.adoc | 63 +------------- .../pages/web/webflux/reactive-spring.adoc | 14 +++- .../pages/web/webmvc/message-converters.adoc | 83 +++++++++++++++++++ 4 files changed, 98 insertions(+), 63 deletions(-) create mode 100644 framework-docs/modules/ROOT/pages/web/webmvc/message-converters.adoc diff --git a/framework-docs/modules/ROOT/nav.adoc b/framework-docs/modules/ROOT/nav.adoc index 867a49c5b4..c6ca6b14a2 100644 --- a/framework-docs/modules/ROOT/nav.adoc +++ b/framework-docs/modules/ROOT/nav.adoc @@ -248,6 +248,7 @@ **** xref:web/webmvc/mvc-servlet/multipart.adoc[] **** xref:web/webmvc/mvc-servlet/logging.adoc[] *** xref:web/webmvc/filters.adoc[] +*** xref:web/webmvc/message-converters.adoc[] *** xref:web/webmvc/mvc-controller.adoc[] **** xref:web/webmvc/mvc-controller/ann.adoc[] **** xref:web/webmvc/mvc-controller/ann-requestmapping.adoc[] diff --git a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc index ad47f5824d..fed6f92352 100644 --- a/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc +++ b/framework-docs/modules/ROOT/pages/integration/rest-clients.adoc @@ -366,68 +366,7 @@ val result = restClient.get() [[rest-message-conversion]] === HTTP Message Conversion -[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs[See equivalent in the Reactive stack]# - -The `spring-web` module contains the `HttpMessageConverter` interface for reading and writing the body of HTTP requests and responses through `InputStream` and `OutputStream`. -`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). - -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]). - -Several implementations of `HttpMessageConverter` are described below. -Refer to the {spring-framework-api}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list. -For all converters, a default media type is used, but you can override it by setting the `supportedMediaTypes` property. - -[[rest-message-converters-tbl]] -.HttpMessageConverter Implementations -[cols="1,3"] -|=== -| MessageConverter | Description - -| `StringHttpMessageConverter` -| An `HttpMessageConverter` implementation that can read and write `String` instances from the HTTP request and response. -By default, this converter supports all text media types(`text/{asterisk}`) and writes with a `Content-Type` of `text/plain`. - -| `FormHttpMessageConverter` -| An `HttpMessageConverter` implementation that can read and write form data from the HTTP request and response. -By default, this converter reads and writes the `application/x-www-form-urlencoded` media type. -Form data is read from and written into a `MultiValueMap`. -The converter can also write (but not read) multipart data read from a `MultiValueMap`. -By default, `multipart/form-data` is supported. -Additional multipart subtypes can be supported for writing form data. -Consult the javadoc for `FormHttpMessageConverter` for further details. - -| `ByteArrayHttpMessageConverter` -| An `HttpMessageConverter` implementation that can read and write byte arrays from the HTTP request and response. -By default, this converter supports all media types (`{asterisk}/{asterisk}`) and writes with a `Content-Type` of `application/octet-stream`. -You can override this by setting the `supportedMediaTypes` property and overriding `getContentType(byte[])`. - -| `MarshallingHttpMessageConverter` -| An `HttpMessageConverter` implementation that can read and write XML by using Spring's `Marshaller` and `Unmarshaller` abstractions from the `org.springframework.oxm` package. -This converter requires a `Marshaller` and `Unmarshaller` before it can be used. -You can inject these through constructor or bean properties. -By default, this converter supports `text/xml` and `application/xml`. - -| `MappingJackson2HttpMessageConverter` -| An `HttpMessageConverter` implementation that can read and write JSON by using Jackson's `ObjectMapper`. -You can customize JSON mapping as needed through the use of Jackson's provided annotations. -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. -By default, this converter supports `application/json`. - -| `MappingJackson2XmlHttpMessageConverter` -| An `HttpMessageConverter` implementation that can read and write XML by using {jackson-github-org}/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`. -You can customize XML mapping as needed through the use of JAXB or Jackson's provided annotations. -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. -By default, this converter supports `application/xml`. - -| `SourceHttpMessageConverter` -| An `HttpMessageConverter` implementation that can read and write `javax.xml.transform.Source` from the HTTP request and response. -Only `DOMSource`, `SAXSource`, and `StreamSource` are supported. -By default, this converter supports `text/xml` and `application/xml`. - -|=== - -By default, `RestClient` and `RestTemplate` register all built-in message converters, depending on the availability of underlying libraries on the classpath. -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`. +xref:web/webmvc/message-converters.adoc#message-converters[See the supported HTTP message converters in the dedicated section]. ==== Jackson JSON Views diff --git a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc index 13d527592c..995a8ca66c 100644 --- a/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc +++ b/framework-docs/modules/ROOT/pages/web/webflux/reactive-spring.adoc @@ -453,7 +453,7 @@ The following table describes the available `WebExceptionHandler` implementation [[webflux-codecs]] == Codecs -[.small]#xref:integration/rest-clients.adoc#rest-message-conversion[See equivalent in the Servlet stack]# +[.small]#xref:web/webmvc/message-converters.adoc#message-converters[See equivalent in the Servlet stack]# The `spring-web` and `spring-core` modules provide support for serializing and 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 `SynchronossPartHttpMessageReader` for a one-time access to `Flux`. +[[webflux-codecs-protobuf]] +=== Protocol Buffers + +`ProtobufEncoder` and `ProtobufDecoder` supporting decoding and encoding "application/x-protobuf", "application/octet-stream" +and "application/vnd.google.protobuf" content for `com.google.protobuf.Message` types. They also support stream of values +if content is received/sent with the "delimited" parameter along the content type (like "application/x-protobuf;delimited=true"). +This requires the "com.google.protobuf:protobuf-java" library, version 3.29 and higher. + +The `ProtobufJsonDecoder` and `ProtobufJsonEncoder` variants support reading and writing JSON documents to and from Protobuf messages. +They require the "com.google.protobuf:protobuf-java-util" dependency. Note, the JSON variants do not support reading stream of messages, +see the {spring-framework-api}/http/codec/protobuf/ProtobufJsonDecoder.html[javadoc of `ProtobufJsonDecoder`] for more details. + [[webflux-codecs-limits]] === Limits diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/message-converters.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/message-converters.adoc new file mode 100644 index 0000000000..2b86c30d53 --- /dev/null +++ b/framework-docs/modules/ROOT/pages/web/webmvc/message-converters.adoc @@ -0,0 +1,83 @@ +[[message-converters]] += HTTP Message Conversion + +[.small]#xref:web/webflux/reactive-spring.adoc#webflux-codecs[See equivalent in the Reactive stack]# + +The `spring-web` module contains the `HttpMessageConverter` interface for reading and writing the body of HTTP requests and responses through `InputStream` and `OutputStream`. +`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). + +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]). + +Several implementations of `HttpMessageConverter` are described below. +Refer to the {spring-framework-api}/http/converter/HttpMessageConverter.html[`HttpMessageConverter` Javadoc] for the complete list. +For all converters, a default media type is used, but you can override it by setting the `supportedMediaTypes` property. + +[[rest-message-converters-tbl]] +.HttpMessageConverter Implementations +[cols="1,3"] +|=== +| MessageConverter | Description + +| `StringHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write `String` instances from the HTTP request and response. +By default, this converter supports all text media types(`text/{asterisk}`) and writes with a `Content-Type` of `text/plain`. + +| `FormHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write form data from the HTTP request and response. +By default, this converter reads and writes the `application/x-www-form-urlencoded` media type. +Form data is read from and written into a `MultiValueMap`. +The converter can also write (but not read) multipart data read from a `MultiValueMap`. +By default, `multipart/form-data` is supported. +Additional multipart subtypes can be supported for writing form data. +Consult the javadoc for `FormHttpMessageConverter` for further details. + +| `ByteArrayHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write byte arrays from the HTTP request and response. +By default, this converter supports all media types (`{asterisk}/{asterisk}`) and writes with a `Content-Type` of `application/octet-stream`. +You can override this by setting the `supportedMediaTypes` property and overriding `getContentType(byte[])`. + +| `MarshallingHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write XML by using Spring's `Marshaller` and `Unmarshaller` abstractions from the `org.springframework.oxm` package. +This converter requires a `Marshaller` and `Unmarshaller` before it can be used. +You can inject these through constructor or bean properties. +By default, this converter supports `text/xml` and `application/xml`. + +| `MappingJackson2HttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write JSON by using Jackson's `ObjectMapper`. +You can customize JSON mapping as needed through the use of Jackson's provided annotations. +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. +By default, this converter supports `application/json`. This requires the `com.fasterxml.jackson.core:jackson-databind` dependency. + +| `MappingJackson2XmlHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write XML by using {jackson-github-org}/jackson-dataformat-xml[Jackson XML] extension's `XmlMapper`. +You can customize XML mapping as needed through the use of JAXB or Jackson's provided annotations. +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. +By default, this converter supports `application/xml`. This requires the `com.fasterxml.jackson.dataformat:jackson-dataformat-xml` dependency. + +| `MappingJackson2CborHttpMessageConverter` +| `com.fasterxml.jackson.dataformat:jackson-dataformat-cbor` + +| `SourceHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write `javax.xml.transform.Source` from the HTTP request and response. +Only `DOMSource`, `SAXSource`, and `StreamSource` are supported. +By default, this converter supports `text/xml` and `application/xml`. + +| `GsonHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write JSON by using "Google Gson". +This requires the `com.google.code.gson:gson` dependency. + +| `JsonbHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write JSON by using the Jakarta Json Bind API. +This requires the `jakarta.json.bind:jakarta.json.bind-api` dependency and an implementation available. + +| `ProtobufHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write Protobuf messages in binary format with the `"application/x-protobuf"` +content type. This requires the `com.google.protobuf:protobuf-java` dependency. + +| `ProtobufJsonFormatHttpMessageConverter` +| An `HttpMessageConverter` implementation that can read and write JSON documents to and from Protobuf messages. +This requires the `com.google.protobuf:protobuf-java-util` dependency. + +|=== + +