Add notes on future deprecation of the RestTemplate

Issue: SPR-16993

Author: rstoyanchev

spring-web/src/main/java/org/springframework/web/client/RestOperations.java

@@ -37,7 +37,6 @@
  * @author Juergen Hoeller
  * @since 3.0
  * @see RestTemplate
- * @see AsyncRestOperations
  */
 public interface RestOperations {
 

spring-web/src/main/java/org/springframework/web/client/RestTemplate.java

@@ -64,55 +64,20 @@
 import org.springframework.web.util.UriTemplateHandler;
 
 /**
- * <strong>Spring's central class for synchronous client-side HTTP access.</strong>
- * 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.
  *
- * <p><strong>Note:</strong> 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.
+ * <p>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.
  *
- * <p>The main entry points of this template are the methods named after the six main HTTP methods:
- * <table>
- * <tr><th>HTTP method</th><th>RestTemplate methods</th></tr>
- * <tr><td>DELETE</td><td>{@link #delete}</td></tr>
- * <tr><td>GET</td><td>{@link #getForObject}</td></tr>
- * <tr><td></td><td>{@link #getForEntity}</td></tr>
- * <tr><td>HEAD</td><td>{@link #headForHeaders}</td></tr>
- * <tr><td>OPTIONS</td><td>{@link #optionsForAllow}</td></tr>
- * <tr><td>POST</td><td>{@link #postForLocation}</td></tr>
- * <tr><td></td><td>{@link #postForObject}</td></tr>
- * <tr><td>PUT</td><td>{@link #put}</td></tr>
- * <tr><td>any</td><td>{@link #exchange}</td></tr>
- * <tr><td></td><td>{@link #execute}</td></tr> </table>
- *
- * <p>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.
- *
- * <p><strong>Note:</strong> 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}.
- *
- * <p>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}.
- *
- * <p>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.
+ * <p><strong>NOTE:</strong> 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 @@
  * @see RequestCallback
  * @see ResponseExtractor
  * @see ResponseErrorHandler
- * @see AsyncRestTemplate
  */
 public class RestTemplate extends InterceptingHttpAccessor implements RestOperations {
 

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java

@@ -43,21 +43,18 @@
 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.
  *
- * <p>Use one of the static factory methods {@link #create()} or
- * {@link #create(String)} or obtain a {@link WebClient#builder()} to create an
- * instance.
+ * <p>Use static factory methods {@link #create()} or {@link #create(String)},
+ * or {@link WebClient#builder()} to prepare an instance.
  *
- * <p>For examples with a response body, see the Javadoc for:
+ * <p>For examples with a response body see:
  * <ul>
  * <li>{@link RequestHeadersSpec#retrieve() retrieve()}
  * <li>{@link RequestHeadersSpec#exchange() exchange()}
  * </ul>
- * For examples with a request body see:
+ * <p>For examples with a request body see:
  * <ul>
  * <li>{@link RequestBodySpec#body(Publisher, Class) body(Publisher,Class)}
  * <li>{@link RequestBodySpec#syncBody(Object) syncBody(Object)}

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:
 
-* <<rest-resttemplate>> -- 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.
-* <<web-reactive.adoc#webflux-client,WebClient>> -- 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.
+* <<rest-resttemplate>> -- the original Spring REST client with a synchronous, template
+method API.
+* <<web-reactive.adoc#webflux-client,WebClient>> -- 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]]

src/docs/asciidoc/web/webmvc-client.adoc

@@ -9,27 +9,28 @@ 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 <<integration.adoc#rest-client-access,RestTemplate>> for more details on using the
-`RestTemplate`.
+See <<integration.adoc#rest-client-access,RestTemplate>> for details.
 
 
 
 
 [[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 <<web-reactive.adoc#webflux-client,WebClient>> for more details on using the `WebClient`.
+See <<web-reactive.adoc#webflux-client,WebClient>> for more details.