From 91d17cf62882a436d506694ee840d59a2d751fed Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Fri, 27 Jul 2018 08:32:59 -0400 Subject: [PATCH] Add notes on future deprecation of the RestTemplate Issue: SPR-16993 --- .../web/client/RestOperations.java | 1 - .../web/client/RestTemplate.java | 60 ++++--------------- .../reactive/function/client/WebClient.java | 15 ++--- src/docs/asciidoc/integration.adoc | 20 ++++--- src/docs/asciidoc/web/webmvc-client.adoc | 29 ++++----- 5 files changed, 45 insertions(+), 80 deletions(-) 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 e16df2bcdb..b1df5af751 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 @@ -64,55 +64,20 @@ import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode; 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 @@ -123,7 +88,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 116350b335..85a20b2690 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,21 +43,18 @@ 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 the Javadoc for: + *

For examples with a response body see: *

- * For examples with a request body see: + *

For examples with a request body see: *