With certain, very special exceptions, every Java class with a constructor that accepts no parameters is a Web Bean. That includes every JavaBean. Furthermore, every EJB 3-style session bean is a Web Bean. Sure, the JavaBeans and EJBs you've been writing every day have not been able to take advantage of the new services defined by the Web Beans specification, but you'll be able to use every one of them as Web Beans — injecting them into other Web Beans, configuring them via the Web Beans XML configuration facility, even adding interceptors and decorators to them — without touching your existing code.

Suppose that we have two existing Java classes, that we've been using for years in various applications. The first class parses a string into a list of sentences:

public class SentenceParser {

    public List<String> parse(String text) { ... }

}

The second existing class is a stateless session bean front-end for an external system that is able to translate sentences from one language to another:

@Stateless

public class SentenceTranslator implements Translator {

    public String translate(String sentence) { ... }

}

Where Translator is the local interface:

@Local

public interface Translator {

    public String translate(String sentence);

}

Unfortunately, we don't have a preexisting class that translates whole text documents. So let's write a Web Bean that does this job:

public class TextTranslator {

    

    private SentenceParser sentenceParser;

    private Translator sentenceTranslator;

    

    @Initializer

    TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator) {

        this.sentenceParser = sentenceParser;

        this.sentenceTranslator = sentenceTranslator;

    }

    

    public String translate(String text) {

        StringBuilder sb = new StringBuilder();

        for (String sentence: sentenceParser.parse(text)) {

            sb.append(sentenceTranslator.translate(sentence));

        }

        return sb.toString();

    }

    

}

We may obtain an instance of TextTranslator by injecting it into a Web Bean, Servlet or EJB:

@Initializer

public setTextTranslator(TextTranslator textTranslator) {

    this.textTranslator = textTranslator;

}

Alternatively, we may obtain an instance by directly calling a method of the Web Bean manager:

TextTranslator tt = manager.getInstanceByType(TextTranslator.class);

But wait: TextTranslator does not have a constructor with no parameters! Is it still a Web Bean? Well, a class that does not have a constructor with no parameters can still be a Web Bean if it has a constructor annotated @Initializer.

As you've guessed, the @Initializer annotation has something to do with dependency injection! @Initializer may be applied to a constructor or method of a Web Bean, and tells the Web Bean manager to call that constructor or method when instantiating the Web Bean. The Web Bean manager will inject other Web Beans to the parameters of the constructor or method.

At system initialization time, the Web Bean manager must validate that exactly one Web Bean exists which satisfies each injection point. In our example, if no implementation of Translator available — if the SentenceTranslator EJB was not deployed — the Web Bean manager would throw an UnsatisfiedDependencyException. If more than one implementation of Translator was available, the Web Bean manager would throw an AmbiguousDependencyException.

So what, exactly, is a Web Bean?

A Web Bean is an application class that contains business logic. A Web Bean may be called directly from Java code, or it may be invoked via Unified EL. A Web Bean may access transactional resources. Dependencies between Web Beans are managed automatically by the Web Bean manager. Most Web Beans are stateful and contextual. The lifecycle of a Web Bean is always managed by the Web Bean manager.

Let's back up a second. What does it really mean to be "contextual"? Since Web Beans may be stateful, it matters which bean instance I have. Unlike a stateless component model (for example, stateless session beans) or a singleton component model (such as servlets, or singleton beans), different clients of a Web Bean see the Web Bean in different states. The client-visible state depends upon which instance of the Web Bean the client has a reference to.

However, like a stateless or singleton model, but unlike stateful session beans, the client does not control the lifecycle of the instance by explicitly creating and destroying it. Instead, the scope of the Web Bean determines:

For a given thread in a Web Beans application, there may be an active context associated with the scope of the Web Bean. This context may be unique to the thread (for example, if the Web Bean is request scoped), or it may be shared with certain other threads (for example, if the Web Bean is session scoped) or even all other threads (if it is application scoped).

Clients (for example, other Web Beans) executing in the same context will see the same instance of the Web Bean. But clients in a different context will see a different instance.

One great advantage of the contextual model is that it allows stateful Web Beans to be treated like services! The client need not concern itself with managing the lifecycle of the Web Bean it is using, nor does it even need to know what that lifecyle is. Web Beans interact by passing messages, and the Web Bean implementations define the lifecycle of their own state. The Web Beans are loosely coupled because:

We can replace one Web Bean with a different Web Bean that implements the same API and has a different lifecycle (a different scope) without affecting the other Web Bean implementation. In fact, Web Beans defines a sophisticated facility for overriding Web Bean implementations at deployment time, as we will see in Section 4.2, “Deployment types”.

Note that not all clients of a Web Bean are Web Beans. Other objects such as Servlets or Message-Driven Beans — which are by nature not injectable, contextual objects — may also obtain references to Web Beans by injection.

Enough hand-waving. More formally, according to the spec:

Let's see what some of these terms mean, to the Web Bean developer.

@CreditCard PaymentProcessor paymentProcessor

@CreditCard

public class CreditCardPaymentProcessor 

    implements PaymentProcessor { ... }

@Mock

public class MockSentenceTranslator implements Translator {

    public String translate(String sentence) {

        return "Lorem ipsum dolor sit amet";

    }

}

@SessionScoped

public class ShoppingCart { ... }

@SessionScoped @Named("cart")

public class ShoppingCart { ... }

<h:dataTable value="#{cart.lineItems}" var="item">
    ....
</h:dataTable>

@SessionScoped @Named

public class ShoppingCart { ... }

@SessionScoped 

@Interceptors(TransactionInterceptor.class)

public class ShoppingCart { ... }

@SessionScoped @Transactional

public class ShoppingCart { ... }

We've already seen that JavaBeans, EJBs and some other Java classes can be Web Beans. But exactly what kinds of objects are Web Beans?

@Stateful @SessionScoped

public class ShoppingCart {


    ...

    

    @Remove

    public void destroy() {}


}

@ApplicationScoped

public class Generator {


    private Random random = new Random( System.currentTimeMillis() );

    

    @Produces @Random int next() {

        return random.nextInt(100);

    }


}

@Random int randomNumber

@Produces @RequestScoped Connection connect(User user) {

    return createConnection( user.getId(), user.getPassword() );

}

void close(@Disposes Connection connection) {

    connection.close();

}

You'll need to download JBoss AS 5.0.1.GA from jboss.org, and unzip it. For example:

$ cd /Applications
$ unzip ~/jboss-5.0.1.GA.zip

Next, download Web Beans from seamframework.org, and unzip it. For example

$ cd ~/
$ unzip ~/webbeans-$VERSION.zip

Next, we need to tell Web Beans where JBoss is located. Edit jboss-as/build.properties and set the jboss.home property. For example:

jboss.home=/Applications/jboss-5.0.1.GA

To install Web Beans, you'll need Ant 1.7.0 installed, and the ANT_HOME environment variable set. For example:

$ unzip apache-ant-1.7.0.zip
$ export ANT_HOME=~/apache-ant-1.7.0

Then, you can install the update. The update script will use Maven to download Web Beans automatically.

$ cd webbeans-$VERSION/jboss-as
$ ant update

Now, you're ready to deploy your first example!

To deploy the numberguess example:

$ cd examples/numberguess
ant deploy

Start JBoss AS:

$ /Application/jboss-5.0.0.GA/bin/run.sh

Wait for the application to deploy, and enjoy hours of fun at http://localhost:8080/webbeans-numberguess!

Web Beans includes a second simple example that will translate your text into Latin. The numberguess example is a war example, and uses only simple beans; the translator example is an ear example, and includes enterprise beans, packaged in an EJB module. To try it out:

$ cd examples/translator
ant deploy

Wait for the application to deploy, and visit http://localhost:8080/webbeans-translator!

You'll need to download Tomcat 6.0.18 or later from tomcat.apache.org, and unzip it. For example:

$ cd /Applications
$ unzip ~/apache-tomcat-6.0.18.zip

Next, download Web Beans from seamframework.org, and unzip it. For example

$ cd ~/
$ unzip ~/webbeans-$VERSION.zip

Next, we need to tell Web Beans where Tomcat is located. Edit jboss-as/build.properties and set the tomcat.home property. For example:

tomcat.home=/Applications/apache-tomcat-6.0.18

To deploy the numberguess example for tomcat:

$ cd examples/tomcat
ant tomcat.deploy

Start Tomcat:

$ /Applications/apache-tomcat-6.0.18/bin/startup.sh

Wait for the application to deploy, and enjoy hours of fun at http://localhost:8080/webbeans-numberguess!

TODO

In the numberguess application you get given 10 attempts to guess a number between 1 and 100. After each attempt, you will be told whether you are too high, or too low.

The numberguess example is comprised of a number of Web Beans, configuration files, and Facelet JSF pages, packaged as a war. Let's start with the configuration files.

All the configuration files for this example are located in WEB-INF/, which is stored in WebContent in the source tree. First, we have faces-config.xml, in which we tell JSF to use Facelets:

<?xml version='1.0' encoding='UTF-8'?>

<faces-config version="1.2"

              xmlns="http://java.sun.com/xml/ns/javaee"

              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

              xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd">

    

    <application>

        <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>

    </application>



</faces-config>

There is an empty web-beans.xml file, which marks this application as a Web Beans application.

Finally there is web.xml:

<?xml version="1.0" encoding="UTF-8"?>

<web-app version="2.5"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
   
   <display-name>Web Beans Numbergues example</display-name>

   <!-- JSF -->

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

	Enable and load the JSF servlet
	Configure requests to .jsf pages to be handled by JSF
	Tell JSF that we will be giving our source files (facelets) an extension of .xhtml
	Configure a session timeout of 10 minutes

Let's take a look at the Facelet view:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:s="http://jboss.com/products/seam/taglib">

  <ui:composition template="template.xhtml">
    <ui:define name="content">
       <h1>Guess a number...</h1>
       <h:form id="NumberGuessMain">
          <div style="color: red">
             <h:messages id="messages" globalOnly="false"/>
             <h:outputText id="Higher" value="Higher!" rendered="#{game.number gt game.guess and game.guess ne 0}"/>
             <h:outputText id="Lower" value="Lower!" rendered="#{game.number lt game.guess and game.guess ne 0}"/>
          </div>
   
          <div>
             I'm thinking of a number between #{game.smallest} and #{game.biggest}.
             You have #{game.remainingGuesses} guesses.
          </div>
     
          <div>
             Your guess: 
             <h:inputText id="inputGuess" 
                          value="#{game.guess}" 
                          required="true" 
                          size="3" 
                          disabled="#{game.number eq game.guess}">
                <f:validateLongRange maximum="#{game.biggest}" 
                                     minimum="#{game.smallest}"/>
             </h:inputText>
            <h:commandButton id="GuessButton"  
                             value="Guess" 
                             action="#{game.check}" 
                             disabled="#{game.number eq game.guess}"/>
          </div>
          <div>
            <h:commandButton id="RestartButton" value="Reset" action="#{game.reset}" immediate="true" />
          </div>
       </h:form>
    </ui:define>
  </ui:composition>
</html>

	Facelets is a templating language for JSF, here we are wrapping our page in a template which defines the header.
	There are a number of messages which can be sent to the user, "Higher!", "Lower!" and "Correct!"
	As the user guesses, the range of numbers they can guess gets smaller - this sentance changes to make sure they know what range to guess in.
	This input field is bound to a Web Bean, using the value expression.
	A range validator is used to make sure the user doesn't accidentally input a number outside of the range in which they can guess - if the validator wasn't here, the user might use up a guess on an out of range number.
	And, of course, there must be a way for the user to send their guess to the server. Here we bind to an action method on the Web Bean.

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

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

@Retention(RUNTIME)

@Documented

@BindingType

public @interface Random {}

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

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

@Retention(RUNTIME)

@Documented

@BindingType

public @interface MaxNumber {}

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

   

   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;

   }


}

You'll notice that the Generator is application scoped; therefore we don't get a different random each time.

The final Web Bean in the application is the session scoped Game.

You'll note that we've used the @Named annotation, so that we can use the bean through EL in the JSF page. Finally, we've used constructor injection to initialize the game with a random number. And of course, we need to tell the player when they've won, so we give feedback with a FacesMessage.

package org.jboss.webbeans.examples.numberguess;



import javax.annotation.PostConstruct;

import javax.faces.application.FacesMessage;

import javax.faces.context.FacesContext;

import javax.webbeans.AnnotationLiteral;

import javax.webbeans.Current;

import javax.webbeans.Initializer;

import javax.webbeans.Named;

import javax.webbeans.SessionScoped;

import javax.webbeans.manager.Manager;


@Named

@SessionScoped

public class Game

{

   private int number;

   

   private int guess;

   private int smallest;

   private int biggest;

   private int remainingGuesses;

   

   @Current Manager manager;

   

   public Game()

   {

   }

   

   @Initializer

   Game(@MaxNumber int maxNumber)

   {      

      this.biggest = maxNumber;

   }


   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;

   }

   

   public String check()

   {

      if (guess>number)

      {

         biggest = guess - 1;

      }

      if (guess<number)

      {

         smallest = guess + 1;

      }

      if (guess == number)

      {

         FacesContext.getCurrentInstance().addMessage(null, new FacesMessage("Correct!"));

      }

      remainingGuesses--;

      return null;

   }

   

   @PostConstruct

   public void reset()

   {

      this.smallest = 0;

      this.guess = 0;

      this.remainingGuesses = 10;

      this.number = manager.getInstanceByType(Integer.class, new AnnotationLiteral<Random>(){});

   }

   

}

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

3.4.2. The numberguess example for Apache Wicket

Whilst JSR-299 specifies integration with Java ServerFaces, Web Beans allows you to inject into Wicket components, and also allows you to use a conversation context with Wicket. In this section, we'll walk you through the Wicket version of the numberguess example.

Note

You may want to review the Wicket documentation at http://wicket.apache.org/.

Like the previous example, the Wicket WebBeans examples make use of the webbeans-servlet module. The use of the Jetty servlet container is common in the Wicket community, and is chosen here as the runtime container in order to facilitate comparison between the standard Wicket examples and these examples, and also to show how the webbeans-servlet integration is not dependent upon Tomcat as the servlet container.

These examples make use of the Eclipse IDE; instructions are also given to deploy the application from the command line.

3.4.2.1. Creating the Eclipse project

To generate an Eclipse project from the example:

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. Note that if you do not intend to run the example with jetty from within eclipse, omit the "-Pjetty." This will create a project in your workspace called webbeans-wicket-numberguess

3.4.2.2. Running the example from Eclipse

This project follows the wicket-quickstart approach of creating an instance of Jetty in the Start class. So running the example is as simple as right-clicking on that Start class in src/test/java in the Package Explorer and choosing Run as Java Application. You should see console output related to Jetty starting up; then visit able http://localhost:8080 to view the app. To debug choose Debug as Java Application.

3.4.2.3. Running the example from the command line in JBoss AS or Tomcat

This example can also be deployed from the command line in a (similar to the other examples). Assuming you have set up the build.properties file in the examples directory to specify the location of JBoss AS or Tomcat, as previously described, you can run ant deploy from the examples/wicket/numberguess directory, and access the application at http://localhost:8080/webbeans-numberguess-wicket.

3.4.2.4. Understanding the code

JSF uses Unified EL expressions to bind view layer components in JSP or Facelet views to beans, Wicket defines it's components in Java. The markup is plain html with a one-to-one mapping between html elements and the view components. All view logic, including binding of components to models and controlling the response of view actions, is handled in Java. The integration of Web Beans with Wicket takes advantage of the same binding annotations used in your business layer to provide injection into your WebPage subclass (or into other custom wicket component subclasses).

The code in the wicket numberguess example is very similar to the JSF-based numberguess example. The business layer is identical!

Differences are:

• Each wicket application must have a WebApplication subclass, In our case, our application class is SampleApplication:

  public class SampleApplication extends WebBeansApplication {
     @Override
     public Class getHomePage() {
        return HomePage.class;
     }
  }

  This class specifies which page wicket should treat as our home page, in our case, HomePage.class

• In HomePage we see typical wicket code to set up page elements. The bit that is interesting is the injection of the Game bean:

   @Current Game game;

  The Game bean is can then be used, for example, by the code for submitting a guess:

  final Component guessButton = new AjaxButton("GuessButton") { 
     protected void onSubmit(AjaxRequestTarget target, Form form) {
        if (game.check()) {

  Note

  All injections may be serialized; actual storage of the bean is managed by JSR-299. Note that Wicket components, like the HomePage and it subcomponents, are not JSR-299 beans.

  Wicket components allow injection, but they cannot use interceptors, decorators and lifecycle callbacks such as @PostConstruct or @Initializer methods.

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

• In order to activate wicket for this webapp, the Wicket filter is added to web.xml, and our application class is specified:

  <filter>
     <filter-name>wicket.numberguess-example</filter-name>
     <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
     <init-param>
        <param-name>applicationClassName</param-name>
        <param-value>org.jboss.webbeans.examples.wicket.SampleApplication</param-value>
     </init-param>
  </filter>
  
  <filter-mapping>
     <filter-name>wicket.numberguess-example</filter-name>
     <url-pattern>/*</url-pattern>
  </filter-mapping>
   
  <listener>
     <listener-class>org.jboss.webbeans.environment.servlet.Listener</listener-class>
  </listener>

  Note that the servlet listener is also added, as in the Tomcat example, in order to boostrap Web Beans when Jetty starts, and to hook Web Beans into the Jetty servlet request and session lifecycles.

3.4.3. The numberguess example for Java SE with Swing

This example can be found in the examples/se/numberguess folder of the Web Beans distribution.

To run this example:

• Open a command line/terminal window in the examples/se/numberguess directory

• Ensure that Maven 2 is installed and in your PATH

• Ensure that the JAVA_HOME environment variable is pointing to your JDK installation

• execute the following command

  mvn -Drun

There is an empty beans.xml file in the root package (src/main/resources/beans.xml), which marks this application as a Web Beans application.

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

@ApplicationScoped

public class Game implements Serializable

{


    private int number;

    private int guess;

    private int smallest;


    @MaxNumber

    private int maxNumber;


    private int biggest;

    private int remainingGuesses;

    private boolean validNumberRange = true;


    @Current Generator rndGenerator;


    ...


    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.number = rndGenerator.next();

    }

}

	The bean is application scoped instead of session scoped, since an instance of the application represents a single 'session'.
	The bean is not named, since it doesn't need to be accessed via EL
	There is no JSF FacesContext to add messages to. Instead the Game class provides additional information about the state of the current game including: If the game has been won or lost If the most recent guess was invalid This allows the Swing UI to query the state of the game, which it does indirectly via a class called MessageGenerator, in order to determine the appropriate messages to display to the user during the game.
	Validation of user input is performed during the check() method, since there is no dedicated validation phase
	The reset() method makes a call to the injected rndGenerator in order to get the random number at the start of each game. It cannot use manager.getInstanceByType(Integer.class, new AnnotationLiteral<Random>(){}) as the JSF example does because there will not be any active contexts like there is during a JSF request.

The MessageGenerator class depends on the current instance of Game, 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 MessageGenerator is as follows:

public class MessageGenerator

{

    @Current 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 guess 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.";

        }

    }

}

	The instance of Game for the application is injected here.
	The Game's state is interrogated to determine the appropriate challenge message.
	And again to determine whether to congratulate, console or encourage the user to continue.

Finally we come to the NumberGuessFrame class which provides the Swing front end to our guessing game.

public class NumberGuessFrame  extends javax.swing.JFrame

{

    private @Current Game game;

    private @Current MessageGenerator msgGenerator;


    public void start( @Observes @Deployed Manager manager )

    {

        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;


}

	The injected instance of the game (logic and state).
	The injected message generator for UI messages.
	This application is started in the usual Web Beans SE way, by observing the @Deployed Manager event.
	This method initialises all of the Swing components. Note the use of the msgGenerator.
	guessButtonActionPerformed is called when the 'Guess' button is clicked, and it does the following: Gets the guess entered by the user and sets it as the current guess in the Game Calls game.check() to validate and perform one 'turn' of the game Calls refreshUI. If there were validation errors with the input, this will have been captured during game.check() and as such will be reflected in the messeges returned by MessageGenerator 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).
	replayBtnActionPerformed simply calls game.reset() to start a new game and refreshes the messages in the UI.
	refreshUI uses the MessageGenerator to update the messages to the user based on the current state of the Game.

The translator example will take any sentences you enter, and translate them to Latin.

The translator example is built as an ear, and contains EJBs. As a result, it's structure is more complex than the numberguess example.

First, let's take a look at the ear aggregator, which is located in webbeans-translator-ear module. Maven automatically generates the application.xml for us:

<plugin>

   <groupId>org.apache.maven.plugins</groupId>

   <artifactId>maven-ear-plugin</artifactId>

   <configuration>

      <modules>

         <webModule>

            <groupId>org.jboss.webbeans.examples.translator</groupId>

            <artifactId>webbeans-translator-war</artifactId>

            <contextRoot>/webbeans-translator</contextRoot>

         </webModule>

      </modules>

   </configuration>

</plugin>

Here we set the context path, which gives us a nice url (http://localhost:8080/webbeans-translator).

<?xml version="1.0" encoding="UTF-8"?>

<application xmlns="http://java.sun.com/xml/ns/javaee" 

             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

             xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_5.xsd"

             version="5">

  <display-name>webbeans-translator-ear</display-name>

  <description>Ear Example for the reference implementation of JSR 299: Web Beans</description>

  

  <module>

    <web>

      <web-uri>webbeans-translator.war</web-uri>

      <context-root>/webbeans-translator</context-root>

    </web>

  </module>

  <module>

    <ejb>webbeans-translator.jar</ejb>

  </module>

</application>

Next, lets look at the war. Just as in the numberguess example, we have a faces-config.xml (to enable Facelets) and a web.xml (to enable JSF) in WebContent/WEB-INF.

More intersting is the facelet used to translate text. Just as in the numberguess example we have a template, which surrounds the form (ommitted here for brevity):

<h:form id="NumberGuessMain">

            

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

The user can enter some text in the lefthand textarea, and hit the translate button to see the result to the right.

Finally, let's look at the ejb module, webbeans-translator-ejb. In src/main/resources/META-INF there is just an empty web-beans.xml, used to mark the archive as containing Web Beans.

We've saved the most interesting bit to last, the code! The project has two simple beans, SentenceParser and TextTranslator and two enterprise beans, TranslatorControllerBean and SentenceTranslator. You should be getting quite familiar with what a Web Bean looks like by now, so we'll just highlight the most interesting bits here.

Both SentenceParser and TextTranslator are dependent beans, and TextTranslator uses constructor initialization:

public class TextTranslator { 

   private SentenceParser sentenceParser; 

   private Translator sentenceTranslator; 

   

   @Initializer

   TextTranslator(SentenceParser sentenceParser, Translator sentenceTranslator) 

   { 

      this.sentenceParser = sentenceParser; 

      this.sentenceTranslator = sentenceTranslator;

TextTranslator is a stateless bean (with a local business interface), where the magic happens - of course, we couldn't develop a full translator, but we gave it a good go!

Finally, there is UI orientated controller, that collects the text from the user, and dispatches it to the translator. This is a request scoped, named, stateful session bean, which injects the translator.

@Stateful

@RequestScoped

@Named("translator")

public class TranslatorControllerBean implements TranslatorController

{

   

   @Current TextTranslator translator;

The bean also has getters and setters for all the fields on the page.

As this is a stateful session bean, we have to have a remove method:

   @Remove

   public void remove()

   {

      

   }

The Web Beans manager will call the remove method for you when the bean is destroyed; in this case at the end of the request.

If we have more than one Web Bean that implements a particular API type, the injection point can specify exactly which Web Bean should be injected using a binding annotation. For example, there might be two implementations of PaymentProcessor:

@PayByCheque

public class ChequePaymentProcessor implements PaymentProcessor {

    public void process(Payment payment) { ... }

}

@PayByCreditCard

public class CreditCardPaymentProcessor implements PaymentProcessor {

    public void process(Payment payment) { ... }

}

Where @PayByCheque and @PayByCreditCard are binding annotations:

@Retention(RUNTIME)

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

@BindingType

public @interface PayByCheque {}

@Retention(RUNTIME)

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

@BindingType

public @interface PayByCreditCard {}

A client Web Bean developer uses the binding annotation to specify exactly which Web Bean should be injected.

Using field injection:

@PayByCheque PaymentProcessor chequePaymentProcessor;

@PayByCreditCard PaymentProcessor creditCardPaymentProcessor;

Using initializer method injection:

@Initializer

public void setPaymentProcessors(@PayByCheque PaymentProcessor chequePaymentProcessor, 

                                 @PayByCreditCard PaymentProcessor creditCardPaymentProcessor) {

   this.chequePaymentProcessor = chequePaymentProcessor;

   this.creditCardPaymentProcessor = creditCardPaymentProcessor;

}

Or using constructor injection:

@Initializer

public Checkout(@PayByCheque PaymentProcessor chequePaymentProcessor, 

                @PayByCreditCard PaymentProcessor creditCardPaymentProcessor) {

   this.chequePaymentProcessor = chequePaymentProcessor;

   this.creditCardPaymentProcessor = creditCardPaymentProcessor;

}

@Retention(RUNTIME)

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

@BindingType

public @interface PayBy {

    PaymentType value();

}

@PayBy(CHEQUE) PaymentProcessor chequePaymentProcessor;

@PayBy(CREDIT_CARD) PaymentProcessor creditCardPaymentProcessor;

@Asynchronous @PayByCheque PaymentProcessor paymentProcessor

@Produces 

@Asynchronous @PayByCheque 

PaymentProcessor createAsyncPaymentProcessor(@PayByCheque PaymentProcessor processor) {

    return new AsynchronousPaymentProcessor(processor);

}

All Web Beans have a deployment type. Each deployment type identifies a set of Web Beans that should be conditionally installed in some deployments of the system.

For example, we could define a deployment type named @Mock, which would identify Web Beans that should only be installed when the system executes inside an integration testing environment:

@Retention(RUNTIME)

  @Target({TYPE, METHOD})

  @DeploymentType

  public @interface Mock {}

Suppose we had some Web Bean that interacted with an external system to process payments:

public class ExternalPaymentProcessor {

        

    public void process(Payment p) {

        ...

    }

    

}

Since this Web Bean does not explicitly specify a deployment type, it has the default deployment type @Production.

For integration or unit testing, the external system is slow or unavailable. So we would create a mock object:

@Mock 

public class MockPaymentProcessor implements PaymentProcessor {


    @Override

    public void process(Payment p) {

        p.setSuccessful(true);

    }


}

But how does the Web Bean manager determine which implementation to use in a particular deployment?

<WebBeans>

    <Deploy>

        <Standard/>

        <Production/>

        <test:Mock/>

    </Deploy>

</WebBeans>

@Current PaymentProcessor paymentProcessor

The typesafe resolution algorithm fails when, after considering the binding annotations and and deployment types of all Web Beans that implement the API type of an injection point, the Web Bean manager is unable to identify exactly one Web Bean to inject.

It's usually easy to fix an UnsatisfiedDependencyException or AmbiguousDependencyException.

To fix an UnsatisfiedDependencyException, simply provide a Web Bean which implements the API type and has the binding types of the injection point — or enable the deployment type of a Web Bean that already implements the API type and has the binding types.

To fix an AmbiguousDependencyException, introduce a binding type to distinguish between the two implementations of the API type, or change the deployment type of one of the implementations so that the Web Bean manager can use deployment type precedence to choose between them. An AmbiguousDependencyException can only occur if two Web Beans share a binding type and have exactly the same deployment type.

There's one more issue you need to be aware of when using dependency injection in Web Beans.

Clients of an injected Web Bean do not usually hold a direct reference to a Web Bean instance.

Imagine that a Web Bean bound to the application scope held a direct reference to a Web Bean bound to the request scope. The application scoped Web Bean is shared between many different requests. However, each request should see a different instance of the request scoped Web bean!

Now imagine that a Web Bean bound to the session scope held a direct reference to a Web Bean bound to the application scope. From time to time, the session context is serialized to disk in order to use memory more efficiently. However, the application scoped Web Bean instance should not be serialized along with the session scoped Web Bean!

Therefore, unless a Web Bean has the default scope @Dependent, the Web Bean manager must indirect all injected references to the Web Bean through a proxy object. This client proxy is responsible for ensuring that the Web Bean instance that receives a method invocation is the instance that is associated with the current context. The client proxy also allows Web Beans bound to contexts such as the session context to be serialized to disk without recursively serializing other injected Web Beans.

Unfortunately, due to limitations of the Java language, some Java types cannot be proxied by the Web Bean manager. Therefore, the Web Bean manager throws an UnproxyableDependencyException if the type of an injection point cannot be proxied.

The following Java types cannot be proxied by the Web Bean manager:

It's usually very easy to fix an UnproxyableDependencyException. Simply add a constructor with no parameters to the injected class, introduce an interface, or change the scope of the injected Web Bean to @Dependent.

The application may obtain an instance of the interface Manager by injection:

@Current Manager manager;

The Manager object provides a set of methods for obtaining a Web Bean instance programatically.

PaymentProcessor p = manager.getInstanceByType(PaymentProcessor.class);

Binding annotations may be specified by subclassing the helper class AnnotationLiteral, since it is otherwise difficult to instantiate an annotation type in Java.

PaymentProcessor p = manager.getInstanceByType(PaymentProcessor.class, 

                                               new AnnotationLiteral<CreditCard>(){});

If the binding type has an annotation member, we can't use an anonymous subclass of AnnotationLiteral — instead we'll need to create a named subclass:

abstract class CreditCardBinding 

    extends AnnotationLiteral<CreditCard> 

    implements CreditCard {}

PaymentProcessor p = manager.getInstanceByType(PaymentProcessor.class, 

                                               new CreditCardBinding() { 

                                                   public void value() { return paymentType; } 

                                               } );

Enterprise Web Beans support all the lifecycle callbacks defined by the EJB specification: @PostConstruct, @PreDestroy, @PrePassivate and @PostActivate.

Simple Web Beans support only the @PostConstruct and @PreDestroy callbacks.

Both enterprise and simple Web Beans support the use of @Resource, @EJB and @PersistenceContext for injection of Java EE resources, EJBs and JPA persistence contexts, respectively. Simple Web Beans do not support the use of @PersistenceContext(type=EXTENDED).

The @PostConstruct callback always occurs after all dependencies have been injected.

There are certain kinds of dependent objects — Web Beans with scope @Dependent — that need to know something about the object or injection point into which they are injected in order to be able to do what they do. For example:

A Web Bean with scope @Dependent may inject an instance of InjectionPoint and access metadata relating to the injection point to which it belongs.

Let's look at an example. The following code is verbose, and vulnerable to refactoring problems:

Logger log = Logger.getLogger(MyClass.class.getName());

This clever little producer method lets you inject a JDK Logger without explicitly specifying the log category:

class LogFactory {


   @Produces Logger createLogger(InjectionPoint injectionPoint) { 

      return Logger.getLogger(injectionPoint.getMember().getDeclaringClass().getName()); 

   }


}

We can now write:

@Current Logger log;

Not convinced? Then here's a second example. To inject HTTP parameters, we need to define a binding type:

@BindingType

@Retention(RUNTIME)

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

public @interface HttpParam {

   @NonBinding public String value();

}

We would use this binding type at injection points as follows:

@HttpParam("username") String username;

@HttpParam("password") String password;

The following producer method does the work:

class HttpParams


   @Produces @HttpParam("")

   String getParamValue(ServletRequest request, InjectionPoint ip) {

      return request.getParameter(ip.getAnnotation(HttpParam.class).value());

   }


}

(Note that the value() member of the HttpParam annotation is ignored by the Web Bean manager since it is annotated @NonBinding.)

The Web Bean manager provides a built-in Web Bean that implements the InjectionPoint interface:

public interface InjectionPoint { 

   public Object getInstance(); 

   public Bean<?> getBean(); 

   public Member getMember(): 

   public <T extends Annotation> T getAnnotation(Class<T> annotation); 

   public Set<T extends Annotation> getAnnotations(); 

}

Web Beans features an extensible context model. It is possible to define new scopes by creating a new scope type annotation:

@Retention(RUNTIME)

@Target({TYPE, METHOD})

@ScopeType

public @interface ClusterScoped {}

Of course, that's the easy part of the job. For this scope type to be useful, we will also need to define a Context object that implements the scope! Implementing a Context is usually a very technical task, intended for framework development only.

We can apply a scope type annotation to a Web Bean implementation class to specify the scope of the Web Bean:

@ClusterScoped

public class SecondLevelCache { ... }

Usually, you'll use one of Web Beans' built-in scopes.

Web Beans defines four built-in scopes:

For a web application that uses Web Beans:

The request and application scopes are also active:

If the application tries to invoke a Web Bean with a scope that does not have an active context, a ContextNotActiveException is thrown by the Web Bean manager at runtime.

Three of the four built-in scopes should be extremely familiar to every Java EE developer, so let's not waste time discussing them here. One of the scopes, however, is new.

The Web Beans conversation scope is a bit like the traditional session scope in that it holds state associated with a user of the system, and spans multiple requests to the server. However, unlike the session scope, the conversation scope:

A conversation represents a task, a unit of work from the point of view of the user. The conversation context holds state associated with what the user is currently working on. If the user is doing multiple things at the same time, there are multiple conversations.

The conversation context is active during any JSF request. However, most conversations are destroyed at the end of the request. If a conversation should hold state across multiple requests, it must be explicitly promoted to a long-running conversation.

@Current Conversation conversation;

@ConversationScoped @Stateful

public class OrderBuilder {


    private Order order;

    private @Current Conversation conversation;

    private @PersistenceContext(type=EXTENDED) EntityManager em;

    

    @Produces public Order getOrder() {

        return order;

    }


    public Order createOrder() {

        order = new Order();

        conversation.begin();

        return order;

    }

    

    public void addLineItem(Product product, int quantity) {

        order.add( new LineItem(product, quantity) );

    }


    public void saveOrder(Order order) {

        em.persist(order);

        conversation.end();

    }

    

    @Remove

    public void destroy() {}

    

}

<a href="/addProduct.jsp?cid=#{conversation.id}">Add Product</a>

conversation.setTimeout(timeoutInMillis);

In addition to the four built-in scopes, Web Beans features the so-called dependent pseudo-scope. This is the default scope for a Web Bean which does not explicitly declare a scope type.

For example, this Web Bean has the scope type @Dependent:

public class Calculator { ... }

When an injection point of a Web Bean resolves to a dependent Web Bean, a new instance of the dependent Web Bean is created every time the first Web Bean is instantiated. Instances of dependent Web Beans are never shared between different Web Beans or different injection points. They are dependent objects of some other Web Bean instance.

Dependent Web Bean instances are destroyed when the instance they depend upon is destroyed.

Web Beans makes it easy to obtain a dependent instance of a Java class or EJB bean, even if the class or EJB bean is already declared as a Web Bean with some other scope type.

@New Calculator calculator;

@ConversationScoped

public class Calculator { ... }

public class PaymentCalc {


    @Current Calculator calculator;

    @New Calculator newCalculator;


}

The scope of the producer method defaults to @Dependent, and so it will be called every time the Web Bean manager injects this field or any other field that resolves to the same producer method. Thus, there could be multiple instances of the PaymentStrategy object for each user session.

To change this behavior, we can add a @SessionScoped annotation to the method.

@Produces @Preferred @SessionScoped

public PaymentStrategy getPaymentStrategy() {

    ...

}

Now, when the producer method is called, the returned PaymentStrategy will be bound to the session context. The producer method won't be called again in the same session.

There's one potential problem with the code above. The implementations of CreditCardPaymentStrategy are instantiated using the Java new operator. Objects instantiated directly by the application can't take advantage of dependency injection and don't have interceptors.

If this isn't what we want we can use dependency injection into the producer method to obtain Web Bean instances:

@Produces @Preferred @SessionScoped

public PaymentStrategy getPaymentStrategy(CreditCardPaymentStrategy ccps,

                                          ChequePaymentStrategy cps,

                                          PayPalPaymentStrategy ppps) {

    switch (paymentStrategy) {

        case CREDIT_CARD: return ccps;

        case CHEQUE: return cps;

        case PAYPAL: return ppps;

        default: return null;

    } 

}

Wait, what if CreditCardPaymentStrategy is a request scoped Web Bean? Then the producer method has the effect of "promoting" the current request scoped instance into session scope. This is almost certainly a bug! The request scoped object will be destroyed by the Web Bean manager before the session ends, but the reference to the object will be left "hanging" in the session scope. This error will not be detected by the Web Bean manager, so please take extra care when returning Web Bean instances from producer methods!

There's at least three ways we could go about fixing this bug. We could change the scope of the CreditCardPaymentStrategy implementation, but this would affect other clients of that Web Bean. A better option would be to change the scope of the producer method to @Dependent or @RequestScoped.

But a more common solution is to use the special @New binding annotation.

Consider the following producer method:

@Produces @Preferred @SessionScoped

public PaymentStrategy getPaymentStrategy(@New CreditCardPaymentStrategy ccps,

                                          @New ChequePaymentStrategy cps,

                                          @New PayPalPaymentStrategy ppps) {

    switch (paymentStrategy) {

        case CREDIT_CARD: return ccps;

        case CHEQUE: return cps;

        case PAYPAL: return ppps;

        default: return null;

    } 

}

Then a new dependent instance of CreditCardPaymentStrategy will be created, passed to the producer method, returned by the producer method and finally bound to the session context. The dependent object won't be destroyed until the Preferences object is destroyed, at the end of the session.