Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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: ed0576c
  • Loading branch information...
commit 8bab873107ffe78422bab1dd3641e119852b99f7 1 parent e8006bd
@cbeams cbeams authored
Showing with 564 additions and 48 deletions.
  1. +3 −1 build-spring-framework/resources/changelog.txt
  2. +127 −0 org.springframework.aop/src/main/java/org/springframework/aop/interceptor/AsyncExecutionAspectSupport.java
  3. +32 −18 org.springframework.aop/src/main/java/org/springframework/aop/interceptor/AsyncExecutionInterceptor.java
  4. +1 −0  org.springframework.aspects/ivy.xml
  5. +16 −15 ...pringframework.aspects/src/main/java/org/springframework/scheduling/aspectj/AbstractAsyncExecutionAspect.aj
  6. +27 −0 ...ingframework.aspects/src/main/java/org/springframework/scheduling/aspectj/AnnotationAsyncExecutionAspect.aj
  7. +35 −0 ...ework.aspects/src/test/java/org/springframework/scheduling/aspectj/AnnotationAsyncExecutionAspectTests.java
  8. +70 −0 ...rk.context/src/main/java/org/springframework/scheduling/annotation/AnnotationAsyncExecutionInterceptor.java
  9. +16 −1 org.springframework.context/src/main/java/org/springframework/scheduling/annotation/Async.java
  10. +23 −9 ...springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncAnnotationAdvisor.java
  11. +13 −2 ...ework.context/src/main/java/org/springframework/scheduling/annotation/AsyncAnnotationBeanPostProcessor.java
  12. +6 −0 org.springframework.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd
  13. +53 −0 ...ntext/src/test/java/org/springframework/scheduling/annotation/AnnotationAsyncExecutionInterceptorTests.java
  14. +50 −0 org.springframework.context/src/test/java/org/springframework/scheduling/annotation/AsyncExecutionTests.java
  15. +67 −0 org.springframework.context/src/test/java/org/springframework/scheduling/annotation/EnableAsyncTests.java
  16. +25 −2 spring-framework-reference/src/scheduling.xml
View
4 build-spring-framework/resources/changelog.txt
@@ -23,11 +23,13 @@ Changes in version 3.1.2 (2012-06-??)
* fix content negotiation issue when sorting selected media types by quality value
* raise RestClientException instead of IllegalArgumentException for unknown status codes
* discover controllers based on type-level @RequestMapping in new @MVC support classes
-* fix issue with suffix pattern in AnnotationMethodHandlerAdapter
+* fix issue with suffix pattern in AnnotationMethodHandlerAdapter
* merge rather than add URI vars in ExtendedServletRequestDataBinder
* raise RestClientException for unknown HTTP status codes
+* support executor qualification with @Async#value
* fix issue with encoded params in UriComponentsBuilder
+
Changes in version 3.1.1 (2012-02-16)
-------------------------------------
View
127 ...rk.aop/src/main/java/org/springframework/aop/interceptor/AsyncExecutionAspectSupport.java
@@ -0,0 +1,127 @@
+/*
+ * 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.aop.interceptor;
+
+import java.lang.reflect.Method;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.Executor;
+
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.BeanFactory;
+import org.springframework.beans.factory.BeanFactoryAware;
+import org.springframework.beans.factory.BeanFactoryUtils;
+import org.springframework.core.task.AsyncTaskExecutor;
+import org.springframework.core.task.support.TaskExecutorAdapter;
+import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
+
+/**
+ * Base class for asynchronous method execution aspects, such as
+ * {@link org.springframework.scheduling.annotation.AnnotationAsyncExecutionInterceptor}
+ * or {@link org.springframework.scheduling.aspectj.AnnotationAsyncExecutionAspect}.
+ *
+ * <p>Provides support for <i>executor qualification</i> on a method-by-method basis.
+ * {@code AsyncExecutionAspectSupport} objects must be constructed with a default {@code
+ * Executor}, but each individual method may further qualify a specific {@code Executor}
+ * bean to be used when executing it, e.g. through an annotation attribute.
+ *
+ * @author Chris Beams
+ * @since 3.1.2
+ */
+public abstract class AsyncExecutionAspectSupport implements BeanFactoryAware {
+
+ private final Map<Method, AsyncTaskExecutor> executors = new HashMap<Method, AsyncTaskExecutor>();
+
+ private Executor defaultExecutor;
+
+ private BeanFactory beanFactory;
+
+
+ /**
+ * Create a new {@link AsyncExecutionAspectSupport}, using the provided default
+ * executor unless individual async methods indicate via qualifier that a more
+ * specific executor should be used.
+ * @param defaultExecutor the executor to use when executing asynchronous methods
+ */
+ public AsyncExecutionAspectSupport(Executor defaultExecutor) {
+ this.setExecutor(defaultExecutor);
+ }
+
+
+ /**
+ * Supply the executor to be used when executing async methods.
+ * @param defaultExecutor the {@code Executor} (typically a Spring {@code
+ * AsyncTaskExecutor} or {@link java.util.concurrent.ExecutorService}) to delegate to
+ * unless a more specific executor has been requested via a qualifier on the async
+ * method, in which case the executor will be looked up at invocation time against the
+ * enclosing bean factory.
+ * @see #getExecutorQualifier
+ * @see #setBeanFactory(BeanFactory)
+ */
+ public void setExecutor(Executor defaultExecutor) {
+ this.defaultExecutor = defaultExecutor;
+ }
+
+ /**
+ * Set the {@link BeanFactory} to be used when looking up executors by qualifier.
+ */
+ public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
+ this.beanFactory = beanFactory;
+ }
+
+ /**
+ * Return the qualifier or bean name of the executor to be used when executing the
+ * given async method, typically specified in the form of an annotation attribute.
+ * Returning an empty string or {@code null} indicates that no specific executor has
+ * been specified and that the {@linkplain #setExecutor(Executor) default executor}
+ * should be used.
+ * @param method the method to inspect for executor qualifier metadata
+ * @return the qualifier if specified, otherwise empty string or {@code null}
+ * @see #determineAsyncExecutor(Method)
+ */
+ protected abstract String getExecutorQualifier(Method method);
+
+ /**
+ * Determine the specific executor to use when executing the given method.
+ * @returns the executor to use (never {@code null})
+ */
+ protected AsyncTaskExecutor determineAsyncExecutor(Method method) {
+ if (!this.executors.containsKey(method)) {
+ Executor executor = this.defaultExecutor;
+
+ String qualifier = getExecutorQualifier(method);
+ if (StringUtils.hasLength(qualifier)) {
+ Assert.notNull(this.beanFactory,
+ "BeanFactory must be set on " + this.getClass().getSimpleName() +
+ " to access qualified executor [" + qualifier + "]");
+ executor = BeanFactoryUtils.qualifiedBeanOfType(this.beanFactory, Executor.class, qualifier);
+ }
+
+ if (executor instanceof AsyncTaskExecutor) {
+ this.executors.put(method, (AsyncTaskExecutor) executor);
+ }
+ else if (executor instanceof Executor) {
+ this.executors.put(method, new TaskExecutorAdapter(executor));
+ }
+ }
+
+ return this.executors.get(method);
+ }
+
+}
View
50 ...work.aop/src/main/java/org/springframework/aop/interceptor/AsyncExecutionInterceptor.java
@@ -16,6 +16,8 @@
package org.springframework.aop.interceptor;
+import java.lang.reflect.Method;
+
import java.util.concurrent.Callable;
import java.util.concurrent.Executor;
import java.util.concurrent.Future;
@@ -25,8 +27,6 @@
import org.springframework.core.Ordered;
import org.springframework.core.task.AsyncTaskExecutor;
-import org.springframework.core.task.support.TaskExecutorAdapter;
-import org.springframework.util.Assert;
import org.springframework.util.ReflectionUtils;
/**
@@ -44,39 +44,39 @@
* (like Spring's {@link org.springframework.scheduling.annotation.AsyncResult}
* or EJB 3.1's <code>javax.ejb.AsyncResult</code>).
*
+ * <p>As of Spring 3.1.2 the {@code AnnotationAsyncExecutionInterceptor} subclass is
+ * preferred for use due to its support for executor qualification in conjunction with
+ * Spring's {@code @Async} annotation.
+ *
* @author Juergen Hoeller
+ * @author Chris Beams
* @since 3.0
* @see org.springframework.scheduling.annotation.Async
* @see org.springframework.scheduling.annotation.AsyncAnnotationAdvisor
+ * @see org.springframework.scheduling.annotation.AnnotationAsyncExecutionInterceptor
*/
-public class AsyncExecutionInterceptor implements MethodInterceptor, Ordered {
-
- private final AsyncTaskExecutor asyncExecutor;
-
+public class AsyncExecutionInterceptor extends AsyncExecutionAspectSupport
+ implements MethodInterceptor, Ordered {
/**
* Create a new {@code AsyncExecutionInterceptor}.
* @param executor the {@link Executor} (typically a Spring {@link AsyncTaskExecutor}
* or {@link java.util.concurrent.ExecutorService}) to delegate to.
*/
- public AsyncExecutionInterceptor(AsyncTaskExecutor asyncExecutor) {
- Assert.notNull(asyncExecutor, "TaskExecutor must not be null");
- this.asyncExecutor = asyncExecutor;
+ public AsyncExecutionInterceptor(Executor executor) {
+ super(executor);
}
/**
- * Create a new AsyncExecutionInterceptor.
- * @param asyncExecutor the <code>java.util.concurrent</code> Executor
- * to delegate to (typically a {@link java.util.concurrent.ExecutorService}
+ * Intercept the given method invocation, submit the actual calling of the method to
+ * the correct task executor and return immediately to the caller.
+ * @param invocation the method to intercept and make asynchronous
+ * @return {@link Future} if the original method returns {@code Future}; {@code null}
+ * otherwise.
*/
- public AsyncExecutionInterceptor(Executor asyncExecutor) {
- this.asyncExecutor = new TaskExecutorAdapter(asyncExecutor);
- }
-
-
public Object invoke(final MethodInvocation invocation) throws Throwable {
- Future<?> result = this.asyncExecutor.submit(
+ Future<?> result = this.determineAsyncExecutor(invocation.getMethod()).submit(
new Callable<Object>() {
public Object call() throws Exception {
try {
@@ -99,6 +99,20 @@ public Object call() throws Exception {
}
}
+ /**
+ * {@inheritDoc}
+ * <p>This implementation is a no-op for compatibility in Spring 3.1.2. Subclasses may
+ * override to provide support for extracting qualifier information, e.g. via an
+ * annotation on the given method.
+ * @return always {@code null}
+ * @see #determineAsyncExecutor(Method)
+ * @since 3.1.2
+ */
+ @Override
+ protected String getExecutorQualifier(Method method) {
+ return null;
+ }
+
public int getOrder() {
return Ordered.HIGHEST_PRECEDENCE;
}
View
1  org.springframework.aspects/ivy.xml
@@ -38,6 +38,7 @@
<dependency org="org.springframework" name="org.springframework.context.support" rev="latest.integration" conf="optional, cache->compile"/>
<dependency org="javax.persistence" name="com.springsource.javax.persistence" rev="1.0.0" conf="optional, orm->compile"/>
<dependency org="org.junit" name="com.springsource.org.junit" rev="${junit.version}" conf="test->compile"/>
+ <dependency org="org.hamcrest" name="com.springsource.org.hamcrest" rev="1.1.0" conf="test->compile"/>
<dependency org="javax.mail" name="com.springsource.javax.mail" rev="1.4.0" conf="optional, test->compile"/>
</dependencies>
View
31 ...ects/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 {
-
- private AsyncTaskExecutor asyncExecutor;
+public abstract aspect AbstractAsyncExecutionAspect extends AsyncExecutionAspectSupport {
- 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 {
View
27 ...ts/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";
View
35 ...test/java/org/springframework/scheduling/aspectj/AnnotationAsyncExecutionAspectTests.java
@@ -22,9 +22,16 @@
import org.junit.Before;
import org.junit.Test;
+
+import org.springframework.beans.factory.support.DefaultListableBeanFactory;
+import org.springframework.beans.factory.support.RootBeanDefinition;
import org.springframework.core.task.SimpleAsyncTaskExecutor;
import org.springframework.scheduling.annotation.Async;
import org.springframework.scheduling.annotation.AsyncResult;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
+
+import static org.hamcrest.CoreMatchers.not;
+import static org.hamcrest.Matchers.startsWith;
import static org.junit.Assert.*;
@@ -104,6 +111,22 @@ public void methodReturningNonVoidNonFutureInAsyncClassGetsRoutedSynchronously()
assertEquals(0, executor.submitCompleteCounter);
}
+ @Test
+ public void qualifiedAsyncMethodsAreRoutedToCorrectExecutor() throws InterruptedException, ExecutionException {
+ DefaultListableBeanFactory beanFactory = new DefaultListableBeanFactory();
+ beanFactory.registerBeanDefinition("e1", new RootBeanDefinition(ThreadPoolTaskExecutor.class));
+ AnnotationAsyncExecutionAspect.aspectOf().setBeanFactory(beanFactory);
+
+ ClassWithQualifiedAsyncMethods obj = new ClassWithQualifiedAsyncMethods();
+
+ Future<Thread> defaultThread = obj.defaultWork();
+ assertThat(defaultThread.get(), not(Thread.currentThread()));
+ assertThat(defaultThread.get().getName(), not(startsWith("e1-")));
+
+ Future<Thread> e1Thread = obj.e1Work();
+ assertThat(e1Thread.get().getName(), startsWith("e1-"));
+ }
+
@SuppressWarnings("serial")
private static class CountingExecutor extends SimpleAsyncTaskExecutor {
@@ -180,4 +203,16 @@ public int return5() {
}
}
+
+ static class ClassWithQualifiedAsyncMethods {
+ @Async
+ public Future<Thread> defaultWork() {
+ return new AsyncResult<Thread>(Thread.currentThread());
+ }
+
+ @Async("e1")
+ public Future<Thread> e1Work() {
+ return new AsyncResult<Thread>(Thread.currentThread());
+ }
+ }
}
View
70 ...n/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();
+ }
+
+}
View
17 ...pringframework.context/src/main/java/org/springframework/scheduling/annotation/Async.java
@@ -37,8 +37,9 @@
* 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 @@
@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 "";
+
}
View
32 ...ntext/src/main/java/org/springframework/scheduling/annotation/AsyncAnnotationAdvisor.java
@@ -25,11 +25,12 @@
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 @@
* @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 AsyncAnnotationAdvisor(Executor executor) {
// 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 Pointcut getPointcut() {
protected Advice buildAdvice(Executor executor) {
- if (executor instanceof AsyncTaskExecutor) {
- return new AsyncExecutionInterceptor((AsyncTaskExecutor) executor);
- }
- else {
- return new AsyncExecutionInterceptor(executor);
- }
+ return new AnnotationAsyncExecutionInterceptor(executor);
}
/**
View
15 ...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.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 @@
*/
@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 @@
*/
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 void setBeanClassLoader(ClassLoader classLoader) {
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() {
View
6 ...work.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd
@@ -36,6 +36,9 @@
Specifies the java.util.Executor instance to use when invoking asynchronous methods.
If not provided, an instance of org.springframework.core.task.SimpleAsyncTaskExecutor
will be used by default.
+ Note that as of Spring 3.1.2, individual @Async methods may qualify which executor to
+ use, meaning that the executor specified here acts as a default for all non-qualified
+ @Async methods.
]]></xsd:documentation>
</xsd:annotation>
</xsd:attribute>
@@ -98,6 +101,9 @@
required even when defining the executor as an inner bean: The executor
won't be directly accessible then but will nevertheless use the specified
id as the thread name prefix of the threads that it manages.
+ In the case of multiple task:executors, as of Spring 3.1.2 this value may be used to
+ qualify which executor should handle a given @Async method, e.g. @Async("executorId").
+ See the Javadoc for the #value attribute of Spring's @Async annotation for details.
]]></xsd:documentation>
</xsd:annotation>
</xsd:attribute>
View
53 ...a/org/springframework/scheduling/annotation/AnnotationAsyncExecutionInterceptorTests.java
@@ -0,0 +1,53 @@
+/*
+ * 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 org.junit.Test;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.junit.Assert.*;
+
+/**
+ * Unit tests for {@link AnnotationAsyncExecutionInterceptor}.
+ *
+ * @author Chris Beams
+ * @since 3.1.2
+ */
+public class AnnotationAsyncExecutionInterceptorTests {
+
+ @Test
+ @SuppressWarnings("unused")
+ public void testGetExecutorQualifier() throws SecurityException, NoSuchMethodException {
+ AnnotationAsyncExecutionInterceptor i = new AnnotationAsyncExecutionInterceptor(null);
+ {
+ class C { @Async("qMethod") void m() { } }
+ assertThat(i.getExecutorQualifier(C.class.getDeclaredMethod("m")), is("qMethod"));
+ }
+ {
+ @Async("qClass") class C { void m() { } }
+ assertThat(i.getExecutorQualifier(C.class.getDeclaredMethod("m")), is("qClass"));
+ }
+ {
+ @Async("qClass") class C { @Async("qMethod") void m() { } }
+ assertThat(i.getExecutorQualifier(C.class.getDeclaredMethod("m")), is("qMethod"));
+ }
+ {
+ @Async("qClass") class C { @Async void m() { } }
+ assertThat(i.getExecutorQualifier(C.class.getDeclaredMethod("m")), is(""));
+ }
+ }
+}
View
50 ....context/src/test/java/org/springframework/scheduling/annotation/AsyncExecutionTests.java
@@ -25,11 +25,13 @@
import org.springframework.context.ApplicationEvent;
import org.springframework.context.ApplicationListener;
import org.springframework.context.support.GenericApplicationContext;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import static org.junit.Assert.*;
/**
* @author Juergen Hoeller
+ * @author Chris Beams
*/
public class AsyncExecutionTests {
@@ -56,6 +58,26 @@ public void asyncMethods() throws Exception {
}
@Test
+ public void asyncMethodsWithQualifier() throws Exception {
+ originalThreadName = Thread.currentThread().getName();
+ GenericApplicationContext context = new GenericApplicationContext();
+ context.registerBeanDefinition("asyncTest", new RootBeanDefinition(AsyncMethodWithQualifierBean.class));
+ context.registerBeanDefinition("autoProxyCreator", new RootBeanDefinition(DefaultAdvisorAutoProxyCreator.class));
+ context.registerBeanDefinition("asyncAdvisor", new RootBeanDefinition(AsyncAnnotationAdvisor.class));
+ context.registerBeanDefinition("e0", new RootBeanDefinition(ThreadPoolTaskExecutor.class));
+ context.registerBeanDefinition("e1", new RootBeanDefinition(ThreadPoolTaskExecutor.class));
+ context.registerBeanDefinition("e2", new RootBeanDefinition(ThreadPoolTaskExecutor.class));
+ context.refresh();
+ AsyncMethodWithQualifierBean asyncTest = context.getBean("asyncTest", AsyncMethodWithQualifierBean.class);
+ asyncTest.doNothing(5);
+ asyncTest.doSomething(10);
+ Future<String> future = asyncTest.returnSomething(20);
+ assertEquals("20", future.get());
+ Future<String> future2 = asyncTest.returnSomething2(30);
+ assertEquals("30", future2.get());
+ }
+
+ @Test
public void asyncClass() throws Exception {
originalThreadName = Thread.currentThread().getName();
GenericApplicationContext context = new GenericApplicationContext();
@@ -165,6 +187,34 @@ public void doSomething(int i) {
}
+ @Async("e0")
+ public static class AsyncMethodWithQualifierBean {
+
+ public void doNothing(int i) {
+ assertTrue(Thread.currentThread().getName().equals(originalThreadName));
+ }
+
+ @Async("e1")
+ public void doSomething(int i) {
+ assertTrue(!Thread.currentThread().getName().equals(originalThreadName));
+ assertTrue(Thread.currentThread().getName().startsWith("e1-"));
+ }
+
+ @Async("e2")
+ public Future<String> returnSomething(int i) {
+ assertTrue(!Thread.currentThread().getName().equals(originalThreadName));
+ assertTrue(Thread.currentThread().getName().startsWith("e2-"));
+ return new AsyncResult<String>(Integer.toString(i));
+ }
+
+ public Future<String> returnSomething2(int i) {
+ assertTrue(!Thread.currentThread().getName().equals(originalThreadName));
+ assertTrue(Thread.currentThread().getName().startsWith("e0-"));
+ return new AsyncResult<String>(Integer.toString(i));
+ }
+ }
+
+
@Async
public static class AsyncClassBean {
View
67 ...ork.context/src/test/java/org/springframework/scheduling/annotation/EnableAsyncTests.java
@@ -21,7 +21,9 @@
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executor;
+import java.util.concurrent.Future;
import org.junit.Test;
@@ -29,6 +31,7 @@
import org.springframework.aop.framework.Advised;
import org.springframework.aop.support.AopUtils;
import org.springframework.beans.factory.BeanDefinitionStoreException;
+import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.AdviceMode;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.context.annotation.Bean;
@@ -71,6 +74,48 @@ public AsyncBean asyncBean() {
}
+ @SuppressWarnings("unchecked")
+ @Test
+ public void withAsyncBeanWithExecutorQualifiedByName() throws ExecutionException, InterruptedException {
+ AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
+ ctx.register(AsyncWithExecutorQualifiedByNameConfig.class);
+ ctx.refresh();
+
+ AsyncBeanWithExecutorQualifiedByName asyncBean = ctx.getBean(AsyncBeanWithExecutorQualifiedByName.class);
+ Future<Thread> workerThread0 = asyncBean.work0();
+ assertThat(workerThread0.get().getName(), not(anyOf(startsWith("e1-"), startsWith("otherExecutor-"))));
+ Future<Thread> workerThread = asyncBean.work();
+ assertThat(workerThread.get().getName(), startsWith("e1-"));
+ Future<Thread> workerThread2 = asyncBean.work2();
+ assertThat(workerThread2.get().getName(), startsWith("otherExecutor-"));
+ Future<Thread> workerThread3 = asyncBean.work3();
+ assertThat(workerThread3.get().getName(), startsWith("otherExecutor-"));
+ }
+
+
+ static class AsyncBeanWithExecutorQualifiedByName {
+ @Async
+ public Future<Thread> work0() {
+ return new AsyncResult<Thread>(Thread.currentThread());
+ }
+
+ @Async("e1")
+ public Future<Thread> work() {
+ return new AsyncResult<Thread>(Thread.currentThread());
+ }
+
+ @Async("otherExecutor")
+ public Future<Thread> work2() {
+ return new AsyncResult<Thread>(Thread.currentThread());
+ }
+
+ @Async("e2")
+ public Future<Thread> work3() {
+ return new AsyncResult<Thread>(Thread.currentThread());
+ }
+ }
+
+
static class AsyncBean {
private Thread threadOfExecution;
@@ -208,6 +253,28 @@ public Executor getAsyncExecutor() {
executor.initialize();
return executor;
}
+ }
+
+ @Configuration
+ @EnableAsync
+ static class AsyncWithExecutorQualifiedByNameConfig {
+ @Bean
+ public AsyncBeanWithExecutorQualifiedByName asyncBean() {
+ return new AsyncBeanWithExecutorQualifiedByName();
+ }
+
+ @Bean
+ public Executor e1() {
+ ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+ return executor;
+ }
+
+ @Bean
+ @Qualifier("e2")
+ public Executor otherExecutor() {
+ ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+ return executor;
+ }
}
}
View
27 spring-framework-reference/src/scheduling.xml
@@ -591,7 +591,7 @@ Future&lt;String&gt; returnSomething(int i) {
<para><interfacename>@Async</interfacename> can not be used in
conjunction with lifecycle callbacks such as
- <interfacename>@PostConstruct</interfacename>. To asynchonously
+ <interfacename>@PostConstruct</interfacename>. To asynchronously
initialize Spring beans you currently have to use a separate
initializing Spring bean that invokes the
<interfacename>@Async</interfacename> annotated method on the target
@@ -637,6 +637,29 @@ public class SampleBeanInititalizer {
scheduler reference is provided for managing those methods annotated
with @Scheduled.</para>
</section>
+
+ <section id="scheduling-annotation-support-qualification">
+ <title>Executor qualification with @Async</title>
+
+ <para>By default when specifying <interfacename>@Async</interfacename> on
+ a method, the executor that will be used is the one supplied to the
+ 'annotation-driven' element as described above. However, the
+ <literal>value</literal> attribute of the
+ <interfacename>@Async</interfacename> annotation can be used when needing
+ to indicate that an executor other than the default should be used when
+ executing a given method.</para>
+ <programlisting language="java">@Async("otherExecutor")
+void doSomething(String s) {
+ // this will be executed asynchronously by "otherExecutor"
+}</programlisting>
+
+ <para>In this case, "otherExecutor" may be the name of any
+ <interfacename>Executor</interfacename> bean in the Spring container, or
+ may be the name of a <emphasis>qualifier</emphasis> associated with any
+ <interfacename>Executor</interfacename>, e.g. as specified with the
+ <literal>&lt;qualifier&gt;</literal> element or Spring's
+ <interfacename>@Qualifier</interfacename> annotation.</para>
+ </section>
</section>
<section id="scheduling-quartz">
@@ -820,7 +843,7 @@ public class ExampleJob extends QuartzJobBean {
<classname>SchedulerFactoryBean</classname> for you to set, such as the
calendars used by the job details, properties to customize Quartz with,
etc. Have a look at the <ulink
- url="http://static.springframework.org/spring/docs/3.0.x/javadoc-api/org/springframework/scheduling/quartz/SchedulerFactoryBean.html">SchedulerFactoryBean
+ url="http://static.springframework.org/spring/docs/current/api/org/springframework/scheduling/quartz/SchedulerFactoryBean.html">SchedulerFactoryBean
Javadoc</ulink> for more information.</para>
</section>
</section>
Please sign in to comment.
Something went wrong with that request. Please try again.