From weld-commits at lists.jboss.org Mon Nov  9 22:07:46 2009
Content-Type: multipart/mixed; boundary="===============7627957899818588766=="
MIME-Version: 1.0
From: weld-commits at lists.jboss.org
To: weld-commits at lists.jboss.org
Subject: [weld-commits] Weld SVN:  r4931 - doc/trunk/reference/en-US.
Date: Mon, 09 Nov 2009 22:07:46 -0500
Message-ID: <200911100307.nAA37kon017189@svn01.web.mwc.hst.phx2.redhat.com>

--===============7627957899818588766==
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 22:07:46 -0500 (Mon, 09 Nov 2009)
New Revision: 4931

Modified:
   doc/trunk/reference/en-US/decorators.xml
   doc/trunk/reference/en-US/next.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 03:02:49 UTC (rev 4=
930)
+++ doc/trunk/reference/en-US/decorators.xml	2009-11-10 03:07:46 UTC (rev 4=
931)
@@ -43,76 +43,66 @@
   =

    <programlisting role=3D"JAVA"><![CDATA[@Decorator
 public abstract class LargeTransactionDecorator
-   implements Account {
+      implements Account {
    ...
 }]]></programlisting>
     =

    <para>
-      So what goes in the decorator? Well, decorators have to inject the i=
nstance of the bean they are decorating,
-      termed the <emphasis>delegate injection point</emphasis>. The inject=
ion point has the same type as the bean to
-      decorate and the annotation <literal>@Delegate</literal>. There can =
be at most one injection point, which can be a
-      constructor, initializer method or field injection.
+      The decorator implements the methods of the decorated type that it w=
ants to intercept.
    </para>
-
-   <programlisting role=3D"JAVA"><![CDATA[@Decorator
-public abstract class LargeTransactionDecorator
-   implements Account {
-   @Inject @Delegate @Any Account account;
-   ...
-}]]></programlisting>
-      =

-   <para>
-      You'll see in a moment that the beans which are decorated can be fur=
ther restricted by specifying qualifiers at
-      the injection point, a familiar pattern in CDI.
-   </para>
-
-   <para>
-      The decorator then implements any methods of the bean type it wants =
to decorate. The decorator can in turn invoke
-      the method on the decorated instance. Note that the method on the de=
corate is being called by the container
-      <emphasis>instead of</emphasis> the method on the bean instance. It'=
s up to the decorator to invoke the method on
-      the bean instance. In fact, the decorator can invoke any method on t=
he bean instance.
-   </para>
     =

    <programlisting role=3D"JAVA"><![CDATA[@Decorator
 public abstract class LargeTransactionDecorator
-   implements Account {
+      implements Account {
    @Inject @Delegate @Any Account account;
 =

    @PersistenceContext EntityManager em;
     =

    public void withdraw(BigDecimal amount) {
-       account.withdraw(amount);
-       if ( amount.compareTo(LARGE_AMOUNT)>0 ) {
-          em.persist( new LoggedWithdrawl(amount) );
-       }
-    }
+      ...
+   }
     =

    public void deposit(BigDecimal amount);
-      account.deposit(amount);
-      if ( amount.compareTo(LARGE_AMOUNT)>0 ) {
-         em.persist( new LoggedDeposit(amount) );
-      }
+      ...
    }
 }]]></programlisting>
 =

    <para>
-      Interceptors for a method are called before decorators that apply to=
 that method.
-   </para>
-
-   <para>
       Unlike other beans, a decorator may be an abstract class. Therefore,=
 if there's nothing special the decorator
       needs to do for a particular method of the decorated interface, you =
don't need to implement that method.
    </para>
   =

+   <para>
+      Interceptors for a method are called before decorators that apply to=
 the method.
+   </para>
+
    <section>
       <title>Delegate object</title>
   =

-      <para>
-         All decorators must have a delegate injection point that injects =
the delegate object, as shown above. The type
-         and qualifier types of the delegate injection point determine whi=
ch beans the decorator is bound to. The
-         delegate object type must implement or extend all interfaces impl=
emented by the decorator.
-      </para>
+   <para>
+      Decorators have a special injection point, called the <emphasis>dele=
gate injection point</emphasis>, with the same =

+      type as the beans they decorate, and the annotation <literal>@Delega=
te</literal>. There must be exactly one delegate =

+      injection point, which can be a constructor parameter, initializer m=
ethod parameter or injected field.
+   </para>
+
+   <programlisting role=3D"JAVA"><![CDATA[@Decorator
+public abstract class LargeTransactionDecorator
+      implements Account {
+   @Inject @Delegate @Any Account account;
+   ...
+}]]></programlisting>
+
+      <para>A decorator is bound to any bean which:</para>
     =

+      <itemizedlist>
+         <listitem>
+            <para>has the type of the delegate injection point as a bean t=
ype, and</para>
+         </listitem>
+         <listitem>
+            <para>has all qualifiers that are declared at the delegate inj=
ection point.</para>
+         </listitem>
+      </itemizedlist>
+    =

       <para>
          This delegate injection point specifies that the decorator is bou=
nd to all beans that implement
          <literal>Account</literal>:
@@ -121,29 +111,40 @@
       <programlisting role=3D"JAVA"><![CDATA[@Inject @Delegate @Any Accoun=
t account;]]></programlisting>
 =

       <para>
-         A delegate injection point may specify any number of qualifier an=
notations. Then the decorator will only be
+         A delegate injection point may specify any number of qualifier an=
notations. The decorator will only be
          bound to beans with the same qualifiers.
       </para>
     =

       <programlisting role=3D"JAVA"><![CDATA[@Inject @Delegate @Foreign Ac=
count account;]]></programlisting>
-
-      <para>A decorator is bound to any bean which:</para>
     =

-      <itemizedlist>
-         <listitem>
-            <para>has the type of the delegate object as a bean type, and<=
/para>
-         </listitem>
-         <listitem>
-            <para>has all qualifiers that are declared at the delegate inj=
ection point.</para>
-         </listitem>
-      </itemizedlist>
-    =

       <para>
          The decorator may invoke the delegate object, which has much the =
same effect as calling
          <literal>InvocationContext.proceed()</literal> from an intercepto=
r. The main difference is that the decorator
          can invoke <emphasis>any</emphasis> business method on the delega=
te object.
       </para>
   =

+   <programlisting role=3D"JAVA"><![CDATA[@Decorator
+public abstract class LargeTransactionDecorator
+      implements Account {
+   @Inject @Delegate @Any Account account;
+
+   @PersistenceContext EntityManager em;
+    =

+   public void withdraw(BigDecimal amount) {
+      account.withdraw(amount);
+      if ( amount.compareTo(LARGE_AMOUNT)>0 ) {
+         em.persist( new LoggedWithdrawl(amount) );
+      }
+   }
+    =

+   public void deposit(BigDecimal amount);
+      account.deposit(amount);
+      if ( amount.compareTo(LARGE_AMOUNT)>0 ) {
+         em.persist( new LoggedDeposit(amount) );
+      }
+   }
+}]]></programlisting>
+
    </section>
   =

    <section>
@@ -167,7 +168,7 @@
 </beans>]]></programlisting>
 =

       <para>
-         This declaration serves the same purpose for decorators that the =
<literal>&lt;Interceptors&gt;</literal>
+         This declaration serves the same purpose for decorators that the =
<literal>&lt;interceptors&gt;</literal>
          declaration serves for interceptors:
       </para>
 =


Modified: doc/trunk/reference/en-US/next.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/next.xml	2009-11-10 03:02:49 UTC (rev 4930)
+++ doc/trunk/reference/en-US/next.xml	2009-11-10 03:07:46 UTC (rev 4931)
@@ -5,12 +5,10 @@
   =

    <para>
       Because CDI is so new, there's not yet a lot of information availabl=
e online. That will change over time.
-      Regardless, the CDI specification remains the authority for informat=
ion on CDI. The spec is kept at around 100
-      pages intentionally easy to read (don't worry, it's not like your Bl=
ue-ray player manual). You may be especially
-      interested in reading it since it covers many details that we've ski=
pped over. The spec is available on the
-      <ulink src=3D"http://jcp.org/en/jsr/detail?id=3D299">JSR-299 page</u=
link> at the JCP website. Updates to the spec are
-      also frequently mailed to the <ulink src=3D"https://lists.jboss.org/=
mailman/listinfo/weld-dev">weld-dev</ulink>
-      mailing list.
+      Regardless, the CDI specification remains the authority for informat=
ion on CDI. The spec less than 100 pages and =

+      is quite readable (don't worry, it's not like your Blu-ray player ma=
nual). Of course, it covers many details we've =

+      skipped over here. The spec is available on the
+      <ulink src=3D"http://jcp.org/en/jsr/detail?id=3D299">JSR-299 page</u=
link> at the JCP website.
    </para>
   =

    <para>


--===============7627957899818588766==--