From weld-commits at lists.jboss.org Mon Nov 9 18:16:01 2009 Content-Type: multipart/mixed; boundary="===============7943540319543106040==" MIME-Version: 1.0 From: weld-commits at lists.jboss.org To: weld-commits at lists.jboss.org Subject: [weld-commits] Weld SVN: r4907 - doc/trunk/reference/en-US. Date: Mon, 09 Nov 2009 18:16:00 -0500 Message-ID: <200911092316.nA9NG0EO006041@svn01.web.mwc.hst.phx2.redhat.com> --===============7943540319543106040== 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 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=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-09 23:16:00 UTC (rev 49= 06) +++ doc/trunk/reference/en-US/injection.xml 2009-11-09 23:16:00 UTC (rev 49= 07) @@ -4,10 +4,8 @@ Dependency injection and programmatic lookup = - One of the most significant features of CDI, certainly the most reco= gnized, is dependency injection; but not just - dependency injection—typesafe 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 cli= ents. + One of the most significant features of CDI—certainly the most= recognized—is dependency injection; + excuse me, typesafe dependency injection. =
@@ -283,10 +281,11 @@ Then we select one of the possible member values when appling = the qualifier: = - = + = = - We can force the container to ignore a member of a qualifier t= ype by annotating the member @NonBinding. + We can force the container to ignore a member of a qualifier t= ype by annotating the member = + @NonBinding. = = - Then a bean which has both qualifier anno= tations would be eligible for + Then only a bean which has both qualifier= annotations would be eligible for injection. = @@ -319,41 +318,7 @@ }]]> = =
- -
- Qualifiers on producer methods - - - Even producer methods may specify qualifiers: - - - - - - - If we really need to create beans with asynchronous semanti= cs, EJB 3.1 asynchronous methods are an - excellent solution. - - - -
- -
- The default qualifier = - - CDI defines the qualifier annotation @Default that is the default qualifier type for any - injection point or bean that does not explicitly specify a qua= lifier. - - = - - - The most common circumstance when it's necessary to explicitly= specify @Default is on a bean - which has another qualifier in addition to the default one. - - = -
- = =
@@ -363,40 +328,38 @@ The typesafe resolution algorithm fails when, after considering t= he qualifier annotations on all beans that implement the bean type of an injection point and filtering out d= isabled beans (@Alternative beans which are not explicitly enabled), the container is unable = to identify exactly one bean to inject. The - container will either throw an UnsatisfiedDependencyExce= ption or - AmbiguousDependencyException, depending on the= circumstance. + container will abort deployment, informing us of the unsatisfied = or ambiguous dependency. = - 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 he= re. + During the course of your development, you're going to encounter = this situation. Let's learn how to resolve it. = - To fix an UnsatisfiedDependencyException, eith= er: = + To fix an unsatisfied dependency, either: = = = - create a bean which implements the bean type and has all the q= ualifier types of the injection point, + create a bean which implements the bean type and has all th= e qualifier types of the injection point, = - make sure that the bean you already have is in the classpath o= f the module with the injection point, or + make sure that the bean you already have is in the classpat= h of the module with the injection point, or = = - explicitly enable an @Alternative bean that= implements the bean type and has the = - appropriate qualifier types, using beans.xml. + explicitly enable an @Alternative bean t= hat implements the bean type and has the = + appropriate qualifier types, using beans.xml. = = - To fix an AmbiguousDependencyException, either= : = + To fix an ambiguous dependency, either: = = @@ -423,11 +386,6 @@ = - = - - An AmbiguousDependencyException can only occur= if two enabled beans share the same = - qualifier types. - = Just remember: "There can be only one." @@ -439,7 +397,7 @@ = - There's one more issue you need to be aware of when using the dep= endency injection service: client proxies. + Now there's one more issue you need to be aware of when using the= dependency injection service. =
@@ -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. - - - - 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 establi= shed prior to the method call and cleared - afterword using an interceptor—a process known as biject= ion. This model was not very friendly to multiple - threads sharing instances and therefore the client proxy appro= ach was adopted in CDI instead. - - = - 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 = - @Dependent, the container throws an U= nproxyableDependencyException 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 t= o a bean with any scope other than = + @Dependent, the container will abort deploymen= t, informing us of the problem. = The following Java types cannot be proxied by the container: @@ -506,9 +454,9 @@ = - It's usually very easy to fix an UnproxyableDependencyEx= ception. 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 @Dependent. = + 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 = + @Dependent. = = @@ -565,43 +513,42 @@ = - In these situations, the application may obtain an instance of th= e interface Instance = - parameterized for the bean type by injection: + In these situations, the application may obtain an instance of th= e interface Instance, = + parameterized for the bean type, by injection: = paymentProcessorSource;]]> = - The get() method on Instance can be used to produce a contextual instance - of the bean programmatically. + The get() method of Instance produces a contextual instance of the bean. = = - 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: = paymentProcessorSource;]]> = - You can also select a bean dynamically from the Instance= by passing the bean's qualifier. - First, you need to add the @Any annotation at = the injection point: + Alternatively, we can specify the qualifier dynamically. First, w= e add the @Any qualifier to + the injection point: = paymentProcessorSource;]]> = - Then you specify which bean you want, by passing its qualifier t= o the select() method of - Instance. You represent a qualifier annotation= in code by subclassing the helper class - AnnotationLiteral, since it's otherwise diffic= ult to instantiate an annotation type in Java. + Now we can pass the qualifier to the select() = method of Instance. We can = + obtain a qualifier instance by subclassing the helper class AnnotationLiteral, since it's = + otherwise difficult to instantiate an annotation type in Java. = () {});]]> = - You can choose to create a concrete type for all of your annotati= on literals, such as: + We can choose to create a concrete type for the annotation litera= l: = - The concrete type is required if your qualifier has members, s= ince an anonymous subclass cannot define members. + The concrete type is required if the qualifier has members. - + = - Again, like with annotation definitions, the AnnotationL= iteral definition may seem a bit - foreign at first, but it will soon become second nature as you wi= ll see it often in CDI applications. - - - Here's how you might make use of dynamic selection: = = = = -
+ =
- Lifecycle callbacks and resource injections + Lifecycle callbacks and component environment injection</titl= e> = <para> - As part of the managed bean contract, all CDI beans support the l= ifecycle callback methods, - <literal>@PostConstruct</literal> and <literal>@PreDestroy</liter= al> which are called after the bean is - initialized (and after injections take place) and before it is de= stroyed (when the context to which it is bound - ends), respectively. + Managed beans and EJB beans support the lifecycle callback method= s, <literal>@PostConstruct</literal> and = + <literal>@PreDestroy</literal> which are called after after all d= ependencies have been injected, and before the = + bean is destroyed (when the context to which it belongs ends), re= spectively. EJB beans also support the EJB = + callback methods <literal>@PrePassivate</literal> and <literal>@P= ostActivate</literal>. </para> = <para> - Of course, session beans also support callback methods introduced= by the EJB specification, such as - <literal>@PrePassivate</literal> and <literal>@PostActivate</lite= ral>. + Managed beans and EJB beans also support Java EE 5-style componen= t environment injection, where the injection + point is declared using <literal>@Resource</literal>, <literal>@P= ersistenceContext</literal>, = + <literal>@PersistenceUnit</literal>, <literal>@WebServiceRef</lit= eral> or <literal>@EJB</literal>. However, in = + a CDI environment, these annotations are most useful for declarin= g resources that can be injected by CDI. </para> = - <para> - Managed beans also support Java EE 5-style resource injections, d= eclared using the <literal>@Resource</literal> - annotation on a field. CDI beans can also inject session beans wi= th the <literal>@EJB</literal> annotation. - </para> - - <para> - However, as you learned in a previous section, these injections a= re 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 fie= lds to mold these container-managed objects - into injectable beans. - </para> - </section> = <!-- --===============7943540319543106040==--