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

weld-commits at lists.jboss.org weld-commits at lists.jboss.org
Mon Nov 9 18:16:00 EST 2009


Author: gavin.king at jboss.com
Date: 2009-11-09 18:16:00 -0500 (Mon, 09 Nov 2009)
New Revision: 4907

Modified:
   doc/trunk/reference/en-US/injection.xml
Log:
clean up

Modified: doc/trunk/reference/en-US/injection.xml
===================================================================
--- doc/trunk/reference/en-US/injection.xml	2009-11-09 23:16:00 UTC (rev 4906)
+++ doc/trunk/reference/en-US/injection.xml	2009-11-09 23:16:00 UTC (rev 4907)
@@ -4,10 +4,8 @@
    <title>Dependency injection and programmatic lookup</title>
 
    <para>
-      One of the most significant features of CDI, certainly the most recognized, is dependency injection; but not just
-      dependency injection&#8212;<emphasis>typesafe</emphasis> dependency injection. In this chapter, you'll learn how 
-      CDI is able to leverage the Java type system and annotations into a dependency injection strategy that is both
-      strongly typed and keeps the bean implementation hidden from its clients.
+      One of the most significant features of CDI&#8212;certainly the most recognized&#8212;is dependency injection;
+      excuse me, <emphasis>typesafe</emphasis> dependency injection.
    </para>
 
    <section>
@@ -283,10 +281,11 @@
             Then we select one of the possible member values when appling the qualifier:
          </para>
 
-         <programlisting role="JAVA"><![CDATA[private @Inject @PayBy(CHECK) CheckPayment checkPayment;]]></programlisting> 
+         <programlisting role="JAVA"><![CDATA[private @Inject @PayBy(CHECK) PaymentProcessor checkPayment;]]></programlisting> 
 
          <para>
-            We can force the container to ignore a member of a qualifier type by annotating the member <literal>@NonBinding</literal>.
+            We can force the container to ignore a member of a qualifier type by annotating the member 
+            <literal>@NonBinding</literal>.
          </para>
 
          <programlisting role="JAVA"><![CDATA[@Qualifier
@@ -309,7 +308,7 @@
          <programlisting role="JAVA"><![CDATA[@Inject @Synchronous @Reliable PaymentProcessor syncPaymentProcessor;]]></programlisting>
 
          <para>
-            Then a bean which has <emphasis>both</emphasis> qualifier annotations would be eligible for
+            Then only a bean which has <emphasis>both</emphasis> qualifier annotations would be eligible for
             injection.
          </para>
 
@@ -319,41 +318,7 @@
 }]]></programlisting>      
 
       </section>
-
-      <section>
-         <title>Qualifiers on producer methods</title>
-
-         <para>
-            Even producer methods may specify qualifiers:
-         </para>
-
-         <programlisting role="JAVA"><![CDATA[@Produces @Asynchronous PaymentProcessor getPaymentProcessor() { ... }]]></programlisting>
-
-         <tip>
-            <para>
-               If we really need to create beans with asynchronous semantics, EJB 3.1 asynchronous methods are an
-               excellent solution.
-            </para>
-         </tip>
-
-      </section>
-
-      <section>
-         <title>The default qualifier</title>
   
-         <para>
-            CDI defines the qualifier annotation <literal>@Default</literal> that is the default qualifier type for any
-            injection point or bean that does not explicitly specify a qualifier.
-         </para>
-  
-         <para>
-            <!-- this is a really vague point -->
-            The most common circumstance when it's necessary to explicitly specify <literal>@Default</literal> is on a bean
-            which has another qualifier in addition to the default one.
-         </para>
-  
-      </section>
-  
    </section>
 
    <section>
@@ -363,40 +328,38 @@
          The typesafe resolution algorithm fails when, after considering the qualifier annotations on all beans that
          implement the bean type of an injection point and filtering out disabled beans (<literal>@Alternative</literal>
          beans which are not explicitly enabled), the container is unable to identify exactly one bean to inject. The
-         container will either throw an <literal>UnsatisfiedDependencyException</literal> or
-         <literal>AmbiguousDependencyException</literal>, depending on the circumstance.
+         container will abort deployment, informing us of the unsatisfied or ambiguous dependency.
       </para>
   
       <para>
-         During the course of your development, you're going to encounter these errors. Let's learn how to resolve them.
-         It's usually pretty easy, and a decent IDE can really help out here.
+         During the course of your development, you're going to encounter this situation. Let's learn how to resolve it.
       </para>
   
       <para>
-         To fix an <literal>UnsatisfiedDependencyException</literal>, either: 
+         To fix an <emphasis>unsatisfied dependency</emphasis>, either: 
       </para>
          
       <itemizedlist>
          <listitem>      
             <para>
-            create a bean which implements the bean type and has all the qualifier types of the injection point,
+               create a bean which implements the bean type and has all the qualifier types of the injection point,
             </para>
          </listitem> 
          <listitem>
             <para>
-            make sure that the bean you already have is in the classpath of the module with the injection point, or
+               make sure that the bean you already have is in the classpath of the module with the injection point, or
             </para>
          </listitem> 
          <listitem> 
             <para>
-            explicitly enable an <literal>@Alternative</literal> bean that implements the bean type and has the 
-            appropriate qualifier types, using <literal>beans.xml</literal>.
+               explicitly enable an <literal>@Alternative</literal> bean that implements the bean type and has the 
+               appropriate qualifier types, using <literal>beans.xml</literal>.
             </para>
          </listitem> 
       </itemizedlist>
       
       <para>
-         To fix an <literal>AmbiguousDependencyException</literal>, either: 
+         To fix an <emphasis>ambiguous dependency</emphasis>, either: 
       </para>
 
       <itemizedlist>
@@ -423,11 +386,6 @@
             </para>
          </listitem> 
       </itemizedlist>
-               
-      <para>
-         An <literal>AmbiguousDependencyException</literal> can only occur if two enabled beans share the same 
-         qualifier types.
-      </para>
       
       <tip>
          <para>Just remember: "There can be only one."</para>
@@ -439,7 +397,7 @@
       </para>
   
       <para>
-         There's one more issue you need to be aware of when using the dependency injection service: client proxies.
+         Now there's one more issue you need to be aware of when using the dependency injection service.
       </para>
 
    </section>
@@ -472,21 +430,11 @@
          the current context. The client proxy also allows beans bound to contexts such as the session context to be
          serialized to disk without recursively serializing other injected beans.
       </para>
-
-      <note>
-         <para>
-            If you recall, Seam also boasted the ability to reference the current instance of a component. However, Seam
-            went about it differently. In Seam, the references are established prior to the method call and cleared
-            afterword using an interceptor&#8212;a process known as bijection. This model was not very friendly to multiple
-            threads sharing instances and therefore the client proxy approach was adopted in CDI instead.
-         </para>
-      </note>
   
       <para>
-         Unfortunately, due to limitations of the Java language, some Java types cannot be proxied by the container. If
-         an inection point declared with one of these types resolves to a bean with any scope other than 
-         <literal>@Dependent</literal>, the container throws an <literal>UnproxyableDependencyException</literal> at
-         system initialization time.
+         Unfortunately, due to limitations of the Java language, some Java types cannot be proxied by the container. 
+         If an injection point declared with one of these types resolves to a bean with any scope other than 
+         <literal>@Dependent</literal>, the container will abort deployment, informing us of the problem.
       </para>
   
       <para>The following Java types cannot be proxied by the container:</para>
@@ -506,9 +454,9 @@
       </itemizedlist>
   
       <para>
-         It's usually very easy to fix an <literal>UnproxyableDependencyException</literal>. Simply add a constructor
-         with no parameters to the injected class, introduce an interface, or, if all else fails, change the scope of
-         the injected bean to <literal>@Dependent</literal>. 
+         It's usually very easy to fix an unproxyable dependency problem. Simply add a constructor with no parameters to 
+         the injected class, introduce an interface, or, if all else fails, change the scope of the injected bean to 
+         <literal>@Dependent</literal>. 
       </para>
       
       <note>
@@ -565,43 +513,42 @@
       </itemizedlist>
 
       <para>
-         In these situations, the application may obtain an instance of the interface <literal>Instance</literal> 
-         parameterized for the bean type by injection:
+         In these situations, the application may obtain an instance of the interface <literal>Instance</literal>, 
+         parameterized for the bean type, by injection:
       </para>
   
       <programlisting role="JAVA"><![CDATA[@Inject Instance<PaymentProcessor> paymentProcessorSource;]]></programlisting>
   
       <para>
-         The <literal>get()</literal> method on <literal>Instance</literal> can be used to produce a contextual instance
-         of the bean programmatically.
+         The <literal>get()</literal> method of <literal>Instance</literal> produces a contextual instance of the bean.
       </para>
   
       <programlisting role="JAVA"><![CDATA[PaymentProcessor p = paymentProcessorSource.get();]]></programlisting>
 
       <para>
-         Of course, qualifiers can be specified at the injection point, as with a bean injection:
+         Of course, qualifiers can be specified at the injection point:
       </para>
 
       <programlisting role="JAVA"><![CDATA[@Inject @Asynchronous Instance<PaymentProcessor> paymentProcessorSource;]]></programlisting>
   
       <para>
-         You can also select a bean dynamically from the <literal>Instance</literal> by passing the bean's qualifier.
-         First, you need to add the <literal>@Any</literal> annotation at the injection point:
+         Alternatively, we can specify the qualifier dynamically. First, we add the <literal>@Any</literal> qualifier to
+         the injection point:
       </para>
 
       <programlisting role="JAVA"><![CDATA[@Inject @Any Instance<PaymentProcessor> paymentProcessorSource;]]></programlisting>
       
       <para>
-         Then you specify which bean you want, by passing  its qualifier to the <literal>select()</literal> method of
-         <literal>Instance</literal>. You represent a qualifier annotation in code by subclassing the helper class
-         <literal>AnnotationLiteral</literal>, since it's otherwise difficult to instantiate an annotation type in Java.
+         Now we can pass the qualifier to the <literal>select()</literal> method of <literal>Instance</literal>. We can 
+         obtain a qualifier instance by subclassing the helper class <literal>AnnotationLiteral</literal>, since it's 
+         otherwise difficult to instantiate an annotation type in Java.
       </para>
   
       <programlisting role="JAVA"><![CDATA[PaymentProcessor p = paymentProcessorSource
    .select(new AnnotationLiteral<Asynchronous>() {});]]></programlisting>
 
       <para>
-         You can choose to create a concrete type for all of your annotation literals, such as:
+         We can choose to create a concrete type for the annotation literal:
       </para>
 
       <programlisting role="JAVA"><![CDATA[abstract class AsynchronousQualifier
@@ -609,26 +556,24 @@
 
       <note>
          <para>
-            The concrete type is required if your qualifier has members, since an anonymous subclass cannot define members.
+            The concrete type is required if the qualifier has members.
          </para>
       </note>
-
+      
       <para>
-         Again, like with annotation definitions, the <literal>AnnotationLiteral</literal> definition may seem a bit
-         foreign at first, but it will soon become second nature as you will see it often in CDI applications.
-      </para>
-
-      <para>
          Here's how you might make use of dynamic selection:
       </para>
 
       <programlisting><![CDATA[Annotation qualifier = synchronously ?
-new SynchronousQualifier() : new AsynchronousQualifier();
+      new SynchronousQualifier() : new AsynchronousQualifier();
 PaymentProcessor p = anyPaymentProcessor.select(qualifier).get().process(payment);]]></programlisting> 
 
    </section>
 
-   <section>
+   <!--section>
+   
+      What the hell is the purpose of this section?! I didn't learn anything useful from it.
+   
       <title>Bean names and EL lookup</title>
 
       <para>
@@ -667,35 +612,25 @@
          business tier isn't tied to JSF in any way.
       </para>
 
-   </section>
+   </section-->
 
    <section>
-      <title>Lifecycle callbacks and resource injections</title>
+      <title>Lifecycle callbacks and component environment injection</title>
 
       <para>
-         As part of the managed bean contract, all CDI beans support the lifecycle callback methods,
-         <literal>@PostConstruct</literal> and <literal>@PreDestroy</literal> which are called after the bean is
-         initialized (and after injections take place) and before it is destroyed (when the context to which it is bound
-         ends), respectively.
+         Managed beans and EJB beans support the lifecycle callback methods, <literal>@PostConstruct</literal> and 
+         <literal>@PreDestroy</literal> which are called after after all dependencies have been injected, and before the 
+         bean is destroyed (when the context to which it belongs ends), respectively. EJB beans also support the EJB 
+         callback methods <literal>@PrePassivate</literal> and <literal>@PostActivate</literal>.
       </para>
 
       <para>
-         Of course, session beans also support callback methods introduced by the EJB specification, such as
-         <literal>@PrePassivate</literal> and <literal>@PostActivate</literal>.
+         Managed beans and EJB beans also support Java EE 5-style component environment injection, where the injection
+         point is declared using <literal>@Resource</literal>, <literal>@PersistenceContext</literal>, 
+         <literal>@PersistenceUnit</literal>, <literal>@WebServiceRef</literal> or <literal>@EJB</literal>. However, in 
+         a CDI environment, these annotations are most useful for declaring resources that can be injected by CDI.
       </para>
 
-      <para>
-         Managed beans also support Java EE 5-style resource injections, declared using the <literal>@Resource</literal>
-         annotation on a field. CDI beans can also inject session beans with the <literal>@EJB</literal> annotation.
-      </para>
-
-      <para>
-         However, as you learned in a previous section, these injections are not fully type-safe, nor do they have the
-         semantics that CDI provides. Therefore, it's the use of <literal>@Inject</literal> for injection is preferred.
-         Relegate the resource injections to a bean that uses producer fields to mold these container-managed objects
-         into injectable beans.
-      </para>
-
    </section>
 
 <!--



More information about the weld-commits mailing list