From c3822bd26d67e7404525cb4ba5fbdb2915ef260a Mon Sep 17 00:00:00 2001 From: Chris Beams Date: Thu, 2 Jun 2011 14:42:26 +0000 Subject: [PATCH] Polish @EnableAsync Javadoc and related XSD git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@4412 50f2f4bb-b051-0410-bef5-90022cba6387 --- .../aspectj/AspectJAsyncConfiguration.java | 5 +- .../AbstractAsyncConfiguration.java | 4 +- .../AsyncConfigurationSelector.java | 2 +- .../annotation/AsyncConfigurer.java | 6 +-- .../scheduling/annotation/EnableAsync.java | 49 ++++++++++++++----- .../annotation/ProxyAsyncConfiguration.java | 5 +- .../scheduling/config/spring-task-3.1.xsd | 12 ++++- 7 files changed, 59 insertions(+), 24 deletions(-) diff --git a/org.springframework.aspects/src/main/java/org/springframework/scheduling/aspectj/AspectJAsyncConfiguration.java b/org.springframework.aspects/src/main/java/org/springframework/scheduling/aspectj/AspectJAsyncConfiguration.java index 9f8c83ea73a..d9d677a5709 100644 --- a/org.springframework.aspects/src/main/java/org/springframework/scheduling/aspectj/AspectJAsyncConfiguration.java +++ b/org.springframework.aspects/src/main/java/org/springframework/scheduling/aspectj/AspectJAsyncConfiguration.java @@ -25,12 +25,13 @@ import org.springframework.scheduling.annotation.AbstractAsyncConfiguration; import org.springframework.scheduling.annotation.EnableAsync; /** - * Enables AspectJ-based asynchronous method execution. + * {@code @Configuration} class that registers the Spring infrastructure beans necessary + * to enable AspectJ-based asynchronous method execution. * * @author Chris Beams * @since 3.1 * @see EnableAsync - * @see EnableAsync#mode + * @see AsyncConfigurationSelector */ @Configuration public class AspectJAsyncConfiguration extends AbstractAsyncConfiguration { diff --git a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AbstractAsyncConfiguration.java b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AbstractAsyncConfiguration.java index 1339998d481..d0bbe8899b4 100644 --- a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AbstractAsyncConfiguration.java +++ b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AbstractAsyncConfiguration.java @@ -27,8 +27,8 @@ import org.springframework.core.type.AnnotationMetadata; import org.springframework.util.Assert; /** - * Abstract base class providing common structure for enabling Spring's asynchronous - * method execution capability. + * Abstract base {@code Configuration} class providing common structure for enabling + * Spring's asynchronous method execution capability. * * @author Chris Beams * @since 3.1 diff --git a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurationSelector.java b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurationSelector.java index a5a00fcfb67..41539bb6f16 100644 --- a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurationSelector.java +++ b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurationSelector.java @@ -25,7 +25,7 @@ import org.springframework.core.type.AnnotationMetadata; import org.springframework.util.Assert; /** - * Select which implementation of {@link AbstractAsyncConfiguration} + * Selects which implementation of {@link AbstractAsyncConfiguration} * should be used based on the value of {@link EnableAsync#mode} on the * importing @{@link Configuration} class. * diff --git a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurer.java b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurer.java index 537c804eda4..c57ba71e40b 100644 --- a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurer.java +++ b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/AsyncConfigurer.java @@ -19,11 +19,11 @@ package org.springframework.scheduling.annotation; import java.util.concurrent.Executor; /** - * Interface to be implemented by @{@link Configuration} classes - * annotated with @{@link EnableAsync} that wish to customize the + * Interface to be implemented by @{@link org.springframework.context.annotation.Configuration + * Configuration} classes annotated with @{@link EnableAsync} that wish to customize the * {@link Executor} instance used when processing async method invocations. * - *

See {@link EnableAsync} for usage examples. + *

See @{@link EnableAsync} for usage examples. * * @author Chris Beams * @since 3.1 diff --git a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java index 4b73c69be73..35f79b9b94b 100644 --- a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java +++ b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java @@ -29,8 +29,9 @@ import org.springframework.context.config.AdviceMode; import org.springframework.core.Ordered; /** - * Enables Spring's asynchronous method execution capability. To be used - * on @{@link Configuration} classes as follows: + * Enables Spring's asynchronous method execution capability, similar to functionality + * found in Spring's {@code } XML namespace. To be used on @{@link Configuration} + * classes as follows: * * 

  * @Configuration
@@ -42,12 +43,17 @@ import org.springframework.core.Ordered;
  *     }
  * }
* - *

The various attributes of the annotation control how advice - * is applied ({@link #mode()}), and if the mode is {@link AdviceMode#PROXY} - * (the default), the other attributes control the behavior of the proxying. + * where {@code MyAsyncBean} is a user-defined type with one or methods annotated + * with @{@link Async} (or any custom annotation specified by the {@link #annotation()} + * attribute). * - *

Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ} - * the {@code org.springframework.aspects} module must be present on the classpath. + *

The {@link #mode()} attribute controls how advice is applied; if the mode is + * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior + * of the proxying. + * + *

Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then + * the {@link #proxyTargetClass()} attribute is obsolete. Note also that in this case the + * {@code spring-aspects} module JAR must be present on the classpath. * *

By default, a {@link org.springframework.core.task.SimpleAsyncTaskExecutor * SimpleAsyncTaskExecutor} will be used to process async method invocations. To @@ -68,12 +74,30 @@ import org.springframework.core.Ordered; * @Override * public Executor getAsyncExecutor() { * ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); - * executor.setThreadNamePrefix("Custom-"); + * executor.setCorePoolSize(7); + * executor.setMaxPoolSize(42); + * executor.setQueueCapacity(11); + * executor.setThreadNamePrefix("MyExecutor-"); * executor.initialize(); * return executor; * } * } * + *

For reference, the example above can be compared to the following Spring XML + * configuration: + * 

+ * {@code
+ * 
+ *     
+ *     
+ *     
+ * 
+ * }
+ * the examples are equivalent save the setting of the thread name prefix of the + * Executor; this is because the the {@code task:} namespace {@code executor} element does + * not expose such an attribute. This demonstrates how the code-based approach allows for + * maximum configurability through direct access to actual componentry.

+ * * @author Chris Beams * @since 3.1 * @see Async @@ -97,10 +121,11 @@ public @interface EnableAsync { Class annotation() default Annotation.class; /** - * Indicate whether class-based (CGLIB) proxies are to be created as opposed - * to standard Java interface-based proxies. The default is {@code false} + * Indicate whether subclass-based (CGLIB) proxies are to be created as opposed + * to standard Java interface-based proxies. The default is {@code false}. + * Applicable only if {@link #mode()} is set to {@link AdviceMode#PROXY}. * - *

Note: Class-based proxies require the async {@link #annotation()} + *

Note that subclass-based proxies require the async {@link #annotation()} * to be defined on the concrete class. Annotations in interfaces will * not work in that case (they will rather only work with interface-based proxies)! */ @@ -115,7 +140,7 @@ public @interface EnableAsync { /** * Indicate the order in which the * {@link org.springframework.scheduling.annotation.AsyncAnnotationBeanPostProcessor} - * should be applied. Defaults to Order.LOWEST_PRIORITY in order to run + * should be applied. The default is {@link Ordered#LOWEST_PRECEDENCE} in order to run * after all other post-processors, so that it can add an advisor to * existing proxies rather than double-proxy. */ diff --git a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/ProxyAsyncConfiguration.java b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/ProxyAsyncConfiguration.java index cc0136795b0..93589de7852 100644 --- a/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/ProxyAsyncConfiguration.java +++ b/org.springframework.context/src/main/java/org/springframework/scheduling/annotation/ProxyAsyncConfiguration.java @@ -27,12 +27,13 @@ import org.springframework.core.annotation.AnnotationUtils; import org.springframework.util.Assert; /** - * Enables proxy-based asynchronous method execution. + * {@code @Configuration} class that registers the Spring infrastructure beans necessary + * to enable proxy-based asynchronous method execution. * * @author Chris Beams * @since 3.1 * @see EnableAsync - * @see EnableAsync#mode + * @see AsyncConfigurationSelector */ @Configuration public class ProxyAsyncConfiguration extends AbstractAsyncConfiguration { diff --git a/org.springframework.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd b/org.springframework.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd index 1166d499ed3..3d0b6074b2b 100644 --- a/org.springframework.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd +++ b/org.springframework.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd @@ -20,8 +20,13 @@ @@ -77,6 +82,9 @@