[weld-commits] Weld SVN: r4943 - doc/trunk/reference/en-US.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Tue Nov 10 00:59:22 EST 2009
Author: gavin.king at jboss.com
Date: 2009-11-10 00:59:22 -0500 (Tue, 10 Nov 2009)
New Revision: 4943
Added:
doc/trunk/reference/en-US/part1.5.xml
doc/trunk/reference/en-US/weldexamples.xml
Modified:
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
Log:
reorg
Modified: doc/trunk/reference/en-US/example.xml
===================================================================
--- doc/trunk/reference/en-US/example.xml 2009-11-10 05:13:46 UTC (rev 4942)
+++ doc/trunk/reference/en-US/example.xml 2009-11-10 05:59:22 UTC (rev 4943)
@@ -115,7 +115,8 @@
</h:panelGroup>]]></programlisting>
<para>
- In the next chapter, we'll explore examples from the CDI reference implementation, Weld, in greater depth.
+ Hopefully, this example gave you a taste of the CDI programming model. In the next chapter, we'll explore
+ dependency injection in greater depth.
</para>
<!--
Modified: doc/trunk/reference/en-US/gettingstarted.xml
===================================================================
--- doc/trunk/reference/en-US/gettingstarted.xml 2009-11-10 05:13:46 UTC (rev 4942)
+++ doc/trunk/reference/en-US/gettingstarted.xml 2009-11-10 05:59:22 UTC (rev 4943)
@@ -2,16 +2,9 @@
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
<chapter id="gettingstarted">
- <title>Getting started with Weld, the JSR-299 reference implementation</title>
+ <title>Getting started with Weld</title>
<para>
- Weld, the JSR-299 Reference Implementation (RI), 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>
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
@@ -215,26 +208,9 @@
pseudo-translating.
</para>
- <tip>
- <para>
- There are a number of other examples that use CDI and JSF together. Consult the readme.txt file in the
- following directories for introductions about how to run these examples.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- examples/jsf/login - A basic login using a session-scoped bean.
- </para>
- </listitem>
- <listitem>
- <para>
- examples/jsf/permalink - A basic blog that demonstrates JSF 2.0 bookmarkable URL support using view
- parameters and pre-render view listeners. The build and deployment is based exclusively on Maven 2.
- </para>
- </listitem>
- </itemizedlist>
- </tip>
+ <para>
+ TODO Insert note about upgrading the Weld deployer that directs reader to section on the JBoss AS environment
+ </para>
</section>
@@ -568,1352 +544,13 @@
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>.
+ know a little bit about how they actually work.
</para>
</section>
-
- <section id="numberguess">
- <title>The numberguess example in depth</title>
-
- <para>
- In the numberguess application you get 10 attempts to guess a number between 1 and 100. After each
- attempt, you're told whether your guess was too high or too low.
- </para>
-
- <para>
- 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 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[<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'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's the familiar <literal>web.xml</literal>:
- </para>
-
- <programlistingco>
- <areaspec>
- <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 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>weld-jsf-numberguess-war</display-name>
- <description>Weld JSF numberguess example (WAR)</description>
-
- <servlet>
- <servlet-name>Faces Servlet</servlet-name>
- <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
- <load-on-startup>1</load-on-startup>
- </servlet>
-
- <servlet-mapping>
- <servlet-name>Faces Servlet</servlet-name>
- <url-pattern>*.jsf</url-pattern>
- </servlet-mapping>
-
- <context-param>
- <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
- <param-value>.xhtml</param-value>
- </context-param>
-
- <session-config>
- <session-timeout>10</session-timeout>
- </session-config>
-
-</web-app>]]></programlisting>
- <calloutlist>
- <callout arearefs="faces.servlet">
- <para>
- Enable and initialize the JSF servlet
- </para>
- </callout>
- <callout arearefs="faces.servlet.mapping">
- <para>
- 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 JSF views (Facelets templates) an
- extension of <literal>.xhtml</literal>
- </para>
- </callout>
- <callout arearefs="session.timeout">
- <para>
- Configure a session timeout of 10 minutes
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <note>
- <para>
- 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 main JSF view, <literal>src/main/webapp/home.xhtml</literal>.
- </para>
-
- <programlistingco>
- <areaspec>
- <area id="template" coords="8" />
- <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 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">
-
- <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 the built-in templating language for JSF. Here we are
- wrapping our page in a template which defines the layout.
- </para>
- </callout>
- <callout arearefs="statusMessages">
- <para>
- There are a number of messages which can be sent to the user,
- "Higher!", "Lower!" and "Correct!"
- </para>
- </callout>
- <callout arearefs="instructions">
- <para>
- As the user guesses, the range of numbers they can guess gets
- smaller - this sentence 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 bean property using a value
- expression.
- </para>
- </callout>
- <callout arearefs="validator">
- <para>
- 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 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 bean.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <para>
- 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[@Qualifier
- at Target( { TYPE, METHOD, PARAMETER, FIELD })
- at Retention(RUNTIME)
-public @interface Random {}]]></programlisting>
-
- <para>
- There is also the <literal>@MaxNumber</literal> qualifier, used for
- injecting the maximum number that can be injected:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Qualifier
- at Target( { TYPE, METHOD, PARAMETER, FIELD })
- at Retention(RUNTIME)
-public @interface MaxNumber {}
-]]></programlisting>
-
- <para>
- 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 implements Serializable {
-
- private java.util.Random random = new java.util.Random(System.currentTimeMillis());
-
- private int maxNumber = 100;
-
- java.util.Random getRandom() {
- return random;
- }
-
- @Produces @Random int next() {
- return getRandom().nextInt(maxNumber);
- }
-
- @Produces @MaxNumber int getMaxNumber() {
- return maxNumber;
- }
-
-}]]></programlisting>
-
- <para>
- 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 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 the
- post-construct lifecycle method to initialize the game by retrieving a random number from the <literal>@Random
- Instance<Integer></literal> bean.
- </para>
-
- <para>
- 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[@Named
- at SessionScoped
-public class Game implements Serializable {
-
- private int number;
- private int guess;
- private int smallest;
- private int biggest;
- private int remainingGuesses;
-
- @Inject @MaxNumber private int maxNumber;
- @Inject @Random Instance<Integer> randomNumber;
-
- public Game() {}
-
- public void check() {
- if (guess > number) {
- biggest = guess - 1;
- }
- else if (guess < number) {
- smallest = guess + 1;
- }
- else if (guess == number) {
- FacesContext.getCurrentInstance().addMessage(null, new FacesMessage("Correct!"));
- }
- remainingGuesses--;
- }
-
- @PostConstruct
- public void reset() {
- this.smallest = 0;
- this.guess = 0;
- this.remainingGuesses = 10;
- this.biggest = maxNumber;
- this.number = randomNumber.get();
- }
-
- 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);
- return;
- }
- int input = (Integer) value;
-
- if (input < smallest || input > biggest) {
- ((UIInput) toValidate).setValid(false);
-
- FacesMessage message = new FacesMessage("Invalid guess");
- context.addMessage(toValidate.getClientId(context), message);
- }
- }
-
- 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>
- 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>
- 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 platform (a Java EE
- application server). Are you starting to appreciate why a Java EE platform is worth using?
- </para>
- </tip>
-
- <para>
- 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 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="numberguess-wicket">
- <title>The numberguess example for Apache Wicket</title>
- <para>
- 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>
-
- <tip>
- <para>
- 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>
- </tip>
-
- <para>
- 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>
-
- <note>
- <para>
- We'll also be using the Eclipse IDE in these examples. Instructions are provided later for running the
- example from the command line, 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 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 existence 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>
-
- <note>
- <para>
- You are also advised to uncheck the box "Skip Maven compiler when processing resources" in the Maven
- properties screen because of conflicts with the Maven enforcer plugin.
- </para>
- </note>
-
- <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
-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. This will
- create a project in your workspace called <literal>weld-wicket-numberguess</literal>.
- </para>
-
- <mediaobject>
- <imageobject>
- <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:9090</literal> to view the app. To debug choose <emphasis>Debug
- as Java Application</emphasis> instead.
- </para>
- </section>
-
- <section>
- <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>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:9090/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>
- 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 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>
- Here's where things differ from the JSF numberguess example:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Each wicket application must have a <literal>WeldApplication</literal> subclass. In our case, our
- application class is <literal>NumberGuessApplication</literal>:
- </para>
- <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>
- </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:
- </para>
-
- <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:
- </para>
-
- <programlisting role="JAVA"><![CDATA[final Component guessButton = new AjaxButton("GuessButton") {
- protected void onSubmit(AjaxRequestTarget target, Form form) {
- 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 <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 or lifecycle callbacks such as <literal>@PostConstruct</literal> or 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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- In order to activate Wicket for this webapp, the Wicket filter is added to <literal>web.xml</literal>,
- and our application class is specified in <literal>web.xml</literal>:
- </para>
-
- <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.weld.examples.wicket.NumberGuessApplication</param-value>
- </init-param>
-</filter>
-
-<filter-mapping>
- <filter-name>Wicket Filter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>]]></programlisting>
-
- <para>
- 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 lifecycles. However, rather than
- putting it into the web.xml, it is placed into an override file,
- <literal>src/main/webapp/WEB-INF/jetty-additions-to-web.xml</literal>, that is passed to Jetty as
- an extra descriptor to be appended to the <literal>web.xml</literal> 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 id="numberguess-se">
- <title>The numberguess example for Java SE with Swing</title>
-
- <para>
- This example shows how to use the Weld SE extension to in a
- Java SE based Swing application with no EJB or servlet dependencies.
- This example can be found in the <literal>examples/se/numberguess</literal>
- folder of the Weld distribution.
- </para>
-
- <para>
- To run the example:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Ensure that Maven 2 (version 2.0.10+) is installed and in your PATH
- </para>
- </listitem>
- <listitem>
- <para>
- Ensure that the <literal>JAVA_HOME</literal> environment
- variable is pointing to your JDK installation
- </para>
- </listitem>
- <listitem>
- <para>
- Open a command line or terminal window in the
- <literal>examples/se/numberguess</literal> directory
- </para>
- </listitem>
- <listitem>
- <para>
- Execute the following command
- </para>
- <programlisting>mvn -Drun</programlisting>
- </listitem>
- </itemizedlist>
-
- <para>
- Let's have a look at the significant code and configuration
- files that make up this example.
- </para>
-
- <para>
- As usual, 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 CDI application.
- </para>
-
- <para>
- The game's main logic is located in <literal>Game.java</literal>.
- Here is the code for that class, highlighting the ways in which this
- differs from the web application version:
- </para>
-
- <programlistingco>
- <areaspec>
- <area id="scope" coords="1" />
- <area id="name" coords="2" />
- <area id="messages1" coords="26" />
- <area id="validation" coords="41" />
- <area id="reset" coords="73" />
- </areaspec>
- <programlisting role="JAVA"><![CDATA[@ApplicationScoped
-public class Game implements Serializable
-{
-
- public static final int MAX_NUM_GUESSES = 10;
-
- private Integer number;
- private int guess = 0;
- private int smallest = 0;
-
- @Inject
- @MaxNumber
- private int maxNumber;
-
- private int biggest;
- private int remainingGuesses = MAX_NUM_GUESSES;
- private boolean validNumberRange = true;
-
- @Inject
- Generator rndGenerator;
-
- public Game()
- {
- }
-
- ...
-
- public boolean isValidNumberRange()
- {
- return validNumberRange;
- }
-
- public boolean isGameWon()
- {
- return guess == number;
- }
-
- public boolean isGameLost()
- {
- return guess != number && remainingGuesses <= 0;
- }
-
- public boolean check()
- {
- boolean result = false;
-
- if (checkNewNumberRangeIsValid())
- {
- if (guess > number)
- {
- biggest = guess - 1;
- }
-
- if (guess < number)
- {
- smallest = guess + 1;
- }
-
- if (guess == number)
- {
- result = true;
- }
-
- remainingGuesses--;
- }
-
- return result;
- }
-
- private boolean checkNewNumberRangeIsValid()
- {
- return validNumberRange = ((guess >= smallest) && (guess <= biggest));
- }
-
- @PostConstruct
- public void reset()
- {
- this.smallest = 0;
- this.guess = 0;
- this.remainingGuesses = 10;
- this.biggest = maxNumber;
- this.number = rndGenerator.next();
- }
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="scope">
- <para>
- The bean is application scoped rather than session scoped,
- since an instance of a Swing application typically represents
- a single 'session'.
- </para>
- </callout>
- <callout arearefs="name">
- <para>
- Notice that the bean is not named, since it doesn't need to
- be accessed via EL.
- </para>
- </callout>
- <callout arearefs="messages1">
- <para>
- In Java SE there is no JSF <literal>FacesContext</literal>
- to which messages can be added. Instead the <literal>Game</literal>
- class provides additional information about the state of the
- current game including:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- If the game has been won or lost
- </para>
- </listitem>
- <listitem>
- <para>
- If the most recent guess was invalid
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- This allows the Swing UI to query the state of the game,
- which it does indirectly via a class called
- <literal>MessageGenerator</literal>, in order to determine
- the appropriate messages to display to the user during the
- game.
- </para>
- </callout>
- <callout arearefs="validation">
- <para>
- Since there is no dedicated validation phase, validation of
- user input is performed during the <literal>check()</literal> method.
- </para>
- </callout>
- <callout arearefs="reset">
- <para>
- The <literal>reset()</literal> method makes a call to the
- injected <literal>rndGenerator</literal> in order to get
- the random number at the start of each game. Note that it
- cannot use <literal>manager.getInstanceByType(Integer.class, new AnnotationLiteral<Random>(){})</literal>
- as the JSF example does because there will not be any active
- contexts like there is during a JSF request.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <para>
- The <literal>MessageGenerator</literal> class depends on the
- current instance of <literal>Game</literal> and queries its
- state in order to determine the appropriate messages to provide
- as the prompt for the user's next guess and the response to the
- previous guess. The code for <literal>MessageGenerator</literal>
- is as follows:
- </para>
-
- <programlistingco>
- <areaspec>
- <area id="game" coords="3" />
- <area id="challenge" coords="6" />
- <area id="result" coords="17" />
- </areaspec>
- <programlisting role="JAVA"><![CDATA[public class MessageGenerator
-{
- @Inject
- private Game game;
-
- public String getChallengeMessage()
- {
- StringBuilder challengeMsg = new StringBuilder("I'm thinking of a number between ");
- challengeMsg.append(game.getSmallest());
- challengeMsg.append(" and ");
- challengeMsg.append(game.getBiggest());
- challengeMsg.append(". Can you guess what it is?");
-
- return challengeMsg.toString();
- }
-
- public String getResultMessage()
- {
- if (game.isGameWon())
- {
- return "You guessed it! The number was " + game.getNumber();
- }
- else if (game.isGameLost())
- {
- return "You are fail! The number was " + game.getNumber();
- }
- else if (!game.isValidNumberRange())
- {
- return "Invalid number range!";
- }
- else if (game.getRemainingGuesses() == Game.MAX_NUM_GUESSES)
- {
- return "What is your first guess?";
- }
- else
- {
- String direction = null;
-
- if (game.getGuess() < game.getNumber())
- {
- direction = "Higher";
- }
- else
- {
- direction = "Lower";
- }
-
- return direction + "! You have " + game.getRemainingGuesses() + " guesses left.";
- }
- }
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="game">
- <para>
- The instance of <literal>Game</literal> for the application
- is injected here.
- </para>
- </callout>
- <callout arearefs="challenge">
- <para>
- The <literal>Game</literal>'s state is interrogated to
- determine the appropriate challenge message ...
- </para>
- </callout>
- <callout arearefs="result">
- <para>
- ... and again to determine whether to congratulate, console or
- encourage the user to continue.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <para>
- Finally we come to the <literal>NumberGuessFrame</literal> class
- which provides the Swing front end to our guessing game.
- </para>
-
- <programlistingco>
- <areaspec>
- <area id="gameIn" coords="3" />
- <area id="messagesIn" coords="6" />
- <area id="start" coords="9" />
- <area id="init" coords="21" />
- <area id="guess1" coords="38" />
- <area id="replay" coords="48" />
- </areaspec>
- <programlisting role="JAVA"><![CDATA[public class NumberGuessFrame extends javax.swing.JFrame
-{
- @Inject
- private Game game;
-
- @Inject
- private MessageGenerator msgGenerator;
-
- public void start(@Observes ContainerInitialized event)
- {
- java.awt.EventQueue.invokeLater(new Runnable()
- {
- public void run()
- {
- initComponents();
- setVisible(true);
- }
- });
- }
-
- private void initComponents()
- {
-
- buttonPanel = new javax.swing.JPanel();
- mainMsgPanel = new javax.swing.JPanel();
- mainLabel = new javax.swing.JLabel();
- messageLabel = new javax.swing.JLabel();
- guessText = new javax.swing.JTextField();
- ...
- mainLabel.setText(msgGenerator.getChallengeMessage());
- mainMsgPanel.add(mainLabel);
-
- messageLabel.setText(msgGenerator.getResultMessage());
- mainMsgPanel.add(messageLabel);
- ...
- }
-
- private void guessButtonActionPerformed( java.awt.event.ActionEvent evt )
- {
- int guess = Integer.parseInt(guessText.getText());
- game.setGuess( guess );
- game.check();
- refreshUI();
- }
-
- private void replayBtnActionPerformed(java.awt.event.ActionEvent evt)
- {
- game.reset();
- refreshUI();
- }
-
- private void refreshUI() {
- mainLabel.setText( msgGenerator.getChallengeMessage() );
- messageLabel.setText( msgGenerator.getResultMessage() );
- guessText.setText( "" );
- guessesLeftBar.setValue( game.getRemainingGuesses() );
- guessText.requestFocus();
- }
-
- // swing components
- private javax.swing.JPanel borderPanel;
- ...
- private javax.swing.JButton replayBtn;
-
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="gameIn">
- <para>
- The injected instance of the game (logic and state).
- </para>
- </callout>
- <callout arearefs="messagesIn">
- <para>
- The injected message generator for UI messages.
- </para>
- </callout>
- <callout arearefs="start">
- <para>
- This application is started in the prescribed Weld SE way,
- by observing the <literal>ContainerInitialized</literal> event.
- </para>
- </callout>
- <callout arearefs="init">
- <para>
- This method initializes all of the Swing components. Note
- the use of the <literal>msgGenerator</literal> here.
- </para>
- </callout>
- <callout arearefs="guess1">
- <para>
- <literal>guessButtonActionPerformed</literal> is called
- when the 'Guess' button is clicked, and it does the
- following:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Gets the guess entered by the user and sets it as the
- current guess in the <literal>Game</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Calls <literal>game.check()</literal> to validate and
- perform one 'turn' of the game
- </para>
- </listitem>
- <listitem>
- <para>
- Calls <literal>refreshUI</literal>. If there were
- validation errors with the input, this will have been
- captured during <literal>game.check()</literal> and
- as such will be reflected in the messages returned by
- <literal>MessageGenerator</literal> and subsequently
- presented to the user. If there are no validation
- errors then the user will be told to guess again
- (higher or lower) or that the game has ended either
- in a win (correct guess) or a loss (ran out of
- guesses).
- </para>
- </listitem>
- </itemizedlist>
- </callout>
- <callout arearefs="replay">
- <para>
- <literal>replayBtnActionPerformed</literal> simply calls
- <literal>game.reset()</literal> to start a new game and
- refreshes the messages in the UI.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- </section>
- </section>
-
- <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. (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 numberguess example.
- </para>
-
- <note>
- <para>
- Java 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 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>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-ear-plugin</artifactId>
- <configuration>
- <modules>
- <webModule>
- <groupId>org.jboss.weld.examples.jsf.translator</groupId>
- <artifactId>weld-jsf-translator-war</artifactId>
- <contextRoot>/weld-translator</contextRoot>
- </webModule>
- </modules>
- </configuration>
-</plugin>]]></programlisting>
-
- <para>
- 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 weren't using Maven to generate these files, you would need
- <literal>META-INF/application.xml</literal>:
- </para>
-
- <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>weld-translator.war</web-uri>
- <context-root>/weld-translator</context-root>
- </web>
- </module>
- <module>
- <ejb>weld-translator.jar</ejb>
- </module>
-</application>]]></programlisting>
- </tip>
-
- <para>
- 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 interesting 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="translator">
-
- <table>
- <tr align="center" style="font-weight: bold">
- <td>
- Your text
- </td>
- <td>
- Translation
- </td>
- </tr>
- <tr>
- <td>
- <h:inputTextarea id="text" value="#{translator.text}" required="true" rows="5" cols="80"/>
- </td>
- <td>
- <h:outputText value="#{translator.translatedText}"/>
- </td>
- </tr>
- </table>
- <div>
- <h:commandButton id="button" value="Translate" action="#{translator.translate}"/>
- </div>
-
-</h:form>]]></programlisting>
-
- <para>
- 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, 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 session 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 injection:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public class TextTranslator implements Serializable {
-
- private SentenceParser sentenceParser;
-
- @EJB private Translator translator;
-
- @Inject public TextTranslator(SentenceParser sentenceParser) {
- this.sentenceParser = sentenceParser;
- }
-
- 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> 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. 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
- at RequestScoped
- at Named("translator")
-public class TranslatorControllerBean implements TranslatorController {
-
- @Inject private TextTranslator translator;
-
- 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>
-
- </section>
-
- <para>
- 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>
-
<!--
vim:et:ts=3:sw=3:tw=120
-->
Modified: doc/trunk/reference/en-US/intro.xml
===================================================================
--- doc/trunk/reference/en-US/intro.xml 2009-11-10 05:13:46 UTC (rev 4942)
+++ doc/trunk/reference/en-US/intro.xml 2009-11-10 05:59:22 UTC (rev 4943)
@@ -194,7 +194,7 @@
<para>
Notice that it isn't necessary to create a getter or setter method to inject one bean into another. CDI can
- access an injected field directly (even if it's private!), which sometimes help eliminate some wasteful code.
+ access an injected field directly (even if it's private!), which sometimes helps eliminate some wasteful code.
The name of the field is arbitrary. It's the field's type that determines what is injected.
</para>
Modified: doc/trunk/reference/en-US/master.xml
===================================================================
--- doc/trunk/reference/en-US/master.xml 2009-11-10 05:13:46 UTC (rev 4942)
+++ doc/trunk/reference/en-US/master.xml 2009-11-10 05:59:22 UTC (rev 4943)
@@ -39,13 +39,22 @@
<xi:include href="intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<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" />
<!-- TODO <xi:include href="producerfields.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
</part>
+
+ <part id="1.5">
+ <title>Weld, the CDI Reference Implementation</title>
+
+ <xi:include href="part1.5.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="weldexamples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ </part>
<part id="2">
<title>Developing loosely-coupled code</title>
Added: doc/trunk/reference/en-US/part1.5.xml
===================================================================
--- doc/trunk/reference/en-US/part1.5.xml (rev 0)
+++ doc/trunk/reference/en-US/part1.5.xml 2009-11-10 05:59:22 UTC (rev 4943)
@@ -0,0 +1,16 @@
+<!DOCTYPE partintro PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<partintro>
+
+ <para>
+ Weld, the JSR-299 Reference Implementation (RI), 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>
+ Weld comes with an extensive library of examples, which are a great starting point from which to learn CDI.
+ </para>
+
+</partintro>
\ No newline at end of file
Added: doc/trunk/reference/en-US/weldexamples.xml
===================================================================
--- doc/trunk/reference/en-US/weldexamples.xml (rev 0)
+++ doc/trunk/reference/en-US/weldexamples.xml 2009-11-10 05:59:22 UTC (rev 4943)
@@ -0,0 +1,1345 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<chapter id="weldexamples">
+
+ <title>Diving into the Weld examples</title>
+
+ <para>
+ It's time to pull the covers back and dive into the internals of Weld example applications. Let's start with the
+ simpler of the two examples, <literal>weld-numberguess</literal>.
+ </para>
+
+ <section id="numberguess">
+ <title>The numberguess example in depth</title>
+
+ <para>
+ In the numberguess application you get 10 attempts to guess a number between 1 and 100. After each
+ attempt, you're told whether your guess was too high or too low.
+ </para>
+
+ <para>
+ 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 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[<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'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's the familiar <literal>web.xml</literal>:
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <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 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>weld-jsf-numberguess-war</display-name>
+ <description>Weld JSF numberguess example (WAR)</description>
+
+ <servlet>
+ <servlet-name>Faces Servlet</servlet-name>
+ <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>Faces Servlet</servlet-name>
+ <url-pattern>*.jsf</url-pattern>
+ </servlet-mapping>
+
+ <context-param>
+ <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
+ <param-value>.xhtml</param-value>
+ </context-param>
+
+ <session-config>
+ <session-timeout>10</session-timeout>
+ </session-config>
+
+</web-app>]]></programlisting>
+ <calloutlist>
+ <callout arearefs="faces.servlet">
+ <para>
+ Enable and initialize the JSF servlet
+ </para>
+ </callout>
+ <callout arearefs="faces.servlet.mapping">
+ <para>
+ 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 JSF views (Facelets templates) an
+ extension of <literal>.xhtml</literal>
+ </para>
+ </callout>
+ <callout arearefs="session.timeout">
+ <para>
+ Configure a session timeout of 10 minutes
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <note>
+ <para>
+ 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 main JSF view, <literal>src/main/webapp/home.xhtml</literal>.
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="template" coords="8" />
+ <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 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">
+
+ <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 the built-in templating language for JSF. Here we are
+ wrapping our page in a template which defines the layout.
+ </para>
+ </callout>
+ <callout arearefs="statusMessages">
+ <para>
+ There are a number of messages which can be sent to the user,
+ "Higher!", "Lower!" and "Correct!"
+ </para>
+ </callout>
+ <callout arearefs="instructions">
+ <para>
+ As the user guesses, the range of numbers they can guess gets
+ smaller - this sentence 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 bean property using a value
+ expression.
+ </para>
+ </callout>
+ <callout arearefs="validator">
+ <para>
+ 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 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 bean.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ 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[@Qualifier
+ at Target( { TYPE, METHOD, PARAMETER, FIELD })
+ at Retention(RUNTIME)
+public @interface Random {}]]></programlisting>
+
+ <para>
+ There is also the <literal>@MaxNumber</literal> qualifier, used for
+ injecting the maximum number that can be injected:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Qualifier
+ at Target( { TYPE, METHOD, PARAMETER, FIELD })
+ at Retention(RUNTIME)
+public @interface MaxNumber {}
+]]></programlisting>
+
+ <para>
+ 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 implements Serializable {
+
+ private java.util.Random random = new java.util.Random(System.currentTimeMillis());
+
+ private int maxNumber = 100;
+
+ java.util.Random getRandom() {
+ return random;
+ }
+
+ @Produces @Random int next() {
+ return getRandom().nextInt(maxNumber);
+ }
+
+ @Produces @MaxNumber int getMaxNumber() {
+ return maxNumber;
+ }
+
+}]]></programlisting>
+
+ <para>
+ 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 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 the
+ post-construct lifecycle method to initialize the game by retrieving a random number from the <literal>@Random
+ Instance<Integer></literal> bean.
+ </para>
+
+ <para>
+ 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[@Named
+ at SessionScoped
+public class Game implements Serializable {
+
+ private int number;
+ private int guess;
+ private int smallest;
+ private int biggest;
+ private int remainingGuesses;
+
+ @Inject @MaxNumber private int maxNumber;
+ @Inject @Random Instance<Integer> randomNumber;
+
+ public Game() {}
+
+ public void check() {
+ if (guess > number) {
+ biggest = guess - 1;
+ }
+ else if (guess < number) {
+ smallest = guess + 1;
+ }
+ else if (guess == number) {
+ FacesContext.getCurrentInstance().addMessage(null, new FacesMessage("Correct!"));
+ }
+ remainingGuesses--;
+ }
+
+ @PostConstruct
+ public void reset() {
+ this.smallest = 0;
+ this.guess = 0;
+ this.remainingGuesses = 10;
+ this.biggest = maxNumber;
+ this.number = randomNumber.get();
+ }
+
+ 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);
+ return;
+ }
+ int input = (Integer) value;
+
+ if (input < smallest || input > biggest) {
+ ((UIInput) toValidate).setValid(false);
+
+ FacesMessage message = new FacesMessage("Invalid guess");
+ context.addMessage(toValidate.getClientId(context), message);
+ }
+ }
+
+ 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>
+ 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>
+ 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 platform (a Java EE
+ application server). Are you starting to appreciate why a Java EE platform is worth using?
+ </para>
+ </tip>
+
+ <para>
+ 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 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="numberguess-wicket">
+ <title>The numberguess example for Apache Wicket</title>
+ <para>
+ 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>
+
+ <tip>
+ <para>
+ 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>
+ </tip>
+
+ <para>
+ 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>
+
+ <note>
+ <para>
+ We'll also be using the Eclipse IDE in these examples. Instructions are provided later for running the
+ example from the command line, 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 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 existence 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
+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. This will
+ create a project in your workspace called <literal>weld-wicket-numberguess</literal>.
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <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> instead.
+ </para>
+ </section>
+
+ <section>
+ <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>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>
+ 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 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>
+ Here's where things differ from the JSF numberguess example:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Each wicket application must have a <literal>WeldApplication</literal> subclass. In our case, our
+ application class is <literal>NumberGuessApplication</literal>:
+ </para>
+ <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>
+ </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:
+ </para>
+
+ <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:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[final Component guessButton = new AjaxButton("GuessButton") {
+ protected void onSubmit(AjaxRequestTarget target, Form form) {
+ 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 <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 or lifecycle callbacks such as <literal>@PostConstruct</literal> or 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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In order to activate Wicket for this webapp, the Wicket filter is added to <literal>web.xml</literal>,
+ and our application class is specified in <literal>web.xml</literal>:
+ </para>
+
+ <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.weld.examples.wicket.NumberGuessApplication</param-value>
+ </init-param>
+</filter>
+
+<filter-mapping>
+ <filter-name>Wicket Filter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>]]></programlisting>
+
+ <para>
+ 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 lifecycles. However, rather than
+ putting it into the web.xml, it is placed into an override file,
+ <literal>src/main/webapp/WEB-INF/jetty-additions-to-web.xml</literal>, that is passed to Jetty as
+ an extra descriptor to be appended to the <literal>web.xml</literal> 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 id="numberguess-se">
+ <title>The numberguess example for Java SE with Swing</title>
+
+ <para>
+ This example shows how to use the Weld SE extension to in a
+ Java SE based Swing application with no EJB or servlet dependencies.
+ This example can be found in the <literal>examples/se/numberguess</literal>
+ folder of the Weld distribution.
+ </para>
+
+ <para>
+ To run the example:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Ensure that Maven 2 (version 2.0.10+) is installed and in your PATH
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Ensure that the <literal>JAVA_HOME</literal> environment
+ variable is pointing to your JDK installation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Open a command line or terminal window in the
+ <literal>examples/se/numberguess</literal> directory
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Execute the following command
+ </para>
+ <programlisting>mvn -Drun</programlisting>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Let's have a look at the significant code and configuration
+ files that make up this example.
+ </para>
+
+ <para>
+ As usual, 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 CDI application.
+ </para>
+
+ <para>
+ The game's main logic is located in <literal>Game.java</literal>.
+ Here is the code for that class, highlighting the ways in which this
+ differs from the web application version:
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="scope" coords="1" />
+ <area id="name" coords="2" />
+ <area id="messages1" coords="26" />
+ <area id="validation" coords="41" />
+ <area id="reset" coords="73" />
+ </areaspec>
+ <programlisting role="JAVA"><![CDATA[@ApplicationScoped
+public class Game implements Serializable
+{
+
+ public static final int MAX_NUM_GUESSES = 10;
+
+ private Integer number;
+ private int guess = 0;
+ private int smallest = 0;
+
+ @Inject
+ @MaxNumber
+ private int maxNumber;
+
+ private int biggest;
+ private int remainingGuesses = MAX_NUM_GUESSES;
+ private boolean validNumberRange = true;
+
+ @Inject
+ Generator rndGenerator;
+
+ public Game()
+ {
+ }
+
+ ...
+
+ public boolean isValidNumberRange()
+ {
+ return validNumberRange;
+ }
+
+ public boolean isGameWon()
+ {
+ return guess == number;
+ }
+
+ public boolean isGameLost()
+ {
+ return guess != number && remainingGuesses <= 0;
+ }
+
+ public boolean check()
+ {
+ boolean result = false;
+
+ if (checkNewNumberRangeIsValid())
+ {
+ if (guess > number)
+ {
+ biggest = guess - 1;
+ }
+
+ if (guess < number)
+ {
+ smallest = guess + 1;
+ }
+
+ if (guess == number)
+ {
+ result = true;
+ }
+
+ remainingGuesses--;
+ }
+
+ return result;
+ }
+
+ private boolean checkNewNumberRangeIsValid()
+ {
+ return validNumberRange = ((guess >= smallest) && (guess <= biggest));
+ }
+
+ @PostConstruct
+ public void reset()
+ {
+ this.smallest = 0;
+ this.guess = 0;
+ this.remainingGuesses = 10;
+ this.biggest = maxNumber;
+ this.number = rndGenerator.next();
+ }
+}]]></programlisting>
+ <calloutlist>
+ <callout arearefs="scope">
+ <para>
+ The bean is application scoped rather than session scoped,
+ since an instance of a Swing application typically represents
+ a single 'session'.
+ </para>
+ </callout>
+ <callout arearefs="name">
+ <para>
+ Notice that the bean is not named, since it doesn't need to
+ be accessed via EL.
+ </para>
+ </callout>
+ <callout arearefs="messages1">
+ <para>
+ In Java SE there is no JSF <literal>FacesContext</literal>
+ to which messages can be added. Instead the <literal>Game</literal>
+ class provides additional information about the state of the
+ current game including:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ If the game has been won or lost
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the most recent guess was invalid
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ This allows the Swing UI to query the state of the game,
+ which it does indirectly via a class called
+ <literal>MessageGenerator</literal>, in order to determine
+ the appropriate messages to display to the user during the
+ game.
+ </para>
+ </callout>
+ <callout arearefs="validation">
+ <para>
+ Since there is no dedicated validation phase, validation of
+ user input is performed during the <literal>check()</literal> method.
+ </para>
+ </callout>
+ <callout arearefs="reset">
+ <para>
+ The <literal>reset()</literal> method makes a call to the
+ injected <literal>rndGenerator</literal> in order to get
+ the random number at the start of each game. Note that it
+ cannot use <literal>manager.getInstanceByType(Integer.class, new AnnotationLiteral<Random>(){})</literal>
+ as the JSF example does because there will not be any active
+ contexts like there is during a JSF request.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ The <literal>MessageGenerator</literal> class depends on the
+ current instance of <literal>Game</literal> and queries its
+ state in order to determine the appropriate messages to provide
+ as the prompt for the user's next guess and the response to the
+ previous guess. The code for <literal>MessageGenerator</literal>
+ is as follows:
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="game" coords="3" />
+ <area id="challenge" coords="6" />
+ <area id="result" coords="17" />
+ </areaspec>
+ <programlisting role="JAVA"><![CDATA[public class MessageGenerator
+{
+ @Inject
+ private Game game;
+
+ public String getChallengeMessage()
+ {
+ StringBuilder challengeMsg = new StringBuilder("I'm thinking of a number between ");
+ challengeMsg.append(game.getSmallest());
+ challengeMsg.append(" and ");
+ challengeMsg.append(game.getBiggest());
+ challengeMsg.append(". Can you guess what it is?");
+
+ return challengeMsg.toString();
+ }
+
+ public String getResultMessage()
+ {
+ if (game.isGameWon())
+ {
+ return "You guessed it! The number was " + game.getNumber();
+ }
+ else if (game.isGameLost())
+ {
+ return "You are fail! The number was " + game.getNumber();
+ }
+ else if (!game.isValidNumberRange())
+ {
+ return "Invalid number range!";
+ }
+ else if (game.getRemainingGuesses() == Game.MAX_NUM_GUESSES)
+ {
+ return "What is your first guess?";
+ }
+ else
+ {
+ String direction = null;
+
+ if (game.getGuess() < game.getNumber())
+ {
+ direction = "Higher";
+ }
+ else
+ {
+ direction = "Lower";
+ }
+
+ return direction + "! You have " + game.getRemainingGuesses() + " guesses left.";
+ }
+ }
+}]]></programlisting>
+ <calloutlist>
+ <callout arearefs="game">
+ <para>
+ The instance of <literal>Game</literal> for the application
+ is injected here.
+ </para>
+ </callout>
+ <callout arearefs="challenge">
+ <para>
+ The <literal>Game</literal>'s state is interrogated to
+ determine the appropriate challenge message ...
+ </para>
+ </callout>
+ <callout arearefs="result">
+ <para>
+ ... and again to determine whether to congratulate, console or
+ encourage the user to continue.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>
+ Finally we come to the <literal>NumberGuessFrame</literal> class
+ which provides the Swing front end to our guessing game.
+ </para>
+
+ <programlistingco>
+ <areaspec>
+ <area id="gameIn" coords="3" />
+ <area id="messagesIn" coords="6" />
+ <area id="start" coords="9" />
+ <area id="init" coords="21" />
+ <area id="guess1" coords="38" />
+ <area id="replay" coords="48" />
+ </areaspec>
+ <programlisting role="JAVA"><![CDATA[public class NumberGuessFrame extends javax.swing.JFrame
+{
+ @Inject
+ private Game game;
+
+ @Inject
+ private MessageGenerator msgGenerator;
+
+ public void start(@Observes ContainerInitialized event)
+ {
+ java.awt.EventQueue.invokeLater(new Runnable()
+ {
+ public void run()
+ {
+ initComponents();
+ setVisible(true);
+ }
+ });
+ }
+
+ private void initComponents()
+ {
+
+ buttonPanel = new javax.swing.JPanel();
+ mainMsgPanel = new javax.swing.JPanel();
+ mainLabel = new javax.swing.JLabel();
+ messageLabel = new javax.swing.JLabel();
+ guessText = new javax.swing.JTextField();
+ ...
+ mainLabel.setText(msgGenerator.getChallengeMessage());
+ mainMsgPanel.add(mainLabel);
+
+ messageLabel.setText(msgGenerator.getResultMessage());
+ mainMsgPanel.add(messageLabel);
+ ...
+ }
+
+ private void guessButtonActionPerformed( java.awt.event.ActionEvent evt )
+ {
+ int guess = Integer.parseInt(guessText.getText());
+ game.setGuess( guess );
+ game.check();
+ refreshUI();
+ }
+
+ private void replayBtnActionPerformed(java.awt.event.ActionEvent evt)
+ {
+ game.reset();
+ refreshUI();
+ }
+
+ private void refreshUI() {
+ mainLabel.setText( msgGenerator.getChallengeMessage() );
+ messageLabel.setText( msgGenerator.getResultMessage() );
+ guessText.setText( "" );
+ guessesLeftBar.setValue( game.getRemainingGuesses() );
+ guessText.requestFocus();
+ }
+
+ // swing components
+ private javax.swing.JPanel borderPanel;
+ ...
+ private javax.swing.JButton replayBtn;
+
+}]]></programlisting>
+ <calloutlist>
+ <callout arearefs="gameIn">
+ <para>
+ The injected instance of the game (logic and state).
+ </para>
+ </callout>
+ <callout arearefs="messagesIn">
+ <para>
+ The injected message generator for UI messages.
+ </para>
+ </callout>
+ <callout arearefs="start">
+ <para>
+ This application is started in the prescribed Weld SE way,
+ by observing the <literal>ContainerInitialized</literal> event.
+ </para>
+ </callout>
+ <callout arearefs="init">
+ <para>
+ This method initializes all of the Swing components. Note
+ the use of the <literal>msgGenerator</literal> here.
+ </para>
+ </callout>
+ <callout arearefs="guess1">
+ <para>
+ <literal>guessButtonActionPerformed</literal> is called
+ when the 'Guess' button is clicked, and it does the
+ following:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Gets the guess entered by the user and sets it as the
+ current guess in the <literal>Game</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Calls <literal>game.check()</literal> to validate and
+ perform one 'turn' of the game
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Calls <literal>refreshUI</literal>. If there were
+ validation errors with the input, this will have been
+ captured during <literal>game.check()</literal> and
+ as such will be reflected in the messages returned by
+ <literal>MessageGenerator</literal> and subsequently
+ presented to the user. If there are no validation
+ errors then the user will be told to guess again
+ (higher or lower) or that the game has ended either
+ in a win (correct guess) or a loss (ran out of
+ guesses).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </callout>
+ <callout arearefs="replay">
+ <para>
+ <literal>replayBtnActionPerformed</literal> simply calls
+ <literal>game.reset()</literal> to start a new game and
+ refreshes the messages in the UI.
+ </para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ </section>
+ </section>
+
+ <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. (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 numberguess example.
+ </para>
+
+ <note>
+ <para>
+ Java 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 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>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-ear-plugin</artifactId>
+ <configuration>
+ <modules>
+ <webModule>
+ <groupId>org.jboss.weld.examples.jsf.translator</groupId>
+ <artifactId>weld-jsf-translator-war</artifactId>
+ <contextRoot>/weld-translator</contextRoot>
+ </webModule>
+ </modules>
+ </configuration>
+</plugin>]]></programlisting>
+
+ <para>
+ 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 weren't using Maven to generate these files, you would need
+ <literal>META-INF/application.xml</literal>:
+ </para>
+
+ <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>weld-translator.war</web-uri>
+ <context-root>/weld-translator</context-root>
+ </web>
+ </module>
+ <module>
+ <ejb>weld-translator.jar</ejb>
+ </module>
+</application>]]></programlisting>
+ </tip>
+
+ <para>
+ 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 interesting 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="translator">
+
+ <table>
+ <tr align="center" style="font-weight: bold">
+ <td>
+ Your text
+ </td>
+ <td>
+ Translation
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <h:inputTextarea id="text" value="#{translator.text}" required="true" rows="5" cols="80"/>
+ </td>
+ <td>
+ <h:outputText value="#{translator.translatedText}"/>
+ </td>
+ </tr>
+ </table>
+ <div>
+ <h:commandButton id="button" value="Translate" action="#{translator.translate}"/>
+ </div>
+
+</h:form>]]></programlisting>
+
+ <para>
+ 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, 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 session 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 injection:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[public class TextTranslator implements Serializable {
+
+ private SentenceParser sentenceParser;
+
+ @EJB private Translator translator;
+
+ @Inject public TextTranslator(SentenceParser sentenceParser) {
+ this.sentenceParser = sentenceParser;
+ }
+
+ 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> 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. 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
+ at RequestScoped
+ at Named("translator")
+public class TranslatorControllerBean implements TranslatorController {
+
+ @Inject private TextTranslator translator;
+
+ 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>
+
+ </section>
+
+ <para>
+ 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>
+
+<!--
+vim:et:ts=3:sw=3:tw=120
+-->
+</chapter>
More information about the weld-commits
mailing list