[weld-commits] Weld SVN: r4352 - in doc/trunk/reference/en-US: images and 1 other directory.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Tue Oct 27 14:36:17 EDT 2009
Author: dan.j.allen
Date: 2009-10-27 14:36:17 -0400 (Tue, 27 Oct 2009)
New Revision: 4352
Added:
doc/trunk/reference/en-US/images/m2eclipse-wicket-numberguess-import.png
Modified:
doc/trunk/reference/en-US/Author_Group.xml
doc/trunk/reference/en-US/Book_Info.xml
doc/trunk/reference/en-US/environments.xml
doc/trunk/reference/en-US/example.xml
doc/trunk/reference/en-US/gettingstarted.xml
doc/trunk/reference/en-US/intro.xml
doc/trunk/reference/en-US/master.xml
doc/trunk/reference/en-US/part1.xml
Log:
first round of updates title, part1, example, intro and getting started, as well as some tweaks here and there
Modified: doc/trunk/reference/en-US/Author_Group.xml
===================================================================
--- doc/trunk/reference/en-US/Author_Group.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/Author_Group.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -6,7 +6,7 @@
<surname>King</surname>
<affiliation>
<jobtitle>JSR-299 specification lead</jobtitle>
- <orgname>Red Hat Inc.</orgname>
+ <orgname>Red Hat, Inc.</orgname>
</affiliation>
</author>
<author>
@@ -15,10 +15,18 @@
<affiliation>
<jobtitle>Web Beans (JSR-299 Reference Implementation) lead
</jobtitle>
- <orgname>Red Hat Inc.</orgname>
+ <orgname>Red Hat, Inc.</orgname>
</affiliation>
</author>
<author>
+ <firstname>Dan</firstname>
+ <surname>Allen</surname>
+ <affiliation>
+ <jobtitle>Senior Software Engineer</jobtitle>
+ <orgname>Red Hat, Inc.</orgname>
+ </affiliation>
+ </author>
+ <author>
<firstname>David</firstname>
<surname>Allen</surname>
</author>
@@ -32,7 +40,7 @@
<surname>Guerrero</surname>
<contrib>Spanish Translation</contrib>
<affiliation>
- <orgname>Red Hat Inc.</orgname>
+ <orgname>Red Hat, Inc.</orgname>
</affiliation>
</othercredit>
<othercredit>
@@ -40,7 +48,7 @@
<surname>Ki,</surname>
<contrib>Korean Translation</contrib>
<affiliation>
- <orgname>Red Hat Inc.</orgname>
+ <orgname>Red Hat, Inc.</orgname>
</affiliation>
</othercredit>
<othercredit>
@@ -48,7 +56,7 @@
<surname>Chuang</surname>
<contrib>Traditional Chinese Translation</contrib>
<affiliation>
- <orgname>Red Hat Inc.</orgname>
+ <orgname>Red Hat, Inc.</orgname>
</affiliation>
</othercredit>
<othercredit>
Modified: doc/trunk/reference/en-US/Book_Info.xml
===================================================================
--- doc/trunk/reference/en-US/Book_Info.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/Book_Info.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -1,8 +1,13 @@
-<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
-
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
<bookinfo>
- <title>Web Beans: Java Contexts and Dependency Injection</title>
- <subtitle>The new standard for dependency injection and contextual state management</subtitle>
+ <title>Weld - JSR-299 Reference Implementation</title>
+ <subtitle>
+ JSR-299: The new Java standard for dependency injection and contextual life cycle management
+ </subtitle>
- <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
</bookinfo>
Modified: doc/trunk/reference/en-US/environments.xml
===================================================================
--- doc/trunk/reference/en-US/environments.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/environments.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -272,7 +272,7 @@
</listitem>
</itemizedlist>
- <section>
+ <section id="weld-se">
<title>Web Beans SE Module</title>
<para>To make life easy for developers Web Beans provides a special module with a
Modified: doc/trunk/reference/en-US/example.xml
===================================================================
--- doc/trunk/reference/en-US/example.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/example.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -1,16 +1,15 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
-
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
<chapter id="example">
- <title>JSF web application example</title>
+ <title>JSF web application example</title>
- <para>Let's illustrate these ideas with a full example. We're going
- to implement user login/logout for an application that uses JSF. First,
- we'll define a Web Bean to hold the username and password entered during
- login:</para>
+ <para>
+ Let's illustrate these ideas with a full example. We're going to implement a user login/logout for an application
+ that uses JSF. First, we'll define a request-scoped bean to hold the username and password entered during login:
+ </para>
<programlisting role="JAVA"><![CDATA[@Named @RequestScoped
public class Credentials {
-
private String username;
private String password;
@@ -19,86 +18,110 @@
public String getPassword() { return password; }
public void setPassword(String password) { this.password = password; }
-
}]]></programlisting>
- <para>This Web Bean is bound to the login prompt in the following JSF form:</para>
+ <para>This bean is bound to the login prompt in the following JSF form:</para>
-<programlisting role="JAVA"><![CDATA[<h:form>
- <h:panelGrid columns="2" rendered="#{!login.loggedIn}">
- <h:outputLabel for="username">Username:</h:outputLabel>
- <h:inputText id="username" value="#{credentials.username}"/>
- <h:outputLabel for="password">Password:</h:outputLabel>
- <h:inputText id="password" value="#{credentials.password}"/>
- </h:panelGrid>
- <h:commandButton value="Login" action="#{login.login}" rendered="#{!login.loggedIn}"/>
- <h:commandButton value="Logout" acion="#{login.logout}" rendered="#{login.loggedIn}"/>
+ <programlisting role="JAVA"><![CDATA[<h:form>
+ <h:panelGrid columns="2" rendered="#{!login.loggedIn}">
+ <h:outputLabel for="username">Username:</h:outputLabel>
+ <h:inputText id="username" value="#{credentials.username}"/>
+ <h:outputLabel for="password">Password:</h:outputLabel>
+ <h:inputText id="password" value="#{credentials.password}"/>
+ </h:panelGrid>
+ <h:commandButton value="Login" action="#{login.login}" rendered="#{!login.loggedIn}"/>
+ <h:commandButton value="Logout" action="#{login.logout}" rendered="#{login.loggedIn}"/>
</h:form>]]></programlisting>
- <para>The actual work is done by a session scoped Web Bean that maintains
- information about the currently logged-in user and exposes the <literal>User</literal>
- entity to other Web Beans:</para>
+ <para>
+ The actual work is done by a session-scoped bean that maintains information about the currently logged-in user
+ and exposes the <literal>User</literal> entity to other beans:
+ </para>
-<programlisting role="JAVA"><![CDATA[@SessionScoped @Named
+ <programlisting role="JAVA"><![CDATA[@SessionScoped @Named
public class Login {
- @Current Credentials credentials;
- @PersistenceContext EntityManager userDatabase;
+ @Inject Credentials credentials;
+ @Inject @UserDatabase EntityManager userDatabase;
- private User user;
+ private User user;
- public void login() {
-
- List<User> results = userDatabase.createQuery(
- "select u from User u where u.username=:username and u.password=:password")
- .setParameter("username", credentials.getUsername())
- .setParameter("password", credentials.getPassword())
- .getResultList();
+ public void login() {
+ List<User> results = userDatabase.createQuery(
+ "select u from User u where u.username = :username and u.password = :password")
+ .setParameter("username", credentials.getUsername())
+ .setParameter("password", credentials.getPassword())
+ .getResultList();
- if ( !results.isEmpty() ) {
- user = results.get(0);
- }
-
- }
+ if (!results.isEmpty()) {
+ user = results.get(0);
+ }
+ else {
+ // perhaps add code here to report a failed login
+ }
+ }
- public void logout() {
- user = null;
- }
+ public void logout() {
+ user = null;
+ }
- public boolean isLoggedIn() {
- return user!=null;
- }
+ public boolean isLoggedIn() {
+ return user != null;
+ }
- @Produces @LoggedIn User getCurrentUser() {
- return user;
- }
+ @Produces @LoggedIn User getCurrentUser() {
+ return user;
+ }
}]]></programlisting>
- <para>Of course, <literal>@LoggedIn</literal> is a binding annotation:</para>
+ <para><literal>@LoggedIn</literal> and <literal>@UserDatabase</literal> are custom qualifier annotations:</para>
-<programlisting role="JAVA"><![CDATA[@Retention(RUNTIME)
- at Target({TYPE, METHOD, FIELD})
- at BindingType
+ <programlisting role="JAVA"><![CDATA[@Retention(RUNTIME)
+ at Target({TYPE, METHOD, PARAMETER, FIELD})
+ at Documented
+ at Qualifier
public @interface LoggedIn {}]]></programlisting>
- <para>Now, any other Web Bean can easily inject the current user:</para>
+ <programlisting role="JAVA"><![CDATA[@Retention(RUNTIME)
+ at Target({METHOD, PARAMETER, FIELD})
+ at Documented
+ at Qualifier
+public @interface UserDatabase {}]]></programlisting>
-<programlisting role="JAVA"><![CDATA[public class DocumentEditor {
+ <para>
+ We need an adapter bean to expose our typesafe <literal>EntityManager</literal>:
+ </para>
- @Current Document document;
- @LoggedIn User currentUser;
- @PersistenceContext EntityManager docDatabase;
+ <programlisting role="JAVA"><![CDATA[public class UserDatabaseProducer {
+ @Produces @UserDatabase @PersistenceContext EntityManager userDatabase;
+}]]></programlisting>
+
+ <para>Now, any other bean can easily inject the current user, as well as other beans:</para>
+
+ <programlisting role="JAVA"><![CDATA[public class DocumentEditor {
+ @Inject Document document;
+ @Inject @LoggedIn User currentUser;
+ @Inject @DocumentDatabase EntityManager docDatabase;
- public void save() {
- document.setCreatedBy(currentUser);
- docDatabase.persist(document);
- }
-
+ public void save() {
+ document.setCreatedBy(currentUser);
+ docDatabase.persist(document);
+ }
}]]></programlisting>
- <para>Hopefully, this example gives a flavor of the Web Bean programming model.
- In the next chapter, we'll explore Web Beans dependency injection in greater
- depth.</para>
+ <para>Or we can reference the current user in a JSF view:</para>
-</chapter>
\ No newline at end of file
+ <programlisting role="XML"><![CDATA[<h:panelGroup rendered="#{login.loggedIn}">
+ signed in as #{currentUser.username}
+</h:panelGroup>]]></programlisting>
+
+ <para>
+ Hopefully, this example gives a flavor of the CDI services. In the next chapter, we'll explore examples from the
+ CDI reference implementation, Weld, in greater depth.
+ </para>
+
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
+</chapter>
Modified: doc/trunk/reference/en-US/gettingstarted.xml
===================================================================
--- doc/trunk/reference/en-US/gettingstarted.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/gettingstarted.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -1,293 +1,617 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<chapter id="gettingstarted">
+<!-- TODO
+Explain use of war:inplace to use jetty
+Java SE numberguess example
+-->
-<chapter id="ri">
- <title>Getting started with Web Beans, the Reference Implementation of JSR-299</title>
+ <title>Getting started Weld, the JSR-299 reference implementation</title>
<para>
- The Web Beans is being developed at
- <ulink url="http://seamframework.org/WebBeans">the Seam project</ulink>.
- You can download the latest developer release of Web Beans from the
- <ulink url="http://seamframework.org/Download">the downloads page</ulink>.
- </para>
+ Weld, the JSR-299 RI (Reference Implementation), is being developed as part of the <ulink
+ url="http://seamframework.org/Weld">Seam project</ulink>. You can download the latest community release of Weld
+ from the <ulink url="http://seamframework.org/Download">download page</ulink>. Information about the Weld source
+ code repository and instructions about how to obtain and build the source can be found on the same page.
+ </para>
- <para>
- Web Beans comes with a two deployable example applications:
- <literal>webbeans-numberguess</literal>, a war example which runs on
- JBoss AS, Tomcat, Jetty and Google App Engine, containing only
- simple beans, and <literal>webbeans-translator</literal> an ear example,
- containing enterprise beans.
- To run the examples you'll need the following:
+ <para>
+ Weld comes with two starter example applications, in addition to more specialized examples. The first,
+ <literal>weld-numberguess</literal>, is a web (WAR) example containing only non-transactional managed beans.
+ This example can be run on a wide range of servers, including JBoss AS, GlassFish, Apache Tomcat, Jetty, Google
+ App Engine, and any compliant Java EE 6 container. The second example, <literal>weld-translator</literal>, is
+ an enterprise (EAR) example that contains session beans. This example must be run on JBoss AS 5.2 or any compliant
+ Java EE 6 container.
</para>
- <itemizedlist>
- <listitem>
- <para>the latest release of Web Beans,</para>
- </listitem>
- <listitem>
- <para>JBoss AS 5.2.0, or</para>
- </listitem>
- <listitem>
- <para>Jetty 6.1.x, or</para>
- </listitem>
- <listitem>
- <para>Apache Tomcat 6.0.x, and</para>
- </listitem>
- <listitem>
- <para>Ant 1.7.0.</para>
- </listitem>
- </itemizedlist>
+ <para>
+ Both examples use JSF 2.0 as the web framework and, as such, can be found in the examples/jsf directory of the
+ Weld distribution.
+ </para>
+
+ <section id="prerequisites">
+ <title>Prerequisites</title>
+
+ <para>
+ To run the examples with the provided build scripts, you'll need the following:
+ </para>
- <section>
- <title>Using JBoss AS 5</title>
+ <itemizedlist>
+ <listitem>
+ <para>the latest release of Weld, which contains the examples</para>
+ </listitem>
+ <listitem>
+ <para>Ant 1.7.0, to build and deploy the examples</para>
+ </listitem>
+ <listitem>
+ <para>a supported runtime environment (minimum versions shown)</para>
+ <itemizedlist>
+ <listitem>
+ <para>JBoss AS 5.2.0 (currenly only nightly builds of JBoss AS 5.2.0.Beta1 are available), or</para>
+ </listitem>
+ <listitem>
+ <para>GlassFish 3.0, or</para>
+ </listitem>
+ <listitem>
+ <para>Apache Tomcat 6.0.x (WAR example only), or</para>
+ </listitem>
+ <listitem>
+ <para>Jetty 6.1.x (WAR example only)</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>(optionally) Maven 2.x, to run the examples in an embedded servlet container</para>
+ </listitem>
+ </itemizedlist>
- <para>
- You'll need to download JBoss AS 5.2.0 from
- <ulink url="http://www.jboss.org/jbossas/downloads/">jboss.org</ulink>,
- and unzip it. For example:
+ <note>
+ <para>
+ You'll need a full install of Ant 1.7.0. Some linux distributions only supply a partial installation of Ant
+ which cause the build to fail. If you encounter problems, verify that ant-nodeps.jar is on the classpath.
+ </para>
+ </note>
+
+ <para>
+ In the next few sections, you'll be using the Ant command (ant) to invoke the Ant build script in each of the two
+ examples to compile, assemble and deploy the example to JBoss AS and, for the WAR example, Apache Tomcat. You can
+ also deploy the generated artifact (WAR or EAR) to any other container that supports Java EE 6, such as GlassFish V3.
</para>
+
+ <para>
+ If you have Maven installed, you can also use the Maven command (mvn) to compile and assemble the standalone
+ artifact (WAR or EAR) and, for the WAR example, run it in an embedded container.
+ </para>
- <programlisting><![CDATA[$ cd /Applications
-$ unzip ~/jboss-5.2.0.Beta.zip]]></programlisting>
+ <para>The sections below cover the steps for deploying with both Ant and Maven in detail. Let's start with JBoss AS.</para>
+ </section>
+
+ <section id="jbossas">
+ <title>Deploying to JBoss AS</title>
+
+ <para>
+ To deploy the examples to JBoss AS, you'll need <ulink src="http://jboss.org/jbossas/">JBoss AS
+ 5.2.0.Beta1</ulink> or above. If a release of the JBoss AS 5.2 line isn't yet available, you can download a
+ <ulink src="http://hudson.jboss.org/hudson/view/JBoss%20AS/job/JBoss-AS-5.x-sun16/">nightly snapshot</ulink>.
+ The reason JBoss AS 5.2.0.Beta1 or above is required is because it's the first release that has both CDI and
+ Bean Validation support built-in, making it close enough to Java EE 6 to run the examples. The good news is
+ that there are no additional modifications you have to make to the server. It's ready to go!
+ </para>
+
+ <para>
+ After you have downloaded JBoss AS, extract it. (We recommended renaming the folder to include the
+ <literal>as</literal> qualifier so it's clear that it's the application server). You can move the extracted
+ folder anywhere you like. Whereever it lays to rest, that's what we'll call the JBoss AS installation
+ directory, or <literal>JBOSS_HOME</literal>.
+ </para>
+
+ <programlisting><![CDATA[$> unzip jboss-5.2.*.zip
+$> mv jboss-5.2.*/ jboss-as-5.2]]></programlisting>
+
+ <para>
+ In order for the build scripts to know where to deploy the example, you have to tell them where to find your
+ JBoss AS installation (i.e., <literal>JBOSS_HOME</literal>). Create a new file named local.build.properties in
+ the examples directory of the Weld distribution and assign the path of your JBoss AS installation to the property
+ key <literal>jboss.home</literal>, as follows:
+ </para>
+
+ <programlisting><![CDATA[jboss.home=/path/to/jboss-as-5.2]]></programlisting>
+
+ <para>
+ You're now ready to deploy your first example!
+ </para>
+
+ <para>
+ Switch to the examples/jsf/numberguess directory and execute the Ant deploy target:
+ </para>
+
+ <programlisting><![CDATA[$> cd examples/jsf/numberguess
+$> ant deploy]]></programlisting>
+
+ <para>
+ If you haven't already, start JBoss AS. You can either start JBoss AS from a Linux shell:
+ </para>
+
+ <programlisting><![CDATA[$> cd /path/to/jboss-as-5.2
+$> ./bin/run.sh]]></programlisting>
+
+ <para>
+ a Windows command window:
+ </para>
+
+ <programlisting><![CDATA[$> cd c:\path\to\jboss-as-5.2\bin
+$> run]]></programlisting>
+
+ <para>
+ or you can start the server using an IDE, like Eclipse.
+ </para>
+
<note>
<para>
- JBoss AS 5.2.0 comes with Web Beans built in.
+ If you are using Eclipse, you should seriously consider installing the <ulink
+ src="http://www.jboss.org/tools">JBoss Tools</ulink> add-ons, which include a wide variety of tooling for
+ JSR-299 and Java EE development, as well as an enhanced JBoss AS server view.
</para>
</note>
-
+
<para>
- Now, you're ready to deploy your first example!
+ Wait a few seconds for the application to deploy (or the application server to start) and see if you can
+ determine the most efficient approach to pinpoint the random number at the local URL <ulink
+ src="http://localhost:8080/weld-numberguess">http://localhost:8080/weld-numberguess</ulink>.
</para>
-
+
<tip>
<para>
- The build scripts for the examples offer a number of targets for
- JBoss AS, these are:
+ The Ant build script includes additional targets for JBoss AS to deploy and undeploy the archive in either exploded or packaged format and to tidy things up.
</para>
<itemizedlist>
<listitem>
<para>
- <literal>ant restart</literal> - deploy the example in exploded
- format
+ <literal>ant restart</literal> - deploy the example in exploded format to JBoss AS
</para>
</listitem>
<listitem>
<para>
- <literal>ant explode</literal> - update an exploded example, without
- restarting the deployment
+ <literal>ant explode</literal> - update an exploded example, without restarting the deployment
</para>
</listitem>
<listitem>
<para>
- <literal>ant deploy</literal> - deploy the example in compressed jar format
+ <literal>ant deploy</literal> - deploy the example in compressed jar format to JBoss AS
</para>
</listitem>
<listitem>
<para>
- <literal>ant undeploy</literal> - remove the example from the server
+ <literal>ant undeploy</literal> - remove the example from JBoss AS
</para>
</listitem>
<listitem>
<para>
<literal>ant clean</literal> - clean the example
- </para>
+ </para>
</listitem>
</itemizedlist>
</tip>
-
+
<para>
- To deploy the numberguess example:
+ The second starter example, <literal>weld-translator</literal>, will translate your text into Latin. (Well,
+ not really, but the stub is there for you to implement, at least. Good luck!) To try it out, switch to the
+ translator example directory and execute the deploy target:
</para>
- <programlisting>$ cd examples/jsf/numberguess
-ant deploy</programlisting>
+ <programlisting><![CDATA[$> cd examples/jsf/translator
+$> ant deploy]]></programlisting>
+ <note>
+ <para>
+ The translator uses session beans, which are packaged in an EJB module within an EAR. Java EE 6 will allow
+ session beans to be deployed in WAR modules, but that's a topic for future chapter.
+ </para>
+ </note>
+
<para>
- Start JBoss AS:
+ Again, wait a few seconds for the application to deploy (if you are bored, read the log messages), and visit
+ <ulink src="http://localhost:8080/weld-translator">http://localhost:8080/weld-translator</ulink> to begin
+ pseudo-translating.
</para>
-
- <programlisting>$ /Application/jboss-5.2.0.Beta/bin/run.sh</programlisting>
-
- <tip>
- <para>
- If you use Windows, use the <literal>run.bat</literal>script.
- </para>
- </tip>
+
+ <para>
+ TODO Insert note about upgrading the Weld deployer that directs reader to section on the JBoss AS environment
+ </para>
+ </section>
+
+ <section id="glassfish">
+ <title>Deploying to GlassFish</title>
+
<para>
- Wait for the application to deploy, and enjoy hours of fun at
- <ulink url="http://localhost:8080/webbeans-numberguess" />!
+ Deploying to GlassFish should be easy, right? After all, it's the Java EE 6 reference implementation. Since
+ it's the Java EE 6 reference implementation, that means it also bundles the JSR-299 reference implementation,
+ Weld! So yes, it's very easy.
</para>
-
+
<para>
- Web Beans includes a second simple example that will translate your text
- into Latin. The numberguess example is a war example, and uses only simple
- beans; the translator example is an ear example, and includes enterprise
- beans, packaged in an EJB module. To try it out:
+ To deploy the examples to GlassFish, you'll need the final <ulink
+ src="https://glassfish.dev.java.net/">GlassFish V3</ulink> release (the preview release won't do). If the final
+ release isn't yet available, you can download a <ulink
+ src="http://download.java.net/glassfish/v3/promoted/">promoted build</ulink> in the meantime. Select the b69
+ preview release or above that ends in either -unix.sh or -windows.exe depending on your platform. After the
+ download is complete, execute the installer. On Linux/Unix, you'll need to first make the script executable.
</para>
+
+ <programlisting><![CDATA[$> chmod 755 glassfish-v3-b69-unix.sh
+$> ./glassfish-v3-b69-unix.sh]]></programlisting>
+
+ <para>
+ On Windows you can just click on the executable. Follow the instructions in the installer. It will create a
+ single domain named <literal>domain1</literal>. You'll use that domain to deploy the example. We recommend that
+ you choose 7070 as the main HTTP port to avoid conflicts with a running instance of JBoss AS (or Apache
+ Tomcat).
+ </para>
- <programlisting>$ cd examples/translator
-ant deploy</programlisting>
-
<para>
- Wait for the application to deploy, and visit
- <ulink url="http://localhost:8080/webbeans-translator" />!
+ If you've deployed either of the starter examples, <literal>weld-numberguess</literal> or
+ <literal>weld-translator</literal>, to JBoss AS, then you already have the deployable artifact you need.
+ If not, switch to either of the two directories and build it.
</para>
-
+
+ <programlisting><![CDATA[$> cd examples/jsf/numberguess (or examples/jsf/translator)
+$> ant package]]></programlisting>
+
+ <para>
+ The deployable archive for the <literal>weld-numberguess</literal>, named weld-numberguess.war, ends up in the
+ example's target directory. The archive for the <literal>weld-translator</literal> example, named
+ weld-translator.ear, ends up in the example's ear/target directory. All you need to do now is deploy them to
+ GlassFish.
+ </para>
+
+ <para>
+ You deploy applications to GlassFish using the <ulink src="http://localhost:4848">GlassFish Admin
+ Console</ulink>. To get the Admin Console running, you need to start a GlassFish domain, in our case
+ <literal>domain1</literal>. Switch to the bin folder in the directory where you installed GlassFish and execute
+ the following command:
+ </para>
+
+ <programlisting><![CDATA[$> asadmin start-domain domain1]]></programlisting>
+
+ <para>
+ After a few seconds you can visit the Admin Console in the browser at the URL <ulink
+ src="http://localhost:4848">http://localhost:4848</ulink>. In the tree on the left-hand
+ side of the page, click on "Applications", then click on the "Deploy..." button under
+ the heading "Applications" and select the deployable artifact for either of the two examples.
+ The deployer should recognize that you have selected a Java EE artifact and allow you to
+ start it. You can see the examples running at either <ulink
+ src="http://localhost:7070/weld-numberguess">http://localhost:7070/weld-numberguess</ulink> or <ulink
+ src="http://localhost:7070/weld-translator">http://localhost:7070/weld-translator</ulink>,
+ depending on which example you deployed.
+ </para>
+
+ <para>
+ The reason the same artifact can be deployed to both JBoss AS and GlassFish, without any modifications, is
+ because all of the features being used are part of the standard platform. And what a capable platform it has
+ become!
+ </para>
+
</section>
- <section>
- <title>Using Apache Tomcat 6.0</title>
-
- <para>
- You'll need to download Tomcat 6.0.18 or later from
- <ulink url="http://tomcat.apache.org/download-60.cgi">tomcat.apache.org</ulink>,
- and unzip it. For example:
+ <section id="tomcat">
+ <title>Deploying to Apache Tomcat</title>
+
+ <para>
+ Technically, CDI doesn't support servlet containers. That's because the contexts and dependency injection
+ services are provided by the Java EE container, not the Servlet API. However, CDI implementations can choose to
+ support servlet containers through an extension. Weld does this.</para>
+
+ <para>
+ Weld ships with a Servlet listener which bootstraps the CDI environment, registers the BeanManager in JNDI and
+ provides injection into servlets. Basically, it emulates the work done by the Java EE container. The only
+ limitation is that you cannot use enterprise features such as session beans and container-managed transactions.
</para>
-
- <programlisting><![CDATA[$ cd /Applications
-$ unzip ~/apache-tomcat-6.0.18.zip]]></programlisting>
<para>
- Next, download Web Beans from
- <ulink url="http://seamframework.org/Download">seamframework.org</ulink>,
- and unzip it. For example
+ Let's give the Weld servlet extension a spin on Apache Tomcat. First, you'll need to download Tomcat 6.0.18 or later
+ from <ulink src="http://tomcat.apache.org/download-60.cgi">tomcat.apache.org</ulink> and extract it.
</para>
+
+ <programlisting><![CDATA[$> unzip apache-tomcat-6.0.18.zip]]></programlisting>
+
+ <para>
+ You have two choices for how you can deploy the application to Tomcat. You can deploy it by pushing the
+ artifact to the hot deploy directory using Ant or you can deploy to the server across HTTP using a Maven
+ plugin. The Ant approach doesn't require that you have Maven installed, so we'll start there. If you want to
+ use Maven, you can just skip ahead.
+ </para>
+
+ <section id="tomcat-ant">
+ <title>Deploying with Ant</title>
+
+ <para>
+ In order for Ant to push the artifact to the Tomcat hot deploy directory, it needs to know where the Tomcat
+ installation is located. Again, we need to setup a propery in the local.build.properties file in the
+ examples directory of the Weld distribution. If you haven't yet created this file, do so now. Then assign
+ the path of your Tomcat installation to the property key tomcat.home.
+ </para>
+
+ <programlisting><![CDATA[tomcat.home=/path/to/apache-tomcat-6]]></programlisting>
+
+ <para>
+ Now you're ready to deploy the numberguess example to Tomcat!
+ </para>
+
+ <para>
+ Change to the examples/jsf/numberguess directory again and run the Ant deploy target for Tomcat:
+ </para>
+
+ <programlisting><![CDATA[$> cd examples/jsf/numberguess
+$> ant tomcat.deploy]]></programlisting>
+
+ <tip>
+ <para>
+ The Ant build script includes additional targets for Tomcat to deploy and undeploy the archive in either
+ exploded or packaged format. They are the same target names used for JBoss AS, prefixed with "tomcat.".
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>ant tomcat.restart</literal> - deploy the example in exploded format to Tomcat
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ant tomcat.explode</literal> - update an exploded example, without restarting the deployment
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ant tomcat.deploy</literal> - deploy the example in compressed jar format to Tomcat
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ant tomcat.undeploy</literal> - remove the example from Tomcat
+ </para>
+ </listitem>
+ </itemizedlist>
+ </tip>
+
+ <para>
+ If you haven't already, start Tomcat. You can either start Tomcat from a Linux shell:
+ </para>
+
+ <programlisting><![CDATA[$> cd /path/to/apache-tomcat-6
+$> ./bin/start.sh]]></programlisting>
+
+ <para>
+ a Windows command window:
+ </para>
+
+ <programlisting><![CDATA[$> cd c:\path\to\apache-tomcat-6\bin
+$> start]]></programlisting>
+
+ <para>
+ or you can start the server using an IDE, like Eclipse.
+ </para>
+
+ <para>
+ Wait a few seconds for the application to deploy (or the application server to start) and see if you can figure
+ out the most efficient approach to pinpoint the random number at the local URL
+ <ulink src="http://localhost:8080/weld-numberguess">http://localhost:8080/weld-numberguess</ulink>!
+ </para>
+
+ </section>
- <programlisting><![CDATA[$ cd ~/
-$ unzip ~/webbeans-$VERSION.zip]]></programlisting>
-
- <programlisting>tomcat.home=/Applications/apache-tomcat-6.0.18</programlisting>
+ <section id="tomcat-maven">
+ <title>Deploying with Maven</title>
- <tip>
<para>
- The build scripts for the examples offer a number of targets for
- Tomcat, these are:
+ You can also deploy the application to Tomcat using Maven. This section is a bit more advanced, so skip it
+ unless you are itching to use Maven natively. Of course, you'll first need to make sure that you have Maven
+ installed on your path, similar to how you setup Ant.
</para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>mvn war:inplace tomcat:run -Ptomcat</literal> - deploy the example in an embedded Tomcat
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>mvn compile war:exploded tomcat:exploded -Ptomcat</literal> - deploy the example to a running Tomcat install
- </para>
- </listitem>
- </itemizedlist>
+
<para>
- See the <code>jsf/numberguess/readme.txt</code> for more details.
+ The Maven plugin communicates with Tomcat over HTTP, so it doesn't care where you have installed Tomcat.
+ However, the plugin configuration assumes you are running Tomcat in its default configuration, with a hostname
+ of localhost and port 8080. The readme.txt file in the example directory has information about how to modify
+ the Maven settings to accomodate a different setup.
</para>
- </tip>
-
+
+ <para>
+ To allow Maven to communicate with Tomcat over HTTP, edit the conf/tomcat-users.xml file in your Tomcat
+ installation and add the following line:
+ </para>
+
+ <programlisting role="XML"><![CDATA[<user username="admin" password="" roles="manager"/>]]></programlisting>
+
+ <para>
+ Restart Tomcat. You can now deploy the application to Tomcat with Maven using this command:
+ </para>
+
+ <programlisting><![CDATA[$> mvn compile war:exploded tomcat:exploded -Ptomcat]]></programlisting>
+
+ <para>
+ Once the application is deployed, you can redeploy it using this command:
+ </para>
+
+ <programlisting><![CDATA[$> mvn tomcat:redeploy -Ptomcat]]></programlisting>
+
+ <para>
+ The <literal>-Ptomcat</literal> argument activates the tomcat profile defined in the Maven POM (pom.xml).
+ Among other things, this profile activates the Tomcat plugin.
+ </para>
+
+ <para>
+ Rather than shipping the container off to a standalone Tomcat installation, you can also execute the
+ application in an embedded Tomcat 6 container:
+ </para>
+
+ <programlisting><![CDATA[$> mvn war:inplace tomcat:run -Ptomcat]]></programlisting>
+
+ <para>
+ The advantage of using the embedded server is that changes to assets in src/main/webapp take affect
+ immediately. If a change to a webapp configuration file is made, the application may automatically redeploy
+ (depending on the plugin configuration). If you make a change to a classpath resource, you need to execute a
+ build:
+ </para>
+
+ <programlisting><![CDATA[$> mvn compile war:inplace -Ptomcat]]></programlisting>
+
+ <para>
+ There are several other Maven goals that you can use if you are hacking on the example, which are documented in
+ the example's readme.txt file.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="jetty">
+ <title>Deploying to Jetty</title>
+
+ <!-- subsections? -->
+
<para>
- To deploy the numberguess example for tomcat:
+ Support for Jetty in the examples is a more recent addition. Since Jetty is traditionally used with Maven,
+ there are no Ant targets. You must invoke the Maven build directly to deploy the examples to Jetty out of the
+ box. Also, only the <literal>weld-numberguess</literal> example is configured for Jetty support at the time of
+ this writing.
</para>
-
- <programlisting>$ cd examples/jsf/numberguess
-ant tomcat.deploy</programlisting>
<para>
- Edit <code>$TOMCAT_HOME/conf/tomcat-users.xml</code> and add
+ If you've read through the entire Tomcat section, then you're all ready to go. The Maven build parallels the
+ embedded Tomcat deployment. If not, don't worry. We'll still go over everything in this section that you need
+ to know.
</para>
-
- <programlisting><![CDATA[<user username="admin" password="" roles="manager"/>]]></programlisting>
-
- <para>This allows Maven to communicate with Tomcat.</para>
-
+
<para>
- Start Tomcat:
+ The Maven POM (pom.xml) includes a profile named jetty that activates the Maven Jetty plugin, which you can use
+ to start Jetty in embedded mode and deploy the application in place. You don't need anything else installed
+ except to have the Maven command (mvn) on your path. The rest will be downloaded from the internet when the
+ build is run.
</para>
-
- <programlisting>$ /Applications/apache-tomcat-6.0.18/bin/startup.sh</programlisting>
-
- <tip>
- <para>
- If you use Windows, use the <literal>startup.bat</literal>script.
- </para>
- </tip>
-
- <para>Deploy the application</para>
-
- <programlisting>$ mvn compile war:exploded tomcat:exploded -Ptomcat</programlisting>
-
+
<para>
- Wait for the application to deploy, and enjoy hours of fun at
- <ulink url="http://localhost:8080/webbeans-numberguess" />!
+ To run the <literal>weld-numberguess</literal> example on Jetty, switch to the example directory and execute
+ the inplace goal of the Maven WAR plugin followed by the run goal of the Maven Jetty plugin with the jetty
+ profile enabled, as follows:
</para>
+ <programlisting><![CDATA[$> cd examples/jsf/numberguess
+$> mvn war:inplace jetty:run -Pjetty]]></programlisting>
+
+ <para>
+ The log output of Jetty will be shown in the console. Once Jetty reports that the application has deployed, you
+ can access it at the following local URL: <ulink
+ src="http://localhost:9090/weld-numberguess">http://localhost:9090/weld-numberguess</ulink>. The port is
+ defined in the Maven Jetty plugin configuration within the jetty profile.
+ </para>
+
+ <para>
+ Any changes to assets in src/main/webapp take affect immediately. If a change to a webapp configuration file is
+ made, the application may automatically redeploy. The redeploy behavior can be fined tuned in the plugin
+ configuration. If you make a change to a classpath resource, you need to execute a build and the inplace goal
+ of the Maven WAR plugin, again with the jetty profile enabled.
+ </para>
+
+ <programlisting><![CDATA[$> mvn compile war:inplace -Pjetty]]></programlisting>
+
+ <para>
+ The war:inplace goal copies the compiled classes and JARs inside src/main/webapp, under WEB-INF/classes and
+ WEB-INF/lib, respectively, mixing source and compiled files. However, the build does work around these
+ temporary files by excluding them from the packaged WAR and cleaning them during the Maven clean phase.
+ </para>
+
+ <para>
+ You have two options if you want to run the example on Jetty from the IDE. You can either install the
+ m2eclispe[link] plugin and run the goals as described above. Your other option is to start the Jetty container
+ from a Java application.
+ </para>
+
+ <para>
+ First, initialize the Eclipse project:
+ </para>
+
+ <programlisting><![CDATA[$> mvn clean eclipse:clean eclipse:eclipse -Pjetty-ide]]></programlisting>
+
+ <para>
+ Next, assemble all the necessary resources under src/main/webapp:
+ </para>
+
+ <programlisting><![CDATA[$> mvn war:inplace -Pjetty-ide]]></programlisting>
+
+ <para>
+ Now, you are ready to run the server in Eclipse. Import the project into your Eclipse workspace using "Import
+ Existing Project into Workspace. Then, find the start class in src/jetty/java and run its main method as a Java
+ Application. Jetty will launch. You can view the application at the following local URL: <ulink
+ src="http://localhost:8080">http://localhost:8080</ulink>. Pay particular attention to the port in the URL and
+ the lack of a trailing context path.
+ </para>
+
+ <!-- NOTE Transition paragraph into the example explanation sections. -->
+ <para>
+ Now that you have gotten the starter applications deployed on the server of your choice, you probably want to
+ know a little bit about how they actually work. It's time to pull the covers back and dive into the internals
+ of these two examples. Let's start with the simpler of the two examples, <literal>weld-numberguess</literal>.
+ </para>
+
</section>
- <section>
- <title>Using GlassFish</title>
+ <section id="numberguess">
+ <title>The numberguess example in depth</title>
- <para>TODO</para>
- </section>
-
- <section>
- <title>The numberguess example</title>
-
<para>
- In the numberguess application you get given 10 attempts to guess a
- number between 1 and 100. After each attempt, you will be told whether
- you are too high, or too low.
+ In the numberguess application you get given 10 attempts to guess a number between 1 and 100. After each
+ attempt, you will be told whether you are too high or too low.
</para>
<para>
- The numberguess example is comprised of a number of Web Beans,
- configuration files, and Facelet JSF pages, packaged as a war. Let's
- start with the configuration files.
+ The numberguess example is comprised of a number of beans, configuration files and Facelets (JSF) views,
+ packaged as a WAR module. Let's start by examining the configuration files.
</para>
<para>
- All the configuration files for this example are located in
- <literal>WEB-INF/</literal>, which is stored in
- <literal>WebContent</literal> in the source tree. First, we have
- <literal>faces-config.xml</literal>, in which we tell JSF to use
- Facelets:
+ All the configuration files for this example are located in <literal>WEB-INF/</literal>, which can be found in
+ the <literal>src/main/webapp</literal> directory of the example. First, we have the JSF 2.0 version of
+ <literal>faces-config.xml</literal>. A standardized version of Facelets is the default view handler in JSF
+ 2.0, so there's really nothing that we have to configure. Thus, the configuration consists of only the root
+ element.
</para>
- <programlisting role="XML"><![CDATA[<?xml version='1.0' encoding='UTF-8'?>
-<faces-config version="1.2"
- xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd">
-
- <application>
- <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
- </application>
-
+ <programlisting role="XML"><![CDATA[<faces-config version="2.0"
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd">
</faces-config>]]></programlisting>
<para>
- There is an empty <literal>web-beans.xml</literal> file, which marks
- this application as a Web Beans application.
+ There's also an empty <literal>beans.xml</literal> file, which tells the container to look for beans in this
+ application and to activate the CDI services.
</para>
<para>
- Finally there is <literal>web.xml</literal>:
+ Finally, there's the familiar <literal>web.xml</literal>:
</para>
<programlistingco>
<areaspec>
- <area id="faces.servlet" coords="12" />
- <area id="faces.servlet.mapping" coords="18" />
- <area id="faces.default.suffix" coords="23" />
- <area id="session.timeout" coords="28" />
- <area id="webbeans.listener" coords="32" />
+ <area id="faces.servlet" coords="10" />
+ <area id="faces.servlet.mapping" coords="16" />
+ <area id="faces.default.suffix" coords="21" />
+ <area id="session.timeout" coords="26" />
</areaspec>
- <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-
-<web-app version="2.5"
- xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
+ <programlisting role="XML"><![CDATA[<web-app version="2.5"
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
- <display-name>Web Beans Numbergues example</display-name>
+ <display-name>weld-jsf-numberguess-war</display-name>
+ <description>Weld JSF numberguess example (WAR)</description>
- <!-- JSF -->
-
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
@@ -312,18 +636,18 @@
<calloutlist>
<callout arearefs="faces.servlet">
<para>
- Enable and load the JSF servlet
+ Enable and initialize the JSF servlet
</para>
</callout>
<callout arearefs="faces.servlet.mapping">
<para>
- Configure requests to <literal>.jsf</literal> pages to be
+ Configure requests for URLs ending in <literal>.jsf</literal> to be
handled by JSF
</para>
</callout>
<callout arearefs="faces.default.suffix">
<para>
- Tell JSF that we will be giving our source files (facelets) an
+ Tell JSF that we will be giving our JSF views (Facelets templates) an
extension of <literal>.xhtml</literal>
</para>
</callout>
@@ -337,76 +661,71 @@
<note>
<para>
- Whilst this demo is a JSF demo, you can use Web Beans with any
- Servlet based web framework.
+ This demo uses JSF 2 as the view framework, but you can use Weld with any Servlet-based web framework, such
+ as JSF 1.2 or Wicket.
</para>
</note>
<para>
- Let's take a look at the Facelet view:
+ Let's take a look at the main JSF view, src/main/webapp/home.xhtml.
</para>
<programlistingco>
<areaspec>
<area id="template" coords="8" />
- <area id="messages2" coords="12" />
- <area id="instructions" coords="19" />
- <area id="guess" coords="25" />
- <area id="validator" coords="30" />
- <area id="submit" coords="33" />
+ <area id="statusMessages" coords="12" />
+ <area id="instructions" coords="20" />
+ <area id="guess" coords="27" />
+ <area id="validator" coords="29" />
+ <area id="submit" coords="30" />
</areaspec>
- <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+ <programlisting role="HTML"><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
- xmlns:ui="http://java.sun.com/jsf/facelets"
- xmlns:h="http://java.sun.com/jsf/html"
- xmlns:f="http://java.sun.com/jsf/core"
- xmlns:s="http://jboss.com/products/seam/taglib">
+ xmlns:ui="http://java.sun.com/jsf/facelets"
+ xmlns:h="http://java.sun.com/jsf/html"
+ xmlns:f="http://java.sun.com/jsf/core">
- <ui:composition template="template.xhtml">
- <ui:define name="content">
- <h1>Guess a number...</h1>
- <h:form id="NumberGuessMain">
- <div style="color: red">
- <h:messages id="messages" globalOnly="false"/>
- <h:outputText id="Higher" value="Higher!" rendered="#{game.number gt game.guess and game.guess ne 0}"/>
- <h:outputText id="Lower" value="Lower!" rendered="#{game.number lt game.guess and game.guess ne 0}"/>
- </div>
-
- <div>
- I'm thinking of a number between #{game.smallest} and #{game.biggest}.
- You have #{game.remainingGuesses} guesses.
- </div>
-
- <div>
- Your guess:
- <h:inputText id="inputGuess"
- value="#{game.guess}"
- required="true"
- size="3"
- disabled="#{game.number eq game.guess}">
- <f:validateLongRange maximum="#{game.biggest}"
- minimum="#{game.smallest}"/>
- </h:inputText>
- <h:commandButton id="GuessButton"
- value="Guess"
- action="#{game.check}"
- disabled="#{game.number eq game.guess}"/>
- </div>
- <div>
- <h:commandButton id="RestartButton" value="Reset" action="#{game.reset}" immediate="true" />
- </div>
- </h:form>
- </ui:define>
- </ui:composition>
+ <ui:composition template="/template.xhtml">
+ <ui:define name="content">
+ <h1>Guess a number...</h1>
+ <h:form id="numberGuess">
+ <div style="color: red">
+ <h:messages id="messages" globalOnly="false"/>
+ <h:outputText id="Higher" value="Higher!"
+ rendered="#{game.number gt game.guess and game.guess ne 0}"/>
+ <h:outputText id="Lower" value="Lower!"
+ rendered="#{game.number lt game.guess and game.guess ne 0}"/>
+ </div>
+
+ <div>
+ I'm thinking of a number between #{game.smallest} and #{game.biggest}.
+ You have #{game.remainingGuesses} guesses remaining.
+ </div>
+
+ <div>
+ Your guess:
+ <h:inputText id="inputGuess" value="#{game.guess}"
+ size="3" required="true" disabled="#{game.number eq game.guess}"
+ validator="#{game.validateNumberRange}"/>
+ <h:commandButton id="guessButton" value="Guess"
+ action="#{game.check}" disabled="#{game.number eq game.guess}"/>
+ </div>
+ <div>
+ <h:commandButton id="restartButton" value="Reset" action="#{game.reset}" immediate="true"/>
+ </div>
+ </h:form>
+ </ui:define>
+ </ui:composition>
</html>]]></programlisting>
<calloutlist>
<callout arearefs="template">
<para>
- Facelets is a templating language for JSF, here we are
- wrapping our page in a template which defines the header.
+ Facelets is the built-in templating language for JSF. Here we are
+ wrapping our page in a template which defines the layout.
</para>
</callout>
- <callout arearefs="messages2">
+ <callout arearefs="statusMessages">
<para>
There are a number of messages which can be sent to the user,
"Higher!", "Lower!" and "Correct!"
@@ -415,73 +734,69 @@
<callout arearefs="instructions">
<para>
As the user guesses, the range of numbers they can guess gets
- smaller - this sentance changes to make sure they know what
- range to guess in.
+ smaller - this sentance changes to make sure they know the
+ number range of a valid guess.
</para>
</callout>
<callout arearefs="guess">
<para>
- This input field is bound to a Web Bean, using the value
+ This input field is bound to a bean property using a value
expression.
</para>
</callout>
<callout arearefs="validator">
<para>
- A range validator is used to make sure the user doesn't
+ A validator binding is used to make sure the user doesn't
accidentally input a number outside of the range in which they
can guess - if the validator wasn't here, the user might use
- up a guess on an out of range number.
+ up a guess on an out of bounds number.
</para>
</callout>
<callout arearefs="submit">
<para>
And, of course, there must be a way for the user to send their
- guess to the server. Here we bind to an action method on the
- Web Bean.
+ guess to the server. Here we bind to an action method on the bean.
</para>
</callout>
</calloutlist>
</programlistingco>
<para>
- The example exists of 4 classes, the first two of which are binding
- types. First, there is the <literal>@Random</literal> binding type,
- used for injecting a random number:
+ The example exists of 4 classes, the first two of which are qualifiers. First, there is the
+ <literal>@Random</literal> qualifier, used for injecting a random number:
</para>
<programlisting role="JAVA"><![CDATA[@Target( { TYPE, METHOD, PARAMETER, FIELD })
@Retention(RUNTIME)
@Documented
- at BindingType
+ at Qualifier
public @interface Random {}]]></programlisting>
<para>
- There is also the <literal>@MaxNumber</literal> binding type, used for
+ There is also the <literal>@MaxNumber</literal> qualifier, used for
injecting the maximum number that can be injected:
</para>
<programlisting role="JAVA"><![CDATA[@Target( { TYPE, METHOD, PARAMETER, FIELD })
@Retention(RUNTIME)
@Documented
- at BindingType
+ at Qualifier
public @interface MaxNumber {}
]]></programlisting>
<para>
- The <literal>Generator</literal> class is responsible for creating the
- random number, via a producer method. It also exposes the maximum
- possible number via a producer method:
+ The application-scoped <literal>Generator</literal> class is responsible for creating the random number, via a
+ producer method. It also exposes the maximum possible number via a producer method:
</para>
<programlisting role="JAVA"><![CDATA[@ApplicationScoped
-public class Generator {
+public class Generator implements Serializable {
+
+ private java.util.Random random = new java.util.Random(System.currentTimeMillis());
- private java.util.Random random = new java.util.Random( System.currentTimeMillis() );
-
private int maxNumber = 100;
- java.util.Random getRandom()
- {
+ java.util.Random getRandom() {
return random;
}
@@ -489,117 +804,65 @@
return getRandom().nextInt(maxNumber);
}
- @Produces @MaxNumber int getMaxNumber()
- {
+ @Produces @MaxNumber int getMaxNumber() {
return maxNumber;
}
}]]></programlisting>
<para>
- You'll notice that the <literal>Generator</literal> is application
- scoped; therefore we don't get a different random each time.
+ The <literal>Generator</literal> is application scoped, so we don't get a different random each time.
</para>
+
+ <note>
+ <para>
+ The package declaration and imports have been excluded from these listings. The complete listing is
+ available in the example source code.
+ </para>
+ </note>
<para>
- The final Web Bean in the application is the session scoped
- <literal>Game</literal>.
+ The final bean in the application is the session-scoped <literal>Game</literal> class. This is the primary
+ entry point of the application. It's responsible for setting up or resetting the game, capturing and validating
+ the user's guess and providing feedback to the user with a <literal>FacesMessage</literal>. We've used
+ constructor injection to initialize the game with a random number.
</para>
-
+
<para>
- You'll note that we've used the <literal>@Named</literal>
- annotation, so that we can use the bean through EL in the JSF page.
- Finally, we've used constructor injection to initialize the game with
- a random number. And of course, we need to tell the player when they've
- won, so we give feedback with a <literal>FacesMessage</literal>.
+ You'll notice that we've also added the <literal>@Named</literal> annotation to this class. This annotation is
+ only required when you want to make the bean accessible to a JSF view via EL (i.e., #{game}).
</para>
-
- <programlisting role="JAVA"><![CDATA[package org.jboss.webbeans.examples.numberguess;
+
+ <programlisting role="JAVA"><![CDATA[@Named
+ at SessionScoped
+public class Game implements Serializable {
-import java.io.Serializable;
-
-import javax.annotation.PostConstruct;
-import javax.enterprise.context.SessionScoped;
-import javax.enterprise.inject.Instance;
-import javax.faces.application.FacesMessage;
-import javax.faces.component.UIComponent;
-import javax.faces.component.UIInput;
-import javax.faces.context.FacesContext;
-import javax.inject.Inject;
-import javax.inject.Named;
-
- at Named
- at SessionScoped
-public class Game implements Serializable
-{
private int number;
-
private int guess;
private int smallest;
-
- @Inject @MaxNumber
- private int maxNumber;
-
private int biggest;
private int remainingGuesses;
-
+
+ @Inject @MaxNumber private int maxNumber;
@Inject @Random Instance<Integer> randomNumber;
- public Game()
- {
- }
-
- public int getNumber()
- {
- return number;
- }
+ public Game() {}
- public int getGuess()
- {
- return guess;
- }
-
- public void setGuess(int guess)
- {
- this.guess = guess;
- }
-
- public int getSmallest()
- {
- return smallest;
- }
-
- public int getBiggest()
- {
- return biggest;
- }
-
- public int getRemainingGuesses()
- {
- return remainingGuesses;
- }
-
- public String check()
- {
- if (guess>number)
- {
+ public void check() {
+ if (guess > number) {
biggest = guess - 1;
}
- if (guess<number)
- {
+ else if (guess < number) {
smallest = guess + 1;
}
- if (guess == number)
- {
+ else if (guess == number) {
FacesContext.getCurrentInstance().addMessage(null, new FacesMessage("Correct!"));
}
remainingGuesses--;
- return null;
}
@PostConstruct
- public void reset()
- {
+ public void reset() {
this.smallest = 0;
this.guess = 0;
this.remainingGuesses = 10;
@@ -607,108 +870,164 @@
this.number = randomNumber.get();
}
- public void validateNumberRange(FacesContext context, UIComponent toValidate, Object value)
- {
- if (remainingGuesses <= 0)
- {
+ public void validateNumberRange(FacesContext context, UIComponent toValidate, Object value) {
+ if (remainingGuesses <= 0) {
FacesMessage message = new FacesMessage("No guesses left!");
context.addMessage(toValidate.getClientId(context), message);
- ((UIInput)toValidate).setValid(false);
+ ((UIInput) toValidate).setValid(false);
return;
}
int input = (Integer) value;
- if (input < smallest || input > biggest)
- {
- ((UIInput)toValidate).setValid(false);
+ if (input < smallest || input > biggest) {
+ ((UIInput) toValidate).setValid(false);
FacesMessage message = new FacesMessage("Invalid guess");
context.addMessage(toValidate.getClientId(context), message);
}
}
-}
-]]></programlisting>
- <section>
- <title>The numberguess example in Tomcat</title>
+ public int getNumber() {
+ return number;
+ }
+
+ public int getGuess() {
+ return guess;
+ }
+
+ public void setGuess(int guess) {
+ this.guess = guess;
+ }
+
+ public int getSmallest() {
+ return smallest;
+ }
+
+ public int getBiggest() {
+ return biggest;
+ }
+
+ public int getRemainingGuesses() {
+ return remainingGuesses;
+ }
+
+}]]></programlisting>
+
+ <section id="numberguess-servlet">
+ <title>The numberguess example in Apache Tomcat or Jetty</title>
<para>
- The numberguess for Tomcat differs in a couple of ways. Firstly,
- Web Beans should be deployed as a Web Application library in
- <literal>WEB-INF/lib</literal>. For your convenience we provide a
- single jar suitable for running Web Beans in any servlet container
- <literal>webbeans-servlet.jar</literal>.
+ A couple of modifications must be made to the numberguess artifact in order to deploy it to Tomcat or Jetty.
+ First, Weld must be deployed as a Web Application library under <literal>WEB-INF/lib</literal> since the
+ servlet container does not provide the CDI services. For your convenience we provide a single JAR suitable
+ for running Weld in any servlet container (including Jetty), <literal>weld-servlet.jar</literal>.
</para>
<tip>
<para>
- Of course, you must also include JSF and EL, as well common
- annotations (<literal>jsr250-api.jar</literal>) which a JEE server
- includes by default.
+ You must also include the JARs for JSF, EL, and the common annotations
+ (<literal>jsr250-api.jar</literal>), all of which are provided by the Java EE platorm (a Java EE
+ application server). Are you starting to appreciate why a Java EE platform is worth using?
</para>
</tip>
<para>
- Secondly, we need to explicitly specify the servlet listener
- (used to boot Web Beans, and control it's interaction with requests)
- in <literal>web.xml</literal>:
+ Second, we need to explicitly specify the servlet listener in <literal>web.xml</literal>, again because the
+ container isn't doing this stuff for you. The servlet listener boots Weld and controls it's interaction with
+ requests.
</para>
- <programlisting><![CDATA[<listener>
- <listener-class>org.jboss.webbeans.environment.servlet.Listener</listener-class>
+ <programlisting role="XML"><![CDATA[<listener>
+ <listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
</listener>]]></programlisting>
-
+
+ <para>
+ When Weld boots, it places the <literal>javax.enterprise.inject.spi.BeanManager</literal>, the portable SPI
+ for obtaining bean instances, in the ServletContext under a variable name equal to the fully-qualified
+ interface name. You generally don't need to access this interface, but Weld makes use of it.
+ </para>
+
</section>
- <section id="numberguessWicket">
- <title>The numberguess example for Apache Wicket</title>
+ <section id="numberguess-wicket">
+ <title>The numberguess example for Apache Wicket</title>
<para>
- Whilst JSR-299 specifies integration with Java ServerFaces, Web
- Beans allows you to inject into Wicket components, and also allows
- you to use a conversation context with Wicket. In this section,
- we'll walk you through the Wicket version of the numberguess
- example.
+ Weld includes a number of portable extensions for JSR-299, including an extension for Wicket, which allows
+ you to inject beans into Wicket components and leverage the conversation context. In this section, we'll
+ walk you through the Wicket version of the numberguess example.
</para>
- <note>
+ <tip>
<para>
- You may want to review the Wicket documentation at
- <ulink url="http://wicket.apache.org/">http://wicket.apache.org/</ulink>.
+ You may want to review the Wicket documentation at <ulink
+ url="http://wicket.apache.org/">http://wicket.apache.org/</ulink> before reading this section, if you
+ aren't already familiar with the framework.
</para>
- </note>
+ </tip>
<para>
- Like the previous example, the Wicket WebBeans examples make use of
- the <literal>webbeans-servlet</literal> module. The use of the
- <ulink url="http://jetty.mortbay.org/">Jetty servlet container</ulink>
- is common in the Wicket community, and is chosen here as the
- runtime container in order to facilitate comparison between the
- standard Wicket examples and these examples, and also to show how
- the webbeans-servlet integration is not dependent upon Tomcat as the
- servlet container.
+ Wicket is another environment that relies on the Weld servlet extension. The use of <ulink
+ url="http://jetty.mortbay.org">Jetty</ulink> is common in the Wicket community, and is thus chosen here as
+ the runtime container. You've seen already that Jetty is perfectly capable of running CDI applications with
+ Weld add-ons, and this environment is no different.
</para>
- <para>
- These examples make use of the Eclipse IDE; instructions are also
- given to deploy the application from the command line.
- </para>
+ <note>
+ <para>
+ We'll also be using the Eclipse IDE in these examples. Instructions are provided later for running the
+ example from the commandline, but since you'll likely need to do more than just deploy examples, we'll get
+ setup in this full development environment.
+ </para>
+ </note>
<section>
<title>Creating the Eclipse project</title>
<para>
- To generate an Eclipse project from the example:
+ To use the Wicket example in Eclipse, you have one of two choices. You can either use a Maven plugin to
+ generate a regular Eclipse Web project, or you can open the example natively using the <ulink
+ src="http://m2eclipse.sonatype.org/">m2eclipse plugin</ulink>. Since the Weld source code relies so
+ heavily on Maven, we encourage you to bite the bullet and adopt the m2eclipse plugin. Both approaches are
+ described here for your convenience..
</para>
+
+ <para>
+ If you have m2eclipse installed, you can open any Maven project directly. From within Eclipse, select
+ <emphasis>File -> Import... -> Maven Projects</emphasis>. Then, browse to the location of the Wicket
+ numberguess example. You should see that Eclipse recognizes the existance of a Maven project.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/m2eclipse-wicket-numberguess-import.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>
+ This will create a project in your workspace called <literal>weld-wicket-numberguess</literal>.
+ </para>
+
+ <para>
+ You'll notice after importing, the project has a build error. That's because we need to enable a Maven
+ profile. Right-click on the project and select <emphasis>Properties</emphasis>, then select the
+ <emphasis>Maven</emphasis> tab in the window that appears. In the form field labeled "Active Maven
+ Profiles (comma separated):", type <literal>jetty</literal>. That will enable some extra dependencies
+ that allow the project to compile. You're now ready to develop!
+ </para>
+
+ <para>
+ If you are not using the m2eclipse plugin, you have to follow different steps to import the project.
+ First, switch into the Wicket numberguess example, then execute the Maven Eclipse plugin with the jetty
+ profile activated, as follows:
+ </para>
- <programlisting><![CDATA[cd examples/wicket/numberguess
+ <programlisting><![CDATA[$> cd examples/wicket/numberguess
mvn -Pjetty eclipse:eclipse]]></programlisting>
<para>
- Then, from eclipse, choose <emphasis>File -> Import -> General -> Existing Projects into Workspace</emphasis>,
- select the root directory of the numberguess example, and click
- finish. Note that if you do not intend to run the example with jetty from
- within eclipse, omit the "-Pjetty." This will create a project in your
- workspace called <literal>webbeans-wicket-numberguess</literal>
+ Then, from Eclipse, choose <emphasis>File -> Import... -> General -> Existing Projects into
+ Workspace</emphasis>, select the root directory of the numberguess example, and click Finish. This will
+ create a project in your workspace called <literal>weld-wicket-numberguess</literal>.
</para>
<mediaobject>
@@ -716,22 +1035,23 @@
<imagedata fileref="images/wicket-numberguess-project.png" format="PNG"/>
</imageobject>
</mediaobject>
+
+ <para>
+ It's time to get the example running!
+ </para>
+
</section>
<section>
<title>Running the example from Eclipse</title>
<para>
- This project follows the <literal>wicket-quickstart</literal>
- approach of creating an instance of Jetty in the
- <literal>Start</literal> class. So running the example is as
- simple as right-clicking on that Start class in
- <literal>src/test/java</literal> in the
- <emphasis>Package Explorer</emphasis> and choosing
- <emphasis>Run as Java Application</emphasis>. You should
- see console output related to Jetty starting up; then visit able
- <literal>http://localhost:8080</literal> to view the app. To
- debug choose <emphasis>Debug as Java Application</emphasis>.
+ This project follows the <literal>wicket-quickstart</literal> approach of creating an instance of Jetty
+ in the <literal>Start</literal> class. So running the example is as simple as right-clicking on that
+ Start class in <literal>src/test/java</literal> in the <emphasis>Package Explorer</emphasis> and choosing
+ <emphasis>Run as Java Application</emphasis>. You should see console output related to Jetty starting up;
+ then visit able <literal>http://localhost:8080</literal> to view the app. To debug choose <emphasis>Debug
+ as Java Application</emphasis> instead.
</para>
</section>
@@ -739,144 +1059,179 @@
<title>Running the example from the command line in JBoss AS or Tomcat</title>
<para>
- This example can also be deployed from the command line in a
- (similar to the other examples). Assuming you have set up the
- <literal>build.properties</literal> file in the
- <literal>examples</literal> directory to specify the location of
- JBoss AS or Tomcat, as previously described, you can run
- <literal>ant deploy</literal> from the
- <literal>examples/wicket/numberguess</literal> directory, and
- access the application at
- <literal>http://localhost:8080/webbeans-numberguess-wicket</literal>.
+ This example can also be deployed from the command line in a (similar to the other examples). Assuming
+ you have set up the <literal>local.build.properties</literal> file in the <literal>examples</literal>
+ directory to specify the location of JBoss AS or Tomcat, as previously described, you can run:
</para>
+
+ <programlisting><![CDATA[$> ant deploy]]></programlisting>
+
+ <para>to deploy the example to JBoss AS, and:</para>
+
+ <programlisting><![CDATA[$> ant tomcat.deploy]]></programlisting>
+
+ <para>
+ to deploy the example to Tomcat. You can then access application at
+ <literal>http://localhost:8080/weld-numberguess-wicket</literal>.
+ </para>
+
+ <para>
+ Alternatively, you can run the application in place on an embedded Jetty container using the following
+ Maven command:
+ </para>
+
+ <programlisting><![CDATA[$> mvn jetty:run -Pjetty]]></programlisting>
+
+ <para>
+ Enough toying with deployment, let's dive into the code.
+ </para>
+
</section>
<section>
<title>Understanding the code</title>
<para>
- JSF uses Unified EL expressions to bind view layer components in
- JSP or Facelet views to beans, Wicket defines it's components in
- Java. The markup is plain html with a one-to-one mapping between
- html elements and the view components. All view logic, including
- binding of components to models and controlling the response of
- view actions, is handled in Java. The integration of Web Beans
- with Wicket takes advantage of the same binding annotations used
- in your business layer to provide injection into your WebPage
- subclass (or into other custom wicket component subclasses).
+ The code in the wicket numberguess example is very similar to the JSF-based numberguess example. The
+ business layer is identical! Where things differ is in view binding. JSF uses Unified EL expressions to
+ bind XML-based view layer components in JSF views to beans. In contrast, Wicket defines its components in
+ Java. These Java-based view components have a one-to-one mapping with HTML elements in an adjacent (pure)
+ HTML file. All view logic, including binding of components to models and controlling the response of view
+ actions, is handled in Java.
</para>
-
+
<para>
- The code in the wicket numberguess example is very similar to the
- JSF-based numberguess example. The business layer is identical!
+ The integration of Weld with Wicket takes advantage of the same qualifier annotations used in your
+ business layer to provide injection into your <literal>WebPage</literal> subclass (or into other custom
+ Wicket component subclasses).
</para>
-
+
<para>
- Differences are:
+ Here's where things differ from the JSF numberguess example:
</para>
+
<itemizedlist>
<listitem>
<para>
- Each wicket application must have a
- <literal>WebApplication</literal> subclass, In our case,
- our application class is
- <literal>SampleApplication</literal>:
+ Each wicket application must have a <literal>WeldApplication</literal> subclass. In our case, our
+ application class is <literal>NumberGuessApplication</literal>:
</para>
- <programlisting><![CDATA[public class SampleApplication extends WebBeansApplication {
- @Override
- public Class getHomePage() {
+ <programlisting role="JAVA"><![CDATA[public class NumberGuessApplication extends WeldApplication {
+ @Override public Class getHomePage() {
return HomePage.class;
}
}]]></programlisting>
<para>
- This class specifies which page wicket should treat as our
- home page, in our case, <literal>HomePage.class</literal>
+ This class specifies which page Wicket should treat as our home page, in our case,
+ <literal>HomePage.class</literal>
</para>
</listitem>
<listitem>
<para>
- In <literal>HomePage</literal> we see typical wicket code
- to set up page elements. The bit that is interesting is
- the injection of the <literal>Game</literal> bean:
+ In <literal>HomePage</literal>, we see typical Wicket code to set up page elements. The bit that is
+ interesting is the injection of the <literal>Game</literal> bean:
</para>
- <programlisting><![CDATA[ @Current Game game;]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[@Inject Game game;]]></programlisting>
<para>
- The <literal>Game</literal> bean is can then be used, for
- example, by the code for submitting a guess:
+ The <literal>Game</literal> bean is can then be used, for example, by the code for submitting a
+ guess:
</para>
- <programlisting><![CDATA[final Component guessButton = new AjaxButton("GuessButton") {
+ <programlisting role="JAVA"><![CDATA[final Component guessButton = new AjaxButton("GuessButton") {
protected void onSubmit(AjaxRequestTarget target, Form form) {
- if (game.check()) {]]></programlisting>
+ if (game.check()) {
+ info("Correct!");
+ setVisible(false);
+ prompt.setVisible(false);
+ guessLabel.setVisible(false);
+ inputGuess.setVisible(false);
+ }
+ else if (game.getRemainingGuesses() == 0) {
+ info("Sorry, the answer was " + game.getNumber());
+ setVisible(false);
+ guessLabel.setVisible(false);
+ inputGuess.setVisible(false);
+ }
+ else if (game.getNumber() > game.getGuess()) {
+ info("Higher!");
+ }
+ else if (game.getNumber() < game.getGuess()) {
+ info("Lower");
+ }
+ target.addComponent(form);
+ }
+}; ]]></programlisting>
<note>
<para>
- All injections may be serialized; actual storage of the
- bean is managed by JSR-299. Note that Wicket
- components, like the HomePage and it subcomponents, are
+ All injections may be serialized; actual storage of the bean is managed by JSR-299. Note that
+ Wicket components, like the <literal>HomePage</literal> and it subcomponents, are
<emphasis>not</emphasis> JSR-299 beans.
</para>
<para>
- Wicket components allow injection, but they
- <emphasis>cannot</emphasis> use interceptors, decorators
- and lifecycle callbacks such as
- <literal>@PostConstruct</literal> or
- <literal>@Initializer</literal> methods.
+ Wicket components allow injection, but they <emphasis>cannot</emphasis> use interceptors,
+ decorators and lifecycle callbacks such as <literal>@PostConstruct</literal> or
+ <literal>@Initializer</literal> methods. The components would need to delegate to actual beans
+ to leverage these features.
</para>
</note>
</listitem>
<listitem>
<para>
- The example uses AJAX for processing of button events, and
- dynamically hides buttons that are no longer relevant, for
- example when the user has won the game.
+ The example uses AJAX for processing of button events, and dynamically hides buttons that are no
+ longer relevant, for example when the user has won the game.
</para>
</listitem>
<listitem>
<para>
- In order to activate wicket for this webapp, the Wicket
- filter is added to web.xml, and our application class is
- specified:
+ In order to activate Wicket for this webapp, the Wicket filter is added to web.xml, and our
+ application class is specified in web.xml:
</para>
- <programlisting><![CDATA[<filter>
- <filter-name>wicket.numberguess-example</filter-name>
+
+ <programlisting role="XML"><![CDATA[<filter>
+ <filter-name>Wicket Filter</filter-name>
<filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
<init-param>
<param-name>applicationClassName</param-name>
- <param-value>org.jboss.webbeans.examples.wicket.SampleApplication</param-value>
+ <param-value>org.jboss.weld.examples.wicket.NumberGuessApplication</param-value>
</init-param>
</filter>
<filter-mapping>
- <filter-name>wicket.numberguess-example</filter-name>
+ <filter-name>Wicket Filter</filter-name>
<url-pattern>/*</url-pattern>
-</filter-mapping>
-
-<listener>
- <listener-class>org.jboss.webbeans.environment.servlet.Listener</listener-class>
-</listener>]]></programlisting>
+</filter-mapping>]]></programlisting>
+
<para>
- Note that the servlet listener is also added, as in the
- Tomcat example, in order to boostrap Web Beans when Jetty
- starts, and to hook Web Beans into the Jetty servlet
- request and session lifecycles.
+ The servlet listener is still required, as in the Tomcat example, to bootstrap CDI when Jetty
+ starts and to hook CDI into the Jetty servlet request and session life cycles. However, rather than
+ putting it into the web.xml, it is placed into an override file,
+ src/main/webapp/WEB-INF/jetty-additions-to-web.xml, that is passed to Jetty as extra descriptor to
+ be appended to the web.xml configuration.
</para>
+
+ <programlisting role="XML"><![CDATA[<web-app version="2.4" ...>
+ <listener>
+ <listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
+ </listener>
+</web-app>]]></programlisting>
+
</listitem>
</itemizedlist>
</section>
</section>
- <section>
+ <section id="numberguess-se">
<title>The numberguess example for Java SE with Swing</title>
<para>
This example can be found in the
- <literal>examples/se/numberguess</literal> folder of the Web
- Beans distribution.
+ <literal>examples/se/numberguess</literal> folder of the Weld
+ distribution.
</para>
@@ -906,7 +1261,7 @@
<para>
execute the following command
</para>
- <programlisting>mvn -Drun</programlisting>
+ <programlisting>$> mvn -Drun</programlisting>
</listitem>
</itemizedlist>
@@ -915,7 +1270,7 @@
<para>
There is an empty <literal>beans.xml</literal> file in the root
package (<literal>src/main/resources/beans.xml</literal>), which
- marks this application as a Web Beans application.
+ marks this application as a CDI application.
</para>
<para>
@@ -933,57 +1288,46 @@
<area id="reset" coords="68" />
</areaspec>
<programlisting role="JAVA"><![CDATA[@ApplicationScoped
-public class Game implements Serializable
-{
+public class Game implements Serializable {
private int number;
private int guess;
private int smallest;
-
- @MaxNumber
- private int maxNumber;
-
private int biggest;
private int remainingGuesses;
private boolean validNumberRange = true;
- @Current Generator rndGenerator;
+ @Inject @MaxNumber private int maxNumber;
+ @Inject Generator rndGenerator;
+
...
- public boolean isValidNumberRange()
- {
+ public boolean isValidNumberRange() {
return validNumberRange;
}
- public boolean isGameWon()
- {
+ public boolean isGameWon() {
return guess == number;
}
- public boolean isGameLost()
- {
+ public boolean isGameLost() {
return guess != number && remainingGuesses <= 0;
}
- public boolean check()
- {
+ public boolean check() {
boolean result = false;
- if ( checkNewNumberRangeIsValid() )
- {
- if ( guess > number )
- {
+ if (checkNewNumberRangeIsValid()) {
+ if (guess > number) {
biggest = guess - 1;
}
- if ( guess < number )
- {
+ if (guess < number) {
smallest = guess + 1;
}
- if ( guess == number )
- {
+ if (guess == number) {
result = true;
}
@@ -993,14 +1337,12 @@
return result;
}
- private boolean checkNewNumberRangeIsValid()
- {
- return validNumberRange = ( ( guess >= smallest ) && ( guess <= biggest ) );
+ private boolean checkNewNumberRangeIsValid() {
+ return validNumberRange = ((guess >= smallest) && (guess <= biggest));
}
@PostConstruct
- public void reset()
- {
+ public void reset() {
this.smallest = 0;
...
this.number = rndGenerator.next();
@@ -1084,12 +1426,10 @@
<area id="challenge" coords="5" />
<area id="result" coords="16" />
</areaspec>
- <programlisting role="JAVA"><![CDATA[public class MessageGenerator
-{
- @Current Game game;
+ <programlisting role="JAVA"><![CDATA[public class MessageGenerator {
+ @Inject Game game;
- public String getChallengeMessage()
- {
+ public String getChallengeMessage() {
StringBuilder challengeMsg = new StringBuilder( "I'm thinking of a number between " );
challengeMsg.append( game.getSmallest() );
challengeMsg.append( " and " );
@@ -1099,35 +1439,33 @@
return challengeMsg.toString();
}
- public String getResultMessage()
- {
- if ( game.isGameWon() )
- {
+ public String getResultMessage() {
+ if ( game.isGameWon() ) {
return "You guess it! The number was " + game.getNumber();
- } else if ( game.isGameLost() )
- {
+ }
+ else if ( game.isGameLost() ) {
return "You are fail! The number was " + game.getNumber();
- } else if ( ! game.isValidNumberRange() )
- {
+ }
+ else if ( ! game.isValidNumberRange() ) {
return "Invalid number range!";
- } else if ( game.getRemainingGuesses() == Game.MAX_NUM_GUESSES )
- {
+ }
+ else if ( game.getRemainingGuesses() == Game.MAX_NUM_GUESSES ) {
return "What is your first guess?";
- } else
- {
+ }
+ else {
String direction = null;
- if ( game.getGuess() < game.getNumber() )
- {
+ if ( game.getGuess() < game.getNumber() ) {
direction = "Higher";
- } else
- {
+ }
+ else {
direction = "Lower";
}
return direction + "! You have " + game.getRemainingGuesses() + " guesses left.";
}
}
+
}]]></programlisting>
<calloutlist>
<callout arearefs="game">
@@ -1166,13 +1504,12 @@
<area id="replay" coords="44" />
<area id="refresh" coords="50" />
</areaspec>
- <programlisting role="JAVA"><![CDATA[public class NumberGuessFrame extends javax.swing.JFrame
-{
- private @Current Game game;
- private @Current MessageGenerator msgGenerator;
+ <programlisting role="JAVA"><![CDATA[public class NumberGuessFrame extends javax.swing.JFrame {
- public void start( @Observes @Deployed Manager manager )
- {
+ private @Inject Game game;
+ private @Inject MessageGenerator msgGenerator;
+
+ public void start( @Observes @Deployed Manager manager ) {
java.awt.EventQueue.invokeLater( new Runnable()
{
public void run()
@@ -1199,8 +1536,7 @@
...
}
- private void guessButtonActionPerformed( java.awt.event.ActionEvent evt )
- {
+ private void guessButtonActionPerformed( java.awt.event.ActionEvent evt ) {
int guess = Integer.parseInt(guessText.getText());
game.setGuess( guess );
@@ -1209,14 +1545,12 @@
}
- private void replayBtnActionPerformed( java.awt.event.ActionEvent evt )
- {
+ private void replayBtnActionPerformed( java.awt.event.ActionEvent evt ) {
game.reset();
refreshUI();
}
- private void refreshUI()
- {
+ private void refreshUI() {
mainLabel.setText( msgGenerator.getChallengeMessage() );
messageLabel.setText( msgGenerator.getResultMessage() );
guessText.setText( "" );
@@ -1243,7 +1577,7 @@
</callout>
<callout arearefs="start">
<para>
- This application is started in the usual Web Beans SE way,
+ This application is started in the usual CDI SE way,
by observing the <literal>@Deployed Manager</literal> event.
</para>
</callout>
@@ -1309,30 +1643,29 @@
</section>
</section>
- <section>
- <title>The translator example</title>
+ <section id="translator">
+ <title>The translator example in depth</title>
<para>
- The translator example will take any sentences you enter, and translate
- them to Latin.
+ The translator example will take any sentences you enter, and translate them to Latin. (Well, not really, but
+ the stub is there for you to implement, at least. Good luck!)
</para>
<para>
- The translator example is built as an ear, and contains EJBs. As a result, it's structure is more complex than
+ The translator example is built as an EAR and contains EJBs. As a result, it's structure is more complex than
the numberguess example.
</para>
<note>
<para>
- EJB 3.1 and Jave EE 6 allow you to package EJBs in a war, which will
- make this structure much simpler!
+ Jave EE 6, which bundles EJB 3.1, allows you to package EJBs in a WAR, which will make this structure much
+ simpler! Still, there are other advantages of using an EAR.
</para>
</note>
<para>
- First, let's take a look at the ear aggregator, which is located in
- <literal>webbeans-translator-ear</literal> module. Maven automatically
- generates the <literal>application.xml</literal> for us:
+ First, let's take a look at the EAR aggregator, which is located in the example's <literal>ear</literal> directory. Maven
+ automatically generates the <literal>application.xml</literal> for us from this plugin configuration:
</para>
<programlisting role="XML"><![CDATA[<plugin>
@@ -1341,62 +1674,62 @@
<configuration>
<modules>
<webModule>
- <groupId>org.jboss.webbeans.examples.translator</groupId>
- <artifactId>webbeans-translator-war</artifactId>
- <contextRoot>/webbeans-translator</contextRoot>
+ <groupId>org.jboss.weld.examples.jsf.translator</groupId>
+ <artifactId>weld-jsf-translator-war</artifactId>
+ <contextRoot>/weld-translator</contextRoot>
</webModule>
</modules>
</configuration>
</plugin>]]></programlisting>
<para>
- Here we set the context path, which gives us a nice url
- (<ulink url="http://localhost:8080/webbeans-translator">http://localhost:8080/webbeans-translator</ulink>).
+ This configuration overrides the web context path, resulting in this application URL: <ulink
+ url="http://localhost:8080/weld-translator">http://localhost:8080/weld-translator</ulink>.
</para>
<tip>
<para>
- If you aren't using Maven to generate these files, you would need
+ If you weren't using Maven to generate these files, you would need
<literal>META-INF/application.xml</literal>:
</para>
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<application xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_5.xsd"
- version="5">
- <display-name>webbeans-translator-ear</display-name>
- <description>Ear Example for the reference implementation of JSR 299: Web Beans</description>
+ <programlisting role="XML"><![CDATA[<application version="5"
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/application_5.xsd">
+
+ <display-name>weld-jsf-translator-ear</display-name>
+ <description>The Weld JSF translator example (EAR)</description>
<module>
<web>
- <web-uri>webbeans-translator.war</web-uri>
- <context-root>/webbeans-translator</context-root>
+ <web-uri>weld-translator.war</web-uri>
+ <context-root>/weld-translator</context-root>
</web>
</module>
<module>
- <ejb>webbeans-translator.jar</ejb>
+ <ejb>weld-translator.jar</ejb>
</module>
</application>]]></programlisting>
</tip>
<para>
- Next, lets look at the war. Just as in the numberguess example, we have
- a <literal>faces-config.xml</literal> (to enable Facelets) and a
- <literal>web.xml</literal> (to enable JSF) in
- <literal>WebContent/WEB-INF</literal>.
+ Next, lets look at the WAR, which is located in the example's <literal>war</literal> directory. Just as in the
+ numberguess example, we have a <literal>faces-config.xml</literal> for JSF 2.0 and a <literal>web.xml</literal>
+ (to activate JSF) under WEB-INF, both sourced from <literal>src/main/webapp/WEB-INF</literal>.
</para>
<para>
- More intersting is the facelet used to translate text. Just as in
- the numberguess example we have a template, which surrounds the form
- (ommitted here for brevity):
+ More intersting is the JSF view used to translate text. Just as in the numberguess example we have a template,
+ which surrounds the form (ommitted here for brevity):
</para>
- <programlisting role="XML"><![CDATA[<h:form id="NumberGuessMain">
-
+ <programlisting role="XML"><![CDATA[<h:form id="translator">
+
<table>
- <tr align="center" style="font-weight: bold" >
+ <tr align="center" style="font-weight: bold">
<td>
Your text
</td>
@@ -1406,10 +1739,10 @@
</tr>
<tr>
<td>
- <h:inputTextarea id="text" value="#{translator.text}" required="true" rows="5" cols="80" />
+ <h:inputTextarea id="text" value="#{translator.text}" required="true" rows="5" cols="80"/>
</td>
<td>
- <h:outputText value="#{translator.translatedText}" />
+ <h:outputText value="#{translator.translatedText}"/>
</td>
</tr>
</table>
@@ -1420,93 +1753,128 @@
</h:form>]]></programlisting>
<para>
- The user can enter some text in the lefthand textarea, and hit the
- translate button to see the result to the right.
+ The user can enter some text in the left-hand textarea, and hit the translate button to see the result to the
+ right.
</para>
<para>
- Finally, let's look at the ejb module,
- <literal>webbeans-translator-ejb</literal>.
- In <literal>src/main/resources/META-INF</literal> there is just an
- empty <literal>web-beans.xml</literal>, used to mark the archive as
- containing Web Beans.
+ Finally, let's look at the EJB module, which is located in the example's <literal>ejb</literal> directory. In
+ <literal>src/main/resources/META-INF</literal> there is just an empty <literal>beans.xml</literal>, used to
+ mark the archive as containing beans.
</para>
<para>
- We've saved the most interesting bit to last, the code! The project has
- two simple beans, <literal>SentenceParser</literal> and
- <literal>TextTranslator</literal> and two enterprise beans,
- <literal>TranslatorControllerBean</literal> and
- <literal>SentenceTranslator</literal>. You should be getting quite
- familiar with what a Web Bean looks like by now, so we'll just
- highlight the most interesting bits here.
+ We've saved the most interesting bit to last, the code! The project has two simple beans,
+ <literal>SentenceParser</literal> and <literal>TextTranslator</literal> and two enterprise beans,
+ <literal>TranslatorControllerBean</literal> and <literal>SentenceTranslator</literal>. You should be getting
+ quite familiar with what a bean looks like by now, so we'll just highlight the most interesting bits here.
</para>
<para>
- Both <literal>SentenceParser</literal> and
- <literal>TextTranslator</literal> are dependent beans, and
- <literal>TextTranslator</literal> uses constructor initialization:
+ Both <literal>SentenceParser</literal> and <literal>TextTranslator</literal> are dependent beans, and
+ <literal>TextTranslator</literal> uses constructor injection:
</para>
- <programlisting role="JAVA"><![CDATA[public class TextTranslator {
+ <programlisting role="JAVA"><![CDATA[public class TextTranslator implements Serializable {
+
private SentenceParser sentenceParser;
- private Translator sentenceTranslator;
+
+ @EJB private Translator translator;
- @Initializer
- TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator)
- {
+ @Inject public TextTranslator(SentenceParser sentenceParser) {
this.sentenceParser = sentenceParser;
- this.sentenceTranslator = sentenceTranslator;]]></programlisting>
+ }
+
+ public String translate(String text) {
+ StringBuilder sb = new StringBuilder();
+ for (String sentence: sentenceParser.parse(text)) {
+ sb.append(translator.translate(sentence)).append(". ");
+ }
+ return sb.toString().trim();
+ }
+
+}]]></programlisting>
<para>
- <literal>TextTranslator</literal> is a stateless bean (with a local
- business interface), where the magic happens - of course, we couldn't
- develop a full translator, but we gave it a good go!
+ <literal>TextTranslator</literal> uses the simple bean (really just a plain Java class!)
+ <literal>SentenceParser</literal> to parse the sentence and then calls on the stateless bean with the local
+ business interface <literal>Translator</literal> to perform the translation. That's where the magic happens.
+ Of course, we couldn't develop a full translator, but it's convincing enough to anyone who doesn't understand
+ Latin!
</para>
-
+
+ <programlisting role="JAVA"><![CDATA[@Stateless
+public class SentenceTranslator implements Translator {
+
+ public String translate(String sentence) {
+ return "Lorem ipsum dolor sit amet";
+ }
+
+}]]></programlisting>
+
<para>
- Finally, there is UI orientated controller, that collects the text from
- the user, and dispatches it to the translator. This is a request
- scoped, named, stateful session bean, which injects the translator.
+ Finally, there is UI orientated controller. This is a request scoped, named, stateful session bean, which
+ injects the translator. It collects the text from the user and dispatches it to the translator. The bean also
+ has getters and setters for all the fields on the page.
</para>
<programlisting role="JAVA"><![CDATA[@Stateful
@RequestScoped
@Named("translator")
-public class TranslatorControllerBean implements TranslatorController
-{
+public class TranslatorControllerBean implements TranslatorController {
+
+ @Inject private TextTranslator translator;
- @Current TextTranslator translator;]]></programlisting>
+ private String inputText;
+ private String translatedText;
+
+ public void translate() {
+ translatedText = translator.translate(inputText);
+ }
+
+ public String getText() {
+ return inputText;
+ }
+
+ public void setText(String text) {
+ this.inputText = text;
+ }
+
+ public String getTranslatedText() {
+ return translatedText;
+ }
+
+ @Remove public void remove() {}
+
+}]]></programlisting>
+
<para>
- The bean also has getters and setters for all the fields on the page.
+ [CHECK is this still accurate?] Since this is a stateful session bean, we have to have a remove method. The
+ bean manager will call the remove method for you when the bean is destroyed; in this case at the end of the
+ request.
</para>
-
+
<para>
- As this is a stateful session bean, we have to have a remove method:
+ You'll notice in this example the smooth integration between the existing <literal>@EJB</literal> resource
+ injection annotation and the new <literal>@Inject</literal> annotation for injecting any managed or session
+ bean. The tight integration with Java EE is a key value proposition of CDI (not to mention a requirement).
</para>
-
- <programlisting role="JAVA"><![CDATA[ @Remove
- public void remove()
- {
-
- }]]></programlisting>
-
- <para>
- The Web Beans manager will call the remove method for you when the bean
- is destroyed; in this case at the end of the request.
- </para>
+
</section>
<para>
- That concludes our short tour of the Web Beans examples. For more on Web
- Beans , or to help out, please visit
- <ulink url="http://www.seamframework.org/WebBeans/Development">http://www.seamframework.org/WebBeans/Development</ulink>.
+ That concludes our short tour of the Weld starter examples. For more information on Weld, or to help out with
+ development, please visit <ulink
+ url="http://www.seamframework.org/Weld/Development">http://www.seamframework.org/Weld/Development</ulink>.
</para>
<para>
- We need help in all areas - bug fixing, writing new features, writing
- examples and translating this reference guide.
+ We need help in all areas - bug fixing, writing new features, writing examples and translating this reference
+ guide.
</para>
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
</chapter>
Added: doc/trunk/reference/en-US/images/m2eclipse-wicket-numberguess-import.png
===================================================================
(Binary files differ)
Property changes on: doc/trunk/reference/en-US/images/m2eclipse-wicket-numberguess-import.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: doc/trunk/reference/en-US/intro.xml
===================================================================
--- doc/trunk/reference/en-US/intro.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/intro.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -1,538 +1,1000 @@
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<!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 Web Beans</title>
+ <title>Getting started with JSR-299 (CDI)</title>
- <para>So you're already keen to get started writing your first Web Bean?
- Or perhaps you're skeptical, wondering what kinds of hoops the Web Beans
- specification will make you jump through! The good news is that you've
- probably already written and used hundreds, perhaps thousands of Web Beans.
- You might not even remember the first Web Bean you wrote.</para>
+ <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.
+ </para>
+
+ <section id="bean-definition">
+ <title>What is a bean?</title>
+
+ <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.
+ </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.
+ </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
+ 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.
+ </para>
- <section>
- <title>Your first Web Bean</title>
+ <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.
+ </para>
+
+ <para>
+ Let's see how to create your first bean.
+ </para>
+
+ </section>
+
+ <section id="first-bean">
+ <title>Your first bean (or is it?)</title>
+
+ <para>
+ Suppose that we have two existing Java classes, that we've been using for years in various applications. The
+ first class parses a string into a list of sentences:
+ </para>
- <para>With certain, very special exceptions, every Java class with a
- constructor that accepts no parameters is a Web Bean. That includes every
- JavaBean. Furthermore, every EJB 3-style session bean is a Web Bean. Sure,
- the JavaBeans and EJBs you've been writing every day have not been able to
- take advantage of the new services defined by the Web Beans specification,
- but you'll be able to use every one of them as Web Beans — injecting them
- into other Web Beans, configuring them via the Web Beans XML configuration
- facility, even adding interceptors and decorators to them — without
- touching your existing code.</para>
-
- <para>Suppose that we have two existing Java classes, that we've been using
- for years in various applications. The first class parses a string into a
- list of sentences:</para>
-
- <programlisting role="JAVA"><![CDATA[public class SentenceParser {
- public List<String> parse(String text) { ... }
+ <programlisting role="JAVA"><![CDATA[public class SentenceParser {
+ public List<String> parse(String text) { ... }
}]]></programlisting>
- <para>The second existing class is a stateless session bean front-end for an
- external system that is able to translate sentences from one language to
- another:</para>
+ <para>
+ The second existing class is a stateless session bean front-end for an external system that is able to
+ translate sentences from one language to another:
+ </para>
- <programlisting role="JAVA"><![CDATA[@Stateless
+ <programlisting role="JAVA"><![CDATA[@Stateless
public class SentenceTranslator implements Translator {
- public String translate(String sentence) { ... }
+ public String translate(String sentence) { ... }
}]]></programlisting>
- <para>Where <literal>Translator</literal> is the local interface:</para>
+ <para>Where <literal>Translator</literal> is the EJB local interface:</para>
- <programlisting role="JAVA"><![CDATA[@Local
+ <programlisting role="JAVA"><![CDATA[@Local
public interface Translator {
- public String translate(String sentence);
+ public String translate(String sentence);
}]]></programlisting>
- <para>Unfortunately, we don't have a preexisting class that translates whole
- text documents. So let's write a Web Bean that does this job:</para>
+ <para>
+ Unfortunately, we don't have a class that translates whole text documents. So let's write a bean for this job:
+ </para>
- <programlisting role="JAVA"><![CDATA[public class TextTranslator {
+ <programlisting role="JAVA"><![CDATA[public class TextTranslator {
+ private SentenceParser sentenceParser;
+ private Translator sentenceTranslator;
- private SentenceParser sentenceParser;
- private Translator sentenceTranslator;
+ @Inject
+ TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator) {
+ this.sentenceParser = sentenceParser;
+ this.sentenceTranslator = sentenceTranslator;
+ }
- @Initializer
- TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator) {
- this.sentenceParser = sentenceParser;
- this.sentenceTranslator = sentenceTranslator;
- }
-
- public String translate(String text) {
- StringBuilder sb = new StringBuilder();
- for (String sentence: sentenceParser.parse(text)) {
- sb.append(sentenceTranslator.translate(sentence));
- }
- return sb.toString();
- }
-
+ public String translate(String text) {
+ StringBuilder sb = new StringBuilder();
+ for (String sentence: sentenceParser.parse(text)) {
+ sb.append(sentenceTranslator.translate(sentence));
+ }
+ return sb.toString();
+ }
}]]></programlisting>
- <para>We may obtain an instance of <literal>TextTranslator</literal> by
- injecting it into a Web Bean, Servlet or EJB:</para>
+ <para>
+ But wait! <literal>TextTranslator</literal> does not have a constructor with no parameters! Is it still a bean?
+ If you remember, a class that does not have a constructor with no parameters can still be a bean if it has a
+ constructor annotated <literal>@Inject</literal>.
+ </para>
+
+ <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 bean manager to
+ call that constructor or method when instantiating the bean. The bean manager 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.
+ </para>
+
+ <para>
+ Let's create a UI controller bean that uses field injection to obtain an instance of the
+ <literal>TextTranslator</literal>, translating the text entered by a user:
+ </para>
- <programlisting role="JAVA"><![CDATA[@Initializer
-public setTextTranslator(TextTranslator textTranslator) {
- this.textTranslator = textTranslator;
+ <programlisting role="JAVA"><![CDATA[@Named @RequestScoped
+public class TranslateController {
+ @Inject private TextTranslator textTranslator;
+
+ private String inputText;
+ private String translation;
+
+ // action method, perhaps
+ public void translate() {
+ translation = textTranslator.translate(inputText);
+ }
+
+ public String getInputText() {
+ return inputText;
+ }
+
+ public void setInputText(String text) {
+ this.inputText = text;
+ }
+
+ public String getTranslation() {
+ return translation;
+ }
}]]></programlisting>
- <para>Alternatively, we may obtain an instance by directly calling a method
- of the Web Bean manager:</para>
+ <para>
+ Notice that it isn't necessary to create a getter or setter method to inject one bean into another. CDI can
+ access the field directly (even if it's private!), which should help eliminate some wasteful code. The name of
+ the field is arbitrary. It's the field's type that determines what is injected.
+ </para>
+
+ <para>
+ At system initialization time, the bean manager must validate that exactly one bean exists which satisfies each
+ injection point. In our example, if no implementation of <literal>Translator</literal> is available -- if
+ the <literal>SentenceTranslator</literal> EJB was not deployed -- the bean manager would throw an
+ <literal>UnsatisfiedDependencyException</literal>. If more than one implementation of
+ <literal>Translator</literal> were available, the bean manager would throw an
+ <literal>AmbiguousDependencyException</literal>. The same for the <literal>TextTranslator</literal> injection
+ point.
+ </para>
- <programlisting role="JAVA"><![CDATA[TextTranslator tt = manager.getInstanceByType(TextTranslator.class);]]></programlisting>
+ <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?
+ </para>
- <para>But wait: <literal>TextTranslator</literal> does not have a constructor
- with no parameters! Is it still a Web Bean? Well, a class that does not have a
- constructor with no parameters can still be a Web Bean if it has a constructor
- annotated <literal>@Initializer</literal>.</para>
-
- <para>As you've guessed, the <literal>@Initializer</literal> annotation has
- something to do with dependency injection! <literal>@Initializer</literal>
- may be applied to a constructor or method of a Web Bean, and tells the
- Web Bean manager to call that constructor or method when instantiating the
- Web Bean. The Web Bean manager will inject other Web Beans to the parameters
- of the constructor or method.</para>
-
- <para>At system initialization time, the Web Bean manager must validate that
- exactly one Web Bean exists which satisfies each injection point. In our example,
- if no implementation of <literal>Translator</literal> available — if the
- <literal>SentenceTranslator</literal> EJB was not deployed — the Web Bean
- manager would throw an <literal>UnsatisfiedDependencyException</literal>. If
- more than one implementation of <literal>Translator</literal> was available,
- the Web Bean manager would throw an
- <literal>AmbiguousDependencyException</literal>.</para>
-
- </section>
+ </section>
+
+ <!-- mention alternatives here? -->
+ <section id="bean-anatomy">
+ <title>The anatomy of a bean</title>
-<section>
- <title>What is a Web 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
+ managed automatically by the bean manager. Most beans are <emphasis>stateful</emphasis> and
+ <emphasis>contextual</emphasis>. The lifecycle of a bean is always managed by the bean manager.
+ </para>
- <para>So what, <emphasis>exactly</emphasis>, is a Web Bean?</para>
+ <para>
+ Let's back up a second. What does it really mean to be <emphasis>contextual</emphasis>? Since beans may be
+ stateful, it matters <emphasis>which</emphasis> bean instance I have. Unlike a stateless component model (for
+ example, stateless session beans) or a singleton component model (such as servlets, or singleton beans),
+ different clients of a bean see the bean in different states. The client-visible state depends upon which
+ instance of the bean the client has a reference to.
+ </para>
- <para>A Web Bean is an application class that contains business logic. A Web
- Bean may be called directly from Java code, or it may be invoked via Unified EL.
- A Web Bean may access transactional resources. Dependencies between Web Beans
- are managed automatically by the Web Bean manager. Most Web Beans are
- <emphasis>stateful</emphasis> and <emphasis>contextual</emphasis>. The lifecycle
- of a Web Bean is always managed by the Web Bean manager.</para>
+ <para>
+ However, like a stateless or singleton model, but <emphasis>unlike</emphasis> stateful session beans, the
+ client does not control the lifecycle of the instance by explicitly creating and destroying it. Instead, the
+ <emphasis>scope</emphasis> of the bean determines:
+ </para>
- <para>Let's back up a second. What does it really mean to be "contextual"? Since
- Web Beans may be stateful, it matters <emphasis>which</emphasis> bean instance I
- have. Unlike a stateless component model (for example, stateless session beans)
- or a singleton component model (such as servlets, or singleton beans), different
- clients of a Web Bean see the Web Bean in different states. The client-visible
- state depends upon which instance of the Web Bean the client has a reference to.</para>
-
- <para>However, like a stateless or singleton model, but <emphasis>unlike</emphasis>
- stateful session beans, the client does not control the lifecycle of the instance
- by explicitly creating and destroying it. Instead, the <emphasis>scope</emphasis>
- of the Web Bean determines:</para>
-
- <itemizedlist>
- <listitem>
- <para>the lifecycle of each instance of the Web Bean and</para>
- </listitem>
- <listitem>
- <para>which clients share a reference to a particular instance of the Web
- Bean.</para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>the lifecycle of each instance of the bean and</para>
+ </listitem>
+ <listitem>
+ <para>which clients share a reference to a particular instance of the bean.</para>
+ </listitem>
+ </itemizedlist>
- <para>For a given thread in a Web Beans application, there may be an
- <emphasis>active context</emphasis> associated with the scope of the Web Bean.
- This context may be unique to the thread (for example, if the Web Bean is request
- scoped), or it may be shared with certain other threads (for example, if the Web
- Bean is session scoped) or even all other threads (if it is application scoped).</para>
+ <para>
+ For a given thread in a CDI application, there may be an <emphasis>active context</emphasis> associated with
+ the scope of the bean. This context may be unique to the thread (for example, if the bean is request scoped),
+ or it may be shared with certain other threads (for example, if the bean is session scoped) or even all other
+ threads (if it is application scoped).
+ </para>
- <para>Clients (for example, other Web Beans) executing in the same context will
- see the same instance of the Web Bean. But clients in a different context will
- see a different instance.</para>
+ <para>
+ Clients (for example, other beans) executing in the same context will see the same instance of the bean. But
+ clients in a different context may see a different instance (depending on the relationship between the
+ contexts).
+ </para>
- <para>One great advantage of the contextual model is that it allows stateful
- Web Beans to be treated like services! The client need not concern itself with
- managing the lifecycle of the Web Bean it is using, <emphasis>nor does it even
- need to know what that lifecyle is.</emphasis> Web Beans interact by passing
- messages, and the Web Bean implementations define the lifecycle of their own state.
- The Web Beans are loosely coupled because:</para>
+ <para>
+ One great advantage of the contextual model is that it allows stateful beans to be treated like services! The
+ client need not concern itself with managing the lifecycle of the bean it's using, <emphasis>nor does it even
+ need to know what that lifecyle is.</emphasis> Beans interact by passing messages, and the bean implementations
+ define the lifecycle of their own state. The beans are loosely coupled because:
+ </para>
- <itemizedlist>
- <listitem>
- <para>they interact via well-defined public APIs</para>
- </listitem>
- <listitem>
- <para>their lifecycles are completely decoupled</para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>they interact via well-defined public APIs</para>
+ </listitem>
+ <listitem>
+ <para>their lifecycles are completely decoupled</para>
+ </listitem>
+ </itemizedlist>
- <para>We can replace one Web Bean with a different Web Bean that implements the
- same API and has a different lifecycle (a different scope) without affecting the
- other Web Bean implementation. In fact, Web Beans defines a sophisticated
- facility for overriding Web Bean implementations at deployment time, as we will
- see in <xref linkend="deploymenttypes"/>.</para>
+ <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).
+ </para>
- <para>Note that not all clients of a Web Bean are Web Beans. Other objects
- such as Servlets or Message-Driven Beans — which are by nature not injectable,
- contextual objects — may also obtain references to Web Beans by injection.</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
+ injection.
+ </para>
- <para>Enough hand-waving. More formally, according to the spec:</para>
+ <para>Enough hand-waving. More formally, the anatomy of a bean, according to the spec:</para>
- <blockquote>
+ <blockquote>
- <para>A Web Bean comprises:</para>
+ <para>A bean comprises of the following attributes:</para>
- <itemizedlist>
- <listitem><para>A (nonempty) set of API types</para></listitem>
- <listitem><para>A (nonempty) set of binding annotation types</para></listitem>
- <listitem><para>A scope</para></listitem>
- <listitem><para>A deployment type</para></listitem>
- <listitem><para>Optionally, a Web Bean name</para></listitem>
- <listitem><para>A set of interceptor binding types</para></listitem>
- <listitem><para>A Web Bean implementation</para></listitem>
- </itemizedlist>
+ <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>
- </blockquote>
+ </blockquote>
- <para>Let's see what some of these terms mean, to the Web Bean developer.</para>
+ <para>Let's see what some of these terms mean, to the CDI developer.</para>
-<section>
- <title>API types, binding types and dependency injection</title>
+ <section>
+ <title>Bean types, qualifiers and dependency injection</title>
- <para>Web Beans usually acquire references to other Web Beans via dependency
- injection. Any injected attribute specifies a "contract" that must be
- satisfied by the Web Bean to be injected. The contract is:</para>
+ <para>
+ Beans usually acquire references to other beans via dependency injection. Any injected attribute specifies a
+ "contract" that must be satisfied by the bean to be injected. The contract is:
+ </para>
- <itemizedlist>
- <listitem><para>an API type, together with</para></listitem>
- <listitem><para>a set of binding types.</para></listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem><para>a bean type, together with</para></listitem>
+ <listitem><para>a set of qualifiers.</para></listitem>
+ </itemizedlist>
- <para>An API is a user-defined class or interface. (If the Web Bean is an
- EJB session bean, the API type is the <literal>@Local</literal> interface or
- bean-class local view). A binding type represents some client-visible semantic
- that is satisfied by some implementations of the API and not by others.</para>
+ <para>
+ A bean type is a user-defined class or interface; types that are 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>
- <para>Binding types are represented by user-defined annotations that are
- themselves annotated <literal>@BindingType</literal>. For example, the following
- injection point has API type <literal>PaymentProcessor</literal> and binding
- type <literal>@CreditCard</literal>:</para>
+ <programlisting role="JAVA"><![CDATA[public class BookShop extends Business implements Shop<Book> {
+ ...
+}]]></programlisting>
-<programlisting role="JAVA"><![CDATA[@CreditCard PaymentProcessor paymentProcessor]]></programlisting>
+ <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.
+ </para>
- <para>If no binding type is explicitly specified at an injection point, the
- default binding type <literal>@Current</literal> is assumed.</para>
+ <programlisting role="JAVA"><![CDATA[@Stateful
+public class BookShopBean extends Business implements BookShop, Auditable {
+ ...
+}]]></programlisting>
- <para>For each injection point, the Web Bean manager searches for a Web Bean
- which satisfies the contract (implements the API, and has all the binding
- types), and injects that Web Bean.</para>
+ <note>
+ <para>
+ Most bean types you can probably figure out. One gotcha is primitive types. All primitive types are assumed
+ to be identical to their corresponding wrapper types in <literal>java.lang</literal>.
+ </para>
+ </note>
- <para>The following Web Bean has the binding type <literal>@CreditCard</literal>
- and implements the API type <literal>PaymentProcessor</literal>. It could
- therefore be injected to the example injection point:</para>
+ <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>:
+ </para>
-<programlisting role="JAVA"><![CDATA[@CreditCard
-public class CreditCardPaymentProcessor
- implements PaymentProcessor { ... }]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[@Typed(Shop.class)
+public class BookShop extends Business implements Shop<Book> {
+ ...
+}]]></programlisting>
- <para>If a Web Bean does not explicitly specify a set of binding types, it has
- exactly one binding type: the default binding type <literal>@Current</literal>.</para>
+ <para>
+ The bean types alone often do not provide enough information for the bean manager to know which bean to
+ inject. For instance, say you 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
+ bean manager must rely on some client-visible semantic that is satisified by one implementation of the bean
+ type, but not by others. That semantic is called a qualifier.
+ </para>
- <para>Web Beans defines a sophisticated but intuitive <emphasis>resolution
- algorithm</emphasis> that helps the container decide what to do if there is more
- than one Web Bean that satisfies a particular contract. We'll get into the
- details in <xref linkend="injection"/>.</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 many dependency injection frameworks use.
+ Here's an example of a qualifier annotation:
+ </para>
-</section>
+ <programlisting role="JAVA"><![CDATA[@Target( { TYPE, METHOD, PARAMETER, FIELD })
+ at Retention(RUNTIME)
+ at Documented
+ at Qualifier
+public @interface CreditCard {}]]></programlisting>
-<section>
- <title>Deployment types</title>
+ <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.
+ </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.
+ </para>
+ </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>:
+ </para>
- <para><emphasis>Deployment types</emphasis> let us classify our Web Beans by
- deployment scenario. A deployment type is an annotation that represents a particular
- deployment scenario, for example <literal>@Mock</literal>, <literal>@Staging</literal>
- or <literal>@AustralianTaxLaw</literal>. We apply the annotation to Web Beans which
- should be deployed in that scenario. A deployment type allows a whole set of Web Beans
- to be conditionally deployed, with a just single line of configuration.</para>
+ <programlisting role="JAVA"><![CDATA[@Inject @CreditCard PaymentProcessor paymentProcessor]]></programlisting>
- <para>Many Web Beans just use the default deployment type <literal>@Production</literal>,
- in which case no deployment type need be explicitly specified. All three Web Bean
- in our example have the deployment type <literal>@Production</literal>.</para>
+ <note>
+ <para>
+ If no qualifier is specified at an injection point, the default qualifier, <literal>@Default</literal>, is
+ assumed.
+ </para>
+ </note>
- <para>In a testing environment, we might want to replace the <literal>SentenceTranslator</literal>
- Web Bean with a "mock object":</para>
+ <para>
+ For each injection point, the bean manager searches for a bean which satisfies the contract, meaning it
+ matches the bean time and all the qualifiers. It then injects that instance.
+ </para>
-<programlisting role="JAVA"><![CDATA[@Mock
-public class MockSentenceTranslator implements Translator {
- public String translate(String sentence) {
- return "Lorem ipsum dolor sit amet";
- }
-}]]></programlisting>
+ <para>
+ We've seen how to indicate that you want to inject 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:
+ </para>
+ <programlisting role="JAVA"><![CDATA[@CreditCard
+public class CreditCardPaymentProcessor
+ implements PaymentProcessor { ... }]]></programlisting>
- <para>We would enable the deployment type <literal>@Mock</literal> in our testing
- environment, to indicate that <literal>MockSentenceTranslator</literal> and any other
- Web Bean annotated <literal>@Mock</literal> should be used.</para>
+ <note>
+ <para>
+ If a bean does not explicitly specify a qualifier, it has exactly one qualifier, the default qualifier,
+ <literal>@Default</literal>.
+ </para>
+ </note>
- <para>We'll talk more about this unique and powerful feature in
- <xref linkend="deploymenttypes"/>.</para>
+ <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"/>.
+ </para>
-</section>
+ </section>
-<section>
- <title>Scope</title>
+ <section>
+ <title>Scope</title>
+ <!-- I wonder whether the explaination of contextual above would fit better here -->
- <para>The <emphasis>scope</emphasis> defines the lifecycle and visibility
- of instances of the Web Bean. The Web Beans context model is extensible,
- accommodating arbitrary scopes. However, certain important scopes are
- built-in to the specification, and provided by the Web Bean manager. A
- scope is represented by an annotation type.</para>
+ <para>
+ The <emphasis>scope</emphasis> of a bean defines the lifecycle and visibility of instances created from it.
+ The CDI context model is extensible, accommodating arbitrary scopes. However, certain important scopes are
+ built-in to the specification, and provided by the bean manager. Each scope is represented by an annotation
+ type.
+ </para>
- <para>For example, any web application may have <emphasis>session scoped</emphasis>
- Web Beans:</para>
+ <para>
+ For example, any web application may have <emphasis>session scoped</emphasis> bean:
+ </para>
-<programlisting role="JAVA"><![CDATA[@SessionScoped
+ <programlisting role="JAVA"><![CDATA[@SessionScoped
public class ShoppingCart { ... }]]></programlisting>
- <para>An instance of a session scoped Web Bean is bound to a user session
+ <para>An instance of a session-scoped bean is bound to a user session
and is shared by all requests that execute in the context of that session.</para>
- <para>By default, Web Beans belong to a special scope called the
- <emphasis>dependent pseudo-scope</emphasis>. Web Beans with this scope are
- pure dependent objects of the object into which they are injected, and their
- lifecycle is bound to the lifecycle of that object.</para>
+ <note>
+ <para>
+ Keep in mind that once a bean is bound to a context, it remains in that context until the context is
+ destroyed. There is no way to explicitly remove a bean from a context. If you don't the bean to live in
+ the session indefinitely, consider using another scope such as the request or conversation scope instead.
+ </para>
+ </note>
- <para>We'll talk more about scopes in <xref linkend="scopescontexts"/>.</para>
+ <para>
+ If a scope is not explicitly specified, then the bean belongs to a special scope called the
+ <emphasis>dependent pseudo-scope</emphasis>. Beans with this scope live to serve the bean into which they
+ are injected, which means their life cycle is bound to the life cycle of that object.
+ </para>
-</section>
+ <para>We'll talk more about scopes in <xref linkend="scopescontexts"/>.</para>
-<section>
- <title>Web Bean names and Unified EL</title>
+ </section>
- <para>A Web Bean may have a <emphasis>name</emphasis>, allowing it to be
- used in Unified EL expressions. It's easy to specify the name of a Web
- Bean:</para>
+ <section>
+ <title>EL name</title>
-<programlisting role="JAVA"><![CDATA[@SessionScoped @Named("cart")
+ <para>
+ If you want to reference a bean outside of Java, such as in 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.
+ </para>
+
+ <para>
+ The name is specified using the <literal>@Named</literal> annotation, as shown here:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@SessionScoped @Named("cart")
public class ShoppingCart { ... }]]></programlisting>
- <para>Now we can easily use the Web Bean in any JSF or JSP page:</para>
+ <para>Now we can easily use the bean in any JSF or JSP page:</para>
-<programlisting role="HTML"><![CDATA[<h:dataTable value="#{cart.lineItems}" var="item">
- ....
+ <programlisting role="XML"><![CDATA[<h:dataTable value="#{cart.lineItems}" var="item">
+ ...
</h:dataTable>]]></programlisting>
- <para>It's even easier to just let the name be defaulted by the Web Bean
- manager:</para>
+ <note>
+ <para>
+ The <literal>@Named</literal> annotation is not what makes the class a bean. Most classes in a bean
+ archive are already recognized as beans. The <literal>@Named</literal> annotation just makes it
+ possible to reference the bean from the EL, most commonly from a JSF view.
+ </para>
+ </note>
-<programlisting role="JAVA"><![CDATA[@SessionScoped @Named
+ <para>
+ If you want, you can let CDI select a name for you by leaving off the
+ value of the <literal>@Named</literal> annotation:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@SessionScoped @Named
public class ShoppingCart { ... }]]></programlisting>
- <para>In this case, the name defaults to <literal>shoppingCart</literal> — the
- unqualified class name, with the first character changed to lowercase.</para>
+ <para>
+ The name defaults to the unqualified class name, decapitalized; in this case,
+ <literal>shoppingCart</literal>.
+ </para>
-</section>
+ </section>
-<section>
- <title>Interceptor binding types</title>
-
- <para>Web Beans supports the interceptor functionality defined by EJB 3,
- not only for EJB beans, but also for plain Java classes. In addition,
- Web Beans provides a new approach to binding interceptors to EJB beans
- and other Web Beans.</para>
-
- <para>It remains possible to directly specify the interceptor class via
- use of the <literal>@Interceptors</literal> annotation:</para>
-
-<programlisting role="JAVA"><![CDATA[@SessionScoped
- at Interceptors(TransactionInterceptor.class)
-public class ShoppingCart { ... }]]></programlisting>
+ <section>
+ <title>Alternatives</title>
- <para>However, it is more elegant, and better practice, to indirect the
- interceptor binding through an <emphasis>interceptor binding
- type</emphasis>:</para>
-
-<programlisting role="JAVA"><![CDATA[@SessionScoped @Transactional
+ <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.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Alternative
+public class MockPaymentProcessor extends PaymentProcessorImpl { ... }]]></programlisting>
+
+ <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.
+ </para>
+
+ </section>
+
+ <section>
+ <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
+ intercept method calls. Holler. So what does CDI have to offer? Well, a lot actually. Let's cover some
+ background.
+ </para>
+
+ <para>
+ The way that interceptors are defined in Java EE 5 is counter-intuitive. You are required to specify the
+ <emphasis>implementation</emphasis> of the interceptor directly on the <emphasis>implementation</emphasis>
+ of the EJB, either in the <literal>@Interceptors</literal> annotation or in the XML descriptor. You might as
+ well just put the interceptor code <emphasis>in</emphasis> the implementation. Second, the order in which
+ the interceptors are applied is taken from the order in which they are declared in the annotation or the XML
+ descriptor. Perhaps this isn't so bad if you're applying the interceptors to a single bean. But, if you are
+ applying them repeatly, then there is a chance that you'll inadvertly define a different order for different
+ beans. Now that is a problem.
+ </para>
+
+ <para>
+ CDI provides a new approach to binding interceptors to beans that introduces a level of abstraction (and
+ thus control). You define a special kind of annotation called an <emphasis>interceptor binding
+ type</emphasis> whose name describes the role of the interceptor, in this case to add transaction support:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@InterceptorBinding
+ at Inherited
+ at Target( { TYPE, METHOD })
+ at Retention(RUNTIME)
+public @interface Transactional {}]]></programlisting>
+
+ <para>
+ Then you apply the annotation to the class whose methods you wish to have intercepted.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@SessionScoped @Transactional
public class ShoppingCart { ... }]]></programlisting>
- <para>We'll discuss Web Beans interceptors and decorators in
- <xref linkend="interceptors"/> and <xref linkend="decorators"/>.</para>
+ <para>
+ Where is the interceptor? You match the interceptor(s) to apply to the bean by also annotating the
+ interceptor class. Never do the two implementations (bean and interceptor) come in direct contact.
+ Activating and ordering of the interceptors is then controlled by the XML descriptor, one of the few times
+ XML is warranted.
+ </para>
+
+ <para>
+ We'll discuss bean interceptors, and their cousins, decorators, in <xref linkend="interceptors"/> and <xref
+ linkend="decorators"/>.
+ </para>
-</section>
+ </section>
-</section>
+ </section>
-<section>
- <title>What kinds of objects can be Web Beans?</title>
-
- <para>We've already seen that JavaBeans, EJBs and some other Java classes can
- be Web Beans. But exactly what kinds of objects are Web Beans?</para>
-
- <section>
- <title>Simple Web Beans</title>
-
- <para>The Web Beans specification says that a concrete Java class is a
- <emphasis>simple</emphasis> Web Bean if:</para>
-
- <itemizedlist>
- <listitem>
- <para>it is not an EE container-managed component, like an EJB, a Servlet
- or a JPA entity,</para>
- </listitem>
- <listitem>
- <para>it is not a non-static static inner class,</para>
- </listitem>
- <listitem>
- <para>it is not a parameterized type, and</para>
- </listitem>
- <listitem>
- <para>it has a constructor with no parameters, or a constructor annotated
- <literal>@Initializer</literal>.</para>
- </listitem>
- </itemizedlist>
-
- <para>Thus, almost every JavaBean is a simple Web Bean.</para>
-
- <para>Every interface implemented directly or indirectly by a simple Web Bean
- is an API type of the simple Web Bean. The class and its superclasses are also
- API types.</para>
-
- </section>
-
- <section>
- <title>Enterprise Web Beans</title>
-
- <para>The specification says that all EJB 3-style session and singleton beans
- are <emphasis>enterprise</emphasis> Web Beans. Message driven beans are not
- Web Beans — since they are not intended to be injected into other
- objects — but they can take advantage of most of the functionality of Web
- Beans, including dependency injection and interceptors.</para>
-
- <para>Every local interface of an enterprise Web Bean that does not have a
- wildcard type parameter or type variable, and every one of its superinterfaces,
- is an API type of the enterprise Web Bean. If the EJB bean has a bean class
- local view, the bean class, and every one of its superclasses, is also an API
- type.</para>
-
- <para>Stateful session beans should declare a remove method with no parameters
- or a remove method annotated <literal>@Destructor</literal>. The Web Bean
- manager calls this method to destroy the stateful session bean instance at the
- end of its lifecycle. This method is called the <emphasis>destructor</emphasis>
- method of the enterprise Web Bean.</para>
-
-<programlisting role="JAVA"><![CDATA[@Stateful @SessionScoped
-public class ShoppingCart {
+ <section>
+ <title>What kinds of classes can be beans?</title>
+
+ <para>
+ We've already seen that JavaBeans and EJBs can be (CDI) beans. Is that the whole story? Let's start from what
+ we know, and go from there.
+ </para>
+
+ <section>
+ <title>Managed beans</title>
- ...
-
- @Remove
- public void destroy() {}
+ <para>
+ A managed bean is a bean that is implemented by almost any Java class. This class is called the bean class
+ of the managed bean. The basic lifecycle and semantics of a managed bean is defined by the Managed Beans
+ specification. If the class is not picked up as a managed bean by the container, then CDI will allow it
+ to be a bean if:
+ </para>
-}]]></programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>It is not a non-static inner class.</para>
+ </listitem>
+ <listitem>
+ <para>It is a concrete class, or is annotated <literal>@Decorator</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>
+ It is not annotated with an EJB component-defining annotation or declared as an EJB bean class in
+ ejb-jar.xml.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It has an appropriate constructor -- either:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>the class has a constructor with no parameters, or</para>
+ </listitem>
+ <listitem>
+ <para>the class declares a constructor annotated <literal>@Inject</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
- <para>So when should we use an enterprise Web Bean instead of a simple Web Bean?
- Well, whenever we need the advanced enterprise services offered by EJB, such
- as:</para>
-
-
- <itemizedlist>
- <listitem>
- <para>method-level transaction management and security,</para>
- </listitem>
- <listitem>
- <para>concurrency management,</para>
- </listitem>
- <listitem>
- <para>instance-level passivation for stateful session beans and
- instance-pooling for stateless session beans,</para>
- </listitem>
- <listitem>
- <para>remote and web service invocation, and</para>
- </listitem>
- <listitem>
- <para>timers and asynchronous methods,</para>
- </listitem>
- </itemizedlist>
-
- <para>we should use an enterprise Web Bean. When we don't need any of these things,
- a simple Web Bean will serve just fine.</para>
-
- <para>Many Web Beans (including any session or application scoped Web Bean) are
- available for concurrent access. Therefore, the concurrency management provided
- by EJB 3.1 is especially useful. Most session and application scoped Web Beans
- should be EJBs.</para>
-
- <para>Web 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 support for passivation and instance pooling.</para>
-
- <para>Finally, it's usually obvious when method-level transaction management,
- method-level security, timers, remote methods or asynchronous methods are needed.</para>
-
- <para>It's usually easy to start with simple Web Bean, and then turn it into an
- EJB, just by adding an annotation: <literal>@Stateless</literal>,
- <literal>@Stateful</literal> or <literal>@Singleton</literal>.</para>
+ <para>
+ <emphasis>Unlike</emphasis> the managed bean definition, no special declaration is required to define a
+ managed bean. CDI takes advantage of the fact that the Managed Bean specification allows companion
+ specifications to relax the requirement of having to add the <literal>@ManagedBean</literal> annotation.
+ </para>
- </section>
-
- <section>
- <title>Producer methods</title>
+ <para>
+ Some managed beans are much more. Those are the session beans. While still technically managed beans, they
+ have enough additional, enterprise features, that we consider them to be their own kind.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Session beans</title>
- <para>A <emphasis>producer method</emphasis> is a method that is called by the
- Web Bean manager to obtain an instance of the Web Bean when no instance exists
- in the current context. A producer method lets the application take full control
- of the instantiation process, instead of leaving instantiation to the Web Bean
- manager. For example:</para>
+ <para>
+ EJB 3 session beans belong to the EJB specification. That is, the basic life cycle and semantics. Beyond
+ that, they get to participate in CDI just like any other bean. There are some restrictions about which
+ scopes can be assigned to a session bean, but other than that, they are interchangable with regular managed
+ beans. That means you can inject one session bean into another, 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>
-<programlisting role="JAVA"><![CDATA[@ApplicationScoped
-public class Generator {
+ <note>
+ <para>
+ Message-driven and entity beans are by nature non-contextual objects and may not be injected into other
+ objects. Message-driven beans can take advantage of some CDI functionality, such as dependency injection
+ and interceptors. In fact, CDI will perform injection into any message-driven or session bean, even those
+ which are not contextual instances.
+ </para>
+ </note>
- private Random random = new Random( System.currentTimeMillis() );
-
- @Produces @Random int next() {
- return random.nextInt(100);
- }
+ <para>
+ 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
+ types.
+ </para>
+ <para>
+ Stateful session beans can define a no arguments remove method, annotated <literal>@Remove</literal>, that
+ is used by the application to indicate the instance should be destroyed. However, in a CDI environment, this
+ method can only be executed by the application if the bean is dependent-scoped. Otherwise, it's illegal for
+ the application to invoke this method.
+ </para>
+
+ <para>
+ So, when should we use a session instead of a basic managed bean? Whenever we need the advanced enterprise
+ services offered by EJB, such as:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>method-level transaction management and security,</para>
+ </listitem>
+ <listitem>
+ <para>concurrency management,</para>
+ </listitem>
+ <listitem>
+ <para>instance-level passivation for stateful session beans and
+ instance-pooling for stateless session beans,</para>
+ </listitem>
+ <listitem>
+ <para>remote and web service invocation, and</para>
+ </listitem>
+ <listitem>
+ <para>timers and asynchronous methods,</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>When we don't need any of these things, a basic managed bean will serve just fine.</para>
+
+ <para>
+ Many beans (including any session or application scoped bean) are available for concurrent access.
+ Therefore, the concurrency management provided by EJB 3.1 is especially useful. Most session and application
+ scoped beans should be EJBs.
+ </para>
+
+ <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
+ support for passivation and instance pooling.
+ </para>
+
+ <para>
+ Finally, it's usually obvious when method-level transaction management, method-level security, timers,
+ remote methods or asynchronous methods are needed.
+ </para>
+
+ <para>
+ The point is, you use a session bean when you need the services it provides, not just because you want to
+ use dependency injection, life cycle management, or interceptors. The Java EE programming model makes a
+ whole lot more sense now; you won't need to go off and invent your own bean container to make programming
+ in Java EE palatable.
+ </para>
+
+ <para>
+ In fact, it's easy to start with simple managed bean, and later turn it into an EJB just by adding one of
+ the following annotations: <literal>@Stateless</literal>, <literal>@Stateful</literal> or
+ <literal>@Singleton</literal>.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Producer methods</title>
+
+ <para>
+ Surely not everything you want to inject can be a bean class. What if you need to inject the implementation
+ of an API that varies at runtime? And how would you inject objects that are created by another mechanism,
+ such as a JPA result? Fortunately, the CDI specification recognized these and other cases and introduced the
+ concept of a producer method.
+ </para>
+
+ <para>
+ A <emphasis>producer method</emphasis> is a method on a bean that is used as a bean source, meaning the
+ method itself describes the bean and the bean manager invokes the method to obtain an instance of the bean
+ when no instance exists in its specified context. A producer method lets the application take full control
+ of the instantiation process, specifically when:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ the objects to be injected are not required to be instances of beans, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the concrete type of the objects to be injected may vary at runtime, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the objects require some custom initialization that is not performed by the bean constructor.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ For example:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@ApplicationScoped
+public class RandomNumberGenerator {
+
+ private Random random = new Random(System.currentTimeMillis());
+
+ @Produces @Named @Random int getRandomNumber() {
+ return random.nextInt(100);
+ }
+
}]]></programlisting>
- <para>The result of a producer method is injected just like any other Web Bean.</para>
+ <para>
+ Obviously, you cannot define a bean that is itself a random number. A producer method allows you do define
+ its result as a bean, in this case an <literal>Integer</literal> with qualifier <literal>@Random</literal>,
+ scope <literal>@Dependent</literal> (implied) and name <literal>randomNumber</literal> (derived from bean
+ property convention; otherwise it would be the same as the method name). It can be injected just like any
+ other bean:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Inject @Random int randomNumber;]]></programlisting>
- <programlisting role="JAVA"><![CDATA[@Random int randomNumber]]></programlisting>
-
- <para>The method return type and all interfaces it extends/implements directly or indirectly
- are API types of the producer method. If the return type is a class, all superclasses are
- also API types.</para>
-
- <para>Some producer methods return objects that require explicit destruction:</para>
-
-<programlisting role="JAVA"><![CDATA[@Produces @RequestScoped Connection connect(User user) {
- return createConnection( user.getId(), user.getPassword() );
+ <para>
+ or used in a Unified EL expression:
+ </para>
+
+ <programlisting><![CDATA[Your raffle number is #{randomNumber}.]]></programlisting>
+
+ <para>
+ A producer method must be a non-abstract method of a managed bean class or session bean class. A producer
+ method may be either static or non-static. If the bean is a session bean, the producer method must be either
+ a business method of the EJB or a static method of the bean class.
+ </para>
+
+ <para>
+ The bean types of a producer method depend upon the method return type:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ If the return type is an interface, the unrestricted set of bean types contains the return type, all
+ interfaces it extends directly or indirectly and <literal>java.lang.Object</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If a return type is primitive or is a Java array type, the unrestricted set of bean types contains
+ exactly two types: the method return type and <literal>java.lang.Object</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the return type is a class, the unrestricted set of bean types contains the return type, every
+ superclass and all interfaces it implements directly or indirectly.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Some producer methods return objects that require explicit destruction:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Produces @RequestScoped Connection connect(User user) {
+ return createConnection(user.getId(), user.getPassword());
}]]></programlisting>
- <para>These producer methods may define matching <emphasis>disposal methods</emphasis>:</para>
-
-<programlisting role="JAVA"><![CDATA[void close(@Disposes Connection connection) {
- connection.close();
+ <para>
+ If the producer method has method arguments, as in this example, the container will look for matching beans
+ and pass them into the method automatically -- another form of dependency injection.
+ </para>
+
+ <para>Producer methods may also define matching <emphasis>disposal methods</emphasis>:</para>
+
+ <programlisting role="JAVA"><![CDATA[void close(@Disposes Connection connection) {
+ connection.close();
}]]></programlisting>
+
+ <para>
+ The disposal method is called automatically when the context ends (in this case, the end of the request).
+ The disposal method requires at least one parameter, the bean produced by the producer method. Any
+ additional parameters will be satisfied by the container.
+ </para>
+
+ <para>We'll talk much more about producer and disposal methods in <xref linkend="producermethods"/>.</para>
+
+ </section>
- <para>This disposal method is called automatically by the Web Bean manager at
- the end of the request.</para>
+ <section>
+ <title>Producer fields</title>
- <para>We'll talk much more about producer methods in <xref linkend="producermethods"/>.</para>
+ <para>
+ A <emphasis>producer field</emphasis> is a simpler alternative to a producer method and can also marry
+ dependency injection with bean definition. A producer field may be declared by annotating a field of a
+ managed bean class or session bean class with the <literal>@Produces</literal> annotation previously used on
+ producer methods.
+ </para>
- </section>
+ <programlisting role="JAVA"><![CDATA[public class Shop {
+ @Produces PaymentProcessor paymentProcessor = ....;
+ @Produces List<Product> products = ....;
+}]]></programlisting>
- <section>
- <title>JMS endpoints</title>
-
- <para>Finally, a JMS queue or topic can be a Web Bean. Web Beans relieves the
- developer from the tedium of managing the lifecycles of all the various JMS
- objects required to send messages to queues and topics. We'll discuss JMS
- endpoints in <xref linkend="jms"/>.</para>
-
- </section>
+ <para>
+ A producer field may also specify scope, name, stereotypes and/or qualifiers. It's a good way to expose
+ state from a bean as a top-level bean.
+ </para>
-</section>
+ <programlisting role="JAVA"><![CDATA[public class Shop {
+ @Produces @Wishlist @Named("wishlist") List<Product> products = ....;
+}]]></programlisting>
-</chapter>
\ No newline at end of file
+ <para>
+ The result can be injected or used in a Unified EL expression.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Inject @Wishlist List<Product> wishlist;]]></programlisting>
+ <programlisting role="XML"><![CDATA[<h:dataTable var="_product" value="#{wishlist}">...</h:dataTable>]]></programlisting>
+
+ <para>
+ The rules for determining the bean types of a producer field parallel the rules for producer method.
+ </para>
+
+ <para>
+ Aside from convenience, producer fields serve a specific purpose as an adapter for Java EE resources
+ injections.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Java EE resources</title>
+
+ <para>
+ Java EE 5 already introduced some support for dependency injection, in the form of resource injections. A
+ resources is either a component defined in JNDI such as a data source or a container-provided component such
+ as a persistence unit, persistence context, EJB or web service.
+ </para>
+
+ <para>
+ Naturally, there remained some mismatch with the new style of dependency injection in CDI. Most notably,
+ resource injections rely on string-based names to qualify ambigious types, and there is no real consistency
+ as to how a resource obtains its name (sometimes JNDI, other times from an XML descriptor or even a default
+ name). Producer fields turned out to be an elegant adapter to rein them in and get them to participate in
+ the CDI system just like any other injectable bean.
+ </para>
+
+ <para>
+ Producer fields have a duality in that they can both accept a standard Java EE resource injection and
+ produce a bean that can be injected into another bean in a typesafe way. Here are some examples of these
+ injection points. Notice that a qualifier annotation can be assigned at the injection point to adapt the
+ string-based name required by the injection point into a typesafe qualifier for injection elsewhere.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Produces @WebServiceRef(lookup="java:app/service/PaymentService")
+PaymentService paymentService;]]></programlisting>
+
+ <programlisting role="JAVA"><![CDATA[@Produces @PersistenceContext(unitName="CustomerDatabase")
+ at CustomerDatabase EntityManager customerDatabasePersistenceContext;]]></programlisting>
+
+ <para>
+ These resources can then be injected in the usual way.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Inject PaymentService paymentService;]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[@Inject @CustomerDatabase EntityManager customerDatabaseEntityManager;]]></programlisting>
+
+ <para>
+ The bean type and qualifiers of the resource are determined by the producer field declaration.
+ </para>
+
+ <para>
+ While you may have to introduce a couple extra managed beans to serve as typesafe adapters, it's well worth
+ the effort so that you can minimize the number of places in your code you have to repeat the old-style
+ dependency injection and string-based qualifiers.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Built-in beans</title>
+
+ <para>
+ Java EE gives you some other goodies in the form of built-in beans. A Java EE (or embeddable EJB) container
+ provide the following built-in beans, all of which have qualifier <literal>@Default</literal>:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ a bean with bean type <literal>javax.transaction.UserTransaction</literal>, allowing injection of a
+ reference to the JTA <literal>UserTransaction</literal>,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a bean with bean type <literal>javax.security.Principal</literal>, allowing injection of a
+ <literal>Principal</literal> representing the current caller identity.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a bean with bean type <literal>javax.validation.ValidationFactory</literal>, allowing injection of the
+ default <ulink src="http://jcp.org/en/jsr/detail?id=303">Bean Validation</ulink>
+ <literal>ValidationFactory</literal>, and
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a bean with bean type <literal>javax.validation.Validator</literal>, allowing injection of a Validator
+ for the default Bean Validation <literal>ValidationFactory</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Aren't you excited to start using this stuff? Wait no longer. In the next two chapters, we'll look at some
+ examples.
+ </para>
+
+ </section>
+
+ </section>
+
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
+</chapter>
Modified: doc/trunk/reference/en-US/master.xml
===================================================================
--- doc/trunk/reference/en-US/master.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/master.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -1,33 +1,33 @@
<?xml version='1.0' encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
-
<book lang="en">
- <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- <preface>
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <preface>
<title>Note</title>
<para>
- JSR-299 has recently changed its name from "Web Beans" to "Java
- Contexts and Dependency Injection". The reference guide still refers
- to JSR-299 as "Web Beans" and the JSR-299 Reference Implementation as
- the "Web Beans RI". Other documentation, blogs, forum posts etc. may
- use the new nomenclature, including the new name for the JSR-299
- Reference Implementation - "Web Beans".
+ Shortly before the final draft of JSR-299 was submitted, the specification changed its name from "Web Beans" to
+ "Java Contexts and Dependency Injection for the Java EE platform", abbreviated CDI. For a brief period after
+ the renaming, the reference implementation adopted the name "Web Beans". However, this ended up causing more
+ confusion than it solved and Red Hat decided to change the name of the reference implementation to "Weld". You
+ may still find other documentation, blogs, forum posts, etc. that use the old nomenclature. Please update any
+ references you can. The naming game is over.
</para>
-
+
<para>
- You'll also find that some of the more recent functionality to be
- specified is missing (such as producer fields, realization,
- asynchronous events, XML mapping of EE resources).
+ You'll also find that some of the functionality that once existed in the specification is now missing, such as
+ defining beans in XML. These features will be available as portable extensions for CDI in the Weld project, and
+ perhaps other implementations.
</para>
- </preface>
-
- <toc/>
-
- <part>
- <title>Using contextual objects</title>
+ </preface>
+
+ <toc/>
+
+ <part>
+ <title>Contextual components, loose-coupling and strong typing</title>
<xi:include href="part1.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -36,20 +36,20 @@
<xi:include href="injection.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="scopescontexts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="producermethods.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- </part>
-
- <part>
+
+ </part>
+
+ <part>
<title>Developing loosely-coupled code</title>
<xi:include href="part2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="interceptors.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="decorators.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- </part>
-
- <part>
+
+ </part>
+
+ <part>
<title>Making the most of strong typing</title>
<xi:include href="part3.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -58,33 +58,34 @@
<xi:include href="specialization.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- </part>
-
- <part>
- <title>Web Beans and the Java EE ecosystem</title>
+ </part>
+
+ <part>
+ <title>CDI and the Java EE ecosystem</title>
<xi:include href="part4.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="ee.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="extend.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ </part>
+
+ <xi:include href="next.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <part>
+ <title>Weld reference</title>
- </part>
-
- <xi:include href="next.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- <part>
- <title>Web Beans Reference</title>
-
<xi:include href="part5.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="environments.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="extensions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="viewlayers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- </part>
+
+ </part>
+
+ <xi:include href="ri-spi.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- <xi:include href="ri-spi.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
</book>
-
Modified: doc/trunk/reference/en-US/part1.xml
===================================================================
--- doc/trunk/reference/en-US/part1.xml 2009-10-27 18:16:18 UTC (rev 4351)
+++ doc/trunk/reference/en-US/part1.xml 2009-10-27 18:36:17 UTC (rev 4352)
@@ -1,129 +1,176 @@
-<!DOCTYPE partintro PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<!DOCTYPE partintro PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<partintro>
-<partintro>
+ <!-- This part could probably be split into a chapter of it's own, perhaps "Overview" with subsection for Concepts
+ and History -->
+
+<!-- this specification defines an SPI that allows alternative, non-platform technologies to integrate
+with the con-
+tainer, for example, alternative web presentation technologies.
+-->
+
+ <!-- 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 services provide:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ an improved lifecycle for stateful components, bound to well-defined <emphasis>contexts</emphasis>,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a typesafe approach to <emphasis>dependency injection</emphasis>,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ component 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
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ an <emphasis>SPI</emphasis> for developing portable extensions for the Java EE platform.
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>The Web Beans (JSR-299) specification defines a set of services for
- the Java EE environment that makes applications much easier to develop.
- Web Beans layers an enhanced lifecycle and interaction model over existing
- Java component types including JavaBeans and Enterprise Java Beans. As a
- complement to the traditional Java EE programming model, the Web Beans
- services provide:</para>
+ <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:
+ </para>
- <itemizedlist>
- <listitem>
- <para>an improved lifecycle for stateful components, bound to well-defined
- <emphasis>contexts</emphasis>,</para>
- </listitem>
- <listitem>
- <para>a typesafe approach to <emphasis>dependency injection</emphasis>,</para>
- </listitem>
- <listitem>
- <para>interaction via an <emphasis>event notification</emphasis> facility,
- and</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.</para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>all Managed Beans (JavaBeans), including JSF managed beans,</para>
+ </listitem>
+ <listitem>
+ <para>all Enterprise JavaBeans (EJBs), and</para>
+ </listitem>
+ <listitem>
+ <para>all Servlets.</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"/>).
+ </para>
- <para>Dependency injection, together with contextual lifecycle management,
- saves the user of an unfamiliar API from having to ask and answer the following
- questions:</para>
+ <para>
+ The concerns handled by CDI save the user who is unfamiliar with an API from having to answer the following
+ questions:
+ </para>
- <itemizedlist>
- <listitem>
- <para>what is the lifecycle of this object?</para>
- </listitem>
- <listitem>
- <para>how many simultaneous clients can it have?</para>
- </listitem>
- <listitem>
- <para>is it multithreaded?</para>
- </listitem>
- <listitem>
- <para>where can I get one from?</para>
- </listitem>
- <listitem>
- <para>do I need to explicitly destroy it?</para>
- </listitem>
- <listitem>
- <para>where should I keep my reference to it when I'm not
- using it directly?</para>
- </listitem>
- <listitem>
- <para>how can I add an indirection layer, so that the implementation
- of this object can vary at deployment time?</para>
- </listitem>
- <listitem>
- <para>how should I go about sharing this object between other objects?</para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>What is the lifecycle of this object?</para>
+ </listitem>
+ <listitem>
+ <para>How many simultaneous clients can it have?</para>
+ </listitem>
+ <listitem>
+ <para>Is it multithreaded?</para>
+ </listitem>
+ <listitem>
+ <para>How do I retrieve it?</para>
+ </listitem>
+ <listitem>
+ <para>Do I need to explicitly destroy it?</para>
+ </listitem>
+ <listitem>
+ <para>
+ Where should I keep the reference to it when I'm not currently using it?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ How can I define alternatives, so that the implementation of this object can vary at deployment time?
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ How should I go about sharing this object between other objects?
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ The main theme of CDI, which is instrumental in removing these complexities, is <emphasis>loose-couping with
+ strong typing</emphasis>. Let's study what that phrase means.
+ </para>
- <para>A Web Bean specifies only the type and semantics of other Web Beans
- it depends upon. It need not be aware of the actual lifecycle, concrete
- implementation, threading model or other clients of any Web Bean it depends
- upon. Even better, the concrete implementation, lifecycle and threading model
- of a Web Bean it depends upon may vary according to the deployment scenario,
- without affecting any client.</para>
+ <para>
+ A bean specifies only the type and semantics of other beans it depends upon. It need not be aware of the actual
+ lifecycle, concrete implementation, threading model or other clients of any bean it depends upon. Even better, the
+ concrete implementation, lifecycle and threading model of a bean it depends upon may vary according to the
+ deployment scenario, without affecting any client. This loose-coupling is what makes this architecture so simple,
+ yet powerful.
+ </para>
- <para>Events, interceptors and decorators enhance the <emphasis>loose-coupling</emphasis>
- that is inherent in this model:</para>
+ <para>
+ Events, interceptors and decorators enhance the <emphasis>loose-coupling</emphasis> inherent in this model:
+ </para>
- <itemizedlist>
- <listitem>
- <para><emphasis>event notifications</emphasis> decouple event producers
- from event consumers,</para>
- </listitem>
- <listitem>
- <para><emphasis>interceptors</emphasis> decouple technical concerns from
- business logic, and</para>
- </listitem>
- <listitem>
- <para><emphasis>decorators</emphasis> allow business concerns to be
- compartmentalized.</para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>event notifications</emphasis> decouple event producers from event consumers,</para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>interceptors</emphasis> decouple technical concerns from business logic, and</para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>decorators</emphasis> allow business concerns to be compartmentalized.</para>
+ </listitem>
+ </itemizedlist>
- <para>Most importantly, Web Beans provides all these facilities in a
- <emphasis>typesafe</emphasis> way. Web Beans never uses string-based
- identifiers to determine how collaborating objects fit together. And
- XML, though it remains an option, is rarely used. Instead, Web Beans
- uses the typing information that is already available in the Java
- object model, together with a new pattern, called
- <emphasis>binding annotations</emphasis>, to wire together Web Beans,
- their dependencies, their interceptors and decorators and their event
- consumers.</para>
+ <para>
+ What's even more powerful (and comforting) is that CDI provides all these facilities in a
+ <emphasis>typesafe</emphasis> way. CDI never relies on string-based identifiers to determine how collaborating
+ 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.
+ </para>
- <para>The Web Beans services are general and apply to the following types of
- components that exist in the Java EE environment:</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.
+ </para>
- <itemizedlist>
- <listitem>
- <para>all JavaBeans,</para>
- </listitem>
- <listitem>
- <para>all EJBs, and</para>
- </listitem>
- <listitem>
- <para>all Servlets.</para>
- </listitem>
- </itemizedlist>
+ <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
+ (EG).
+ </para>
- <para>Web Beans even provides the necessary integration points so that other
- kinds of components defined by future Java EE specifications or by non-standard
- frameworks may be cleanly integrated with Web Beans, take advantage of the Web
- Beans services, and interact with any other kind of Web Bean.</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).
+ </para>
- <para>Web Beans was influenced by a number of existing Java frameworks,
- including Seam, Guice and Spring. However, Web Beans 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.</para>
-
- <para>Most importantly, Web Beans is a JCP standard that integrates
- cleanly with Java EE, and with any Java SE environment where embeddable
- EJB Lite is available.</para>
-
-</partintro>
\ No newline at end of file
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
+</partintro>
More information about the weld-commits
mailing list