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-9443
Backport-Issue: SPR-6847
Backport-Commit: ed0576c181

org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AnnotationAsyncExecutionInterceptor.java

@@ -0,0 +1,70 @@
+/*
+ * 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.scheduling.annotation;
+
+import java.lang.reflect.Method;
+import java.util.concurrent.Executor;
+
+import org.springframework.aop.interceptor.AsyncExecutionInterceptor;
+import org.springframework.core.annotation.AnnotationUtils;
+
+/**
+ * Specialization of {@link AsyncExecutionInterceptor} that delegates method execution to
+ * an {@code Executor} based on the {@link Async} annotation. Specifically designed to
+ * support use of {@link Async#value()} executor qualification mechanism introduced in
+ * Spring 3.1.2. Supports detecting qualifier metadata via {@code @Async} at the method or
+ * declaring class level. See {@link #getExecutorQualifier(Method)} for details.
+ *
+ * @author Chris Beams
+ * @since 3.1.2
+ * @see org.springframework.scheduling.annotation.Async
+ * @see org.springframework.scheduling.annotation.AsyncAnnotationAdvisor
+ */
+public class AnnotationAsyncExecutionInterceptor extends AsyncExecutionInterceptor {
+
+	/**
+	 * Create a new {@code AnnotationAsyncExecutionInterceptor} with the given executor.
+	 * @param defaultExecutor the executor to be used by default if no more specific
+	 * executor has been qualified at the method level using {@link Async#value()}.
+	 */
+	public AnnotationAsyncExecutionInterceptor(Executor defaultExecutor) {
+		super(defaultExecutor);
+	}
+
+	/**
+	 * Return the qualifier or bean name of the executor to be used when executing the
+	 * given method, specified via {@link Async#value} at the method or declaring
+	 * class level. 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).
+	 * @param method the method to inspect for executor qualifier metadata
+	 * @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
+		// AnnotationAsyncExecutionAspect#getExecutorQualifier
+		Async async = AnnotationUtils.findAnnotation(method, Async.class);
+		if (async == null) {
+			async = AnnotationUtils.findAnnotation(method.getDeclaringClass(), Async.class);
+		}
+		return async == null ? null : async.value();
+	}
+
+}

org.springframework.context/src/main/java/org/springframework/scheduling/annotation/Async.java

@@ -37,8 +37,9 @@ import java.lang.annotation.Target;
  * Spring's {@link AsyncResult} or EJB 3.1's {@link javax.ejb.AsyncResult}.
  *
  * @author Juergen Hoeller
+ * @author Chris Beams
  * @since 3.0
- * @see org.springframework.aop.interceptor.AsyncExecutionInterceptor
+ * @see AnnotationAsyncExecutionInterceptor
  * @see AsyncAnnotationAdvisor
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
@@ -46,4 +47,18 @@ import java.lang.annotation.Target;
 @Documented
 public @interface Async {
 
+	/**
+	 * A qualifier value for the specified asynchronous operation(s).
+	 * <p>May be used to determine the target executor to be used when executing this
+	 * method, matching the qualifier value (or the bean name) of a specific
+	 * {@link java.util.concurrent.Executor Executor} or
+	 * {@link org.springframework.core.task.TaskExecutor TaskExecutor}
+	 * bean definition.
+	 * <p>When specified on a class level {@code @Async} annotation, indicates that the
+	 * given executor should be used for all methods within the class. Method level use
+	 * of {@link Async#value} always overrides any value set at the class level.
+	 * @since 3.1.2
+	 */
+	String value() default "";
+
 }

org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncAnnotationAdvisor.java

@@ -25,11 +25,12 @@ import java.util.concurrent.Executor;
 import org.aopalliance.aop.Advice;
 
 import org.springframework.aop.Pointcut;
-import org.springframework.aop.interceptor.AsyncExecutionInterceptor;
 import org.springframework.aop.support.AbstractPointcutAdvisor;
 import org.springframework.aop.support.ComposablePointcut;
 import org.springframework.aop.support.annotation.AnnotationMatchingPointcut;
-import org.springframework.core.task.AsyncTaskExecutor;
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.BeanFactory;
+import org.springframework.beans.factory.BeanFactoryAware;
 import org.springframework.core.task.SimpleAsyncTaskExecutor;
 import org.springframework.util.Assert;
 
@@ -51,12 +52,14 @@ import org.springframework.util.Assert;
  * @see org.springframework.dao.support.PersistenceExceptionTranslator
  */
 @SuppressWarnings("serial")
-public class AsyncAnnotationAdvisor extends AbstractPointcutAdvisor {
+public class AsyncAnnotationAdvisor extends AbstractPointcutAdvisor implements BeanFactoryAware {
 
 	private Advice advice;
 
 	private Pointcut pointcut;
 
+	private BeanFactory beanFactory;
+
 
 	/**
 	 * Create a new {@code AsyncAnnotationAdvisor} for bean-style configuration.
@@ -81,14 +84,30 @@ public class AsyncAnnotationAdvisor extends AbstractPointcutAdvisor {
 			// If EJB 3.1 API not present, simply ignore.
 		}
 		this.advice = buildAdvice(executor);
+		this.setTaskExecutor(executor);
 		this.pointcut = buildPointcut(asyncAnnotationTypes);
 	}
 
+	/**
+	 * Set the {@code BeanFactory} to be used when looking up executors by qualifier.
+	 */
+	public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
+		this.beanFactory = beanFactory;
+		delegateBeanFactory(beanFactory);
+	}
+
+	public void delegateBeanFactory(BeanFactory beanFactory) {
+		if (this.advice instanceof AnnotationAsyncExecutionInterceptor) {
+			((AnnotationAsyncExecutionInterceptor)this.advice).setBeanFactory(beanFactory);
+		}
+	}
+
 	/**
 	 * Specify the task executor to use for asynchronous methods.
 	 */
 	public void setTaskExecutor(Executor executor) {
 		this.advice = buildAdvice(executor);
+		delegateBeanFactory(this.beanFactory);
 	}
 
 	/**
@@ -118,12 +137,7 @@ public class AsyncAnnotationAdvisor extends AbstractPointcutAdvisor {
 
 
 	protected Advice buildAdvice(Executor executor) {
-		if (executor instanceof AsyncTaskExecutor) {
-			return new AsyncExecutionInterceptor((AsyncTaskExecutor) executor);
-		}
-		else {
-			return new AsyncExecutionInterceptor(executor);
-		}
+		return new AnnotationAsyncExecutionInterceptor(executor);
 	}
 
 	/**

org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncAnnotationBeanPostProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * 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.
@@ -24,7 +24,10 @@ import org.springframework.aop.framework.AopInfrastructureBean;
 import org.springframework.aop.framework.ProxyConfig;
 import org.springframework.aop.framework.ProxyFactory;
 import org.springframework.aop.support.AopUtils;
+import org.springframework.beans.BeansException;
 import org.springframework.beans.factory.BeanClassLoaderAware;
+import org.springframework.beans.factory.BeanFactory;
+import org.springframework.beans.factory.BeanFactoryAware;
 import org.springframework.beans.factory.InitializingBean;
 import org.springframework.beans.factory.config.BeanPostProcessor;
 import org.springframework.core.Ordered;
@@ -53,7 +56,8 @@ import org.springframework.util.ClassUtils;
  */
 @SuppressWarnings("serial")
 public class AsyncAnnotationBeanPostProcessor extends ProxyConfig
-		implements BeanPostProcessor, BeanClassLoaderAware, InitializingBean, Ordered {
+		implements BeanPostProcessor, BeanClassLoaderAware, BeanFactoryAware,
+		InitializingBean, Ordered {
 
 	private Class<? extends Annotation> asyncAnnotationType;
 
@@ -69,6 +73,8 @@ public class AsyncAnnotationBeanPostProcessor extends ProxyConfig
 	 */
 	private int order = Ordered.LOWEST_PRECEDENCE;
 
+	private BeanFactory beanFactory;
+
 
 	/**
 	 * Set the 'async' annotation type to be detected at either class or method
@@ -95,12 +101,17 @@ public class AsyncAnnotationBeanPostProcessor extends ProxyConfig
 		this.beanClassLoader = classLoader;
 	}
 
+	public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
+		this.beanFactory = beanFactory;
+	}
+
 	public void afterPropertiesSet() {
 		this.asyncAnnotationAdvisor = (this.executor != null ?
 				new AsyncAnnotationAdvisor(this.executor) : new AsyncAnnotationAdvisor());
 		if (this.asyncAnnotationType != null) {
 			this.asyncAnnotationAdvisor.setAsyncAnnotationType(this.asyncAnnotationType);
 		}
+		this.asyncAnnotationAdvisor.setBeanFactory(this.beanFactory);
 	}
 
 	public int getOrder() {