diff --git a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java index 69da49ba5e..afc9baa203 100644 --- a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java +++ b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java @@ -37,7 +37,6 @@ import org.springframework.lang.Nullable; * @author Juergen Hoeller * @since 3.0 * @see RestTemplate - * @see AsyncRestOperations */ public interface RestOperations { diff --git a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java index 8f6e87efe1..7315e3151f 100644 --- a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java +++ b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java @@ -60,55 +60,20 @@ import org.springframework.web.util.DefaultUriBuilderFactory; import org.springframework.web.util.UriTemplateHandler; /** - * Spring's central class for synchronous client-side HTTP access. - * It simplifies communication with HTTP servers, and enforces RESTful principles. - * It handles HTTP connections, leaving application code to provide URLs - * (with possible template variables) and extract results. + * Synchronous client to perform HTTP requests, exposing a simple, template + * method API over underlying HTTP client libraries such as the JDK + * {@code HttpURLConnection}, Apache HttpComponents, and others. * - *

Note: by default the RestTemplate relies on standard JDK - * facilities to establish HTTP connections. You can switch to use a different - * HTTP library such as Apache HttpComponents, Netty, and OkHttp through the - * {@link #setRequestFactory} property. + *

The RestTemplate offers templates for common scenarios by HTTP method, in + * addition to the generalized {@code exchange} and {@code execute} methods that + * support of less frequent cases. * - *

The main entry points of this template are the methods named after the six main HTTP methods: - * - * - * - * - * - * - * - * - * - * - * - *
HTTP methodRestTemplate methods
DELETE{@link #delete}
GET{@link #getForObject}
{@link #getForEntity}
HEAD{@link #headForHeaders}
OPTIONS{@link #optionsForAllow}
POST{@link #postForLocation}
{@link #postForObject}
PUT{@link #put}
any{@link #exchange}
{@link #execute}
- * - *

In addition the {@code exchange} and {@code execute} methods are generalized versions of - * the above methods and can be used to support additional, less frequent combinations (e.g. - * HTTP PATCH, HTTP PUT with response body, etc.). Note however that the underlying HTTP - * library used must also support the desired combination. - * - *

Note: For URI templates it is assumed encoding is necessary, e.g. - * {@code restTemplate.getForObject("http://example.com/hotel list")} becomes - * {@code "http://example.com/hotel%20list"}. This also means if the URI template - * or URI variables are already encoded, double encoding will occur, e.g. - * {@code http://example.com/hotel%20list} becomes - * {@code http://example.com/hotel%2520list}). To avoid that use a {@code URI} method - * variant to provide (or re-use) a previously encoded URI. To prepare such an URI - * with full control over encoding, consider using - * {@link org.springframework.web.util.UriComponentsBuilder}. - * - *

Internally the template uses {@link HttpMessageConverter} instances to - * convert HTTP messages to and from POJOs. Converters for the main mime types - * are registered by default but you can also register additional converters - * via {@link #setMessageConverters}. - * - *

This template uses a - * {@link org.springframework.http.client.SimpleClientHttpRequestFactory} and a - * {@link DefaultResponseErrorHandler} as default strategies for creating HTTP - * connections or handling HTTP errors, respectively. These defaults can be overridden - * through {@link #setRequestFactory} and {@link #setErrorHandler} respectively. + *

NOTE: As of 5.0, the non-blocking, reactive + * {@link org.springframework.web.reactive.client.WebClient WebClient} offers a + * modern alternative to the {@code RestTemplate} with efficient support for + * both sync and async, as well as streaming scenarios. The {@code RestTemplate} + * will be deprecated in a future version and will not have major new features + * gong forward. * * @author Arjen Poutsma * @author Brian Clozel @@ -119,7 +84,6 @@ import org.springframework.web.util.UriTemplateHandler; * @see RequestCallback * @see ResponseExtractor * @see ResponseErrorHandler - * @see AsyncRestTemplate */ public class RestTemplate extends InterceptingHttpAccessor implements RestOperations { diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java b/spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java index 657b8f70dd..cc2105b162 100644 --- a/spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java +++ b/spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java @@ -43,14 +43,11 @@ import org.springframework.web.util.UriBuilder; import org.springframework.web.util.UriBuilderFactory; /** - * A non-blocking, reactive client for performing HTTP requests with Reactive - * Streams back pressure. Provides a higher level, common API over HTTP client - * libraries. Reactor Netty is used by default but other clients may be plugged - * in with a {@link ClientHttpConnector}. + * Non-blocking, reactive client to perform HTTP requests, exposing a fluent, + * reactive API over underlying HTTP client libraries such as Reactor Netty. * - *

Use one of the static factory methods {@link #create()} or - * {@link #create(String)} or obtain a {@link WebClient#builder()} to create an - * instance. + *

Use static factory methods {@link #create()} or {@link #create(String)}, + * or {@link WebClient#builder()} to prepare an instance. * *

For examples with a response body see * {@link RequestHeadersSpec#retrieve() retrieve()} and diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 3532b3a3b8..c13a7b8683 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -950,14 +950,18 @@ plugging in third-party or custom solutions here. The Spring Framework provides two choices for making calls to REST endpoints: -* <> -- the original Spring REST client with an API similar to other -template classes in Spring such as `JdbcTemplate`, `JmsTemplate` and others. -`RestTemplate` has a synchronous API and relies on blocking I/O which is okay for -client scenarios with low concurrency. -* <> -- reactive client with a functional, -fluent API from the `spring-webflux` module. It relies on non-blocking I/O which allows it -to support high concurrency more efficiently (i.e. using a small number of threads) than the -`RestTemplate`. `WebClient` is a natural fit for streaming scenarios. +* <> -- the original Spring REST client with a synchronous, template +method API. +* <> -- non-blocking, reactive alternative +that supports both sync and async, as well as streaming scenarios. + +[NOTE] +==== +As of 5.0, the non-blocking, reactive `WebClient` offers a modern alternative to the +`RestTemplate` with efficient support for both sync and async, as well as streaming +scenarios. The `RestTemplate` will be deprecated in a future version and will not have +major new features gong forward. +==== [[rest-resttemplate]] diff --git a/src/docs/asciidoc/web/webmvc-client.adoc b/src/docs/asciidoc/web/webmvc-client.adoc index 92ced6c4a9..8aac741021 100644 --- a/src/docs/asciidoc/web/webmvc-client.adoc +++ b/src/docs/asciidoc/web/webmvc-client.adoc @@ -9,17 +9,19 @@ This section describes options for client-side access to REST endpoints. [[webmvc-resttemplate]] == RestTemplate -`RestTemplate` is the original Spring REST client that follows a similar approach to other -template classes in the Spring Framework (e.g. `JdbcTemplate`, `JmsTemplate`, etc.) by -providing a list of parameterizable methods to perform HTTP requests. +`RestTemplate` is a synchronous client to perform HTTP requests. It is the original +Spring REST client, exposing a simple, template method API over underlying HTTP client +libraries. -`RestTemplate` has a synchronous API and relies on blocking I/O. This is okay for -client scenarios with low concurrency. In a server environment or when orchestrating a -sequence of remote calls, prefer using the `WebClient` which provides a more efficient -execution model including seamless support for streaming. +[NOTE] +==== +As of 5.0, the non-blocking, reactive `WebClient` offers a modern alternative to the +`RestTemplate` with efficient support for both sync and async, as well as streaming +scenarios. The `RestTemplate` will be deprecated in a future version and will not have +major new features gong forward. +==== -See <> for more details on using the -`RestTemplate`. +See <> for details. @@ -27,9 +29,8 @@ See <> for more details on usi [[webmvc-webclient]] == WebClient -`WebClient` is a reactive client that provides an alternative to the `RestTemplate`. It -exposes a functional, fluent API and relies on non-blocking I/O which allows it to support -high concurrency more efficiently (i.e. using a small number of threads) than the -`RestTemplate`. `WebClient` is a natural fit for streaming scenarios. +`WebClient` is a non-blocking, reactive client to perform HTTP requests. It was +introduced in 5.0 and offers a modern alternative to the `RestTemplate` with efficient +support for both synchronous and asynchronous, as well as streaming scenarios. -See <> for more details on using the `WebClient`. +See <> for more details.