SPR-7651 - Document limitations of @Async.

* documented that @Async can't be used in conjunction with lifecycle callbacks such as @PostConstruct
* provide sample for workaround
* added semantic markup for code

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

spring-framework-reference/src/scheduling.xml

@@ -551,23 +551,26 @@ public void doSomething() {
     <section id="scheduling-annotation-support-async">
       <title>The @Async Annotation</title>
 
-      <para>The @Async annotation can be provided on a method so that
+      <para>The <interfacename>@Async</interfacename> annotation can be
-      invocation of that method will occur asynchronously. In other words, the
+      provided on a method so that invocation of that method will occur
-      caller will return immediately upon invocation and the actual execution
+      asynchronously. In other words, the caller will return immediately upon
-      of the method will occur in a task that has been submitted to a Spring
+      invocation and the actual execution of the method will occur in a task
-      TaskExecutor. In the simplest case, the annotation may be applied to a
+      that has been submitted to a Spring
-      void-returning method.</para>
+      <interfacename>TaskExecutor</interfacename>. In the simplest case, the
+      annotation may be applied to a <literal>void</literal>-returning
+      method.</para>
 
       <programlisting language="java">@Async
 void doSomething() {
     // this will be executed asynchronously
 }</programlisting>
 
-      <para>Unlike the methods annotated with the @Scheduled annotation, these
+      <para>Unlike the methods annotated with the
-      methods can expect arguments, because they will be invoked in the
+      <interfacename>@Scheduled</interfacename> annotation, these methods can
-      "normal" way by callers at runtime rather than from a scheduled task
+      expect arguments, because they will be invoked in the "normal" way by
-      being managed by the container. For example, the following is a
+      callers at runtime rather than from a scheduled task being managed by
-      legitimate application of the @Async annotation.</para>
+      the container. For example, the following is a legitimate application of
+      the <interfacename>@Async</interfacename> annotation.</para>
 
       <programlisting language="java">@Async
 void doSomething(String s) {
@@ -575,15 +578,45 @@ void doSomething(String s) {
 }</programlisting>
 
       <para>Even methods that return a value can be invoked asynchronously.
-      However, such methods are required to have a Future typed return value.
+      However, such methods are required to have a
-      This still provides the benefit of asynchronous execution so that the
+      <interfacename>Future</interfacename> typed return value. This still
-      caller can perform other tasks prior to calling 'get()' on that
+      provides the benefit of asynchronous execution so that the caller can
-      Future.</para>
+      perform other tasks prior to calling <methodname>get()</methodname> on
+      that Future.</para>
 
       <programlisting language="java">@Async
 Future&lt;String&gt; returnSomething(int i) {
     // this will be executed asynchronously
 }</programlisting>
+
+      <para><interfacename>@Async</interfacename> can not be used in
+      conjunction with lifecycle callbacks such as
+      <interfacename>@PostConstruct</interfacename>. To asynchonously
+      initialize Spring beans you currently have to use a separate
+      initializing Spring bean that invokes the
+      <interfacename>@Async</interfacename> annotated method on the target
+      then.</para>
+
+      <programlisting language="java">public class SampleBeanImpl implements SampleBean {
+
+  @Async
+  void doSomething() { … }
+}
+
+
+public class SampleBeanInititalizer {
+
+  private final SampleBean bean;
+
+  public SampleBeanInitializer(SampleBean bean) {
+    this.bean = bean;
+  }
+
+  @PostConstruct
+  public void initialize() {
+    bean.doSomething();
+  }
+}</programlisting>
     </section>
 
     <section id="scheduling-annotation-support-namespace">