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

--===============6781143625144789335==
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 23:14:25 -0500 (Mon, 09 Nov 2009)
New Revision: 4935

Modified:
   doc/trunk/reference/en-US/specialization.xml
   doc/trunk/reference/en-US/stereotypes.xml
Log:
updates

Modified: doc/trunk/reference/en-US/specialization.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/specialization.xml	2009-11-10 03:56:39 UTC (r=
ev 4934)
+++ doc/trunk/reference/en-US/specialization.xml	2009-11-10 04:14:25 UTC (r=
ev 4935)
@@ -17,18 +17,22 @@
       The CDI specification recognizes two distinct scenarios in which one=
 bean extends another:
    </para>
 =

+   <blockquote>
    <itemizedlist>
       <listitem>
          <para>
-            The second bean specializes the first bean in certain deployme=
nt scenarios. In these deployments, the second
-            bean completely replaces the first, fulfilling the same role i=
n the system.
+            The second bean <emphasis>specializes</emphasis> the first bea=
n in certain deployment scenarios. In these =

+            deployments, the second bean completely replaces the first, fu=
lfilling the same role in the system.
          </para>
+      </listitem>
+      <listitem>
          <para>
             The second bean is simply reusing the Java implementation, and=
 otherwise bears no relation to the first
             bean. The first bean may not even have been designed for use a=
s a contextual object.
          </para>
       </listitem>
    </itemizedlist>
+   </blockquote>
 =

    <para>
       The second case is the default assumed by CDI. It's possible to have=
 two beans in the system with the same part
@@ -39,15 +43,15 @@
    <para>
       The first case is the exception, and also requires more care. In any=
 given deployment, only one bean can fulfill a
       given role at a time. That means one bean needs to be enabled and th=
e other disabled. There are a two modifiers
-      involved: <literal>@Alternative</literal> and <literal>@Specializes<=
/literal>. We'll start by looking at bean
+      involved: <literal>@Alternative</literal> and <literal>@Specializes<=
/literal>. We'll start by looking at
       alternatives and then show the guarantees that specialization adds.
    </para>
 =

    <section id=3D"alternatives">
-      <title>Bean alternatives</title>
+      <title>Alternatives</title>
 =

       <para>
-         CDI let's you <emphasis>override</emphasis> the implementation of=
 a bean type at deployment time using a bean
+         CDI lets you <emphasis>override</emphasis> the implementation of =
a bean type at deployment time using an
          alternative. For example, the following bean provides an implemen=
tation of the
          <literal>PaymentProcessor</literal> bean type in the default envi=
ronment:
       </para>
@@ -144,7 +148,7 @@
       <programlisting role=3D"JAVA"><![CDATA[@LargeTransaction @CreditCard=
 PaymentProcessor paymentProcessor;]]></programlisting>
 =

       <para>
-         So we haven't completely replaced the default implementation in a=
 particular deployment of the system. The only
+         So we haven't completely replaced the default implementation in t=
his deployment of the system. The only
          way one bean can completely override a second bean at all injecti=
on points is if it implements all the bean
          types and declares all the qualifiers of the second bean. However=
, if the second bean declares a producer
          method or observer method, then even this is not enough to ensure=
 that the second bean is never called! We need
@@ -191,25 +195,20 @@
          When an enabled bean specializes another bean, the other bean is =
never instantiated or called by the container.
          Even if the other bean defines a producer or observer method, the=
 method will never be called.
       </para>
-   </section>
-
-   <section>
-      <title>Inheritance</title>
-
+      =

       <para>
          So why does specialization work, and what does it have to do with=
 inheritance?
       </para>
       =

       <para>
-         Since you are informing the container that your alternative bean =
is meant to stand in as a replacement for the
-         default implementation, the container automatically adds any qual=
ifiers that are on the default implementation
-         to the alternative implementation.  Thus, in our example, <litera=
l>MockCreditCardPaymentProcessor</literal> has
-         the qualifiers <literal>@Default</literal> and <literal>@CreditCa=
rd</literal>. Therefore, there are no
-         circumstances when the default implementation is going to get use=
d because it is completely shadowed.
+         Since we're informing the container that our alternative bean is =
meant to stand in as a replacement for the
+         default implementation, the alternative implementation automatica=
lly inherits all qualifiers of the default =

+         implementation. Thus, in our example, <literal>MockCreditCardPaym=
entProcessor</literal> inherits the qualifiers =

+         <literal>@Default</literal> and <literal>@CreditCard</literal>.
       </para>
 =

       <para>
-         Additionally, if the default implementation declares a bean EL na=
me using <literal>@Named</literal>, the name
+         Furthermore, if the default implementation declares a bean EL nam=
e using <literal>@Named</literal>, the name
          is inherited by the specialized alternative bean.
       </para>
 =


Modified: doc/trunk/reference/en-US/stereotypes.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/stereotypes.xml	2009-11-10 03:56:39 UTC (rev =
4934)
+++ doc/trunk/reference/en-US/stereotypes.xml	2009-11-10 04:14:25 UTC (rev =
4935)
@@ -143,6 +143,7 @@
 =

       <para>
          A stereotype can indicate that all beans to which it is applied a=
re <literal>@Alternative</literal>s.
+         An <emphasis>alternative stereotype</emphasis> lets us classify b=
eans by deployment scenario.
       </para>
 =

       <programlisting role=3D"JAVA"><![CDATA[@Alternative
@@ -158,12 +159,14 @@
 =

       <programlisting role=3D"JAVA"><![CDATA[@Mock
 public class MockLoginAction extends LoginAction { ... }]]></programlistin=
g>
-
+<!-- =

       <programlisting role=3D"JAVA"><![CDATA[<beans>
    <alternatives>
       <stereotype>org.mycompany.testing.Mock</stereotype>
    </alternatives>
 </beans>]]></programlisting>
+-->
+
    </section>
 =

    <section>
@@ -177,7 +180,8 @@
       </para>
 =

       <para>
-         Here's an example that combines the <literal>@Action</literal> an=
d <literal>@Auditable</literal> stereotypes:
+         Here's an example that combines the <literal>@Action</literal> an=
d <literal>@Auditable</literal> =

+         stereotypes:
       </para>
 =

       <programlisting role=3D"JAVA"><![CDATA[@Auditable


--===============6781143625144789335==--