Polishing

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

@@ -51,9 +51,10 @@ import org.springframework.util.ClassUtils;
 import org.springframework.web.util.UriTemplate;
 
 /**
- * <strong>The central class for client-side HTTP access.</strong> It simplifies communication with HTTP servers, and
+ * <strong>Spring's central class for client-side HTTP access.</strong>
- * enforces RESTful principles. It handles HTTP connections, leaving application code to provide URLs (with possible
+ * It simplifies communication with HTTP servers, and enforces RESTful principles.
- * template variables) and extract results.
+ * It handles HTTP connections, leaving application code to provide URLs
+ * (with possible template variables) and extract results.
  *
  * <p>The main entry points of this template are the methods named after the six main HTTP methods:
  * <table>
@@ -71,19 +72,19 @@ import org.springframework.web.util.UriTemplate;
  *
  * <p>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.</p>
+ * HTTP PATCH method. However, note that the underlying HTTP library must also support the desired combination.
  *
- * <p>For each of these HTTP methods, there are three corresponding Java methods in the {@code RestTemplate}. Two
+ * <p>For each of these HTTP methods, there are three corresponding Java methods in the {@code RestTemplate}.
- * variant take a {@code String} URI as first argument (eg. {@link #getForObject(String, Class, Object[])}, {@link
+ * Two variants take a {@code String} URI as first argument (eg. {@link #getForObject(String, Class, Object[])},
- * #getForObject(String, Class, Map)}), and are capable of substituting any {@linkplain UriTemplate URI templates} in
+ * {@link #getForObject(String, Class, Map)}), and are capable of substituting any {@linkplain UriTemplate URI templates}
- * that URL using either a {@code String} variable arguments array, or a {@code Map<String, String>}. The string varargs
+ * in that URL using either a {@code String} variable arguments array, or a {@code Map<String, String>}.
- * variant expands the given template variables in order, so that
+ * The string varargs variant expands the given template variables in order, so that
  * <pre>
- * String result = restTemplate.getForObject("http://example.com/hotels/{hotel}/bookings/{booking}", String.class,"42",
+ * String result = restTemplate.getForObject("http://example.com/hotels/{hotel}/bookings/{booking}", String.class, "42",
  * "21");
  * </pre>
- * will perform a GET on {@code http://example.com/hotels/42/bookings/21}. The map variant expands the template based on
+ * will perform a GET on {@code http://example.com/hotels/42/bookings/21}. The map variant expands the template based
- * variable name, and is therefore more useful when using many variables, or when a single variable is used multiple
+ * on variable name, and is therefore more useful when using many variables, or when a single variable is used multiple
  * times. For example:
  * <pre>
  * Map&lt;String, String&gt; vars = Collections.singletonMap("hotel", "42");
@@ -102,12 +103,13 @@ import org.springframework.web.util.UriTemplate;
  * http://example.com/hotel%2520list}). If this behavior is undesirable, use the {@code URI}-argument methods, which
  * will not perform any URL encoding.
  *
- * <p>Objects passed to and returned from these methods are converted to and from HTTP messages by {@link
+ * <p>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
+ * {@link HttpMessageConverter} instances. Converters for the main mime types are registered by default,
- * your own converter and register it via the {@link #setMessageConverters messageConverters} bean property.
+ * but you can also write your own converter and register it via the {@link #setMessageConverters messageConverters}
+ * bean property.
  *
- * <p>This template uses a {@link org.springframework.http.client.SimpleClientHttpRequestFactory} and a {@link
+ * <p>This template uses a {@link org.springframework.http.client.SimpleClientHttpRequestFactory} and a
- * DefaultResponseErrorHandler} as default strategies for creating HTTP connections or handling HTTP errors,
+ * {@link DefaultResponseErrorHandler} as default strategies for creating HTTP connections or handling HTTP errors,
  * respectively. These defaults can be overridden through the {@link #setRequestFactory(ClientHttpRequestFactory)
  * requestFactory} and {@link #setErrorHandler(ResponseErrorHandler) errorHandler} bean properties.
  *
@@ -120,6 +122,9 @@ import org.springframework.web.util.UriTemplate;
  */
 public class RestTemplate extends InterceptingHttpAccessor implements RestOperations {
 
+	private static boolean romePresent =
+			ClassUtils.isPresent("com.sun.syndication.feed.WireFeed", RestTemplate.class.getClassLoader());
+
 	private static final boolean jaxb2Present =
 			ClassUtils.isPresent("javax.xml.bind.Binder", RestTemplate.class.getClassLoader());
 
@@ -131,9 +136,6 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 			ClassUtils.isPresent("org.codehaus.jackson.map.ObjectMapper", RestTemplate.class.getClassLoader()) &&
 					ClassUtils.isPresent("org.codehaus.jackson.JsonGenerator", RestTemplate.class.getClassLoader());
 
-	private static boolean romePresent =
-			ClassUtils.isPresent("com.sun.syndication.feed.WireFeed", RestTemplate.class.getClassLoader());
-
 
 	private final ResponseExtractor<HttpHeaders> headersExtractor = new HeadersExtractor();
 
@@ -170,6 +172,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 	 * Create a new instance of the {@link RestTemplate} based on the given {@link ClientHttpRequestFactory}.
 	 * @param requestFactory HTTP request factory to use
 	 * @see org.springframework.http.client.SimpleClientHttpRequestFactory
+	 * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
 	 */
 	public RestTemplate(ClientHttpRequestFactory requestFactory) {
 		this();
@@ -178,26 +181,33 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 
 
 	/**
-	 * Set the message body converters to use. These converters are used to convert from and to HTTP requests and
+	 * Set the message body converters to use.
-	 * responses.
+	 * <p>These converters are used to convert from and to HTTP requests and responses.
 	 */
 	public void setMessageConverters(List<HttpMessageConverter<?>> messageConverters) {
 		Assert.notEmpty(messageConverters, "'messageConverters' must not be empty");
 		this.messageConverters = messageConverters;
 	}
 
-	/** Returns the message body converters. These converters are used to convert from and to HTTP requests and responses. */
+	/**
+	 * Return the message body converters.
+	 */
 	public List<HttpMessageConverter<?>> getMessageConverters() {
 		return this.messageConverters;
 	}
 
-	/** Set the error handler. */
+	/**
+	 * Set the error handler.
+	 * <p>By default, RestTemplate uses a {@link DefaultResponseErrorHandler}.
+	 */
 	public void setErrorHandler(ResponseErrorHandler errorHandler) {
 		Assert.notNull(errorHandler, "'errorHandler' must not be null");
 		this.errorHandler = errorHandler;
 	}
 
-	/** Return the error handler. By default, this is the {@link DefaultResponseErrorHandler}. */
+	/**
+	 * Return the error handler.
+	 */
 	public ResponseErrorHandler getErrorHandler() {
 		return this.errorHandler;
 	}
@@ -309,17 +319,16 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 
 	public <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Object... uriVariables)
 			throws RestClientException {
+
 		HttpEntityRequestCallback requestCallback = new HttpEntityRequestCallback(request, responseType);
 		ResponseEntityResponseExtractor<T> responseExtractor =
 				new ResponseEntityResponseExtractor<T>(responseType);
 		return execute(url, HttpMethod.POST, requestCallback, responseExtractor, uriVariables);
 	}
 
-	public <T> ResponseEntity<T> postForEntity(String url,
+	public <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables)
-										   Object request,
-										   Class<T> responseType,
-										   Map<String, ?> uriVariables)
 			throws RestClientException {
+
 		HttpEntityRequestCallback requestCallback = new HttpEntityRequestCallback(request, responseType);
 		ResponseEntityResponseExtractor<T> responseExtractor =
 				new ResponseEntityResponseExtractor<T>(responseType);

spring-web/src/main/java/org/springframework/web/util/UriTemplate.java

@@ -71,6 +71,7 @@ public class UriTemplate implements Serializable {
 		this.uriComponents = UriComponentsBuilder.fromUriString(uriTemplate).build();
 	}
 
+
 	/**
 	 * Return the names of the variables in the template, in order.
 	 * @return the template variable names
@@ -79,8 +80,6 @@ public class UriTemplate implements Serializable {
 		return this.variableNames;
 	}
 
-	// expanding
-
 	/**
 	 * Given the Map of variables, expands this template into a URI. The Map keys represent variable names,
 	 * the Map values variable values. The order of variables is not significant.
@@ -124,8 +123,6 @@ public class UriTemplate implements Serializable {
 		return encodedComponents.toUri();
 	}
 
-	// matching
-
 	/**
 	 * Indicate whether the given URI matches this template.
 	 * @param uri the URI to match to
@@ -194,7 +191,8 @@ public class UriTemplate implements Serializable {
 				}
 				else {
 					if (colonIdx + 1 == match.length()) {
-						throw new IllegalArgumentException("No custom regular expression specified after ':' in \"" + match	+ "\"");
+						throw new IllegalArgumentException(
+								"No custom regular expression specified after ':' in \"" + match + "\"");
 					}
 					String variablePattern = match.substring(colonIdx + 1, match.length());
 					this.patternBuilder.append('(');