Polishing

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,12 +29,14 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.util.concurrent.ListenableFuture;
 
 /**
- * Interface specifying a basic set of asynchronous RESTful operations. Implemented by
- * {@link AsyncRestTemplate}. Not often used directly, but a useful option to enhance
- * testability, as it can easily be mocked or stubbed.
+ * Interface specifying a basic set of asynchronous RESTful operations.
+ * Implemented by {@link AsyncRestTemplate}. Not often used directly, but a useful
+ * option to enhance testability, as it can easily be mocked or stubbed.
  *
  * @author Arjen Poutsma
  * @since 4.0
+ * @see AsyncRestTemplate
+ * @see RestOperations
  */
 public interface AsyncRestOperations {
 
@@ -47,8 +49,8 @@ public interface AsyncRestOperations {
 	// GET
 
 	/**
-	 * Asynchronously retrieve an entity by doing a GET on the specified URL. The response is
-	 * converted and stored in an {@link ResponseEntity}.
+	 * Asynchronously retrieve an entity by doing a GET on the specified URL.
+	 * The response is converted and stored in an {@link ResponseEntity}.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * @param url the URL
 	 * @param responseType the type of the return value
@@ -59,8 +61,8 @@ public interface AsyncRestOperations {
 			Object... uriVariables) throws RestClientException;
 
 	/**
-	 * Asynchronously retrieve a representation by doing a GET on the URI template. The
-	 * response is converted and stored in an {@link ResponseEntity}.
+	 * Asynchronously retrieve a representation by doing a GET on the URI template.
+	 * The response is converted and stored in an {@link ResponseEntity}.
 	 * <p>URI Template variables are expanded using the given map.
 	 * @param url the URL
 	 * @param responseType the type of the return value
@@ -80,6 +82,7 @@ public interface AsyncRestOperations {
 	<T> ListenableFuture<ResponseEntity<T>> getForEntity(URI url, Class<T> responseType)
 			throws RestClientException;
 
+
 	// HEAD
 
 	/**
@@ -109,6 +112,7 @@ public interface AsyncRestOperations {
 	 */
 	ListenableFuture<HttpHeaders> headForHeaders(URI url) throws RestClientException;
 
+
 	// POST
 
 	/**
@@ -117,7 +121,7 @@ public interface AsyncRestOperations {
 	 * typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the value for the {@code Location} header wrapped in a {@link Future}
 	 * @see org.springframework.http.HttpEntity
@@ -131,7 +135,7 @@ public interface AsyncRestOperations {
 	 * typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given map.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the value for the {@code Location} header wrapped in a {@link Future}
 	 * @see org.springframework.http.HttpEntity
@@ -144,7 +148,7 @@ public interface AsyncRestOperations {
 	 * returns the value of the {@code Location} header. This header typically indicates
 	 * where the new resource is stored.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the value for the {@code Location} header wrapped in a {@link Future}
 	 * @see org.springframework.http.HttpEntity
 	 */
@@ -155,7 +159,7 @@ public interface AsyncRestOperations {
 	 * and asynchronously returns the response as {@link ResponseEntity}.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the entity wrapped in a {@link Future}
 	 * @see org.springframework.http.HttpEntity
@@ -168,26 +172,26 @@ public interface AsyncRestOperations {
 	 * and asynchronously returns the response as {@link ResponseEntity}.
 	 * <p>URI Template variables are expanded using the given map.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the entity wrapped in a {@link Future}
 	 * @see org.springframework.http.HttpEntity
 	 */
 	<T> ListenableFuture<ResponseEntity<T>> postForEntity(String url, HttpEntity<?> request,
-			Class<T> responseType, Map<String, ?> uriVariables)
-			throws RestClientException;
+			Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException;
 
 	/**
 	 * Create a new resource by POSTing the given object to the URL,
 	 * and asynchronously returns the response as {@link ResponseEntity}.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the entity wrapped in a {@link Future}
 	 * @see org.springframework.http.HttpEntity
 	 */
 	<T> ListenableFuture<ResponseEntity<T>> postForEntity(URI url, HttpEntity<?> request,
 			Class<T> responseType) throws RestClientException;
 
+
 	// PUT
 
 	/**
@@ -195,7 +199,7 @@ public interface AsyncRestOperations {
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The Future will return a {@code null} result upon completion.
 	 * @param url the URL
-	 * @param request the Object to be PUT, may be {@code null}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @see HttpEntity
 	 */
@@ -207,7 +211,7 @@ public interface AsyncRestOperations {
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The Future will return a {@code null} result upon completion.
 	 * @param url the URL
-	 * @param request the Object to be PUT, may be {@code null}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @see HttpEntity
 	 */
@@ -218,11 +222,12 @@ public interface AsyncRestOperations {
 	 * Creates a new resource by PUTting the given object to URL.
 	 * <p>The Future will return a {@code null} result upon completion.
 	 * @param url the URL
-	 * @param request the Object to be PUT, may be {@code null}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @see HttpEntity
 	 */
 	ListenableFuture<?> put(URI url, HttpEntity<?> request) throws RestClientException;
 
+
 	// DELETE
 
 	/**
@@ -251,6 +256,7 @@ public interface AsyncRestOperations {
 	 */
 	ListenableFuture<?> delete(URI url) throws RestClientException;
 
+
 	// OPTIONS
 
 	/**
@@ -344,7 +350,7 @@ public interface AsyncRestOperations {
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
 	 * @param requestEntity the entity (headers and/or body) to write to the
-	 * request, may be {@code null}
+	 * request (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand in the template
 	 * @return the response as entity wrapped in a {@link Future}
@@ -364,7 +370,8 @@ public interface AsyncRestOperations {
 	 * </pre>
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
-	 * @param requestEntity the entity (headers and/or body) to write to the request, may be {@code null}
+	 * @param requestEntity the entity (headers and/or body) to write to the request
+	 * (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand in the template
 	 * @return the response as entity wrapped in a {@link Future}
@@ -384,7 +391,8 @@ public interface AsyncRestOperations {
 	 * </pre>
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
-	 * @param requestEntity the entity (headers and/or body) to write to the request, may be {@code null}
+	 * @param requestEntity the entity (headers and/or body) to write to the request
+	 * (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @return the response as entity wrapped in a {@link Future}
 	 */

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

@@ -53,10 +53,8 @@ import org.springframework.web.util.UriTemplateHandler;
  * wrappers as opposed to concrete results.
  *
  * <p>The {@code AsyncRestTemplate} exposes a synchronous {@link RestTemplate} via the
- * {@link #getRestOperations()} method, and it shares its
- * {@linkplain #setErrorHandler(ResponseErrorHandler) error handler} and
- * {@linkplain #setMessageConverters(List) message converters} with this
- * {@code RestTemplate}.
+ * {@link #getRestOperations()} method and shares its {@linkplain #setErrorHandler error handler}
+ * and {@linkplain #setMessageConverters message converters} with that {@code RestTemplate}.
  *
  * <p><strong>Note:</strong> by default {@code AsyncRestTemplate} relies on
  * standard JDK facilities to establish HTTP connections. You can switch to use

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

@@ -28,9 +28,9 @@ import org.springframework.http.RequestEntity;
 import org.springframework.http.ResponseEntity;
 
 /**
- * Interface specifying a basic set of RESTful operations. Implemented by {@link RestTemplate}.
- * Not often used directly, but a useful option to enhance testability, as it can easily
- * be mocked or stubbed.
+ * Interface specifying a basic set of RESTful operations.
+ * Implemented by {@link RestTemplate}. Not often used directly, but a useful
+ * option to enhance testability, as it can easily be mocked or stubbed.
  *
  * @author Arjen Poutsma
  * @author Juergen Hoeller
@@ -139,13 +139,13 @@ public interface RestOperations {
 	// POST
 
 	/**
-	 * Create a new resource by POSTing the given object to the URI template, and returns the value of the
-	 * {@code Location} header. This header typically indicates where the new resource is stored.
+	 * Create a new resource by POSTing the given object to the URI template, and returns the value of
+	 * the {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the value for the {@code Location} header
 	 * @see HttpEntity
@@ -153,13 +153,13 @@ public interface RestOperations {
 	URI postForLocation(String url, Object request, Object... uriVariables) throws RestClientException;
 
 	/**
-	 * Create a new resource by POSTing the given object to the URI template, and returns the value of the
-	 * {@code Location} header. This header typically indicates where the new resource is stored.
+	 * Create a new resource by POSTing the given object to the URI template, and returns the value of
+	 * the {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the value for the {@code Location} header
 	 * @see HttpEntity
@@ -172,7 +172,7 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the value for the {@code Location} header
 	 * @see HttpEntity
 	 */
@@ -185,7 +185,7 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
@@ -201,7 +201,7 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
@@ -216,7 +216,7 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @return the converted object
 	 * @see HttpEntity
@@ -230,11 +230,11 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
-	 * @see HttpEntity
 	 * @since 3.0.2
+	 * @see HttpEntity
 	 */
 	<T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Object... uriVariables)
 			throws RestClientException;
@@ -246,11 +246,11 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
-	 * @see HttpEntity
 	 * @since 3.0.2
+	 * @see HttpEntity
 	 */
 	<T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables)
 			throws RestClientException;
@@ -261,10 +261,10 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the converted object
-	 * @see HttpEntity
 	 * @since 3.0.2
+	 * @see HttpEntity
 	 */
 	<T> ResponseEntity<T> postForEntity(URI url, Object request, Class<T> responseType) throws RestClientException;
 
@@ -277,7 +277,7 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be PUT, may be {@code null}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @see HttpEntity
 	 */
@@ -289,7 +289,7 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be PUT, may be {@code null}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @see HttpEntity
 	 */
@@ -300,7 +300,7 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be PUT, may be {@code null}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @see HttpEntity
 	 */
 	void put(URI url, Object request) throws RestClientException;
@@ -315,12 +315,12 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be PATCHed, may be {@code null}
+	 * @param request the Object to be PATCHed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
+	 * @since 4.3.5
 	 * @see HttpEntity
-	 * @since 5.0
 	 */
 	<T> T patchForObject(String url, Object request, Class<T> responseType, Object... uriVariables)
 			throws RestClientException;
@@ -332,10 +332,11 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be PATCHed, may be {@code null}
+	 * @param request the Object to be PATCHed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
+	 * @since 4.3.5
 	 * @see HttpEntity
 	 */
 	<T> T patchForObject(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables)
@@ -347,9 +348,10 @@ public interface RestOperations {
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
 	 * add additional HTTP headers to the request.
 	 * @param url the URL
-	 * @param request the Object to be POSTed, may be {@code null}
+	 * @param request the Object to be PATCHed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @return the converted object
+	 * @since 4.3.5
 	 * @see HttpEntity
 	 */
 	<T> T patchForObject(URI url, Object request, Class<T> responseType) throws RestClientException;
@@ -418,7 +420,8 @@ public interface RestOperations {
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
-	 * @param requestEntity the entity (headers and/or body) to write to the request, may be {@code null}
+	 * @param requestEntity the entity (headers and/or body) to write to the request
+	 * may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand in the template
 	 * @return the response as entity
@@ -433,7 +436,8 @@ public interface RestOperations {
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
-	 * @param requestEntity the entity (headers and/or body) to write to the request, may be {@code null}
+	 * @param requestEntity the entity (headers and/or body) to write to the request
+	 * (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand in the template
 	 * @return the response as entity
@@ -447,7 +451,8 @@ public interface RestOperations {
 	 * returns the response as {@link ResponseEntity}.
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
-	 * @param requestEntity the entity (headers and/or body) to write to the request, may be {@code null}
+	 * @param requestEntity the entity (headers and/or body) to write to the request
+	 * (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @return the response as entity
 	 * @since 3.0.2
@@ -466,7 +471,7 @@ public interface RestOperations {
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
 	 * @param requestEntity the entity (headers and/or body) to write to the
-	 * request, may be {@code null}
+	 * request (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand in the template
 	 * @return the response as entity
@@ -485,7 +490,8 @@ public interface RestOperations {
 	 * </pre>
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
-	 * @param requestEntity the entity (headers and/or body) to write to the request, may be {@code null}
+	 * @param requestEntity the entity (headers and/or body) to write to the request
+	 * (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand in the template
 	 * @return the response as entity
@@ -504,7 +510,8 @@ public interface RestOperations {
 	 * </pre>
 	 * @param url the URL
 	 * @param method the HTTP method (GET, POST, etc)
-	 * @param requestEntity the entity (headers and/or body) to write to the request, may be {@code null}
+	 * @param requestEntity the entity (headers and/or body) to write to the request
+	 * (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @return the response as entity
 	 * @since 3.2

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

@@ -458,6 +458,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 		execute(url, HttpMethod.PUT, requestCallback, null);
 	}
 
+
 	// PATCH
 
 	@Override
@@ -490,6 +491,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 		return execute(url, HttpMethod.PATCH, requestCallback, responseExtractor);
 	}
 
+
 	// DELETE
 
 	@Override
@@ -692,8 +694,8 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 	 * @param method the HTTP method to execute (GET, POST, etc.)
 	 * @param response the resulting {@link ClientHttpResponse}
 	 * @throws IOException if propagated from {@link ResponseErrorHandler}
-	 * @see #setErrorHandler
 	 * @since 4.1.6
+	 * @see #setErrorHandler
 	 */
 	protected void handleResponse(URI url, HttpMethod method, ClientHttpResponse response) throws IOException {
 		ResponseErrorHandler errorHandler = getErrorHandler();