root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Improve HTTP message reading/writing docs 

Cross-reference sections on HttpMessageReader/Writer and
HttpMessageConverter and improve the content.

Issue: SPR-16260
This commit is contained in:
Rossen Stoyanchev 2018-01-04 21:15:04 -05:00
parent 0f1f95e090
commit 7bf9b767fd
3 changed files with 48 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
src/docs/asciidoc/integration.adoc
View File

@ -1232,39 +1232,18 @@ to serialize only a subset of the object properties. For example:
[[rest-message-conversion]] [[rest-message-conversion]]
==== HTTP message conversion ==== HTTP Message Converters
[.small]#<<web-reactive.adoc#webflux-codecs,Same in Spring WebFlux>>#
Objects passed to and returned from the methods `getForObject()`, `postForLocation()`, The `spring-web` module contains the `HttpMessageConverter` contract for reading and
and `put()` are converted to HTTP requests and from HTTP responses by writing the body of HTTP requests and responses via `InputStream` and `OutputStream`.
`HttpMessageConverters`. The `HttpMessageConverter` interface is shown below to give you ``HttpMessageConverter``'s are used on the client side, e.g. in the `RestTemplate`, and
a better feel for its functionality also on the server side, e.g. in Spring MVC REST controllers.
[source,java,indent=0]
[subs="verbatim,quotes"]
----
public interface HttpMessageConverter<T> {
// Indicate whether the given class and media type can be read by this converter.
boolean canRead(Class<?> clazz, MediaType mediaType);
// Indicate whether the given class and media type can be written by this converter.
boolean canWrite(Class<?> clazz, MediaType mediaType);
// Return the list of MediaType objects supported by this converter.
List<MediaType> getSupportedMediaTypes();
// Read an object of the given type from the given input message, and returns it.
T read(Class<T> clazz, HttpInputMessage inputMessage) throws IOException, HttpMessageNotReadableException;
// Write an given object to the given output message.
void write(T t, HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException;
}
----
Concrete implementations for the main media (mime) types are provided in the framework Concrete implementations for the main media (mime) types are provided in the framework
and are registered by default with the `RestTemplate` on the client-side and with and are registered by default with the `RestTemplate` on the client-side and with
`RequestMethodHandlerAdapter` on the server-side. `RequestMethodHandlerAdapter` on the server-side (see
<<web.adoc#mvc-config-message-converters,Configuring Message Converters>>).
The implementations of ``HttpMessageConverter``s are described in the following sections. The implementations of ``HttpMessageConverter``s are described in the following sections.
For all converters a default media type is used but can be overridden by setting the For all converters a default media type is used but can be overridden by setting the

50
src/docs/asciidoc/web/webflux.adoc
View File

@ -110,9 +110,10 @@ of RxJava or other reactive library. See <<webflux-reactive-libraries>> for more
[[webflux-programming-models]] [[webflux-programming-models]]
=== Programming models === Programming models
The `spring-web` module contains the reactive foundation that underlies Spring WebFlux -- The `spring-web` module contains the reactive foundation that underlies Spring WebFlux
HTTP abstractions, Reactive Streams server adapters, reactive codecs, and a including HTTP abstractions, Reactive Streams <<webflux-httphandler,adapters>> for supported
core Web API whose role is comparable to the Servlet API but with non-blocking semantics. servers, <<webflux-codecs,codecs>>, and a core <<webflux-web-handler-api>> comparable to
the Servlet API but with non-blocking contracts.
On that foundation Spring WebFlux provides a choice of two programming models: On that foundation Spring WebFlux provides a choice of two programming models:
@ -425,31 +426,34 @@ to have the following detected:
[[webflux-codecs]] [[webflux-codecs]]
=== Codecs === HTTP Message Codecs
[.small]#<<integration.adoc#rest-message-conversion,Same in Spring MVC>>#
The `spring-web` module provides The `spring-web` module defines the
{api-spring-framework}/http/codec/HttpMessageReader.html[HttpMessageReader] and {api-spring-framework}/http/codec/HttpMessageReader.html[HttpMessageReader] and
{api-spring-framework}/http/codec/HttpMessageWriter.html[HttpMessageWriter] {api-spring-framework}/http/codec/HttpMessageWriter.html[HttpMessageWriter] contracts
for encoding and decoding the HTTP request and response body with Reactive Streams. for encoding and decoding the body of HTTP requests and responses via Rective Streams
It builds on lower level contracts from `spring-core`: ``Publisher``'s. These contacts are used on the client side, e.g. in the `WebClient`,
and on the server side, e.g. in annotated controllers and functional endpoints.
* {api-spring-framework}/core/io/buffer/DataBuffer.html[DataBuffer] -- abstraction for The `spring-core` module defines the
byte buffers -- e.g. Netty `ByteBuf`, `java.nio.ByteBuffer`, see {api-spring-framework}/core/codec/Encoder.html[Encoder] and
<<core#databuffers, Data Buffers and Codecs>>. {api-spring-framework}/core/codec/Decoder.html[Decoder] contracts that are independent of
* {api-spring-framework}/core/codec/Encoder.html[Encoder] -- serialize a stream of Objects HTTP and rely on the {api-spring-framework}/core/io/buffer/DataBuffer.html[DataBuffer]
to a stream of data buffers contract that abstracts different byte buffer representations such as the Netty `ByteBuf`
* {api-spring-framework}/core/codec/Decoder.html[Decoder] -- deserialize a stream of data and `java.nio.ByteBuffer` (see <<core#databuffers, Data Buffers and Codecs>>).
buffers into a stream of Objects An `Encoder` can be wrapped with `EncoderHttpMessageWriter` to be used as an
`HttpMessageWriter` while a `Decoder` can be wrapped with `DecoderHttpMessageReader` to
be used as an `HttpMessageReader`.
Basic `Encoder` and `Decoder` implementations exist in `spring-core` but `spring-web` adds The `spring-core` module contains basic `Encoder` and `Decoder` implementations for
more for JSON, XML, and other formats. You can wrap any `Encoder` and `Decoder` as a reader `byte[]`, `ByteBuffer`, `DataBuffer`, `Resource`, and `String`. The `spring-web` module
or writer with `EncoderHttpMessageWriter` and `DecoderHttpMessageReader`. There are some adds ``Encoder``'s and ``Decoder``'s for Jackson JSON, Jackson Smile, and JAXB2.
additional, web-only reader and writer implementations for server-sent events, form data, The `spring-web` module also contains some web-specific readers and writers for
and more. server-sent events, form data, and multipart requests.
Finally, `ClientCodecConfigurer` and `ServerCodecConfigurer` can be used to initialize To configure or customize the readers and writers to use applications will typically use
a list of readers and writers. They include support for classpath detection and a `ClientCodecConfigurer` or `ServerCodecConfigurer`.
of defaults along with the ability to override or replace those defaults.

24
src/docs/asciidoc/web/webmvc.adoc
View File

@ -2274,7 +2274,8 @@ You could access the part named "meta-data" with a `@RequestParam("meta-data") S
metadata` controller method argument. However, you would probably prefer to accept a metadata` controller method argument. However, you would probably prefer to accept a
strongly typed object initialized from the JSON formatted data in the body of the strongly typed object initialized from the JSON formatted data in the body of the
request part, very similar to the way `@RequestBody` converts the body of a request part, very similar to the way `@RequestBody` converts the body of a
non-multipart request to a target object with the help of an `HttpMessageConverter`. non-multipart request to a target object with the help of an
<<integration.adoc#rest-message-conversion,HttpMessageConverter>>.
You can use the `@RequestPart` annotation instead of the `@RequestParam` annotation for You can use the `@RequestPart` annotation instead of the `@RequestParam` annotation for
this purpose. It allows you to have the content of a specific multipart passed through this purpose. It allows you to have the content of a specific multipart passed through
@ -2314,7 +2315,8 @@ be bound to the value of the HTTP request body. For example:
} }
---- ----
You convert the request body to the method argument by using an `HttpMessageConverter`. You convert the request body to the method argument by using an
<<integration.adoc#rest-message-conversion,HttpMessageConverter>>.
`HttpMessageConverter` is responsible for converting from the HTTP request message to an `HttpMessageConverter` is responsible for converting from the HTTP request message to an
object and converting from an object to the HTTP response body. The object and converting from an object to the HTTP response body. The
`RequestMappingHandlerAdapter` supports the `@RequestBody` annotation with the following `RequestMappingHandlerAdapter` supports the `@RequestBody` annotation with the following
@ -2422,8 +2424,7 @@ The above example will result in the text `Hello World` being written to the HTT
response stream. response stream.
As with `@RequestBody`, Spring converts the returned object to a response body by using As with `@RequestBody`, Spring converts the returned object to a response body by using
an `HttpMessageConverter`. For more information on these converters, see the previous an <<integration.adoc#rest-message-conversion,HttpMessageConverter>>.
section and <<integration.adoc#rest-message-conversion,Message Converters>>.
[[mvc-ann-responseentity]] [[mvc-ann-responseentity]]
@ -2443,7 +2444,8 @@ also allows setting response headers:
} }
---- ----
As with `@ResponseBody`, Spring uses `HttpMessageConverter` to As with `@ResponseBody`, Spring uses
<<integration.adoc#rest-message-conversion,HttpMessageConverter>> to
convert from and to the request and response streams. For more information on these convert from and to the request and response streams. For more information on these
converters, see the previous section and <<integration.adoc#rest-message-conversion, converters, see the previous section and <<integration.adoc#rest-message-conversion,
Message Converters>>. Message Converters>>.
@ -3353,7 +3355,7 @@ This is a technique related to "Long Polling" that is known as "HTTP Streaming".
Spring MVC makes this possible through the `ResponseBodyEmitter` return value Spring MVC makes this possible through the `ResponseBodyEmitter` return value
type which can be used to send multiple Objects, instead of one as is normally type which can be used to send multiple Objects, instead of one as is normally
the case with `@ResponseBody`, where each Object sent is written to the the case with `@ResponseBody`, where each Object sent is written to the
response with an `HttpMessageConverter`. response with an <<integration.adoc#rest-message-conversion,HttpMessageConverter>>.
Here is an example of that: Here is an example of that:
@ -3412,11 +3414,11 @@ http://blog.pivotal.io/pivotal/products/websocket-architecture-in-spring-4-0[the
=== Streaming raw data === Streaming raw data
`ResponseBodyEmitter` allows sending events by writing Objects to the `ResponseBodyEmitter` allows sending events by writing Objects to the
response through an `HttpMessageConverter`. This is probably the most common response through an <<integration.adoc#rest-message-conversion,HttpMessageConverter>>.
case, for example when writing JSON data. However sometimes it is useful to This is probably the most common case, for example when writing JSON data.
bypass message conversion and write directly to the response `OutputStream` However sometimes it is useful to bypass message conversion and write directly to the
for example for a file download. This can be done with the help of the response `OutputStream` for example for a file download. This can be done with the help
`StreamingResponseBody` return value type. of the `StreamingResponseBody` return value type.
Here is an example of that: Here is an example of that: