Revise documentation on using WebClient::exchange

This commit revised the paragraph regarding the need to consume or
release the ClientResponse body when using WebClient::exchange.

Closes gh-23498
This commit is contained in:
Arjen Poutsma 2019-09-03 10:49:39 +02:00
parent 37398c669c
commit 4c863f3f83
1 changed files with 13 additions and 5 deletions

View File

@ -462,12 +462,20 @@ At this level, you can also create a full `ResponseEntity`:
Note that (unlike `retrieve()`), with `exchange()`, there are no automatic error signals for
4xx and 5xx responses. You have to check the status code and decide how to proceed.
CAUTION: When you use `exchange()`, you must always use any of the `body` or `toEntity` methods of
`ClientResponse` to ensure resources are released and to avoid potential issues with HTTP
connection pooling. You can use `bodyToMono(Void.class)` if no response content is
expected. However, if the response does have content, the connection
is closed and is not placed back in the pool.
[CAUTION]
====
When using `exchange()`, you have to make sure that the body is always consumed or released,
even when an exception occurs (see <<core.adoc#databuffers-using,Using DataBuffer>>).
Typically, you do this by invoking either `bodyTo*` or `toEntity*` on `ClientResponse`
to convert the body into an object of the desired type, but
you can also invoke `releaseBody()` to discard the body contents without consuming it or
`toBodilessEntity()` to get just the status and headers (while discarding the body).
Finally, there is `bodyToMono(Void.class)`, which should only be used if no response content is
expected.
If the response does have content, the connection is closed and is not placed back in the pool,
because it is not left in a reusable state.
====