From weld-commits at lists.jboss.org Tue Nov 10 01:29:17 2009
Content-Type: multipart/mixed; boundary="===============2187895246077787424=="
MIME-Version: 1.0
From: weld-commits at lists.jboss.org
To: weld-commits at lists.jboss.org
Subject: [weld-commits] Weld SVN:  r4944 - doc/trunk/reference/en-US.
Date: Tue, 10 Nov 2009 01:29:16 -0500
Message-ID: <200911100629.nAA6TG87027681@svn01.web.mwc.hst.phx2.redhat.com>

--===============2187895246077787424==
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-10 01:29:16 -0500 (Tue, 10 Nov 2009)
New Revision: 4944

Modified:
   doc/trunk/reference/en-US/injection.xml
   doc/trunk/reference/en-US/specialization.xml
Log:
fallout from reorg

Modified: doc/trunk/reference/en-US/injection.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/injection.xml	2009-11-10 05:59:22 UTC (rev 49=
43)
+++ doc/trunk/reference/en-US/injection.xml	2009-11-10 06:29:16 UTC (rev 49=
44)
@@ -315,14 +315,51 @@
          <programlisting role=3D"JAVA"><![CDATA[@Synchronous @Reliable
 public class SynchronousReliablePaymentProcessor implements PaymentProcess=
or {
    public void process(Payment payment) { ... }
-}]]></programlisting>      =

+}]]></programlisting>
 =

       </section>
   =

    </section>
+   =

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

+      <para>Alternatives are beans whose implementation is specific to a p=
articular client module or deployment
+      scenario. This alternative defines a mock implementation of both <li=
teral>@Synchronous PaymentProcessor</literal>
+      and <literal>@Asynchronous PaymentProcessor</literal>, all in one:</=
para>
+      =

+      <programlisting role=3D"JAVA"><![CDATA[@Alternative @Synchronous @As=
ynchronous
+public class MockPaymentProcessor implements PaymentProcessor {
+   public void process(Payment payment) { ... }
+}]]></programlisting>
+      =

+      <para>
+         By default, <literal>@Alternative</literal> beans are disabled. W=
e need to <emphasis>enable</emphasis> an
+         alternative in the <literal>beans.xml</literal> descriptor of a b=
ean archive to make it available for
+         instantiation and injection. This activation only applies to the =
beans in that archive.
+      </para>
 =

+      <programlisting role=3D"XML"><![CDATA[<beans
+   xmlns=3D"http://java.sun.com/xml/ns/javaee"
+   xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
+   xsi:schemaLocation=3D"
+      http://java.sun.com/xml/ns/javaee
+      http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
+   <alternatives>
+         <class>org.mycompany.mock.MockPaymentProcessor</class>
+   </alternatives>
+</beans>]]></programlisting>
+      =

+      <para>
+         When an ambiguous dependency exists at an injection point, the co=
ntainer attempts to resolve the ambiguity
+         by looking for an enabled alternative among the beans that could =
be injected. If there is exactly one
+         enabled alternative, that's the bean that will be injected.
+      </para>
+      =

+   </section>
+
    <section>
-      <title>Fixing unsatisfied dependencies</title>
+      <title>Fixing unsatisfied and ambiguous dependencies</title>
   =

       <para>
          The typesafe resolution algorithm fails when, after considering t=
he qualifier annotations on all beans that

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 05:59:22 UTC (r=
ev 4943)
+++ doc/trunk/reference/en-US/specialization.xml	2009-11-10 06:29:16 UTC (r=
ev 4944)
@@ -47,68 +47,53 @@
       alternatives and then show the guarantees that specialization adds.
    </para>
 =

-   <section id=3D"alternatives">
-      <title>Alternatives</title>
+   <section id=3D"alternativestereotypes">
+      <title>Using alternative stereotypes</title>
 =

       <para>
          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:
+         alternative. For example, the following bean provides a default i=
mplementation of the =

+         <literal>PaymentProcessor</literal> interface:
       </para>
   =

-      <programlisting role=3D"JAVA"><![CDATA[@CreditCard
-public class CreditCardPaymentProcessor =

+      <programlisting role=3D"JAVA"><![CDATA[public class DefaultPaymentPr=
ocessor =

       implements PaymentProcessor {
    ...
 }]]></programlisting>
 =

       <para>
-         But in our staging environment, we override that implementation o=
f <literal>PaymentProcessor</literal> with a
-         different bean:
+         But in our staging environment, we don't really want to submit pa=
yments to the external system, so we override =

+         that implementation of <literal>PaymentProcessor</literal> with a=
 different bean:
       </para>
   =

-      <programlisting role=3D"JAVA"><![CDATA[@CreditCard @Alternative
-public class StagingCreditCardPaymentProcessor =

+      <programlisting role=3D"JAVA"><![CDATA[public @Alternative
+class StagingPaymentProcessor =

       implements PaymentProcessor {
    ...
 }]]></programlisting>
 =

       <para>or</para>
 =

-      <programlisting role=3D"JAVA"><![CDATA[@CreditCard @Alternative
-public class StagingCreditCardPaymentProcessor =

-      extends CreditCardPaymentProcessor {
+      <programlisting role=3D"JAVA"><![CDATA[public @Alternative
+class StagingPaymentProcessor =

+      extends DefaultPaymentProcessor {
    ...
 }]]></programlisting>
 =

       <para>
-         By default, <literal>@Alternative</literal> beans are disabled. W=
e need to <emphasis>enable</emphasis> the
-         alternative&#8212;effectively replacing the bean implementation w=
ithout the <literal>@Alternative</literal>
-         annotation&#8212;in the <literal>beans.xml</literal> descriptor o=
f a bean archive by specifying the bean
-         class (or the class that contains the alternative producer method=
 or field). This activation only applies =

-         to the beans in that archive.
+         We've already seen how we can enable this alternative by listing =
its class in the <literal>beans.xml</literal>
+         descriptor.
       </para>
 =

-      <programlisting role=3D"XML"><![CDATA[<beans
-   xmlns=3D"http://java.sun.com/xml/ns/javaee"
-   xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
-   xsi:schemaLocation=3D"
-      http://java.sun.com/xml/ns/javaee
-      http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
-   <alternatives>
-         <class>org.mycompany.myapp.StagingCreditCardProcessor</class>
-   </alternatives>
-</beans>]]></programlisting>
-
       <para>
-         Of course, if the goal is to enable all the alternatives for the =
staging environment, it would make much more
-         sense to make <literal>@Staging</literal> an <literal>@Alternativ=
e</literal> stereotype and annotate the
-         staging beans with this stereotype instead. You'll see how this l=
evel of indirection pays off. First, we create
-         the stereotype:
+         But suppose we have many alternatives in the staging environment.=
 It would be much more convenient to be able
+         to enable them all at once. So let's make <literal>@Staging</lite=
ral> an <literal>@Alternative</literal> stereotype =

+         and annotate the staging beans with this stereotype instead. You'=
ll see how this level of indirection pays off. =

+         First, we create the stereotype:
       </para>
 =

-      <programlisting role=3D"JAVA"><![CDATA[@Stereotype
-(a)Alternative
+      <programlisting role=3D"JAVA"><![CDATA[@Alternative
+(a)Stereotype
 @Retention(RUNTIME)
 @Target(TYPE)
 public @interface Staging {}]]></programlisting>
@@ -117,14 +102,14 @@
          Then we replace the <literal>@Alternative</literal> annotation on=
 our bean with <literal>@Staging</literal>:
       </para>
 =

-      <programlisting role=3D"JAVA"><![CDATA[@CreditCard @Staging
-public class StagingCreditCardPaymentProcessor =

-      extends CreditCardPaymentProcessor {
+      <programlisting role=3D"JAVA"><![CDATA[@Staging
+public class StagingPaymentProcessor =

+      implements PaymentProcessor {
    ...
 }]]></programlisting>
 =

       <para>
-         Finally, we activate the <literal>@Staging</literal> stereotype i=
n the beans.xml descriptor:
+         Finally, we activate the <literal>@Staging</literal> stereotype i=
n the <literal>beans.xml</literal> descriptor:
       </para>
 =

       <programlisting role=3D"XML"><![CDATA[<beans
@@ -139,20 +124,28 @@
 </beans>]]></programlisting>
 =

       <para>
-         Now, no matter how many staging beans we have, they will all be e=
nabled at once. Does that mean the default
-         implementation is disabled? Well, not exactly. If the default imp=
lementation has a qualifier, for instance
-         <literal>@LargeTransaction</literal>, and the alternative does no=
t, you could still inject the default
-         implementation.
+         Now, no matter how many staging beans we have, they will all be e=
nabled at once. =

       </para>
+      =

+   </section>
+    =

+   <section>
+      <title>A minor problem with alternatives</title>
+    =

+      <para>
+         When we enable an alternative, does that mean the default impleme=
ntation is disabled? Well, not exactly. If the =

+         default implementation has a qualifier, for instance <literal>@La=
rgeTransaction</literal>, and the alternative =

+         does not, you could still inject the default implementation.
+      </para>
 =

-      <programlisting role=3D"JAVA"><![CDATA[@LargeTransaction @CreditCard=
 PaymentProcessor paymentProcessor;]]></programlisting>
+      <programlisting role=3D"JAVA"><![CDATA[@Inject @LargeTransaction Pay=
mentProcessor paymentProcessor;]]></programlisting>
 =

       <para>
-         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
-         something extra.
+         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 injection point=
s is if it implements all the bean types and =

+         declares all the qualifiers of the second bean. However, if the s=
econd 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 something =

+         extra.
       </para>
   =

       <para>
@@ -160,6 +153,7 @@
          these traps. Specialization is a way of informing the system of y=
our intent to completely replace and disable
          an implementation of a bean.
       </para>
+      =

    </section>
   =

    <section>


--===============2187895246077787424==--