[weld-commits] Weld SVN: r4900 - doc/trunk/reference/en-US.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Mon Nov 9 17:31:19 EST 2009
Author: gavin.king at jboss.com
Date: 2009-11-09 17:31:19 -0500 (Mon, 09 Nov 2009)
New Revision: 4900
Modified:
doc/trunk/reference/en-US/intro.xml
Log:
various improvements
Modified: doc/trunk/reference/en-US/intro.xml
===================================================================
--- doc/trunk/reference/en-US/intro.xml 2009-11-09 22:30:16 UTC (rev 4899)
+++ doc/trunk/reference/en-US/intro.xml 2009-11-09 22:31:19 UTC (rev 4900)
@@ -137,7 +137,7 @@
<programlistingco>
<areaspec>
- <area id="injection" coords="3"/>
+ <area id="textTranslator" coords="3"/>
</areaspec>
<programlisting role="JAVA"><![CDATA[@Named @RequestScoped
public class TranslateController {
@@ -164,7 +164,7 @@
}
}]]></programlisting>
<calloutlist>
- <callout arearefs="injection">
+ <callout arearefs="textTranslator">
<para>
Field injection of <literal>TextTranslator</literal> instance
</para>
@@ -307,7 +307,7 @@
</blockquote>
- <para>Let's see what some of these new terms mean.</para>
+ <para>Let's see what all this new terminology means.</para>
<section>
<title>Bean types, qualifiers and dependency injection</title>
@@ -323,7 +323,7 @@
</itemizedlist>
<para>
- A bean type is a user-defined class or interface; types that are client-visible. If the bean is an EJB
+ A bean type is a user-defined class or interface; a type that is client-visible. If the bean is an EJB
session bean, the bean type is the <literal>@Local</literal> interface or bean-class local view. A bean may
have multiple bean types. For example, the following bean has four bean types:
</para>
@@ -362,9 +362,8 @@
<para>
Bean types may be restricted to an explicit set by annotating the bean with the <literal>@Typed</literal>
- annotation and listing the bean types in the value of the annotation. For instance, this bean has been
- restricted to the bean type explicitly listed, <literal>Shop<Book></literal>, together with
- <literal>java.lang.Object</literal>:
+ annotation and listing the classes that should be bean types. For instance, the bean types of this bean have
+ been restricted to <literal>Shop<Book></literal>, together with <literal>java.lang.Object</literal>:
</para>
<programlisting role="JAVA"><![CDATA[@Typed(Shop.class)
@@ -375,19 +374,18 @@
}]]></programlisting>
<para>
- The bean types alone often do not provide enough information for the container to know which bean to inject.
+ Sometimes, a bean type alone does not provide enough information for the container to know which bean to inject.
For instance, suppose we have two implementations of the <literal>PaymentProcessor</literal> interface:
- <literal>CreditCardPaymentProcessor</literal> and <literal>DebitPaymentProcessor</literal>. Injecting into a
- field of type <literal>PaymentProcessor</literal> introduces an ambiguous condition. In these cases, the
- container must rely on some client-visible semantic that is satisfied by one implementation of the bean
- type, but not by others. That semantic is called a qualifier.
+ <literal>CreditCardPaymentProcessor</literal> and <literal>DebitPaymentProcessor</literal>. Injecting a field of
+ type <literal>PaymentProcessor</literal> introduces an ambiguous condition. In these cases, the client must
+ specify some additional quality of the implementation it is interested in. We model this kind of "quality" using
+ a qualifier.
</para>
<para>
- Qualifiers are represented by user-defined annotations that are themselves annotated with
- <literal>@Qualifer</literal>. These annotations extend the type system in Java to let you further qualify
- the type without having to fall back to string-based names as in many other dependency injection solutions.
- Here's an example of a qualifier annotation:
+ A qualifier is a user-defined annotation that is itself annotated <literal>@Qualifer</literal>. A qualifier
+ annotation is an extension of the type system. It lets us disambiguate a type without having to fall back to
+ string-based names. Here's an example of a qualifier annotation:
</para>
<programlisting role="JAVA"><![CDATA[@Qualifier
@@ -396,9 +394,9 @@
public @interface CreditCard {}]]></programlisting>
<para>
- You may not be used to seeing the definition of an annotation. In fact, this might be the first time you
- have encountered one. With CDI, they will become very familiar artifact as you will be creating them from
- time to time.
+ You may not be used to seeing the definition of an annotation. In fact, this might be the first time you've
+ encountered one. With CDI, annotation definitions will become a familiar artifact as you'll be creating them
+ from time to time.
</para>
<tip>
@@ -410,8 +408,9 @@
</tip>
<para>
- Now that we have defined a qualifier annotation, we can use it. The following injection point has the bean
- type <literal>PaymentProcessor</literal> and qualifier <literal>@CreditCard</literal>:
+ Now that we have defined a qualifier annotation, we can use it to disambiguate an injection point. The
+ following injection point has the bean type <literal>PaymentProcessor</literal> and qualifier
+ <literal>@CreditCard</literal>:
</para>
<programlisting role="JAVA"><![CDATA[@Inject @CreditCard PaymentProcessor paymentProcessor]]></programlisting>
@@ -425,15 +424,14 @@
<para>
For each injection point, the container searches for a bean which satisfies the contract, one which has
- the bean type and all the qualifiers. If it find exactly one matching bean, it injects an instance of
- that bean.
+ the bean type and all the qualifiers. If it finds exactly one matching bean, it injects an instance of
+ that bean. If it doesn't, it reports an error to the user.
</para>
<para>
- We've seen how to indicate that you want to inject a qualified bean. But how do you actually qualify the bean?
- By using the annotation, of course! The following bean has the qualifier <literal>@CreditCard</literal>
- and implements the bean type <literal>PaymentProcessor</literal>. Therefore, it satisfies our qualified
- injection point:
+ How do we specify that qualifiers of a bean? By annotating the bean class, of course! The following bean
+ has the qualifier <literal>@CreditCard</literal> and implements the bean type <literal>PaymentProcessor</literal>.
+ Therefore, it satisfies our qualified injection point:
</para>
<programlisting role="JAVA"><![CDATA[@CreditCard
@@ -455,9 +453,9 @@
-->
<para>
- CDI defines a simple <emphasis>resolution rule</emphasis> that helps the container decide what to do if there
- is more than one bean that satisfies a particular contract. We'll get into the details in
- <xref linkend="alternatives"/>.
+ That's not quite the end of the story. CDI also defines a simple <emphasis>resolution rule</emphasis> that helps
+ the container decide what to do if there is more than one bean that satisfies a particular contract. We'll get
+ into the details in <xref linkend="alternatives"/>.
</para>
<!--
@@ -544,8 +542,7 @@
</note>
<para>
- If you want, you can let CDI select a name for you by leaving off the
- value of the <literal>@Named</literal> annotation:
+ We can let CDI choose a name for us by leaving off the value of the <literal>@Named</literal> annotation:
</para>
<programlisting role="JAVA"><![CDATA[public @SessionScoped @Named
@@ -612,10 +609,14 @@
<para>
CDI provides a new approach to binding interceptors to beans that introduces a level of indirection (and
- thus control). We define a special kind of annotation called an <emphasis>interceptor binding
- type</emphasis> whose name describes the behavior implemented by the interceptor, in this case to perform
- transaction management:
+ thus control). We must define an <emphasis>interceptor binding type</emphasis> to describe the behavior
+ implemented by the interceptor.
</para>
+
+ <para>
+ An interceptor binding type is a user-defined annotation that is itself annotated <literal>@InterceptorBinding</literal>.
+ It lets us bind interceptor classes to bean classes with no direct dependency between the two classes.
+ </para>
<programlisting role="JAVA"><![CDATA[@InterceptorBinding
@Inherited
@@ -631,20 +632,23 @@
class TransactionInterceptor { ... }]]></programlisting>
<para>
- We can apply the interceptor to a bean by annotating to the bean class with the same interceptor
- binding type:
+ We can apply the interceptor to a bean by annotating the bean class with the same interceptor binding type:
</para>
<programlisting role="JAVA"><![CDATA[public @SessionScoped @Transactional
class ShoppingCart implements Serializable { ... }]]></programlisting>
<para>
- Now there's no direct dependency between the two implementations (bean and interceptor). Activation of
- interceptors is controlled by the CDI deployment descriptor <literal>META-INF/beans.xml</literal>
- of the jar or Java EE module, allowing us to control which interceptors apply in which deployment
- scenarios, along with the order of interceptor invocation when multiple interceptors apply to a
- bean.
+ Notice that <literal>ShoppingCart</literal> and <literal>TransactionInterceptor</literal> don't know
+ anything about each other.
</para>
+
+ <para>
+ Interceptors are deployment-specific. (We don't need a <literal>TransactionInterceptor</literal> in our
+ unit tests!) By default, an interceptor is disabled. We can enable an interceptor using the CDI deployment
+ descriptor <literal>META-INF/beans.xml</literal> of the jar or Java EE module. This is also where we
+ specify the interceptor ordering.
+ </para>
<para>
We'll discuss interceptors, and their cousins, decorators, in <xref linkend="interceptors"/> and <xref
@@ -659,8 +663,9 @@
<title>What kinds of classes are beans?</title>
<para>
- We've already seen that JavaBeans and EJB session beans can be (CDI) beans. Is that the whole story?
- Actually, it's just the beginning.
+ We've already seen two types of beans: JavaBeans and EJB session beans. Is that the whole story? Actually,
+ it's just the beginning. Let's explore the various kinds of beans that CDI implementations must support
+ out-of-the-box.
</para>
<section>
@@ -727,10 +732,9 @@
<para>
Session beans belong to the EJB specification. They have a special lifecycle, state management and concurrency
model that is different to other managed beans and non-managed Java objects. But session beans participate in
- CDI just like any other bean. There are some restrictions upon the scope that can be assigned to a session bean,
- but apart from than that, they may be used interchangeably with regular managed beans. That means you can inject
- one session bean into another session bean, a managed bean into a session bean, a session bean into a managed
- bean, have a managed bean observe an event raised by a session bean, and so on.
+ CDI just like any other bean. You can inject one session bean into another session bean, a managed bean into a
+ session bean, a session bean into a managed bean, have a managed bean observe an event raised by a session bean,
+ and so on.
</para>
<note>
@@ -746,7 +750,7 @@
The unrestricted set of bean types for a session bean contains all local interfaces of the bean and their
superinterfaces. If the session bean has a bean class local view, the unrestricted set of bean types
contains the bean class and all superclasses. In addition, <literal>java.lang.Object</literal> is a bean
- type of every session bean. But, remote interfaces are <emphasis>not</emphasis> included in the set of bean
+ type of every session bean. But remote interfaces are <emphasis>not</emphasis> included in the set of bean
types.
</para>
@@ -796,8 +800,7 @@
<para>
Beans which hold references to heavy-weight resources, or hold a lot of internal state benefit from the
- advanced container-managed lifecycle defined by the EJB
- <literal>@Stateless</literal>/<literal>@Stateful</literal>/<literal>@Singleton</literal> model, with its
+ advanced container-managed lifecycle defined by the EJB stateless/stateful/singleton model, with its
support for passivation and instance pooling.
</para>
@@ -830,14 +833,15 @@
<para>
Not everything that needs to be injected can be boiled down to a bean class instantiated by the container
using <literal>new</literal>. There are plenty of cases where we need additional control. What if we need
- to decide at runtime which implementation of a type to instantiate and inject? What if we need to inject an
- object that is obtained by querying a service or transactional resource, for example by executing a JPA query?
+ to decide at runtime which implementation of a type to instantiate and inject? What if we need to inject
+ an object that is obtained by querying a service or transactional resource, for example by executing a JPA
+ query?
</para>
<para>
- A <emphasis>producer method</emphasis> is a method that acts as a source of bean instances, meaning the
- method declaration itself describes the bean and the container invokes the method to obtain an instance of
- the bean when no instance exists in the specified context. A producer method lets the application take full
+ A <emphasis>producer method</emphasis> is a method that acts as a source of bean instances. The method
+ declaration itself describes the bean and the container invokes the method to obtain an instance of the
+ bean when no instance exists in the specified context. A producer method lets the application take full
control of the bean instantiation process.
</para>
@@ -957,10 +961,10 @@
<para>
Naturally, there is now a slight mismatch with the new style of dependency injection in CDI. Most notably,
component environment injection relies on string-based names to qualify ambiguous types, and there is no
- real consistency as to the nature of the names (sometimes a JNDI name, other times an identifier from an
- XML descriptor, or even a default name). Producer fields turned out to be an elegant adaptor to reduce all
- this complexity to a common model and get component environment resources to participate in the CDI system
- just like any other kind of bean.
+ real consistency as to the nature of the names (sometimes a JNDI name, sometimes a persistence unit name,
+ sometimes an EJB link, sometimes a nonportable "mapped name"). Producer fields turned out to be an elegant
+ adaptor to reduce all this complexity to a common model and get component environment resources to
+ participate in the CDI system just like any other kind of bean.
</para>
<para>
More information about the weld-commits
mailing list