Author: gavin.king(a)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[(a)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>