[webbeans-commits] Webbeans SVN: r2607 - examples/trunk/se/numberguess.

Author: peteroyle Date: 2009-04-20 18:35:22 -0400 (Mon, 20 Apr 2009) New Revision: 2607 Added: examples/trunk/se/numberguess/readme.txt Log: Added redame for numberguess example Added: examples/trunk/se/numberguess/readme.txt =================================================================== --- examples/trunk/se/numberguess/readme.txt (rev 0) +++ examples/trunk/se/numberguess/readme.txt 2009-04-20 22:35:22 UTC (rev 2607) @@ -0,0 +1,94 @@ +=================== +Swing Example: Number Guess +=================== + +Here's an example of a Swing application, Number Guess, similar to the example in chapter 3.4. +In the Number Guess 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. This example can +be found in the examples/se/numberguess folder of the Web Beans distribution. + +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. Some key points about this class: + + 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. Some key points about this class: + + 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. + + 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. + +----------------- +Running the Example +----------------- + +As with all Web Beans SE applications, this example is executed +by starting Java with org.jboss.webbeans.environment.se.StartMain +as the main class. Of course you will need all of the relevant jar dependencies +on your classpath, which is most easily done by loading the project into your +favourite Maven-capable IDE and running it from there.. + +To run this example using Maven directly: + +- 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