Initial cut of Servlet 3.0 based async support

From a programming model perspective, @RequestMapping methods now
support two new return value types:

* java.util.concurrent.Callable - used by Spring MVC to obtain the
return value asynchronously in a separate thread managed transparently
by Spring MVC on behalf of the application.
* org.springframework.web.context.request.async.DeferredResult - used
by the application to produce the return value asynchronously in a
separate thread of its own choosing.

The high-level idea is that whatever value a controller normally
returns, it can now provide it asynchronously, through a Callable or
through a DeferredResult, with all remaining processing --
@responsebody, view resolution, etc, working just the same but
completed outside the main request thread.

From an SPI perspective, there are several new types:

* AsyncExecutionChain - the central class for managing async request
processing through a sequence of Callable instances each representing
work required to complete request processing asynchronously.
* AsyncWebRequest - provides methods for starting, completing, and
configuring async request processing.
* StandardServletAsyncWebRequest - Servlet 3 based implementation.
* AsyncExecutionChainRunnable - the Runnable used for async request
execution.

All spring-web and spring-webmvc Filter implementations have been
updated to participate in async request execution.
The open-session-in-view Filter and interceptors implementations in
spring-orm will be updated in a separate pull request.

Issue: SPR-8517

Author: rstoyanchev

spring-web/src/main/java/org/springframework/web/bind/annotation/RequestMapping.java

@@ -21,6 +21,7 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.util.concurrent.Callable;
 
 /**
  * Annotation for mapping web requests onto specific handler classes and/or
@@ -180,12 +181,18 @@
  * be converted to the response stream using
  * {@linkplain org.springframework.http.converter.HttpMessageConverter message
  * converters}.
- * <li>A {@link org.springframework.http.HttpEntity HttpEntity&lt;?&gt;} or
+ * <li>An {@link org.springframework.http.HttpEntity HttpEntity&lt;?&gt;} or
  * {@link org.springframework.http.ResponseEntity ResponseEntity&lt;?&gt;} object
  * (Servlet-only) to access to the Servlet response HTTP headers and contents.
  * The entity body will be converted to the response stream using
  * {@linkplain org.springframework.http.converter.HttpMessageConverter message
  * converters}.
+ * <li>A {@link Callable} which is used by Spring MVC to obtain the return
+ * value asynchronously in a separate thread transparently managed by Spring MVC
+ * on behalf of the application.
+ * <li>A {@code org.springframework.web.context.request.async.DeferredResult}
+ * which the application uses to produce a return value in a separate
+ * thread of its own choosing, as an alternative to returning a Callable.
  * <li><code>void</code> if the method handles the response itself (by
  * writing the response content directly, declaring an argument of type
  * {@link javax.servlet.ServletResponse} / {@link javax.servlet.http.HttpServletResponse}

spring-web/src/main/java/org/springframework/web/context/request/async/AbstractDelegatingCallable.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2002-2012 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.web.context.request.async;
+
+import java.util.concurrent.Callable;
+
+/**
+ * A base class for a Callable that can be used in a chain of Callable instances.
+ *
+ * <p>Typical use for async request processing scenarios involves:
+ * <ul>
+ * 	<li>Create an instance of this type and register it via
+ * {@link AsyncExecutionChain#addDelegatingCallable(AbstractDelegatingCallable)}
+ * (internally the nodes of the chain will be linked so no need to set up "next").
+ * 	<li>Provide an implementation of {@link Callable#call()} that contains the
+ * logic needed to complete request processing outside the main processing thread.
+ * 	<li>In the implementation, delegate to the next Callable to obtain
+ * its result, e.g. ModelAndView, and then do some post-processing, e.g. view
+ * resolution. In some cases both pre- and post-processing might be
+ * appropriate, e.g. setting up {@link ThreadLocal} storage.
+ * </ul>
+ *
+ * @author Rossen Stoyanchev
+ * @since 3.2
+ *
+ * @see AsyncExecutionChain
+ */
+public abstract class AbstractDelegatingCallable implements Callable<Object> {
+
+	private Callable<Object> next;
+
+	public void setNextCallable(Callable<Object> nextCallable) {
+		this.next = nextCallable;
+	}
+
+	protected Callable<Object> getNextCallable() {
+		return this.next;
+	}
+
+}

spring-web/src/main/java/org/springframework/web/context/request/async/AsyncExecutionChain.java

@@ -0,0 +1,189 @@
+/*
+ * Copyright 2002-2012 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.web.context.request.async;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.Callable;
+
+import javax.servlet.ServletRequest;
+
+import org.springframework.core.task.AsyncTaskExecutor;
+import org.springframework.core.task.SimpleAsyncTaskExecutor;
+import org.springframework.util.Assert;
+import org.springframework.web.context.request.async.DeferredResult.DeferredResultHandler;
+
+/**
+ * The central class for managing async request processing, mainly intended as
+ * an SPI and typically not by non-framework classes.
+ *
+ * <p>An async execution chain consists of a sequence of Callable instances and
+ * represents the work required to complete request processing in a separate
+ * thread. To construct the chain, each layer in the call stack of a normal
+ * request (e.g. filter, servlet) may contribute an
+ * {@link AbstractDelegatingCallable} when a request is being processed.
+ * For example the DispatcherServlet might contribute a Callable that
+ * performs view resolution while a HandlerAdapter might contribute a Callable
+ * that returns the ModelAndView, etc. The last Callable is the one that
+ * actually produces an application-specific value, for example the Callable
+ * returned by an {@code @RequestMapping} method.
+ *
+ * @author Rossen Stoyanchev
+ * @since 3.2
+ */
+public final class AsyncExecutionChain {
+
+	public static final String CALLABLE_CHAIN_ATTRIBUTE = AsyncExecutionChain.class.getName() + ".CALLABLE_CHAIN";
+
+	private final List<AbstractDelegatingCallable> delegatingCallables = new ArrayList<AbstractDelegatingCallable>();
+
+	private Callable<Object> callable;
+
+	private AsyncWebRequest asyncWebRequest;
+
+	private AsyncTaskExecutor taskExecutor = new SimpleAsyncTaskExecutor("AsyncExecutionChain");
+
+	/**
+	 * Private constructor
+	 * @see #getForCurrentRequest()
+	 */
+	private AsyncExecutionChain() {
+	}
+
+	/**
+	 * Obtain the AsyncExecutionChain for the current request.
+	 * Or if not found, create an instance and associate it with the request.
+	 */
+	public static AsyncExecutionChain getForCurrentRequest(ServletRequest request) {
+		AsyncExecutionChain chain = (AsyncExecutionChain) request.getAttribute(CALLABLE_CHAIN_ATTRIBUTE);
+		if (chain == null) {
+			chain = new AsyncExecutionChain();
+			request.setAttribute(CALLABLE_CHAIN_ATTRIBUTE, chain);
+		}
+		return chain;
+	}
+
+	/**
+	 * Provide an instance of an AsyncWebRequest.
+	 * This property must be set before async request processing can begin.
+	 */
+	public void setAsyncWebRequest(AsyncWebRequest asyncRequest) {
+		this.asyncWebRequest = asyncRequest;
+	}
+
+	/**
+	 * Provide an AsyncTaskExecutor to use when
+	 * {@link #startCallableChainProcessing()} is invoked, for example when a
+	 * controller method returns a Callable.
+	 * <p>By default a {@link SimpleAsyncTaskExecutor} instance is used.
+	 */
+	public void setTaskExecutor(AsyncTaskExecutor taskExecutor) {
+		this.taskExecutor = taskExecutor;
+	}
+
+	/**
+	 * Whether async request processing has started through one of:
+	 * <ul>
+	 * 	<li>{@link #startCallableChainProcessing()}
+	 * 	<li>{@link #startDeferredResultProcessing(DeferredResult)}
+	 * </ul>
+	 */
+	public boolean isAsyncStarted() {
+		return ((this.asyncWebRequest != null) && this.asyncWebRequest.isAsyncStarted());
+	}
+
+	/**
+	 * Add a Callable with logic required to complete request processing in a
+	 * separate thread. See {@link AbstractDelegatingCallable} for details.
+	 */
+	public void addDelegatingCallable(AbstractDelegatingCallable callable) {
+		Assert.notNull(callable, "Callable required");
+		this.delegatingCallables.add(callable);
+	}
+
+	/**
+	 * Add the last Callable, for example the one returned by the controller.
+	 * This property must be set prior to invoking
+	 * {@link #startCallableChainProcessing()}.
+	 */
+	public AsyncExecutionChain setCallable(Callable<Object> callable) {
+		Assert.notNull(callable, "Callable required");
+		this.callable = callable;
+		return this;
+	}
+
+	/**
+	 * Start the async execution chain by submitting an
+	 * {@link AsyncExecutionChainRunnable} instance to the TaskExecutor provided via
+	 * {@link #setTaskExecutor(AsyncTaskExecutor)} and returning immediately.
+	 * @see AsyncExecutionChainRunnable
+	 */
+	public void startCallableChainProcessing() {
+		startAsync();
+		this.taskExecutor.execute(new AsyncExecutionChainRunnable(this.asyncWebRequest, buildChain()));
+	}
+
+	private void startAsync() {
+		Assert.state(this.asyncWebRequest != null, "An AsyncWebRequest is required to start async processing");
+		this.asyncWebRequest.startAsync();
+	}
+
+	private Callable<Object> buildChain() {
+		Assert.state(this.callable != null, "The callable field is required to complete the chain");
+		this.delegatingCallables.add(new StaleAsyncRequestCheckingCallable(asyncWebRequest));
+		Callable<Object> result = this.callable;
+		for (int i = this.delegatingCallables.size() - 1; i >= 0; i--) {
+			AbstractDelegatingCallable callable = this.delegatingCallables.get(i);
+			callable.setNextCallable(result);
+			result = callable;
+		}
+		return result;
+	}
+
+	/**
+	 * Mark the start of async request processing accepting the provided
+	 * DeferredResult and initializing it such that if
+	 * {@link DeferredResult#set(Object)} is called (from another thread),
+	 * the set Object value will be processed with the execution chain by
+	 * invoking {@link AsyncExecutionChainRunnable}.
+	 * <p>The resulting processing from this method is identical to
+	 * {@link #startCallableChainProcessing()}. The main difference is in
+	 * the threading model, i.e. whether a TaskExecutor is used.
+	 * @see DeferredResult
+	 */
+	public void startDeferredResultProcessing(DeferredResult deferredResult) {
+		Assert.notNull(deferredResult, "A DeferredResult is required");
+		startAsync();
+		deferredResult.setValueProcessor(new DeferredResultHandler() {
+			public void handle(Object value) {
+				if (asyncWebRequest.isAsyncCompleted()) {
+					throw new StaleAsyncWebRequestException("Async request processing already completed");
+				}
+				setCallable(getSimpleCallable(value));
+				new AsyncExecutionChainRunnable(asyncWebRequest, buildChain()).run();
+			}
+		});
+	}
+
+	private Callable<Object> getSimpleCallable(final Object value) {
+		return new Callable<Object>() {
+			public Object call() throws Exception {
+				return value;
+			}
+		};
+	}
+}

spring-web/src/main/java/org/springframework/web/context/request/async/AsyncExecutionChainRunnable.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2002-2012 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.web.context.request.async;
+
+import java.util.concurrent.Callable;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.util.Assert;
+
+/**
+ * A Runnable for invoking a chain of Callable instances and completing async
+ * request processing while also dealing with any unhandled exceptions.
+ *
+ * @author Rossen Stoyanchev
+ * @since 3.2
+ *
+ * @see AsyncExecutionChain#startCallableChainProcessing()
+ * @see AsyncExecutionChain#startDeferredResultProcessing(DeferredResult)
+ */
+public class AsyncExecutionChainRunnable implements Runnable {
+
+	private static final Log logger = LogFactory.getLog(AsyncWebRequest.class);
+
+	private final AsyncWebRequest asyncWebRequest;
+
+	private final Callable<?> callable;
+
+	/**
+	 * Class constructor.
+	 * @param asyncWebRequest the async request
+	 * @param callable the async execution chain
+	 */
+	public AsyncExecutionChainRunnable(AsyncWebRequest asyncWebRequest, Callable<?> callable) {
+		Assert.notNull(asyncWebRequest, "An AsyncWebRequest is required");
+		Assert.notNull(callable, "A Callable is required");
+		Assert.state(asyncWebRequest.isAsyncStarted(), "Not an async request");
+		this.asyncWebRequest = asyncWebRequest;
+		this.callable = callable;
+	}
+
+	/**
+	 * Run the async execution chain and complete the async request.
+	 * <p>A {@link StaleAsyncWebRequestException} is logged at debug level and
+	 * absorbed while any other unhandled {@link Exception} results in a 500
+	 * response code.
+	 */
+	public void run() {
+		try {
+			logger.debug("Starting async execution chain");
+			callable.call();
+		}
+		catch (StaleAsyncWebRequestException ex) {
+			logger.trace("Could not complete async request", ex);
+		}
+		catch (Exception ex) {
+			logger.trace("Could not complete async request", ex);
+			this.asyncWebRequest.sendError(HttpStatus.INTERNAL_SERVER_ERROR, ex.getMessage());
+		}
+		finally {
+			logger.debug("Exiting async execution chain");
+			asyncWebRequest.complete();
+		}
+	}
+
+}