To run the examples with the provided build scripts, you'll need the following:

In the next few sections, you'll be using the Ant command (ant) to invoke the Ant build script in each example 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 3.

If you have Maven installed, you can 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.

The sections below cover the steps for deploying with both Ant and Maven in detail. Let's start with JBoss AS.

To deploy the examples to JBoss AS, you'll need JBoss AS 6.0.0 or above. If a release of the JBoss AS 6.0 line isn't yet available, you can download a nightly snapshot. The reason JBoss AS 6.0.0 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!

After you have downloaded JBoss AS, extract it. (We recommended renaming the folder to include the as qualifier so it's clear that it's the application server). You can move the extracted folder anywhere you like. Wherever it lays to rest, that's what we'll call the JBoss AS installation directory, or JBOSS_HOME.

$> unzip jboss-6.0.*.zip
$> mv jboss-6.0.*/ jboss-as-6.0

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., JBOSS_HOME). 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 jboss.home, as follows:

jboss.home=/path/to/jboss-as-6.0

You're now ready to deploy your first example!

Switch to the examples/jsf/numberguess directory and execute the Ant deploy target:

$> cd examples/jsf/numberguess
$> ant deploy

If you haven't already, start JBoss AS. You can either start JBoss AS from a Linux shell:

$> cd /path/to/jboss-as-6.0
$> ./bin/run.sh

a Windows command window:

$> cd c:\path\to\jboss-as-6.0\bin
$> run

or you can start the server using an IDE, like Eclipse.

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 http://localhost:8080/weld-numberguess.

The second starter example, weld-translator, 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:

$> cd examples/jsf/translator
$> ant deploy

Again, wait a few seconds for the application to deploy (if you're really bored, read the log messages), and visit http://localhost:8080/weld-translator to begin pseudo-translating.

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.

To deploy the examples to GlassFish, you'll need the final GlassFish V3 release (the preview release won't do). If the final release isn't yet available, you can download a promoted build 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.

$> chmod 755 glassfish-v3-b69-unix.sh
$> ./glassfish-v3-b69-unix.sh

On Windows you can just click on the executable. Follow the instructions in the installer. It will create a single domain named domain1. 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).

If you've deployed either of the starter examples, weld-numberguess or weld-translator, to JBoss AS, then you already have the deployable artifact you need. If not, switch to either of the two directories and build it.

$> cd examples/jsf/numberguess (or examples/jsf/translator)
$> ant package

The deployable archive for the weld-numberguess, named weld-numberguess.war, ends up in the example's target directory. The archive for the weld-translator 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.

You deploy applications to GlassFish using the GlassFish Admin Console. To get the Admin Console running, you need to start a GlassFish domain, in our case domain1. Switch to the bin folder in the directory where you installed GlassFish and execute the following command:

$> asadmin start-domain domain1

After a few seconds you can visit the Admin Console in the browser at the URL http://localhost:4848. 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 http://localhost:7070/weld-numberguess or http://localhost:7070/weld-translator, depending on which example you deployed.

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!

Servlet containers are not required to support Java EE services like CDI. However, you can use CDI in a servlet container like Tomcat by embedding a standalone CDI implementation such as Weld.

Weld comes with a servlet listener which bootstraps the CDI environment, registers the BeanManager in JNDI and provides injection into servlets. Basically, it emulates some of the work done by the Java EE container. (But you don't get enterprise features such as session beans and container-managed transactions.)

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 tomcat.apache.org and extract it.

$> unzip apache-tomcat-6.0.18.zip

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.

tomcat.home=/path/to/apache-tomcat-6

$> cd examples/jsf/numberguess
$> ant tomcat.deploy

$> cd /path/to/apache-tomcat-6
$> ./bin/start.sh

$> cd c:\path\to\apache-tomcat-6\bin
$> start

<user username="admin" password="" roles="manager"/>

$> mvn compile war:exploded tomcat:exploded -Ptomcat

$> mvn tomcat:redeploy -Ptomcat

$> mvn war:inplace tomcat:run -Ptomcat

$> mvn compile war:inplace -Ptomcat

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 weld-numberguess example is configured for Jetty support at the time of writing.

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 that you need to know again in this section.

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.

To run the weld-numberguess 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:

$> cd examples/jsf/numberguess
$> mvn war:inplace jetty:run -Pjetty

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: http://localhost:9090/weld-numberguess. The port is defined in the Maven Jetty plugin configuration within the jetty profile.

Any changes to assets in src/main/webapp take effect 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.

$> mvn compile war:inplace -Pjetty

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.

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.

First, initialize the Eclipse project:

$> mvn clean eclipse:clean eclipse:eclipse -Pjetty-ide

Next, assemble all the necessary resources under src/main/webapp:

$> mvn war:inplace -Pjetty-ide

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: http://localhost:8080. Pay particular attention to the port in the URL and the lack of a trailing context path.

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.

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.

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.

All the configuration files for this example are located in WEB-INF/, which can be found in the src/main/webapp directory of the example. First, we have the JSF 2.0 version of faces-config.xml. 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.

<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>

There's also an empty beans.xml file, which tells the container to look for beans in this application and to activate the CDI services.

Finally, there's the familiar web.xml:

<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>

ml_plain">   <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>

ml_plain">   </servlet>



   <servlet-mapping>

      <servlet-name>Faces Servlet</servlet-name>

      <url-pattern>*.jsf</url-pattern>

ml_plain">   </servlet-mapping>

   

   <context-param>

      <param-name>javax.faces.DEFAULT_SUFFIX</param-name>

      <param-value>.xhtml</param-value>

ml_plain">   </context-param>



   <session-config>

      <session-timeout>10</session-timeout>

   </session-config>



</web-app>

Let's take a look at the main JSF view, src/main/webapp/home.xhtml.

<!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">

ml_plain">

   <ui:composition template="/template.xhtml">

      <ui:define name="content">

         <h1>Guess a number...</h1>

ml_plain">         <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>

ml_plain">    

            <div>

               I'm thinking of a number between #{game.smallest} and #{game.biggest}.

               You have #{game.remainingGuesses} guesses remaining.

            </div>

       

            <div>

ml_plain">               Your guess: 

               <h:inputText id="inputGuess" value="#{game.guess}"

ml_plain">                  size="3" required="true" disabled="#{game.number eq game.guess}"

ml_plain">                  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>

The example exists of 4 classes, the first two of which are qualifiers. First, there is the @Random qualifier, used for injecting a random number:

@Qualifier

@Target( { TYPE, METHOD, PARAMETER, FIELD })

@Retention(RUNTIME)

public @interface Random {}

There is also the @MaxNumber qualifier, used for injecting the maximum number that can be injected:

@Qualifier

@Target( { TYPE, METHOD, PARAMETER, FIELD })

@Retention(RUNTIME)

public @interface MaxNumber {}

The application-scoped Generator class is responsible for creating the random number, via a producer method. It also exposes the maximum possible number via a producer method:

@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;

   }


}

The Generator is application scoped, so we don't get a different random each time.

The final bean in the application is the session-scoped Game 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 FacesMessage. We've used the post-construct lifecycle method to initialize the game by retrieving a random number from the @Random Instance<Integer> bean.

You'll notice that we've also added the @Named 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}).

@Named

@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;

   }


}

<listener>

   <listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>

</listener>

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.

Wicket is another environment that relies on the Weld servlet extension. The use of Jetty 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.

7.2.1. Creating the Eclipse project

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 m2eclipse plugin. 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..

If you have m2eclipse installed, you can open any Maven project directly. From within Eclipse, select File -> Import... -> Maven Projects. Then, browse to the location of the Wicket numberguess example. You should see that Eclipse recognizes the existence of a Maven project.

This will create a project in your workspace called weld-wicket-numberguess.

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 Properties, then select the Maven tab in the window that appears. In the form field labeled "Active Maven Profiles (comma separated):", type jetty. That will enable some extra dependencies that allow the project to compile. Additionally, uncheck the box labeled "Skip Maven compile plugin when processing resources (recommended)". That solves an incompatiblity between the m2eclipse plugin and the Maven enforcer plugin that we use for the Weld project. Now, you're ready to develop!

Note

Be sure to uncheck the box "Skip Maven compile plugin when processing resources (recommended)" in the Maven properties screen or else the example might not run in Eclipse because beans.xml will be missing from the classpath! See the MNGECLIPSE-768 issue report for details.

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:

$> cd examples/wicket/numberguess
mvn -Pjetty eclipse:eclipse

Then, from Eclipse, choose File -> Import... -> General -> Existing Projects into Workspace, select the root directory of the numberguess example, and click Finish. This will create a project in your workspace called weld-wicket-numberguess.

It's time to get the example running!

$> ant deploy

$> ant tomcat.deploy

$> mvn jetty:run -Pjetty

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 examples/se/numberguess folder of the Weld distribution.

To run the example:

Let's have a look at the significant code and configuration files that make up this example.

As usual, there is an empty beans.xml file in the root package (src/main/resources/beans.xml), which marks this application as a CDI application.

The game's main logic is located in Game.java. Here is the code for that class, highlighting the ways in which this differs from the web application version:

@ApplicationScoped

public class Game

{


   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();

   }

}