Polish @EnableAsync Javadoc and related XSD

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@4412 50f2f4bb-b051-0410-bef5-90022cba6387

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 {

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

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.
  *

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.
  *
- * <p>See {@link EnableAsync} for usage examples.
+ * <p>See @{@link EnableAsync} for usage examples.
  *
  * @author Chris Beams
  * @since 3.1

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 <task:*>} XML namespace. To be used on @{@link Configuration}
+ * classes as follows:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -42,12 +43,17 @@ import org.springframework.core.Ordered;
  *     }
  * }</pre>
  *
- * <p>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).
  *
- * <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}
- * the {@code org.springframework.aspects} module must be present on the classpath.
+ * <p>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.
+ *
+ * <p>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.
  *
  * <p>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;
  *     &#064;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;
  *     }
  * }</pre>
  *
+ * <p>For reference, the example above can be compared to the following Spring XML
+ * configuration:
+ * <pre class="code">
+ * {@code
+ * <beans>
+ *     <task:annotation-config executor="myExecutor"/>
+ *     <task:executor id="myExecutor" pool-size="7-42" queue-capacity="11"/>
+ *     <bean id="asyncBean" class="com.foo.MyAsyncBean"/>
+ * </beans>
+ * }</pre>
+ * the examples are equivalent save the setting of the <em>thread name prefix</em> 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.<p>
+ *
  * @author Chris Beams
  * @since 3.1
  * @see Async
@@ -97,10 +121,11 @@ public @interface EnableAsync {
 	Class<? extends Annotation> 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}. <strong>
+	 * Applicable only if {@link #mode()} is set to {@link AdviceMode#PROXY}</strong>.
 	 *
-	 * <p>Note: Class-based proxies require the async {@link #annotation()}
+	 * <p>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.
 	 */

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 {

org.springframework.context/src/main/resources/org/springframework/scheduling/config/spring-task-3.1.xsd

@@ -20,8 +20,13 @@
 	<xsd:element name="annotation-driven">
 		<xsd:annotation>
 			<xsd:documentation><![CDATA[
-	Enables the detection of @Async and @Scheduled annotations on any Spring-managed object. If present,
-	a proxy will be generated for executing the annotated methods asynchronously.
+	Enables the detection of @Async and @Scheduled annotations on any Spring-managed
+	object. If present, a proxy will be generated for executing the annotated methods
+	asynchronously.
+
+	See Javadoc for the org.springframework.scheduling.annotation.EnableAsync and
+	org.springframework.scheduling.annotation.EnableScheduling annotations for information
+	on code-based alternatives to this XML element.
 			]]></xsd:documentation>
 		</xsd:annotation>
 		<xsd:complexType>
@@ -77,6 +82,9 @@
 			<xsd:documentation><![CDATA[
 	Defines a ThreadPoolTaskExecutor instance with configurable pool size,
 	queue-capacity, keep-alive, and rejection-policy values.
+
+	See Javadoc for the org.springframework.scheduling.annotation.EnableAsync annotation
+	for information on code-based alternatives to this XML element.
 			]]></xsd:documentation>
 		</xsd:annotation>
 		<xsd:complexType>