Revised javadoc and related polishing

Issue: SPR-11383

Author: jhoeller

spring-web/src/main/java/org/springframework/http/client/AsyncClientHttpRequest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -23,24 +23,24 @@
 import org.springframework.util.concurrent.ListenableFuture;
 
 /**
- * Represents a client-side asynchronous HTTP request. Created via an implementation of
- * the {@link AsyncClientHttpRequestFactory}.
- * <p>A {@code AsyncHttpRequest} can be {@linkplain #executeAsync() executed}, getting a
- * future {@link ClientHttpResponse} which can be read from.
+ * Represents a client-side asynchronous HTTP request. Created via an
+ * implementation of the {@link AsyncClientHttpRequestFactory}.
+ *
+ * <p>A {@code AsyncHttpRequest} can be {@linkplain #executeAsync() executed},
+ * getting a future {@link ClientHttpResponse} which can be read from.
  *
  * @author Arjen Poutsma
  * @since 4.0
- * @see AsyncClientHttpRequestFactory#createAsyncRequest(java.net.URI, org.springframework.http.HttpMethod)
+ * @see AsyncClientHttpRequestFactory#createAsyncRequest
  */
 public interface AsyncClientHttpRequest extends HttpRequest, HttpOutputMessage {
 
 	/**
-	 * Execute this request asynchronously, resulting in a future
+	 * Execute this request asynchronously, resulting in a Future handle.
 	 * {@link ClientHttpResponse} that can be read.
 	 * @return the future response result of the execution
 	 * @throws java.io.IOException in case of I/O errors
 	 */
 	ListenableFuture<ClientHttpResponse> executeAsync() throws IOException;
 
-
 }

spring-web/src/main/java/org/springframework/http/client/AsyncClientHttpRequestFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -22,25 +22,24 @@
 import org.springframework.http.HttpMethod;
 
 /**
- * Factory for {@link AsyncClientHttpRequest} objects. Requests are created by the
- * {@link #createAsyncRequest(URI, HttpMethod)} method.
+ * Factory for {@link AsyncClientHttpRequest} objects.
+ * Requests are created by the {@link #createAsyncRequest(URI, HttpMethod)} method.
  *
  * @author Arjen Poutsma
  * @since 4.0
  */
 public interface AsyncClientHttpRequestFactory {
 
 	/**
-	 * Create a new asynchronous {@link AsyncClientHttpRequest} for the specified URI and
-	 * HTTP method.
+	 * Create a new asynchronous {@link AsyncClientHttpRequest} for the specified URI
+	 * and HTTP method.
 	 * <p>The returned request can be written to, and then executed by calling
 	 * {@link AsyncClientHttpRequest#executeAsync()}.
 	 * @param uri the URI to create a request for
 	 * @param httpMethod the HTTP method to execute
 	 * @return the created request
 	 * @throws IOException in case of I/O errors
 	 */
-	AsyncClientHttpRequest createAsyncRequest(URI uri, HttpMethod httpMethod)
-			throws IOException;
+	AsyncClientHttpRequest createAsyncRequest(URI uri, HttpMethod httpMethod) throws IOException;
 
 }

spring-web/src/main/java/org/springframework/http/client/HttpComponentsAsyncClientHttpRequest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -44,9 +44,8 @@
  *
  * @author Oleg Kalnichevski
  * @author Arjen Poutsma
- * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory#createRequest(java.net.URI,
- *      org.springframework.http.HttpMethod)
- * @since 3.1
+ * @since 4.0
+ * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory#createRequest
  */
 final class HttpComponentsAsyncClientHttpRequest extends AbstractBufferingAsyncClientHttpRequest {
 
@@ -56,13 +55,14 @@ final class HttpComponentsAsyncClientHttpRequest extends AbstractBufferingAsyncC
 
 	private final HttpContext httpContext;
 
-	public HttpComponentsAsyncClientHttpRequest(HttpAsyncClient httpClient,
-			HttpUriRequest httpRequest, HttpContext httpContext) {
+
+	HttpComponentsAsyncClientHttpRequest(HttpAsyncClient httpClient, HttpUriRequest httpRequest, HttpContext httpContext) {
 		this.httpClient = httpClient;
 		this.httpRequest = httpRequest;
 		this.httpContext = httpContext;
 	}
 
+
 	@Override
 	public HttpMethod getMethod() {
 		return HttpMethod.valueOf(this.httpRequest.getMethod());
@@ -74,48 +74,46 @@ public URI getURI() {
 	}
 
 	@Override
-	protected ListenableFuture<ClientHttpResponse> executeInternal(HttpHeaders headers,
-			byte[] bufferedOutput) throws IOException {
+	protected ListenableFuture<ClientHttpResponse> executeInternal(HttpHeaders headers, byte[] bufferedOutput)
+			throws IOException {
+
 		HttpComponentsClientHttpRequest.addHeaders(this.httpRequest, headers);
 
 		if (this.httpRequest instanceof HttpEntityEnclosingRequest) {
-			HttpEntityEnclosingRequest entityEnclosingRequest =
-					(HttpEntityEnclosingRequest) this.httpRequest;
+			HttpEntityEnclosingRequest entityEnclosingRequest = (HttpEntityEnclosingRequest) this.httpRequest;
 			HttpEntity requestEntity = new NByteArrayEntity(bufferedOutput);
 			entityEnclosingRequest.setEntity(requestEntity);
 		}
 
 		final HttpResponseFutureCallback callback = new HttpResponseFutureCallback();
-
 		final Future<HttpResponse> futureResponse =
 				this.httpClient.execute(this.httpRequest, this.httpContext, callback);
 		return new ClientHttpResponseFuture(futureResponse, callback);
 	}
 
+
 	private static class HttpResponseFutureCallback implements FutureCallback<HttpResponse> {
 
 		private final ListenableFutureCallbackRegistry<ClientHttpResponse> callbacks =
 				new ListenableFutureCallbackRegistry<ClientHttpResponse>();
 
-		public void addCallback(
-				ListenableFutureCallback<? super ClientHttpResponse> callback) {
-			callbacks.addCallback(callback);
+		public void addCallback(ListenableFutureCallback<? super ClientHttpResponse> callback) {
+			this.callbacks.addCallback(callback);
 		}
 
 		@Override
 		public void completed(HttpResponse result) {
-			callbacks.success(new HttpComponentsAsyncClientHttpResponse(result));
+			this.callbacks.success(new HttpComponentsAsyncClientHttpResponse(result));
 		}
 
 		@Override
 		public void failed(Exception ex) {
-			callbacks.failure(ex);
+			this.callbacks.failure(ex);
 		}
 
 		@Override
 		public void cancelled() {
 		}
-
 	}
 
 
@@ -124,8 +122,7 @@ private static class ClientHttpResponseFuture extends FutureAdapter<ClientHttpRe
 
 		private final HttpResponseFutureCallback callback;
 
-		private ClientHttpResponseFuture(Future<HttpResponse> futureResponse,
-				HttpResponseFutureCallback callback) {
+		public ClientHttpResponseFuture(Future<HttpResponse> futureResponse, HttpResponseFutureCallback callback) {
 			super(futureResponse);
 			this.callback = callback;
 		}
@@ -136,8 +133,7 @@ protected ClientHttpResponse adapt(HttpResponse response) {
 		}
 
 		@Override
-		public void addCallback(
-				ListenableFutureCallback<? super ClientHttpResponse> callback) {
+		public void addCallback(ListenableFutureCallback<? super ClientHttpResponse> callback) {
 			this.callback.addCallback(callback);
 		}
 	}

spring-web/src/main/java/org/springframework/http/client/HttpComponentsAsyncClientHttpRequestFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -113,8 +113,7 @@ private void startAsyncClient() {
 	}
 
 	@Override
-	public AsyncClientHttpRequest createAsyncRequest(URI uri, HttpMethod httpMethod)
-			throws IOException {
+	public AsyncClientHttpRequest createAsyncRequest(URI uri, HttpMethod httpMethod) throws IOException {
 		HttpAsyncClient asyncClient = getHttpAsyncClient();
 		startAsyncClient();
 		HttpUriRequest httpRequest = createHttpUriRequest(httpMethod, uri);

spring-web/src/main/java/org/springframework/http/client/HttpComponentsAsyncClientHttpResponse.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -32,7 +32,7 @@
  *
  * @author Oleg Kalnichevski
  * @author Arjen Poutsma
- * @since 3.1
+ * @since 4.0
  * @see HttpComponentsAsyncClientHttpRequest#executeAsync()
  */
 final class HttpComponentsAsyncClientHttpResponse extends AbstractClientHttpResponse {
@@ -76,9 +76,8 @@ public InputStream getBody() throws IOException {
 
 	@Override
 	public void close() {
-        // HTTP responses returned by async HTTP client
-        // are not bound to an active connection and
-        // do not have to deallocate any resources
+        // HTTP responses returned by async HTTP client are not bound to an
+        // active connection and do not have to deallocate any resources...
 	}
 
 }

spring-web/src/main/java/org/springframework/http/client/HttpComponentsClientHttpRequest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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,6 +29,7 @@
 import org.apache.http.impl.client.CloseableHttpClient;
 import org.apache.http.protocol.HTTP;
 import org.apache.http.protocol.HttpContext;
+
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpMethod;
 
@@ -52,7 +53,7 @@ final class HttpComponentsClientHttpRequest extends AbstractBufferingClientHttpR
 	private final HttpContext httpContext;
 
 
-	public HttpComponentsClientHttpRequest(CloseableHttpClient httpClient, HttpUriRequest httpRequest, HttpContext httpContext) {
+	HttpComponentsClientHttpRequest(CloseableHttpClient httpClient, HttpUriRequest httpRequest, HttpContext httpContext) {
 		this.httpClient = httpClient;
 		this.httpRequest = httpRequest;
 		this.httpContext = httpContext;
@@ -80,14 +81,13 @@ protected ClientHttpResponse executeInternal(HttpHeaders headers, byte[] buffere
 			HttpEntity requestEntity = new ByteArrayEntity(bufferedOutput);
 			entityEnclosingRequest.setEntity(requestEntity);
 		}
-		CloseableHttpResponse httpResponse =
-				this.httpClient.execute(this.httpRequest, this.httpContext);
+		CloseableHttpResponse httpResponse = this.httpClient.execute(this.httpRequest, this.httpContext);
 		return new HttpComponentsClientHttpResponse(httpResponse);
 	}
 
+
 	/**
-	 * Adds the given headers to the given HTTP request.
-	 *
+	 * Add the given headers to the given HTTP request.
 	 * @param httpRequest the request to add the headers to
 	 * @param headers the headers to add
 	 */

spring-web/src/main/java/org/springframework/http/client/HttpComponentsClientHttpRequestFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -48,6 +48,8 @@
  * <p>Allows to use a pre-configured {@link HttpClient} instance -
  * potentially with authentication, HTTP connection pooling, etc.
  *
+ * <p><b>NOTE:</b> Requires Apache HttpComponents 4.3 or higher, as of Spring 4.0.
+ *
  * @author Oleg Kalnichevski
  * @author Arjen Poutsma
  * @since 3.1

spring-web/src/main/java/org/springframework/http/client/HttpComponentsClientHttpResponse.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -73,7 +73,7 @@ public HttpHeaders getHeaders() {
 	@Override
 	public InputStream getBody() throws IOException {
 		HttpEntity entity = this.httpResponse.getEntity();
-		return entity != null ? entity.getContent() : null;
+		return (entity != null ? entity.getContent() : null);
 	}
 
 	@Override
@@ -83,12 +83,13 @@ public void close() {
             try {
                 // Attempt to keep connection alive by consuming its remaining content
                 EntityUtils.consume(this.httpResponse.getEntity());
-            } finally {
-                // Paranoia
+            }
+			finally {
                 this.httpResponse.close();
             }
         }
-        catch (IOException ignore) {
+        catch (IOException ex) {
+			// Ignore exception on close...
         }
 	}