[weld-commits] Weld SVN: r4592 - doc/trunk/reference/en-US.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Tue Nov 3 05:26:17 EST 2009
Author: gavin.king at jboss.com
Date: 2009-11-03 05:26:17 -0500 (Tue, 03 Nov 2009)
New Revision: 4592
Modified:
doc/trunk/reference/en-US/intro.xml
doc/trunk/reference/en-US/part1.xml
Log:
various revisions
Modified: doc/trunk/reference/en-US/intro.xml
===================================================================
--- doc/trunk/reference/en-US/intro.xml 2009-11-03 10:24:58 UTC (rev 4591)
+++ doc/trunk/reference/en-US/intro.xml 2009-11-03 10:26:17 UTC (rev 4592)
@@ -1,12 +1,12 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
<chapter id="intro">
- <title>Getting started with JSR-299 (CDI)</title>
+ <title>Getting started with CDI</title>
<para>
So you're keen to get started writing your first bean? Or perhaps you're skeptical, wondering what kinds of hoops
the CDI specification will make you jump through! The good news is that you've probably already written and used
- hundreds, perhaps thousands of beans. CDI just helps you make use them in your web or enterprise application.
+ hundreds, perhaps thousands of beans. CDI just makes it easier to actually use them to build an application!
</para>
<section id="bean-definition">
@@ -14,41 +14,42 @@
<para>
In this section, you'll learn that a bean is exactly what you think it is. Only now, it has a true identity in
- Java EE.
+ the container environment.
</para>
<para>
- Prior to Java EE 6, there existed no clear definition of a bean in the platform. Of course, we've been calling
- Java classes used in web and enterprise applications beans for years. Third-party frameworks, such as Spring,
- even have facilities for defining and creating beans; and there are a couple of bean variants in the platform
- itself, including EJB session beans and JSF managed beans. What was missing was a common definition.
+ Prior to Java EE 6, there was no clear definition of the term "bean" in the Java EE platform. Of course,
+ we've been calling Java classes used in web and enterprise applications "beans" for years. There were even a
+ couple of different kinds of things called "beans" in EE specifications, including EJB session beans and JSF
+ managed beans. Meanwhile, other third-party frameworks such as Spring and Seam introduced their own ideas of
+ what it meant to be a "bean". What we've been missing is a common definition.
</para>
<para>
- Java EE 6 finally lays down the definition of a bean in the Managed Bean specification. Managed Beans are
- defined as container-managed objects with minimal requirements, otherwise known by their acronym, POJOs (Plain
- Old Java Objects). They support a small set of basic services, such as resource injection, lifecycle callbacks
- and interceptors. Companion specifications, such as EJB and CDI, build on this basic model. But, <emphasis>at
- last</emphasis>, there is a universally accepted concept of a bean and a lightweight component model that's
+ Java EE 6 finally lays down that common definition in the Managed Beans specification. Managed Beans are
+ defined as container-managed objects with minimal programming restrictions, otherwise known by the acronym
+ POJO (Plain Old Java Object). They support a small set of basic services, such as resource injection, lifecycle
+ callbacks and interceptors. Companion specifications, such as EJB and CDI, build on this basic model. But,
+ <emphasis>at last</emphasis>, there is a uniform concept of a bean and a lightweight component model that's
aligned across the Java EE platform.
</para>
<para>
- With certain, unique exceptions, every Java class that has a constructor with no parameters (or an alternate
- constructor designated with the annotation <literal>@Inject</literal>) is a candidate for becoming a bean. Any
- EJB session bean is also a candidate. They become beans, specifically CDI beans, if they reside in a Java EE
- module that contains a special marker file (META-INF/beans.xml) and if instances of those classes are managed
- by the Java EE container. Just know that, for simple JavaBean classes, there's no special metadata you need to
- add to make them beans. They just are.
+ With very few exceptions, almost every concrete Java class that has a constructor with no parameters (or a
+ constructor designated with the annotation <literal>@Inject</literal>) is a bean. This includes every
+ JavaBean and every EJB session bean. If you've already got some JavaBeans or session beans lying around,
+ they're already beans—you won't need any additional special metadata. There's just little one thing you
+ need to do before you can start injecting them into stuff: you need to put them in an archive (a jar, or a
+ Java EE module like a war or ejb-jar) that contains a special marker file: <literal>META-INF/beans.xml</literal>.
</para>
<para>
- The JavaBeans and EJBs you've been writing every day, up until now, have not been able to take advantage of the
- new services defined by the CDI specification. But you'll be able to use every one of them with CDI --
- allowing the container to create and destroy instances of your beans and associate them with a designed context
- (or scope), injecting them into other beans, using them in EL expressions, specializing them with qualifier
- annotations, even adding interceptors and decorators to them—from this point forward without modifying
- your code. At most, you'll have to add some annotations.
+ The JavaBeans and EJBs you've been writing every day, up until now, have not been able to take advantage
+ of the new services defined by the CDI specification. But you'll be able to use every one of them with
+ CDI—allowing the container to create and destroy instances of your beans and associate them with a
+ designed context, injecting them into other beans, using them in EL expressions, specializing them with
+ qualifier annotations, even adding interceptors and decorators to them—without modifying your
+ existing code. At most, you'll need to add some annotations.
</para>
<para>
@@ -117,16 +118,16 @@
<para>
As you've guessed, the <literal>@Inject</literal> annotation has something to do with dependency injection!
- <literal>@Inject</literal> may be applied to a constructor or method of a bean, and tells the container to call
- that constructor or method when instantiating the bean. The container will inject other beans it finds into the
- parameters of the constructor or method.
+ <literal>@Inject</literal> may be applied to a constructor or method of a bean, and tells the container to
+ call that constructor or method when instantiating the bean. The container will inject other beans it finds
+ into the parameters of the constructor or method.
</para>
<para>
We may obtain an instance of <literal>TextTranslator</literal> by injecting it into a constructor, bean
- "setter" method, producer method, observer method or field of a JavaBean or EJB session, or a field of a
- Servlet. The injection is based on the type of the injection point, not the name of the field, method or
- argument.
+ "setter" method, producer method, observer method or field of a JavaBean or EJB session bean, or a field
+ of a servlet. The injection is based on the type of the injection point, not the name of the field, method
+ or parameter.
</para>
<para>
@@ -209,7 +210,8 @@
<para>
Now we are starting to venture off into the details, so let's pause and examine a bean's anatomy. What aspects
- of the bean are significant, and what gives it its identity?
+ of the bean are significant, and what gives it its identity? Instead of giving examples of beans, we're going
+ to define what <emphasis>makes</emphasis> something a bean.
</para>
</section>
@@ -218,8 +220,8 @@
<title>The anatomy of a bean</title>
<para>
- A bean is an application class that contains business logic. It may be called directly from Java code, or it
- may be invoked via Unified EL. A bean may access transactional resources. Dependencies between beans are
+ A bean is usually an application class that contains business logic. It may be called directly from Java code,
+ or it may be invoked via Unified EL. A bean may access transactional resources. Dependencies between beans are
managed automatically by the container. Most beans are <emphasis>stateful</emphasis> and
<emphasis>contextual</emphasis>. The lifecycle of a bean is always managed by the container.
</para>
@@ -279,12 +281,12 @@
<para>
We can replace one bean with another different bean that implements the same interface and has a different lifecycle
(a different scope) without affecting the other bean implementation. In fact, CDI defines a simple facility for
- overriding bean implementations at deployment time, as we will see in <xref linkend="alternatives"/> (FIXREF).
+ overriding bean implementations at deployment time, as we will see in <xref linkend="alternatives"/>.
</para>
<para>
- Note that not all clients of a bean are beans themselves. Other objects such as Servlets or Message-Driven
- Beans—which are by nature not injectable, contextual objects—may also obtain references to beans by
+ Note that not all clients of a bean are beans themselves. Other objects such as servlets or message-driven
+ beans—which are by nature not injectable, contextual objects—may also obtain references to beans by
injection.
</para>
@@ -292,17 +294,18 @@
<blockquote>
- <para>A bean comprises of the following attributes:</para>
+ <para>A bean comprises the following attributes:</para>
<itemizedlist>
<listitem><para>A (nonempty) set of bean types</para></listitem>
<listitem><para>A (nonempty) set of qualifiers</para></listitem>
<listitem><para>A scope</para></listitem>
- <listitem><para>A deployment type</para></listitem>
<listitem><para>Optionally, a bean EL name</para></listitem>
<listitem><para>A set of interceptor bindings</para></listitem>
<listitem><para>A bean implementation</para></listitem>
</itemizedlist>
+
+ <para>Furthermore, a bean may or may not be an alternative.</para>
</blockquote>
@@ -334,10 +337,14 @@
<para>
The bean types are <literal>BookShop</literal>, <literal>Business</literal> and
<literal>Shop<Book></literal>, as well as the implicit type <literal>java.lang.Object</literal>.
- (Notice that a parameterized type is a legal bean type). Meanwhile, this session bean has only the local
- interfaces <literal>BookShop</literal>, <literal>Auditable</literal> and <literal>java.lang.Object</literal>
- as bean types, since the bean class, <literal>BookShopBean</literal> is not a client-visible type.
+ (Notice that a parameterized type is a legal bean type).
</para>
+
+ <para>
+ Meanwhile, this session bean has only the local interfaces <literal>BookShop</literal>,
+ <literal>Auditable</literal> and <literal>java.lang.Object</literal> as bean types, since the bean class,
+ <literal>BookShopBean</literal> is not a client-visible type.
+ </para>
<programlisting role="JAVA"><![CDATA[@Stateful
public class BookShopBean extends Business implements BookShop, Auditable {
@@ -354,7 +361,7 @@
<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 a single bean type, <literal>Shop</literal>:
+ restricted to a single bean type, <literal>Shop<Book></literal>:
</para>
<programlisting role="JAVA"><![CDATA[@Typed(Shop.class)
@@ -364,7 +371,7 @@
<para>
The bean types alone often do not provide enough information for the container to know which bean to inject.
- For instance, say you have two implementations of the <literal>PaymentProcessor</literal> interface:
+ 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 ambigious condition. In these cases, the
container must rely on some client-visible semantic that is satisified by one implementation of the bean
@@ -374,7 +381,7 @@
<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 many dependency injection frameworks use.
+ 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:
</para>
@@ -385,14 +392,15 @@
<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 often.
- Pay attention to the names of the built-in annotations in CDI and EJB.
+ have encountered one. With CDI, they will become very familiar artifact as you will be creating them from
+ time to time.
</para>
<tip>
<para>
- You'll notice that they are all adjectives. You are encouraged to follow this convention when creating
- your custom annotations, since they serve to describe the behaviors and roles of the class.
+ Pay attention to the names of the built-in annotations in CDI and EJB. You'll notice that they are
+ often adjectives. We encourage you to follow this convention when creating your custom annotations,
+ since they serve to describe the behaviors and roles of the class.
</para>
</tip>
@@ -411,12 +419,13 @@
</note>
<para>
- For each injection point, the container searches for a bean which satisfies the contract, meaning it matches
- the bean time and all the qualifiers. It then injects that instance.
+ 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.
</para>
<para>
- We've seen how to indicate that you want to inject qualified bean. But how do you actually qualify the bean?
+ 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:
@@ -434,9 +443,9 @@
</note>
<para>
- CDI defines a sophisticated, yet intuitive <emphasis>resolution algorithm</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="injection"/>.
+ 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"/>. TBD: write a section about "fixing ambiguous dependencies"!
</para>
</section>
@@ -446,9 +455,9 @@
<!-- I wonder whether the explaination of contextual above would fit better here -->
<para>
- The <emphasis>scope</emphasis> of a bean defines the lifecycle and visibility of instances created from it.
+ The <emphasis>scope</emphasis> of a bean defines the lifecycle and visibility of its instances.
The CDI context model is extensible, accommodating arbitrary scopes. However, certain important scopes are
- built-in to the specification, and provided by the container. Each scope is represented by an annotation
+ built into the specification, and provided by the container. Each scope is represented by an annotation
type.
</para>
@@ -484,13 +493,12 @@
<title>EL name</title>
<para>
- If you want to reference a bean outside of Java, such as in JavaServer Faces (JSF) view, you must assign the
- bean a <emphasis>name</emphasis>. The name is used as the EL name of the bean, allowing the bean to be used
- in a Unified EL expression.
+ If you want to reference a bean in non-Java code that supports Unified EL expressions, for example, in a
+ JSP or JSF page, you must assign the bean an <emphasis>EL name</emphasis>.
</para>
<para>
- The name is specified using the <literal>@Named</literal> annotation, as shown here:
+ The EL name is specified using the <literal>@Named</literal> annotation, as shown here:
</para>
<programlisting role="JAVA"><![CDATA[@SessionScoped @Named("cart")
@@ -531,31 +539,25 @@
<title>Alternatives</title>
<para>
- There are cases when you want to replace one bean implementation with another at deployment time. For
- instance, you may want to use a mock implementation in a testing environment. An
- <emphasis>alternative</emphasis> may be declared by annotating the bean class or producer method or field
- with the <literal>@Alternative</literal> annotation.
+ We've already seen how qualifiers let us choose between multiple implementations of an interface at
+ development time. But sometimes we have an interface whose implementation varies dependending upon
+ the deployment environment. For example, you may want to use a mock implementation in a testing
+ environment. An <emphasis>alternative</emphasis> may be declared by annotating the bean class or
+ producer method or field with the <literal>@Alternative</literal> annotation.
</para>
<programlisting role="JAVA"><![CDATA[@Alternative
public class MockPaymentProcessor extends PaymentProcessorImpl { ... }]]></programlisting>
<para>
- An alternative can also be declared by annotating a bean, producer method or producer fields with a
- stereotype that has the <literal>@Alternative</literal> annotation. Stereotypes are explained in <xref
- linkend="stereotypes"/>.
+ You can choose between alternatives at deployment time by selecting an alternative using the CDI
+ deployment descriptor <literal>META-INF/beans.xml</literal> of the jar or Java EE module that
+ uses it.
</para>
<para>
- You then enable the alternative using the CDI deployment descriptor, META-INF/beans.xml, in the classpath
- entry in which you intent to use it. An alternative must be explicitly selected in every bean deployment
- archive in which the alternative should be available for injection, lookup and EL resolution.
- </para>
-
- <para>
Details on how to enable alternative beans, and how you can use them to specialize (override) beans and
- producer methods is covered in <xref linkend="specialization"/>. CDI is very flexible when it comes
- alternatives that are selected at deployment time.
+ producer methods is covered in <xref linkend="3"/>.
</para>
</section>
@@ -564,8 +566,8 @@
<title>Interceptor binding types</title>
<para>
- Since the introduction of the Managed Bean specification in Java EE 6, interceptors are available on
- JavaBeans in additionn to EJB session beans. That's right, you no longer have to create an EJB just to
+ Since the introduction of the managed bean specification in Java EE 6, interceptors are available on
+ JavaBeans in addition to EJB session beans. That's right, you no longer have to create an EJB just to
intercept method calls. Holler. So what does CDI have to offer? Well, a lot actually. Let's cover some
background.
</para>
Modified: doc/trunk/reference/en-US/part1.xml
===================================================================
--- doc/trunk/reference/en-US/part1.xml 2009-11-03 10:24:58 UTC (rev 4591)
+++ doc/trunk/reference/en-US/part1.xml 2009-11-03 10:26:17 UTC (rev 4592)
@@ -12,16 +12,16 @@
<!-- NOTE synchronize this intro with the intro on http://seamframework.org/Weld -->
<para>
- The <ulink src="http://jcp.org/en/jsr/detail?id=299">JSR-299</ulink> specification (CDI) defines a set of services
- for the Java EE environment that make applications much easier to develop. CDI layers an enhanced lifecycle and
- interaction model over existing Java component types, including Managed Beans (JavaBeans) and Enterprise JavaBeans
- (EJB session beans). As a complement to the traditional Java EE programming model, the CDI services provide:
+ The <ulink src="http://jcp.org/en/jsr/detail?id=299">JSR-299</ulink> specification (CDI) defines a set of
+ complementary services that help improve the structure of application code. CDI layers an enhanced lifecycle
+ and interaction model over existing Java component types, including managed beans (JavaBeans) and Enterprise
+ Java Beans. The CDI services provide:
</para>
<itemizedlist>
<listitem>
<para>
- an improved lifecycle for stateful components, bound to well-defined <emphasis>contexts</emphasis>,
+ an improved lifecycle for stateful objects, bound to well-defined <emphasis>contexts</emphasis>,
</para>
</listitem>
<listitem>
@@ -31,48 +31,76 @@
</listitem>
<listitem>
<para>
- component interaction via an <emphasis>event notification facility</emphasis>,
+ object interaction via an <emphasis>event notification facility</emphasis>,
</para>
</listitem>
<listitem>
<para>
- a better approach to binding <emphasis>interceptors</emphasis> to components, along with a new kind of
- interceptor, called a <emphasis>decorator</emphasis>, that is more appropriate for use in solving business problems, and
+ a better approach to binding <emphasis>interceptors</emphasis> to objects, along with a new kind of
+ interceptor, called a <emphasis>decorator</emphasis>, that is more appropriate for use in solving
+ business problems, and
</para>
</listitem>
<listitem>
<para>
- an <emphasis>SPI</emphasis> for developing portable extensions for the Java EE platform.
+ an <emphasis>SPI</emphasis> for developing portable extensions to the container.
</para>
</listitem>
</itemizedlist>
<para>
- A component that receives CDI services is referred to, generally, as a bean. The CDI services are a core aspect of
- the Java EE platform and apply to the following types of components that exist in the platform:
+ The CDI services are a core aspect of the Java EE platform and include full support for Java EE modularity
+ and the Java EE component architecture. But the specification does not limit the use of CDI to the Java EE
+ environment. In the Java SE environment, the services might be provided by a standalone CDI implementation
+ like Weld (see <xref linkend="weld-se"/>), or even by a container that also implements the subset of EJB
+ defined for embedded usage by the EJB 3.1 specification. CDI is especially useful in the context of web
+ application development, but the problems it solves are general development concerns and it is therefore
+ applicable to a wide variety of application.
</para>
+ <para>
+ An object bound to a lifecycle context is called a bean. CDI includes built-in support for several different
+ kinds of bean, including the following Java EE component types:
+ </para>
+
<itemizedlist>
<listitem>
- <para>all Managed Beans (JavaBeans), including JavaServer Faces (JSF) managed beans,</para>
+ <para>managed beans</para>
</listitem>
<listitem>
- <para>all Enterprise JavaBeans (EJBs), and</para>
+ <para>EJB session beans, and</para>
</listitem>
<listitem>
- <para>all Servlets.</para>
+ <para>JAX-RS resources.</para>
</listitem>
</itemizedlist>
-
+
<para>
- CDI is especially useful in the context of web applications, but is applicable to a wide variety of applications.
- It may even be used in the Java SE context, in conjunction with an embeddable EJB Lite container, as defined in
- the EJB 3.1 specification, or through an extension (see <xref linkend="weld-se"/>).
+ Both managed beans and EJB session beans may inject other beans. But some other objects, which are not
+ themselves beans, can also make use of CDI by injecting beans. In the Java EE platform, the following
+ kinds of component may inject beans:
</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>message-driven beans,</para>
+ </listitem>
+ <listitem>
+ <para>interceptors,</para>
+ </listitem>
+ <listitem>
+ <para>servlets, servlet filters and servlet event listeners,</para>
+ </listitem>
+ <listitem>
+ <para>JAX-WS service endpoints and handlers, and</para>
+ </listitem>
+ <listitem>
+ <para>JSP tag handlers and tag library event listeners.</para>
+ </listitem>
+ </itemizedlist>
<para>
- The concerns handled by CDI save the user who is unfamiliar with an API from having to answer the following
- questions:
+ CDI relieves the user of an unfamiliar API of the need to answer the following questions:
</para>
<itemizedlist>
@@ -86,7 +114,7 @@
<para>Is it multithreaded?</para>
</listitem>
<listitem>
- <para>How do I retrieve it?</para>
+ <para>How do I get access to it from a client?</para>
</listitem>
<listitem>
<para>Do I need to explicitly destroy it?</para>
@@ -98,7 +126,8 @@
</listitem>
<listitem>
<para>
- How can I define alternatives, so that the implementation of this object can vary at deployment time?
+ How can I define alternative an implementation, so that the implementation can vary
+ at deployment time?
</para>
</listitem>
<listitem>
@@ -146,28 +175,26 @@
objects fit together. (XML is rarely used, reserved only to activate alternatives and define ordering at
deployment time). Instead, CDI uses the typing information that is already available in the Java object model,
then extends it with a new typing pattern, called <emphasis>qualifier annotations</emphasis>, to wire together
- beans, their dependencies, their interceptors and decorators and their event consumers.
+ beans, their dependencies, their interceptors and decorators, and their event consumers.
</para>
<para>
- CDI even provides the necessary integration points, through a comprehensive SPI, so that other kinds of components
- defined by future Java EE specifications or by non-standard frameworks may be cleanly integrated with CDI, take
- advantage of the CDI services, and interact with any other kind of platform component.
+ CDI even provides the necessary integration points, through a comprehensive SPI, so that other kinds of object
+ defined by future Java EE specifications or by third-party frameworks may be cleanly integrated with CDI, take
+ advantage of the CDI services, and interact with any other kind of bean.
</para>
<para>
- CDI was influenced by a number of existing Java frameworks, including Seam, Guice and Spring. However, CDI has its
- own, very distinct, character: more typesafe than Seam, more stateful and less XML-centric than Spring, more web and
- enterprise-application capable than Guice. But it couldn't have been any of these without inspiration from the
- frameworks mentioned and <emphasis>lots</emphasis> of collaboration and hard work by the JSR-299 Expert Group
+ CDI was influenced by a number of existing Java frameworks, including Seam, Guice and Spring. However, CDI has
+ its own, very distinct, character: more typesafe than Seam, more stateful and less XML-centric than Spring, more
+ web and enterprise-application capable than Guice. But it couldn't have been any of these without inspiration from
+ the frameworks mentioned and <emphasis>lots</emphasis> of collaboration and hard work by the JSR-299 Expert Group
(EG).
</para>
<para>
- Finally, JSR-299 is a <ulink src="http://jcp.org">Java Community Process</ulink> (JCP) standard that integrates
- cleanly with the Java EE platform, and with any Java SE environment where embeddable EJB Lite is available. In
- fact, Java EE 6 requires that all compliant application servers provide support for JSR-299 (even in the web
- profile).
+ Finally, CDI is a <ulink src="http://jcp.org">Java Community Process</ulink> (JCP) standard. Java EE 6 requires
+ that all compliant application servers provide support for JSR-299 (even in the web profile).
</para>
<!--
More information about the weld-commits
mailing list