From weld-commits at lists.jboss.org Mon Nov  9 21:23:13 2009
Content-Type: multipart/mixed; boundary="===============5020792813711123172=="
MIME-Version: 1.0
From: weld-commits at lists.jboss.org
To: weld-commits at lists.jboss.org
Subject: [weld-commits] Weld SVN:  r4927 - doc/trunk/reference/en-US.
Date: Mon, 09 Nov 2009 21:23:13 -0500
Message-ID: <200911100223.nAA2NDfJ007700@svn01.web.mwc.hst.phx2.redhat.com>

--===============5020792813711123172==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: gavin.king(a)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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- doc/trunk/reference/en-US/decorators.xml	2009-11-10 02:01:50 UTC (rev 4=
926)
+++ doc/trunk/reference/en-US/decorators.xml	2009-11-10 02:23:12 UTC (rev 4=
927)
@@ -17,8 +17,8 @@
       interface, and is therefore aware of all the semantics attached to t=
hat interface. Since decorators directly
       implement operations with business semantics, it makes them the perf=
ect 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 t=
wo complement one another. Let's look at some
-      cases where decorators fit the bill.
+      solve technical concerns that cut across many disparate types. Inter=
ceptors and decorators, though similar in many
+      ways, are complementary. Let's look at some cases where decorators f=
it the bill.
    </para>
   =

    <para>Suppose we have an interface that represents accounts:</para>

Modified: doc/trunk/reference/en-US/interceptors.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- 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 specif=
ication. 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 ma=
de. CDI builds on the interceptor architecture
-      of managed beans by introducing a more sophisticated, semantic, anno=
tation-based approach to binding interceptors
-      to beans.
+      The Interceptors specification defines two kinds of interception poi=
nts:
    </para>
-
-   <para>
-      Interceptor functionality is defined in the interceptor specificatio=
n, which the managed bean, CDI, and EJB
-      specifications all support. The interceptor specification defines tw=
o kinds of interception points:
-   </para>
   =

    <itemizedlist>
       <listitem>
@@ -30,12 +23,17 @@
    </itemizedlist>
   =

    <para>
+      In addition, the EJB specification defines timeout method intercepti=
on.
+   </para>
+  =

+   <para>
       A <emphasis>business method interceptor</emphasis> applies to invoca=
tions of methods of the bean by clients of the
       bean:
    </para>
   =

    <programlisting role=3D"JAVA"><![CDATA[public class TransactionIntercep=
tor {
-   @AroundInvoke public Object manageTransaction(InvocationContext ctx) th=
rows Exception { ... }
+   @AroundInvoke =

+   public Object manageTransaction(InvocationContext ctx) throws Exception=
 { ... }
 }]]></programlisting>
   =

    <para>
@@ -44,19 +42,30 @@
    </para>
   =

    <programlisting role=3D"JAVA"><![CDATA[public class DependencyInjection=
Interceptor {
-   @PostConstruct public void injectDependencies(InvocationContext ctx) { =
... }
+   @PostConstruct =

+   public void injectDependencies(InvocationContext ctx) { ... }
 }]]></programlisting>
 =

    <para>
       An interceptor class may intercept both lifecycle callbacks and busi=
ness methods.
    </para>
+   =

+   <para>
+      A <emphasis>timeout method interceptor</emphasis> applies to invocat=
ions of EJB timeout methods by the
+      container:
+   </para>
   =

+   <programlisting role=3D"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 transaction=
al. The first thing we need is an
-         <emphasis>interceptor binding annotation</emphasis> to specify ex=
actly which beans we're interested in:
+         <emphasis>interceptor binding type</emphasis> to specify exactly =
which beans we're interested in:
       </para>
 =

       <programlisting role=3D"JAVA"><![CDATA[@InterceptorBinding
@@ -92,20 +101,21 @@
 =

       <programlisting role=3D"JAVA"><![CDATA[@Transactional @Interceptor
 public class TransactionInterceptor {
-   @AroundInvoke public Object manageTransaction(InvocationContext ctx) th=
rows Exception { ... }
+   @AroundInvoke =

+   public Object manageTransaction(InvocationContext ctx) throws Exception=
 { ... }
 }]]></programlisting>
 =

       <para>
-         All bean interceptors are beans, and can take advantage of depend=
ency injection and contextual lifecycle
-         management.
+         Interceptors can take advantage of dependency injection:
       </para>
 =

-      <programlisting role=3D"JAVA"><![CDATA[@ApplicationScoped @Transacti=
onal @Interceptor
+      <programlisting role=3D"JAVA"><![CDATA[@Transactional @Interceptor
 public class TransactionInterceptor {
 =

-    @Resource Transaction transaction;
+    @Inject UserTransaction transaction;
 =

-    @AroundInvoke public Object manageTransaction(InvocationContext ctx) t=
hrows Exception { ... }
+    @AroundInvoke =

+    public Object manageTransaction(InvocationContext ctx) throws Exceptio=
n { ... }
     =

 }]]></programlisting>
 =

@@ -169,7 +179,8 @@
    </interceptors>
 </beans>]]></programlisting>
 =

-      <para>Or we could turn them both off in our test environment by simp=
ly taking no action! Ah, so simple.</para>
+      <para>Or we could turn them both off in our test environment by simp=
ly not mentioning them in =

+      <literal>beans.xml</literal>! Ah, so simple.</para>
 =

    </section>
 =

@@ -194,7 +205,8 @@
 =

       <programlisting role=3D"JAVA"><![CDATA[@Transactional(requiresNew =
=3D true) @Interceptor
 public class RequiresNewTransactionInterceptor {
-   @AroundInvoke public Object manageTransaction(InvocationContext ctx) th=
rows Exception { ... }
+   @AroundInvoke =

+   public Object manageTransaction(InvocationContext ctx) throws Exception=
 { ... }
 }]]></programlisting>
 =

       <para>


--===============5020792813711123172==--