org.springframework.web.client Documentation Differences

This file contains all the changes in documentation in the package org.springframework.web.client as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Default implementation of the ResponseErrorHandler interface.

This error handler checks for the status code on the ClientHttpResponse: any code with series org.springframework.http.HttpStatus.Series.CLIENT_ERROR or org.springframework.http.HttpStatus.Series.SERVER_ERROR is considered to be an error. This behavior can be changed by overriding the .hasError(HttpStatus) method. @author Arjen Poutsma @author Rossen Stoyanchev @since 3.0 @see RestTemplate#setErrorHandler

Response extractor that uses the given HttpMessageConverter entityentity converters to convert the response response into a type T. @author Arjen Poutsma @see RestTemplate @since 3.0

Creates a new instance of the {@code HttpMessageConverterExtractor} with the givengiven response type and message message converters. The given converters must support the responseresponse type.

Indicates whether the given response has a message body.

Default implementationimplementation returns {@code false} for a response status of {@code 204} or {@code 304}, or a a {@codecode Content-Length} of {@code 0}. @param response the response to check for a message body @return {@code true} if the response has a body, {@code false} otherwise @throws IOException in case of I/O errors

Base class for exceptions thrown by RestTemplate whenever it encountersencounters client-side HTTP errors. @author Arjen Poutsma @since 3.0

Construct a new instance of {@code HttpClientException} with the given message andand exception. @param msg the message @param ex the exception

The central class for 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.

The main entry points of this template are the methods named after the six main HTTP methods:

HTTP method	RestTemplate methods
DELETE	.delete
GET	.getForObject
	.getForEntity
HEAD	.headForHeaders
OPTIONS	.optionsForAllow
POST	.postForLocation
	.postForObject
PUT	.put
any	.exchange
	.execute

The {@code exchange} and {@code execute} methods are generalized versions of the more specific methods listed above them. They support additional, less frequently used combinations including support for requests using the HTTP PATCH method. However, note that the underlying HTTP library must also support the desired combination.

For each of these HTTP methods, there are three corresponding Java methods in the {@code RestTemplate}. Two variant take a {@code String} URI as first argument (eg. .getForObject(String, Class, Object[]), .getForObject(String, Class, Map)), and are capable of substituting any UriTemplate URI templates in that URL using either a {@code String} variable arguments array, or a {@code Map}. The string varargs variant expands the given template variables in order, so that

 String result = restTemplate.getForObject("http://example.com/hotels/{hotel}/bookings/{booking}", String.class,"42",
 "21");
 

will perform a GET on {@code http://example.com/hotels/42/bookings/21}. The map variant expands the template based on variable name, and is therefore more useful when using many variables, or when a single variable is used multiple times. For example:

 Map<String, String> vars = Collections.singletonMap("hotel", "42");
 String result = restTemplate.getForObject("http://example.com/hotels/{hotel}/rooms/{hotel}", String.class, vars);
 

will perform a GET on {@code http://example.com/hotels/42/rooms/42}. Alternatively, there are URI variant methods (.getForObject(URI, Class)), which do not allow for URI templates, but allow you to reuse a single, expanded URI multiple times.

Furthermore, the {@code String}-argument methods assume that the URL String is unencoded. This means that

 restTemplate.getForObject("http://example.com/hotel list");
 

will perform a GET on {@code http://example.com/hotel%20list}. As a result, any URL passed that is already encoded will be encoded twice (i.e. {@code http://example.com/hotel%20list} will become {@code http://example.com/hotel%2520list}). If this behavior is undesirable, use the {@code URI}-argument methods, which will not perform any URL encoding.

Objects passed to and returned from these methods are converted to and from HTTP messages by HttpMessageConverter instances. Converters for the main mime types are registered by default, but you can also write your own converter and register it via the messageConverters bean property.

This template uses a org.springframework.http.client.SimpleClientHttpRequestFactory and a DefaultResponseErrorHandler as default strategies for creating HTTP connections or handling HTTP errors, respectively. These defaults can be overridden through the requestFactory and errorHandler bean properties. @author Arjen Poutsma @see HttpMessageConverter @see RequestCallback @see ResponseExtractor @see ResponseErrorHandler @since 3.0