Improve documentation of TestRestTemplate's fault tolerance

See gh-26227

Author: crocarneiro

spring-boot-project/spring-boot-test/src/main/java/org/springframework/boot/test/web/client/TestRestTemplate.java

@@ -175,7 +175,6 @@ public String getRootUri() {
 	 * @param urlVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error on client-side HTTP error
 	 * @see RestTemplate#getForObject(String, Class, Object...)
 	 */
 	public <T> T getForObject(String url, Class<T> responseType, Object... urlVariables) throws RestClientException {
@@ -192,7 +191,6 @@ public <T> T getForObject(String url, Class<T> responseType, Object... urlVariab
 	 * @param urlVariables the map containing variables for the URI template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#getForObject(String, Class, Object...)
 	 */
 	public <T> T getForObject(String url, Class<T> responseType, Map<String, ?> urlVariables)
@@ -207,7 +205,6 @@ public <T> T getForObject(String url, Class<T> responseType, Map<String, ?> urlV
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#getForObject(java.net.URI, java.lang.Class)
 	 */
 	public <T> T getForObject(URI url, Class<T> responseType) throws RestClientException {
@@ -224,7 +221,6 @@ public <T> T getForObject(URI url, Class<T> responseType) throws RestClientExcep
 	 * @param urlVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#getForEntity(java.lang.String, java.lang.Class,
 	 * java.lang.Object[])
 	 */
@@ -243,7 +239,6 @@ public <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Obj
 	 * @param urlVariables the map containing variables for the URI template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#getForEntity(java.lang.String, java.lang.Class, java.util.Map)
 	 */
 	public <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String, ?> urlVariables)
@@ -258,7 +253,6 @@ public <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#getForEntity(java.net.URI, java.lang.Class)
 	 */
 	public <T> ResponseEntity<T> getForEntity(URI url, Class<T> responseType) throws RestClientException {
@@ -272,7 +266,6 @@ public <T> ResponseEntity<T> getForEntity(URI url, Class<T> responseType) throws
 	 * @param url the URL
 	 * @param urlVariables the variables to expand the template
 	 * @return all HTTP headers of that resource
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#headForHeaders(java.lang.String, java.lang.Object[])
 	 */
 	public HttpHeaders headForHeaders(String url, Object... urlVariables) throws RestClientException {
@@ -286,7 +279,6 @@ public HttpHeaders headForHeaders(String url, Object... urlVariables) throws Res
 	 * @param url the URL
 	 * @param urlVariables the map containing variables for the URI template
 	 * @return all HTTP headers of that resource
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#headForHeaders(java.lang.String, java.util.Map)
 	 */
 	public HttpHeaders headForHeaders(String url, Map<String, ?> urlVariables) throws RestClientException {
@@ -297,7 +289,6 @@ public HttpHeaders headForHeaders(String url, Map<String, ?> urlVariables) throw
 	 * Retrieve all headers of the resource specified by the URL.
 	 * @param url the URL
 	 * @return all HTTP headers of that resource
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#headForHeaders(java.net.URI)
 	 */
 	public HttpHeaders headForHeaders(URI url) throws RestClientException {
@@ -317,7 +308,6 @@ public HttpHeaders headForHeaders(URI url) throws RestClientException {
 	 * @param request the Object to be POSTed, may be {@code null}
 	 * @param urlVariables the variables to expand the template
 	 * @return the value for the {@code Location} header
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForLocation(java.lang.String, java.lang.Object,
 	 * java.lang.Object[])
@@ -339,7 +329,6 @@ public URI postForLocation(String url, Object request, Object... urlVariables) t
 	 * @param request the Object to be POSTed, may be {@code null}
 	 * @param urlVariables the variables to expand the template
 	 * @return the value for the {@code Location} header
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForLocation(java.lang.String, java.lang.Object,
 	 * java.util.Map)
@@ -358,7 +347,6 @@ public URI postForLocation(String url, Object request, Map<String, ?> urlVariabl
 	 * @param url the URL
 	 * @param request the Object to be POSTed, may be {@code null}
 	 * @return the value for the {@code Location} header
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForLocation(java.net.URI, java.lang.Object)
 	 */
@@ -380,7 +368,6 @@ public URI postForLocation(URI url, Object request) throws RestClientException {
 	 * @param urlVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForObject(java.lang.String, java.lang.Object,
 	 * java.lang.Class, java.lang.Object[])
@@ -404,7 +391,6 @@ public <T> T postForObject(String url, Object request, Class<T> responseType, Ob
 	 * @param urlVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForObject(java.lang.String, java.lang.Object,
 	 * java.lang.Class, java.util.Map)
@@ -425,7 +411,6 @@ public <T> T postForObject(String url, Object request, Class<T> responseType, Ma
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForObject(java.net.URI, java.lang.Object, java.lang.Class)
 	 */
@@ -447,7 +432,6 @@ public <T> T postForObject(URI url, Object request, Class<T> responseType) throw
 	 * @param urlVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForEntity(java.lang.String, java.lang.Object,
 	 * java.lang.Class, java.lang.Object[])
@@ -471,7 +455,6 @@ public <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T>
 	 * @param urlVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForEntity(java.lang.String, java.lang.Object,
 	 * java.lang.Class, java.util.Map)
@@ -492,7 +475,6 @@ public <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T>
 	 * @param responseType the response type to return
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#postForEntity(java.net.URI, java.lang.Object, java.lang.Class)
 	 */
@@ -508,10 +490,12 @@ public <T> ResponseEntity<T> postForEntity(URI url, Object request, Class<T> res
 	 * <p>
 	 * The {@code request} parameter can be a {@link HttpEntity} in order to add
 	 * additional HTTP headers to the request.
+	 * <p>
+	 * If you need to assert the request result consider using the
+	 * {@link TestRestTemplate#exchange exchange} method.
 	 * @param url the URL
 	 * @param request the Object to be PUT, may be {@code null}
 	 * @param urlVariables the variables to expand the template
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#put(java.lang.String, java.lang.Object, java.lang.Object[])
 	 */
@@ -526,10 +510,12 @@ public void put(String url, Object request, Object... urlVariables) throws RestC
 	 * <p>
 	 * The {@code request} parameter can be a {@link HttpEntity} in order to add
 	 * additional HTTP headers to the request.
+	 * <p>
+	 * If you need to assert the request result consider using the
+	 * {@link TestRestTemplate#exchange exchange} method.
 	 * @param url the URL
 	 * @param request the Object to be PUT, may be {@code null}
 	 * @param urlVariables the variables to expand the template
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#put(java.lang.String, java.lang.Object, java.util.Map)
 	 */
@@ -542,9 +528,11 @@ public void put(String url, Object request, Map<String, ?> urlVariables) throws
 	 * <p>
 	 * The {@code request} parameter can be a {@link HttpEntity} in order to add
 	 * additional HTTP headers to the request.
+	 * <p>
+	 * If you need to assert the request result consider using the
+	 * {@link TestRestTemplate#exchange exchange} method.
 	 * @param url the URL
 	 * @param request the Object to be PUT, may be {@code null}
-	 * @throws RestClientException on client-side HTTP error
 	 * @see HttpEntity
 	 * @see RestTemplate#put(java.net.URI, java.lang.Object)
 	 */
@@ -566,7 +554,6 @@ public void put(URI url, Object request) throws RestClientException {
 	 * @param uriVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @since 1.4.4
 	 * @see HttpEntity
 	 */
@@ -589,7 +576,6 @@ public <T> T patchForObject(String url, Object request, Class<T> responseType, O
 	 * @param uriVariables the variables to expand the template
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @since 1.4.4
 	 * @see HttpEntity
 	 */
@@ -609,7 +595,6 @@ public <T> T patchForObject(String url, Object request, Class<T> responseType, M
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the converted object
-	 * @throws RestClientException on client-side HTTP error
 	 * @since 1.4.4
 	 * @see HttpEntity
 	 */
@@ -621,9 +606,11 @@ public <T> T patchForObject(URI url, Object request, Class<T> responseType) thro
 	 * Delete the resources at the specified URI.
 	 * <p>
 	 * URI Template variables are expanded using the given URI variables, if any.
+	 * <p>
+	 * If you need to assert the request result consider using the
+	 * {@link TestRestTemplate#exchange exchange} method.
 	 * @param url the URL
 	 * @param urlVariables the variables to expand in the template
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#delete(java.lang.String, java.lang.Object[])
 	 */
 	public void delete(String url, Object... urlVariables) throws RestClientException {
@@ -634,9 +621,11 @@ public void delete(String url, Object... urlVariables) throws RestClientExceptio
 	 * Delete the resources at the specified URI.
 	 * <p>
 	 * URI Template variables are expanded using the given map.
+	 * <p>
+	 * If you need to assert the request result consider using the
+	 * {@link TestRestTemplate#exchange exchange} method.
 	 * @param url the URL
 	 * @param urlVariables the variables to expand the template
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#delete(java.lang.String, java.util.Map)
 	 */
 	public void delete(String url, Map<String, ?> urlVariables) throws RestClientException {
@@ -645,8 +634,10 @@ public void delete(String url, Map<String, ?> urlVariables) throws RestClientExc
 
 	/**
 	 * Delete the resources at the specified URL.
+	 * <p>
+	 * If you need to assert the request result consider using the
+	 * {@link TestRestTemplate#exchange exchange} method.
 	 * @param url the URL
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#delete(java.net.URI)
 	 */
 	public void delete(URI url) throws RestClientException {
@@ -660,7 +651,6 @@ public void delete(URI url) throws RestClientException {
 	 * @param url the URL
 	 * @param urlVariables the variables to expand in the template
 	 * @return the value of the allow header
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#optionsForAllow(java.lang.String, java.lang.Object[])
 	 */
 	public Set<HttpMethod> optionsForAllow(String url, Object... urlVariables) throws RestClientException {
@@ -674,7 +664,6 @@ public Set<HttpMethod> optionsForAllow(String url, Object... urlVariables) throw
 	 * @param url the URL
 	 * @param urlVariables the variables to expand in the template
 	 * @return the value of the allow header
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#optionsForAllow(java.lang.String, java.util.Map)
 	 */
 	public Set<HttpMethod> optionsForAllow(String url, Map<String, ?> urlVariables) throws RestClientException {
@@ -685,7 +674,6 @@ public Set<HttpMethod> optionsForAllow(String url, Map<String, ?> urlVariables)
 	 * Return the value of the Allow header for the given URL.
 	 * @param url the URL
 	 * @return the value of the allow header
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#optionsForAllow(java.net.URI)
 	 */
 	public Set<HttpMethod> optionsForAllow(URI url) throws RestClientException {
@@ -705,7 +693,6 @@ public Set<HttpMethod> optionsForAllow(URI url) throws RestClientException {
 	 * @param urlVariables the variables to expand in the template
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(java.lang.String, org.springframework.http.HttpMethod,
 	 * org.springframework.http.HttpEntity, java.lang.Class, java.lang.Object[])
 	 */
@@ -727,7 +714,6 @@ public <T> ResponseEntity<T> exchange(String url, HttpMethod method, HttpEntity<
 	 * @param urlVariables the variables to expand in the template
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(java.lang.String, org.springframework.http.HttpMethod,
 	 * org.springframework.http.HttpEntity, java.lang.Class, java.util.Map)
 	 */
@@ -746,7 +732,6 @@ public <T> ResponseEntity<T> exchange(String url, HttpMethod method, HttpEntity<
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(java.net.URI, org.springframework.http.HttpMethod,
 	 * org.springframework.http.HttpEntity, java.lang.Class)
 	 */
@@ -771,7 +756,6 @@ public <T> ResponseEntity<T> exchange(URI url, HttpMethod method, HttpEntity<?>
 	 * @param urlVariables the variables to expand in the template
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(java.lang.String, org.springframework.http.HttpMethod,
 	 * org.springframework.http.HttpEntity,
 	 * org.springframework.core.ParameterizedTypeReference, java.lang.Object[])
@@ -797,7 +781,6 @@ public <T> ResponseEntity<T> exchange(String url, HttpMethod method, HttpEntity<
 	 * @param urlVariables the variables to expand in the template
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(java.lang.String, org.springframework.http.HttpMethod,
 	 * org.springframework.http.HttpEntity,
 	 * org.springframework.core.ParameterizedTypeReference, java.util.Map)
@@ -822,7 +805,6 @@ public <T> ResponseEntity<T> exchange(String url, HttpMethod method, HttpEntity<
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(java.net.URI, org.springframework.http.HttpMethod,
 	 * org.springframework.http.HttpEntity,
 	 * org.springframework.core.ParameterizedTypeReference)
@@ -844,7 +826,6 @@ public <T> ResponseEntity<T> exchange(URI url, HttpMethod method, HttpEntity<?>
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(org.springframework.http.RequestEntity, java.lang.Class)
 	 */
 	public <T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity, Class<T> responseType)
@@ -865,7 +846,6 @@ public <T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity, Class<T> r
 	 * @param responseType the type of the return value
 	 * @param <T> the type of the return value
 	 * @return the response as entity
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#exchange(org.springframework.http.RequestEntity,
 	 * org.springframework.core.ParameterizedTypeReference)
 	 */
@@ -886,7 +866,6 @@ public <T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity, Parameteri
 	 * @param urlVariables the variables to expand in the template
 	 * @param <T> the type of the return value
 	 * @return an arbitrary object, as returned by the {@link ResponseExtractor}
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#execute(java.lang.String, org.springframework.http.HttpMethod,
 	 * org.springframework.web.client.RequestCallback,
 	 * org.springframework.web.client.ResponseExtractor, java.lang.Object[])
@@ -908,7 +887,6 @@ public <T> T execute(String url, HttpMethod method, RequestCallback requestCallb
 	 * @param urlVariables the variables to expand in the template
 	 * @param <T> the type of the return value
 	 * @return an arbitrary object, as returned by the {@link ResponseExtractor}
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#execute(java.lang.String, org.springframework.http.HttpMethod,
 	 * org.springframework.web.client.RequestCallback,
 	 * org.springframework.web.client.ResponseExtractor, java.util.Map)
@@ -927,7 +905,6 @@ public <T> T execute(String url, HttpMethod method, RequestCallback requestCallb
 	 * @param responseExtractor object that extracts the return value from the response
 	 * @param <T> the type of the return value
 	 * @return an arbitrary object, as returned by the {@link ResponseExtractor}
-	 * @throws RestClientException on client-side HTTP error
 	 * @see RestTemplate#execute(java.net.URI, org.springframework.http.HttpMethod,
 	 * org.springframework.web.client.RequestCallback,
 	 * org.springframework.web.client.ResponseExtractor)