Development Guide

1. Go to https://access.redhat.com/.
2. Select Downloads from the menu at the top of the page.
3. Find Red Hat JBoss Developer Studio in the list and click on it.
4. Select the appropriate version and click Download.

Procedure 1.1. Install Red Hat JBoss Developer Studio

1. Open a terminal.
2. Move into the directory containing the downloaded .jar file.
3. Run the following command to launch the GUI installer:

   java -jar jbdevstudio-build_version.jar

   Copy to Clipboard Toggle word wrap
4. Click Next to start the installation process.
5. Select I accept the terms of this license agreement and click Next.
6. Adjust the installation path and click Next.

   Note

   If the installation path folder does not exist, a prompt will appear. Click Ok to create the folder.
7. Choose a JVM, or leave the default JVM selected, and click Next.
8. Add any application platforms available, and click Next.
9. Review the installation details, and click Next.
10. Click Next when the installation process is complete.
11. Configure the desktop shortcuts for Red Hat JBoss Developer Studio, and click Next.
12. Click Done.

Procedure 1.2. Command to start Red Hat JBoss Developer Studio

1. Open a terminal.
2. Change into the installation directory.
3. Run the following command to start Red Hat JBoss Developer Studio:

   [localhost]$ ./jbdevstudio

   Copy to Clipboard Toggle word wrap

Procedure 1.3. Add the server

1. Open the Servers tab. If there is no Servers tab, add it to the panel as follows:
   1. Click Window → Show View → Other....
   2. Select Servers from the Server folder and click OK.
2. Click on No servers are available. Click this link to create a new server... or, if you prefer, right-click within the blank Server panel and select New → Server.
   

   View larger image

   

   Figure 1.1. Add a new server - No servers available

3. Expand JBoss Enterprise Middleware and choose JBoss Enterprise Application Platform 6.1+. Enter a server name, for example, "JBoss Enterprise Application Platform 6.4", then click Next to create the JBoss runtime and define the server. The next time you define a new server, this dialog displays a Server runtime environment selection with the new runtime definition.
   

   View larger image

   

   Figure 1.2. Define a New Server

4. Create a Server Adapter to manage starting and stopping the server. Keep the defaults and click Next.
   

   View larger image

   

   Figure 1.3. Create a New Server Adapter

5. Enter a name, for example "JBoss EAP 6.4 Runtime". Under Home Directory, click Browse and navigate to your JBoss EAP install location. Then click Next.
   

   View larger image

   

   Figure 1.4. Add New Server Runtime Environment

   Note

   Some quickstarts require that you run the server with a different profile or additional arguments. To deploy a quickstart that requires the full profile, you must define a new server and add a Server Runtime Environment that specifies standalone-full.xml for the Configuration file. Be sure to give the new server a descriptive name.
6. Configure existing projects for the new server. Because you do not have any projects at this point, click Finish.
   

   View larger image

   

   Figure 1.5. Modify resources for the new JBoss server

Procedure 1.4. Download the Quickstarts

1. Open a web browser and access this URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
2. Find "Quickstarts" in the list.
3. Click the Download button to download a Zip archive containing the examples.
4. Unzip the archive in a directory of your choosing.

Procedure 1.5. Import the quickstarts into Red Hat JBoss Developer Studio

1. If you have not yet done so, Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.

2. Start Red Hat JBoss Developer Studio.

3. From the menu, select File → Import.

4. In the selection list, choose Maven → Existing Maven Projects, then click Next.
   

   View larger image

   

   Figure 1.7. Import Existing Maven Projects

5. Browse to the directory of the quickstart you plan to test, for example the helloworld quickstart, and click OK. The Projects list box is populated with the pom.xml file of the selected quickstart project.
   

   View larger image

   

   Figure 1.8. Select Maven Projects

6. Click Finish.

Procedure 1.6. Build and Deploy the helloworld quickstart

1. If you do not see a Servers tab or have not yet defined a server, follow the instructions here: Section 1.3.1.5, “Add the JBoss EAP Server Using Define New Server”. If you plan to deploy a quickstart that requires the full profile or additional startup arguments, be sure to create the server runtime environment as noted in the quickstart instructions.
2. Right-click on the jboss-helloworld project in the Project Explorer tab and select Run As. You are provided with a list of choices. Select Run on Server.
   

   View larger image

   

   Figure 1.9. Run As - Run on Server

3. Select JBoss EAP 6.1+ Runtime Server from the server list and click Next.
   

   View larger image

   

   Figure 1.10. Run on Server

4. The next screen displays the resources that are configured on the server. The jboss-helloworld quickstart is configured for you. Click Finish to deploy the quickstart.
   

   View larger image

   

   Figure 1.11. Modify Resources Configured on the Server

5. Review the results.

   • In the Server tab, the JBoss EAP 6.x Runtime Server status changes to [Started, Republish] .
   • The server Console tab shows messages detailing the JBoss EAP 6.x server start and the helloworld quickstart deployment.
   • A helloworld tab appears displaying the URL http://localhost:8080/jboss-helloworld/HelloWorld and the text "Hello World!".
   • The following messages in the Console confirm deployment of the jboss-helloworld.war file:

     JBAS018210: Register web context: /jboss-helloworld
     JBAS018559: Deployed "jboss-helloworld.war" (runtime-name : "jboss-helloworld.war")
     

     Copy to Clipboard Toggle word wrap

     The registered web context is appended to http://localhost:8080 to provide the URL used to access the deployed application.
6. To verify the helloworld quickstart deployed successfully to the JBoss server, open a web browser and access the application at this URL: http://localhost:8080/jboss-helloworld

Procedure 1.7. Run the bean-validation quickstart Arquillian tests

1. Follow the procedure above to import the bean-validation quickstart into Red Hat JBoss Developer Studio.
2. In the Servers tab, right-click on the server and choose Start to start the JBoss EAP server. If you do not see a Servers tab or have not yet defined a server, follow the instructions here: Section 1.3.1.5, “Add the JBoss EAP Server Using Define New Server”.
3. Right-click on the jboss-bean-validation project in the Project Explorer tab and select Run As. You are provided with a list of choices. Select Maven Build.
4. In the Goals input field of the Edit Configuration dialog, type: clean test -Parq-jbossas-remote
   Then click Run.
   

   View larger image

   

   Figure 1.12. Edit Configuration

5. Review the results.
   The server Console tab shows messages detailing the JBoss EAP server start and the output of the bean-validation quickstart Arquillian tests.

   -------------------------------------------------------
    T E S T S
   -------------------------------------------------------
   Running org.jboss.as.quickstarts.bean_validation.test.MemberValidationTest
   Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.189 sec
   
   Results :
   
   Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
   
   [INFO] ------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   

   Copy to Clipboard Toggle word wrap

Procedure 1.8. Build and Deploy the Quickstarts Using a Command Line

1. If you have not yet done so, Section 2.3.2, “Configure the JBoss EAP 6 Maven Repository Using the Maven Settings”.
2. Review the README.html file in the root directory of the quickstarts.
   This file contains general information about system requirements, how to configure Maven, how to add users, and how to run the Quickstarts. Be sure to read through it before you get started.
   It also contains a table listing the available quickstarts. The table lists each quickstart name and the technologies it demonstrates. It gives a brief description of each quickstart and the level of experience required to set it up. For more detailed information about a quickstart, click on the quickstart name.
   Some quickstarts are designed to enhance or extend other quickstarts. These are noted in the Prerequisites column. If a quickstart lists prerequisites, you must install them first before working with the quickstart.
   Some quickstarts require the installation and configuration of optional components. Do not install these components unless the quickstart requires them.
3. Run the helloworld quickstart.
   The helloworld quickstart is one of the simplest quickstarts and is a good way to verify that the JBoss server is configured and running correctly. Open the README.html file in the root of the helloworld quickstart. It contains detailed instructions on how to build and deploy the quickstart and access the running application
4. Run the other quickstarts.
   Follow the instructions in the README.html file located in the root folder of each quickstart to run the example.

Procedure 1.9. Examine the Directory Structure

1. The beans.xml file is located in the WEB-INF/ folder in the src/main/webapp/ directory of the quickstart.
2. The src/main/webapp/ directory also includes an index.html file which uses a simple meta refresh to redirect the user's browser to the Servlet, which is located at http://localhost:8080/jboss-helloworld/HelloWorld.
3. 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.
4. Notice that the quickstart doesn't even need a web.xml file!

Procedure 1.10. Examine the Code

1. Review the HelloWorldServlet code

   The HelloWorldServlet.java file is located in the src/main/java/org/jboss/as/quickstarts/helloworld/ directory. This Servlet sends the information to the browser.

   42.  @SuppressWarnings("serial")
   43.  @WebServlet("/HelloWorld")
   44.  public class HelloWorldServlet extends HttpServlet {
   45.  
   46.      static String PAGE_HEADER = "<html><head><title>helloworld</title></head><body>";
   47.  
   48.      static String PAGE_FOOTER = "</body></html>";
   49.  
   50.      @Inject
   51.      HelloService helloService;
   52.  
   53.      @Override
   54.      protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
   55.          resp.setContentType("text/html");
   56.          PrintWriter writer = resp.getWriter();
   57.          writer.println(PAGE_HEADER);
   58.          writer.println("<h1>" + helloService.createHelloMessage("World") + "</h1>");
   59.          writer.println(PAGE_FOOTER);
   60.          writer.close();
   61.      }
   62.  
   63.  }
   

   Copy to Clipboard Toggle word wrap
   Expand

   Table 1.1. HelloWorldServlet Details

   Line	Note
   43	Before Java EE 6, an XML file was used to register Servlets. It is now much cleaner. All you need to do is add the @WebServlet annotation and provide a mapping to a URL used to access the servlet.
   46-48	Every web page needs correctly formed HTML. This quickstart uses static Strings to write the minimum header and footer output.
   50-51	These lines inject the HelloService CDI bean which generates the actual message. As long as we don't alter the API of HelloService, this approach allows us to alter the implementation of HelloService at a later date without changing the view layer.
   58	This line calls into the service to generate the message "Hello World", and write it out to the HTTP request.

   Show more

2. Review the HelloService code

   The HelloService.java file is located in the src/main/java/org/jboss/as/quickstarts/helloworld/ directory. This service is very simple. It returns a message. No XML or annotation registration is required.

   public class HelloService {
   
       String createHelloMessage(String name) {
           return "Hello " + name + "!"; 
       }
   }
   

   Copy to Clipboard Toggle word wrap

Procedure 1.11. Examine the Configuration Files

1. Examine the faces-config.xml file.
   This quickstart uses the JSF 2.0 version of faces-config.xml filename. A standardized version of Facelets is the default view handler in JSF 2.0, so there's really nothing that you have to configure. JBoss EAP 6 goes above and beyond Java EE here. It will automatically configure the JSF for you if you include this configuration file. As a result, the configuration consists of only the root element:

   19. <faces-config version="2.0"
   20.    xmlns="http://java.sun.com/xml/ns/javaee"
   21.    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   22.    xsi:schemaLocation="
   23.       http://java.sun.com/xml/ns/javaee>
   24.       http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd">
   25.      
   26. </faces-config>
   

   Copy to Clipboard Toggle word wrap
2. Examine the beans.xml file.
   There's also an empty beans.xml file, which tells JBoss EAP 6 to look for beans in this application and to activate the CDI.
3. There is no web.xml file
   Notice that the quickstart doesn't even need a web.xml file!

Procedure 1.12. Examine the JSF Code

• Examine the home.xhtml code.
  The home.xhtml file is located in the src/main/webapp/ directory.

  19. <html xmlns="http://www.w3.org/1999/xhtml"
  20.    xmlns:ui="http://java.sun.com/jsf/facelets"
  21.    xmlns:h="http://java.sun.com/jsf/html"
  22.    xmlns:f="http://java.sun.com/jsf/core">
  23.
  24. <head>
  25. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  26. <title>Numberguess</title>
  27. </head>
  28.
  29. <body>
  30.    <div id="content">
  31.       <h1>Guess a number...</h1>
  32.       <h:form id="numberGuess">
  33.
  34.          <!-- Feedback for the user on their guess -->
  35.          <div style="color: red">
  36.             <h:messages id="messages" globalOnly="false" />
  37.             <h:outputText id="Higher" value="Higher!"
  38.                rendered="#{game.number gt game.guess and game.guess ne 0}" />
  39.             <h:outputText id="Lower" value="Lower!"
  40.                rendered="#{game.number lt game.guess and game.guess ne 0}" />
  41.          </div>
  42.
  43.          <!-- Instructions for the user -->
  44.          <div>
  45.             I'm thinking of a number between <span
  46.                id="numberGuess:smallest">#{game.smallest}</span> and <span
  47.                id="numberGuess:biggest">#{game.biggest}</span>. You have
  48.             #{game.remainingGuesses} guesses remaining.
  49.          </div>
  50.
  51.          <!-- Input box for the users guess, plus a button to submit, and reset -->
  52.          <!-- These are bound using EL to our CDI beans -->
  53.          <div>
  54.             Your guess:
  55.             <h:inputText id="inputGuess" value="#{game.guess}"
  56.                required="true" size="3"
  57.                disabled="#{game.number eq game.guess}"
  58.                validator="#{game.validateNumberRange}" />
  59.             <h:commandButton id="guessButton" value="Guess"
  60.                action="#{game.check}"
  61.                disabled="#{game.number eq game.guess}" />
  62.          </div>
  63.          <div>
  64.             <h:commandButton id="restartButton" value="Reset"
  65.                action="#{game.reset}" immediate="true" />
  66.          </div>
  67.       </h:form>
  68.
  69.    </div>
  70.
  71.    <br style="clear: both" />
  72.
  73. </body>
  74. </html>
  

  Copy to Clipboard Toggle word wrap
  Expand

  Table 1.2. JSF Details

  Line	Note
  36-40	These are the messages which can be sent to the user: "Higher!" and "Lower!"
  45-48	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.
  55-58	This input field is bound to a bean property using a value expression.
  58	A validator binding is used to make sure the user does not accidentally input a number outside of the range in which they can guess. If the validator was not here, the user might use up a guess on an out of bounds number.
  59-61	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.

  Show more

Procedure 1.13. Examine the Class Files

1. Review the Random.java qualifier code.
   A qualifier is used to remove ambiguity between two beans, both of which are eligible for injection based on their type. For more information on qualifiers, refer to Section 11.2.3.3, “Use a Qualifier to Resolve an Ambiguous Injection”
   The @Random qualifier is used for injecting a random number.

   @Target({ TYPE, METHOD, PARAMETER, FIELD })
   @Retention(RUNTIME)
   @Documented
   @Qualifier
   public @interface Random {
   
   }

   Copy to Clipboard Toggle word wrap
2. Review the MaxNumber.java qualifier code.
   The @MaxNumberqualifier is used for injecting the maximum number allowed.

   @Target({ TYPE, METHOD, PARAMETER, FIELD })
   @Retention(RUNTIME)
   @Documented
   @Qualifier
   public @interface MaxNumber {
   
   }

   Copy to Clipboard Toggle word wrap
3. Review the Generator.java code.
   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. This class is application scoped so you don't get a different random each time.

   @SuppressWarnings("serial")
   @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() {
           // a number between 1 and 100
           return getRandom().nextInt(maxNumber - 1) + 1;
       }
   
       @Produces
       @MaxNumber
       int getMaxNumber() {
           return maxNumber;
       }
   }

   Copy to Clipboard Toggle word wrap
4. Review the Game.java code.
   The session scoped class Game is the primary entry point of the application. It is responsible for setting up or resetting the game, capturing and validating the user's guess, and providing feedback to the user with a FacesMessage. It uses the post-construct lifecycle method to initialize the game by retrieving a random number from the @Random Instance<Integer> bean.
   Notice the @Named annotation in the class. This annotation is only required when you want to make the bean accessible to a JSF view via Expression Language (EL), in this case #{game}.

   @SuppressWarnings("serial")
   @Named
   @SessionScoped
   public class Game implements Serializable {
   
       /**
        * The number that the user needs to guess
        */
       private int number;
   
       /**
        * The users latest guess
        */
       private int guess;
   
       /**
        * The smallest number guessed so far (so we can track the valid guess range).
        */
       private int smallest;
   
       /**
        * The largest number guessed so far
        */
       private int biggest;
   
       /**
        * The number of guesses remaining
        */
       private int remainingGuesses;
   
       /**
        * The maximum number we should ask them to guess
        */
       @Inject
       @MaxNumber
       private int maxNumber;
   
       /**
        * The random number to guess
        */
       @Inject
       @Random
       Instance<Integer> randomNumber;
   
       public Game() {
       }
   
       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;
       }
   
       /**
        * Check whether the current guess is correct, and update the biggest/smallest guesses as needed. Give feedback to the user
        * if they are correct.
        */
       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--;
       }
   
       /**
        * Reset the game, by putting all values back to their defaults, and getting a new random number. We also call this method
        * when the user starts playing for the first time using {@linkplain PostConstruct @PostConstruct} to set the initial
        * values.
        */
       @PostConstruct
       public void reset() {
           this.smallest = 0;
           this.guess = 0;
           this.remainingGuesses = 10;
           this.biggest = maxNumber;
           this.number = randomNumber.get();
       }
   
       /**
        * A JSF validation method which checks whether the guess is valid. It might not be valid because there are no guesses left,
        * or because the guess is not in range.
        * 
        */
       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);
           }
       }
   }

   Copy to Clipboard Toggle word wrap

Procedure 6.1. Create an Internationalized Log Message Bundle

1. Create an Message Logger interface

   Add a Java interface to your project to contain the log message definitions. Name the interface descriptively for the log messages that will be defined in it.
   The log message interface has the following requirements:
   • It must be annotated with @org.jboss.logging.MessageLogger.
   • It must extend org.jboss.logging.BasicLogger.
   • The interface must define a field of that is a typed logger that implements this interface. Do this with the getMessageLogger() method of org.jboss.logging.Logger.

   package com.company.accounts.loggers;
   
   import org.jboss.logging.BasicLogger;
   import org.jboss.logging.Logger;
   import org.jboss.logging.MessageLogger;
   
   @MessageLogger(projectCode="")
   interface AccountsLogger extends BasicLogger
   {
      AccountsLogger LOGGER = Logger.getMessageLogger(
            AccountsLogger.class,
            AccountsLogger.class.getPackage().getName() );
   }

   Copy to Clipboard Toggle word wrap

2. Add method definitions

   Add a method definition to the interface for each log message. Name each method descriptively for the log message that it represents.
   Each method has the following requirements:
   • The method must return void.
   • It must be annotated with the @org.jboss.logging.LogMessage annotation.
   • It must be annotated with the @org.jboss.logging.Message annotation.
   • The value attribute of @org.jboss.logging.Message contains the default log message. This is the message that is used if no translation is available.

   @LogMessage
   @Message(value = "Customer query failed, Database not available.")
   void customerQueryFailDBClosed();

   Copy to Clipboard Toggle word wrap
   The default log level is INFO.

3. Invoke the methods

   Add the calls to the interface methods in your code where the messages must be logged from. It is not necessary to create implementations of the interfaces, the annotation processor does this for you when the project is compiled.

   AccountsLogger.LOGGER.customerQueryFailDBClosed();

   Copy to Clipboard Toggle word wrap
   The custom loggers are sub-classed from BasicLogger so the logging methods of BasicLogger (debug(), error() etc) can also be used. It is not necessary to create other loggers to log non-internationalized messages.

   AccountsLogger.LOGGER.error("Invalid query syntax.");

   Copy to Clipboard Toggle word wrap

Procedure 6.2. Create and Use Internationalized Messages

1. Create an interface for the exceptions

   JBoss Logging Tools defines internationalized messages in interfaces. Name each interface descriptively for the messages that will be defined in it.
   The interface has the following requirements:
   • It must be declared as public
   • It must be annotated with @org.jboss.logging.MessageBundle.
   • The interface must define a field that is a message bundle of the same type as the interface.

   @MessageBundle(projectCode="")
   public interface GreetingMessageBundle 
   {
      GreetingMessageBundle MESSAGES = Messages.getBundle(GreetingMessageBundle.class);
   }

   Copy to Clipboard Toggle word wrap

2. Add method definitions

   Add a method definition to the interface for each message. Name each method descriptively for the message that it represents.
   Each method has the following requirements:
   • It must return an object of type String.
   • It must be annotated with the @org.jboss.logging.Message annotation.
   • The value attribute of @org.jboss.logging.Message must be set to the default message. This is the message that is used if no translation is available.

   @Message(value = "Hello world.")
      String helloworldString();

   Copy to Clipboard Toggle word wrap

3. Invoke methods

   Invoke the interface methods in your application where you need to obtain the message.

   System.console.out.println(helloworldString());

   Copy to Clipboard Toggle word wrap