[weld-commits] Weld SVN: r4927 - doc/trunk/reference/en-US.

[weld-commits at lists.jboss.org]

Author: gavin.king at jboss.com
Date: 2009-11-09 21:23:12 -0500 (Mon, 09 Nov 2009)
New Revision: 4927

Modified:
   doc/trunk/reference/en-US/decorators.xml
   doc/trunk/reference/en-US/interceptors.xml
Log:
revisions

Modified: doc/trunk/reference/en-US/decorators.xml
===================================================================
--- doc/trunk/reference/en-US/decorators.xml	2009-11-10 02:01:50 UTC (rev 4926)
+++ doc/trunk/reference/en-US/decorators.xml	2009-11-10 02:23:12 UTC (rev 4927)
@@ -17,8 +17,8 @@
       interface, and is therefore aware of all the semantics attached to that interface. Since decorators directly
       implement operations with business semantics, it makes them the perfect tool for modeling some kinds of business
       concerns. It also means that a decorator doesn't have the generality of an interceptor. Decorators aren't able to
-      solve technical concerns that cut across many disparate types. The two complement one another. Let's look at some
-      cases where decorators fit the bill.
+      solve technical concerns that cut across many disparate types. Interceptors and decorators, though similar in many
+      ways, are complementary. Let's look at some cases where decorators fit the bill.
    </para>
   
    <para>Suppose we have an interface that represents accounts:</para>

Modified: doc/trunk/reference/en-US/interceptors.xml
===================================================================
--- doc/trunk/reference/en-US/interceptors.xml	2009-11-10 02:01:50 UTC (rev 4926)
+++ doc/trunk/reference/en-US/interceptors.xml	2009-11-10 02:23:12 UTC (rev 4927)
@@ -5,20 +5,13 @@
    <title>Interceptors</title>
 
    <para>
-      Thanks to the managed bean specification, interceptors are now part of the core functionality of a bean. That
-      means that you no longer need to make your class an EJB just to use interceptors!
+      Interceptor functionality is defined in the Java Interceptors specification. CDI enhances this functionality with 
+      a more sophisticated, semantic, annotation-based approach to binding interceptors to beans.
    </para>
 
    <para>
-      But that doesn't mean there aren't other improvements that can be made. CDI builds on the interceptor architecture
-      of managed beans by introducing a more sophisticated, semantic, annotation-based approach to binding interceptors
-      to beans.
+      The Interceptors specification defines two kinds of interception points:
    </para>
-
-   <para>
-      Interceptor functionality is defined in the interceptor specification, which the managed bean, CDI, and EJB
-      specifications all support. The interceptor specification defines two kinds of interception points:
-   </para>
   
    <itemizedlist>
       <listitem>
@@ -30,12 +23,17 @@
    </itemizedlist>
   
    <para>
+      In addition, the EJB specification defines timeout method interception.
+   </para>
+  
+   <para>
       A <emphasis>business method interceptor</emphasis> applies to invocations of methods of the bean by clients of the
       bean:
    </para>
   
    <programlisting role="JAVA"><![CDATA[public class TransactionInterceptor {
-   @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
+   @AroundInvoke 
+   public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
 }]]></programlisting>
   
    <para>
@@ -44,19 +42,30 @@
    </para>
   
    <programlisting role="JAVA"><![CDATA[public class DependencyInjectionInterceptor {
-   @PostConstruct public void injectDependencies(InvocationContext ctx) { ... }
+   @PostConstruct 
+   public void injectDependencies(InvocationContext ctx) { ... }
 }]]></programlisting>
 
    <para>
       An interceptor class may intercept both lifecycle callbacks and business methods.
    </para>
+   
+   <para>
+      A <emphasis>timeout method interceptor</emphasis> applies to invocations of EJB timeout methods by the
+      container:
+   </para>
   
+   <programlisting role="JAVA"><![CDATA[public class TimeoutInterceptor {
+   @AroundTimeout 
+   public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
+}]]></programlisting>
+  
    <section>
       <title>Interceptor bindings</title>
 
       <para>
          Suppose we want to declare that some of our beans are transactional. The first thing we need is an
-         <emphasis>interceptor binding annotation</emphasis> to specify exactly which beans we're interested in:
+         <emphasis>interceptor binding type</emphasis> to specify exactly which beans we're interested in:
       </para>
 
       <programlisting role="JAVA"><![CDATA[@InterceptorBinding
@@ -92,20 +101,21 @@
 
       <programlisting role="JAVA"><![CDATA[@Transactional @Interceptor
 public class TransactionInterceptor {
-   @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
+   @AroundInvoke 
+   public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
 }]]></programlisting>
 
       <para>
-         All bean interceptors are beans, and can take advantage of dependency injection and contextual lifecycle
-         management.
+         Interceptors can take advantage of dependency injection:
       </para>
 
-      <programlisting role="JAVA"><![CDATA[@ApplicationScoped @Transactional @Interceptor
+      <programlisting role="JAVA"><![CDATA[@Transactional @Interceptor
 public class TransactionInterceptor {
 
-    @Resource Transaction transaction;
+    @Inject UserTransaction transaction;
 
-    @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
+    @AroundInvoke 
+    public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
     
 }]]></programlisting>
 
@@ -169,7 +179,8 @@
    </interceptors>
 </beans>]]></programlisting>
 
-      <para>Or we could turn them both off in our test environment by simply taking no action! Ah, so simple.</para>
+      <para>Or we could turn them both off in our test environment by simply not mentioning them in 
+      <literal>beans.xml</literal>! Ah, so simple.</para>
 
    </section>
 
@@ -194,7 +205,8 @@
 
       <programlisting role="JAVA"><![CDATA[@Transactional(requiresNew = true) @Interceptor
 public class RequiresNewTransactionInterceptor {
-   @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
+   @AroundInvoke 
+   public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
 }]]></programlisting>
 
       <para>