Support executor qualification with @Async#value

Prior to this change, Spring's @Async annotation support was tied to a
single AsyncTaskExecutor bean, meaning that all methods marked with
@Async were forced to use the same executor. This is an undesirable
limitation, given that certain methods may have different priorities,
etc. This leads to the need to (optionally) qualify which executor
should handle each method.

This is similar to the way that Spring's @Transactional annotation was
originally tied to a single PlatformTransactionManager, but in Spring
3.0 was enhanced to allow for a qualifier via the #value attribute, e.g.

  @Transactional("ptm1")
  public void m() { ... }

where "ptm1" is either the name of a PlatformTransactionManager bean or
a qualifier value associated with a PlatformTransactionManager bean,
e.g. via the <qualifier> element in XML or the @Qualifier annotation.

This commit introduces the same approach to @Async and its relationship
to underlying executor beans. As always, the following syntax remains
supported

  @Async
  public void m() { ... }

indicating that calls to #m will be delegated to the "default" executor,
i.e. the executor provided to

  <task:annotation-driven executor="..."/>

or the executor specified when authoring a @Configuration class that
implements AsyncConfigurer and its #getAsyncExecutor method.

However, it now also possible to qualify which executor should be used
on a method-by-method basis, e.g.

  @Async("e1")
  public void m() { ... }

indicating that calls to #m will be delegated to the executor bean
named or otherwise qualified as "e1". Unlike the default executor
which is specified up front at configuration time as described above,
the "e1" executor bean is looked up within the container on the first
execution of #m and then cached in association with that method for the
lifetime of the container.

Class-level use of Async#value behaves as expected, indicating that all
methods within the annotated class should be executed with the named
executor. In the case of both method- and class-level annotations, any
method-level #value overrides any class level #value.

This commit introduces the following major changes:

 - Add @Async#value attribute for executor qualification

 - Introduce AsyncExecutionAspectSupport as a common base class for
   both MethodInterceptor- and AspectJ-based async aspects. This base
   class provides common structure for specifying the default executor
   (#setExecutor) as well as logic for determining (and caching) which
   executor should execute a given method (#determineAsyncExecutor) and
   an abstract method to allow subclasses to provide specific strategies
   for executor qualification (#getExecutorQualifier).

 - Introduce AnnotationAsyncExecutionInterceptor as a specialization of
   the existing AsyncExecutionInterceptor to allow for introspection of
   the @Async annotation and its #value attribute for a given method.
   Note that this new subclass was necessary for packaging reasons -
   the original AsyncExecutionInterceptor lives in
   org.springframework.aop and therefore does not have visibility to
   the @Async annotation in org.springframework.scheduling.annotation.
   This new subclass replaces usage of AsyncExecutionInterceptor
   throughout the framework, though the latter remains usable and
   undeprecated for compatibility with any existing third-party
   extensions.

 - Add documentation to spring-task-3.2.xsd and reference manual
   explaining @Async executor qualification

 - Add tests covering all new functionality

Note that the public API of all affected components remains backward-
compatible.

Issue: SPR-6847

spring-aspects/src/main/java/org/springframework/scheduling/aspectj/AbstractAsyncExecutionAspect.aj

@@ -21,9 +21,9 @@ import java.util.concurrent.Executor;
 import java.util.concurrent.Future;
 
 import org.aspectj.lang.reflect.MethodSignature;
+
+import org.springframework.aop.interceptor.AsyncExecutionAspectSupport;
 import org.springframework.core.task.AsyncTaskExecutor;
-import org.springframework.core.task.SimpleAsyncTaskExecutor;
-import org.springframework.core.task.support.TaskExecutorAdapter;
 
 /**
  * Abstract aspect that routes selected methods asynchronously.
@@ -34,19 +34,18 @@ import org.springframework.core.task.support.TaskExecutorAdapter;
  *
  * @author Ramnivas Laddad
  * @author Juergen Hoeller
+ * @author Chris Beams
  * @since 3.0.5
  */
-public abstract aspect AbstractAsyncExecutionAspect {
+public abstract aspect AbstractAsyncExecutionAspect extends AsyncExecutionAspectSupport {
 
-	private AsyncTaskExecutor asyncExecutor;
-
-	public void setExecutor(Executor executor) {
-		if (executor instanceof AsyncTaskExecutor) {
-			this.asyncExecutor = (AsyncTaskExecutor) executor;
-		}
-		else {
-			this.asyncExecutor = new TaskExecutorAdapter(executor);
-		}
+	/**
+	 * Create an {@code AnnotationAsyncExecutionAspect} with a {@code null} default
+	 * executor, which should instead be set via {@code #aspectOf} and
+	 * {@link #setExecutor(Executor)}.
+	 */
+	public AbstractAsyncExecutionAspect() {
+		super(null);
 	}
 
 	/**
@@ -57,7 +56,9 @@ public abstract aspect AbstractAsyncExecutionAspect {
 	 * otherwise.
 	 */
 	Object around() : asyncMethod() {
-		if (this.asyncExecutor == null) {
+		MethodSignature methodSignature = (MethodSignature) thisJoinPointStaticPart.getSignature();
+		AsyncTaskExecutor executor = determineAsyncExecutor(methodSignature.getMethod());
+		if (executor == null) {
 			return proceed();
 		}
 		Callable<Object> callable = new Callable<Object>() {
@@ -68,8 +69,8 @@ public abstract aspect AbstractAsyncExecutionAspect {
 				}
 				return null;
 			}};
-		Future<?> result = this.asyncExecutor.submit(callable);
-		if (Future.class.isAssignableFrom(((MethodSignature) thisJoinPointStaticPart.getSignature()).getReturnType())) {
+		Future<?> result = executor.submit(callable);
+		if (Future.class.isAssignableFrom(methodSignature.getReturnType())) {
 			return result;
 		}
 		else {

spring-aspects/src/main/java/org/springframework/scheduling/aspectj/AnnotationAsyncExecutionAspect.aj

@@ -16,7 +16,11 @@
 
 package org.springframework.scheduling.aspectj;
 
+import java.lang.reflect.Method;
+
 import java.util.concurrent.Future;
+
+import org.springframework.core.annotation.AnnotationUtils;
 import org.springframework.scheduling.annotation.Async;
 
 /**
@@ -31,6 +35,7 @@ import org.springframework.scheduling.annotation.Async;
  * constraint, it produces only a warning.
  *
  * @author Ramnivas Laddad
+ * @author Chris Beams
  * @since 3.0.5
  */
 public aspect AnnotationAsyncExecutionAspect extends AbstractAsyncExecutionAspect {
@@ -43,6 +48,28 @@ public aspect AnnotationAsyncExecutionAspect extends AbstractAsyncExecutionAspec
 
 	public pointcut asyncMethod() : asyncMarkedMethod() || asyncTypeMarkedMethod();
 
+	/**
+	 * {@inheritDoc}
+	 * <p>This implementation inspects the given method and its declaring class for the
+	 * {@code @Async} annotation, returning the qualifier value expressed by
+	 * {@link Async#value()}. If {@code @Async} is specified at both the method and class level, the
+	 * method's {@code #value} takes precedence (even if empty string, indicating that
+	 * the default executor should be used preferentially).
+	 * @return the qualifier if specified, otherwise empty string indicating that the
+	 * {@linkplain #setExecutor(Executor) default executor} should be used
+	 * @see #determineAsyncExecutor(Method)
+	 */
+	@Override
+	protected String getExecutorQualifier(Method method) {
+		// maintainer's note: changes made here should also be made in
+		// AnnotationAsyncExecutionInterceptor#getExecutorQualifier
+		Async async = AnnotationUtils.findAnnotation(method, Async.class);
+		if (async == null) {
+			async = AnnotationUtils.findAnnotation(method.getDeclaringClass(), Async.class);
+		}
+		return async == null ? null : async.value();
+	}
+
 	declare error:
 		execution(@Async !(void||Future) *(..)):
 		"Only methods that return void or Future may have an @Async annotation";