mirror of
https://github.com/spring-projects/spring-framework.git
synced 2026-09-22 14:09:25 +00:00
Brian Clozel
ab8de8ec4b
Prior to this commit, the `FormHttpMessageConverter` would only support `MultiValueMap` payloads for reading and writing. While this can be useful when web forms contain multiple values under the same key, this prevent developers from using a common `Map` type and factory methods like `Map.of(...)`. This commit relaxes constraints in `FormHttpMessageConverter` and ensures that `Map` types are supported for reading and writing URL encoded forms. Note that when reading forms to a `Map`, only the first value for each key will be considered and other values will be dropped if they exist. Closes gh-36408
91 lines
6.0 KiB
Plaintext
91 lines
6.0 KiB
Plaintext
[[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 URL encoded forms.
|
|
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<String, String>`.
|
|
`Map<String, String>` is also supported, but multiple values under the same key will be ignored.
|
|
|
|
| `MultipartHttpMessageConverter`
|
|
| An `HttpMessageConverter` implementation that can read and write multipart messages.
|
|
`MultiValueMap<String, Object>` can be written to multipart messages, converting each part independently using
|
|
the configured message converters. Multipart messages can be read into `MultiValueMap<String, Part>`, each value
|
|
being a `Part` or one of its subtypes (`FormFieldPart` and `FilePart`).
|
|
By default, `multipart/form-data` is supported. Additional multipart subtypes can be supported for writing form data.
|
|
|
|
| `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`.
|
|
|
|
| `JacksonJsonHttpMessageConverter`
|
|
| An `HttpMessageConverter` implementation that can read and write JSON by using Jackson's `JsonMapper`.
|
|
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 `JsonMapper` through the `JsonMapper` or `JsonMapper.Builder` constructor parameters.
|
|
By default, this converter supports `application/json`. This requires the `tools.jackson.core:jackson-databind` dependency.
|
|
|
|
| `JacksonXmlHttpMessageConverter`
|
|
| 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 `JsonMapper` or `JsonMapper.Builder` constructor parameters.
|
|
By default, this converter supports `application/xml`. This requires the `tools.jackson.dataformat:jackson-dataformat-xml` dependency.
|
|
|
|
| `KotlinSerializationJsonHttpMessageConverter`
|
|
| An `HttpMessageConverter` implementation that can read and write JSON using `kotlinx.serialization`.
|
|
This converter is not configured by default, as this conflicts with Jackson.
|
|
Developers must configure it as an additional converter ahead of the Jackson one.
|
|
|
|
| `JacksonCborHttpMessageConverter`
|
|
| `tools.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.
|
|
|
|
|===
|