Add AsyncRestTemplate

Added AsyncRestTemplate, the asynchronous counterpart to the
RestTemplate that was introduced in Spring 3. All methods on the
AsyncRestTemplate are similar to those found on the synchronous
RestTemplatem, except that they return Future wrappers instead of
concrete results.

To enable this, this commit introduces the AsyncClientHttpRequest and
AsyncClientHttpRequestFactory, similar to the ClientHttpRequest and
ClientHttpRequestFactory, except that ClientHttpRequest returns a
Future<ClientHttpResponse> for the execute method. Two implementations
of these interfaces are provided, one based on the HttpURLConnection
incombination with a Spring AsyncTaskExecutor and one based on Apache
HttpComponents HttpAsyncClient.

Issue: SPR-8804

Author: Arjen Poutsma

build.gradle

@@ -478,7 +478,8 @@ project("spring-web") {
 		optional("com.caucho:hessian:4.0.7")
 		optional("rome:rome:1.0")
 		optional("commons-fileupload:commons-fileupload:1.3")
-		optional("org.apache.httpcomponents:httpclient:4.2")
+		optional("org.apache.httpcomponents:httpclient:4.3-beta2")
+		optional("org.apache.httpcomponents:httpasyncclient:4.0-beta4")
 		optional("org.codehaus.jackson:jackson-mapper-asl:1.9.12")
 		optional("com.fasterxml.jackson.core:jackson-databind:2.2.0")
 		optional("taglibs:standard:1.1.2")
@@ -619,7 +620,7 @@ project("spring-webmvc") {
 		testCompile("commons-fileupload:commons-fileupload:1.2")
 		testCompile("commons-io:commons-io:1.3")
 		testCompile("org.hibernate:hibernate-validator:4.3.0.Final")
-		testCompile("org.apache.httpcomponents:httpclient:4.2")
+		testCompile("org.apache.httpcomponents:httpclient:4.3-beta2")
 	}
 
 	// pick up DispatcherServlet.properties in src/main

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

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2002-2013 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.http.client;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.concurrent.Future;
+
+import org.springframework.http.HttpHeaders;
+import org.springframework.util.Assert;
+
+/**
+ * Abstract base for {@link AsyncClientHttpRequest} that makes sure that headers and body
+ * are not written multiple times.
+ *
+ * @author Arjen Poutsma
+ * @since 4.0
+ */
+abstract class AbstractAsyncClientHttpRequest implements AsyncClientHttpRequest {
+
+	private final HttpHeaders headers = new HttpHeaders();
+
+	private boolean executed = false;
+
+
+	@Override
+	public final HttpHeaders getHeaders() {
+		return (this.executed ? HttpHeaders.readOnlyHttpHeaders(this.headers) : this.headers);
+	}
+
+	@Override
+	public final OutputStream getBody() throws IOException {
+		assertNotExecuted();
+		return getBodyInternal(this.headers);
+	}
+
+	@Override
+	public Future<ClientHttpResponse> executeAsync() throws IOException {
+		assertNotExecuted();
+		Future<ClientHttpResponse> result = executeInternal(this.headers);
+		this.executed = true;
+		return result;
+	}
+
+	/**
+	 * Asserts that this request has not been {@linkplain #execute() executed} yet.
+	 *
+	 * @throws IllegalStateException if this request has been executed
+	 */
+	protected void assertNotExecuted() {
+		Assert.state(!this.executed, "ClientHttpRequest already executed");
+	}
+
+
+	/**
+	 * Abstract template method that returns the body.
+	 * @param headers the HTTP headers
+	 * @return the body output stream
+	 */
+	protected abstract OutputStream getBodyInternal(HttpHeaders headers) throws IOException;
+
+	/**
+	 * Abstract template method that writes the given headers and content to the HTTP request.
+	 * @param headers the HTTP headers
+	 * @return the response object for the executed request
+	 */
+	protected abstract Future<ClientHttpResponse> executeInternal(HttpHeaders headers) throws IOException;
+
+}

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

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2002-2013 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.http.client;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.concurrent.Future;
+
+import org.springframework.http.HttpHeaders;
+
+/**
+ * Abstract base for {@link org.springframework.http.client.ClientHttpRequest} that buffers output in a byte array before sending it over the wire.
+ *
+ * @author Arjen Poutsma
+ * @since 3.0.6
+ */
+abstract class AbstractBufferingAsyncClientHttpRequest
+		extends AbstractAsyncClientHttpRequest {
+
+	private ByteArrayOutputStream bufferedOutput = new ByteArrayOutputStream();
+
+	@Override
+	protected OutputStream getBodyInternal(HttpHeaders headers) throws IOException {
+		return this.bufferedOutput;
+	}
+
+	@Override
+	protected Future<ClientHttpResponse> executeInternal(HttpHeaders headers) throws IOException {
+		byte[] bytes = this.bufferedOutput.toByteArray();
+		if (headers.getContentLength() == -1) {
+			headers.setContentLength(bytes.length);
+		}
+		Future<ClientHttpResponse> result = executeInternal(headers, bytes);
+		this.bufferedOutput = null;
+		return result;
+	}
+
+	/**
+	 * Abstract template method that writes the given headers and content to the HTTP
+	 * request.
+	 *
+	 * @param headers the HTTP headers
+	 * @param bufferedOutput the body content
+	 * @return the response object for the executed request
+	 */
+	protected abstract Future<ClientHttpResponse> executeInternal(HttpHeaders headers,
+			byte[] bufferedOutput) throws IOException;
+
+
+}

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

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2002-2013 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.http.client;
+
+import java.io.IOException;
+import java.util.concurrent.Future;
+
+import org.springframework.http.HttpOutputMessage;
+import org.springframework.http.HttpRequest;
+
+/**
+ * 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)
+ */
+public interface AsyncClientHttpRequest extends HttpRequest, HttpOutputMessage {
+
+	/**
+	 * Execute this request asynchronously, resulting in a future
+	 * {@link ClientHttpResponse} that can be read.
+	 *
+	 * @return the future response result of the execution
+	 * @throws java.io.IOException in case of I/O errors
+	 */
+	Future<ClientHttpResponse> executeAsync() throws IOException;
+
+
+}

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

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2002-2013 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.http.client;
+
+import java.io.IOException;
+import java.net.URI;
+
+import org.springframework.http.HttpMethod;
+
+/**
+ * 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.
+	 * <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;
+
+}

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

@@ -25,8 +25,8 @@
 /**
  * Represents a client-side HTTP request. Created via an implementation of the {@link ClientHttpRequestFactory}.
  *
- * <p>A {@code HttpRequest} can be {@linkplain #execute() executed}, getting a {@link ClientHttpResponse}
- * which can be read from.
+ * <p>A {@code ClientHttpRequest} can be {@linkplain #execute() executed}, getting a
+ * {@link ClientHttpResponse} which can be read from.
  *
  * @author Arjen Poutsma
  * @since 3.0