Getting Started with JBoss Developer Studio

JBoss Developer Studio is a set of eclipse-based development tools that are pre-configured for JBoss Enterprise Middleware Platforms and Red Hat Enterprise Linux. Developers are not required to use JBoss Developer Studio to develop on JBoss Enterprise Middleware and/or Red Hat Linux. But, many find these pre-configured tools offer significant time-savings and value, making them more productive and speeding time to deployment.

You must have a working installation of JDK 1.5 before you install JBoss Developer Studio. Currently it will only fully work with a 32-bit JVM, not a 64-bit JVM. On a 64-bit JVM the visual editor fails to launch. Thus in this guide we will show you how to install a 32-bit Sun JDK 5.0 on a Linux Platform and Microsoft Windows Platform.

[root@vsr ~]$ /usr/sbin/alternatives --config java
There are 2 programs that provide 'java'.
Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.4.2-gcj/bin/java
*+ 2           /usr/lib/jvm/jre-1.5.0-sun/bin/java
Enter to keep the current selection[+], or type selection number:

[root@vsr ~]$ /usr/sbin/alternatives --config javac
There is 1 program that provides 'javac'.
	Selection   Command
-----------------------------------------------
*+ 1           /usr/lib/jvm/java-1.5.0-sun/bin/javac
Enter to keep the current selection[+], or type selection number:

[root@vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
There is 1 program that provide 'java_sdk_1.5.0'.
	Selection   Command
-----------------------------------------------
*+ 1           /usr/lib/jvm/java-1.5.0-sun
Enter to keep the current selection[+], or type selection number:

[root@vsr ~]$ java -version
java version "1.5.0_11"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_11-b03)
Java HotSpot(TM) Client VM (build 1.5.0_11-b03, mixed mode, sharing)

The welcome page is the first page you see when you first launch JBoss Developer Studio.

Figure 1.5. Welcome to JBoss Developer Studio

With the help of its page you will be able:

Figure 1.6. Getting Started Documentation

Figure 1.7. Create New...

Figure 1.8. Perspectives

Figure 1.9. Web Resources

Start work with JBoss Developer Studio by clicking on Workbench button or simply close the welcome page.

To upgrade, just uninstall your current version and install the new one.

If you have comments or questions, you can discuss them at our JBoss Developer Studio Forum.

When writing to the forum for questions, please include the following information:

For easy reference to JBoss Developer Studio related questions, our FAQ provides answers to our most "popular" questions. The sections of questions are organized by type.

-vmargs -Xms128m -Xmx512m -XX:MaxPermSize=128m

JBDS on JBoss: JBoss Developer Studio

Forum: JBoss Forum

Download: JBDS Download

Although JBoss Developer Studio works closely with JBoss EAP 4.2 we do not ultimately tie you to any particular server for deployment. There are some servers that Studio supports directly (via the bundled Eclipse WTP plug-ins). In this section we discuss how to manage self-installed JBoss AS. Suppose you want to deploy the application to JBoss 4.2.1 server. First of all you need to install it.

2.2.2. Adding and configuring JBoss server

Now we should add just installed server into server manager in JBoss Developer Studio.

• Open the JBoss Server View by selecting Window > Show View > Other > Server > JBoss Server View. You will see JBoss Server view.

• Right click anywhere in this view and select New Server.

• Select JBoss, a division of Red Hat > JBoss v4.2 and click the Installed Runtimes button to select a new installed runtime.

Figure 2.9. Selecting Server Type

• Click Add button to add a new jboss runtime.

• Select JBoss, a division of Red Hat > JBoss v4.2 and press Next.

Figure 2.10. Installed Runtimes

• In the next step make JBoss Developer Studio to know where you have installed the server and define JRE.

Figure 2.11. Defining JBoss Runtime

Note:

When adding a new server you will need to specify what JRE to use. It is important to set this value to a full JDK, not JRE. Again, you need a full JDK to run Web applications, JRE will not be enough.

• In the following window leave all settings default or give your name to a new jboss server and press Finish.

Figure 2.12. Adding New Runtime

A new runtime will now appear in the Preferences > Server > Installed Runtimes dialog.

Figure 2.13. Runtime is Added

• Click OK. Then select a new added runtime in Server runtime drop down list and click Next button twice.

Figure 2.14. Choosing Runtime

• In the next dialog verify a JBoss runtime information and if something is unfair go back and correct it.

Figure 2.15. Configuring Projects

• In the last wizard's dialog modify the projects that are configured on the server and click Finish.

Figure 2.16. Configuring Projects

A new JBoss server should now appear in JBoss Server View.

Figure 2.17. New JBoss Server

To create a new web application in Seam, select New > Project ... > Seam > Seam Web Project. You will be prompted to enter a name and a location directory for your new project. The wizard has an option for selecting the actual Server (and not just WTP runtime) that will be used for the project. This allow the wizard to correctly identify where the needed datasource and driver libraries need to go.

Figure 3.1. Create a Seam Project

Next, you will be asked to select the "features" you want to use in your project. This allows JBoss Developer Studio to setup the appropriate tooling for your project. Since JBoss Seam integrates all popular Java EE frameworks, you can select any combination of technologies from the list. Here, for this project, we will select Dynamic Web Module, Java, JavaServer Faces (JSF), and Seam Facet for a typical database-driven web application.

Figure 3.2. Select Toolings for the Project

In this screen you can also bring up server runtimes panel by clicking Show Runtimes in the bottom right corner. This panel shows available server runtimes. Then this button will be changed into Hide Runtimes one.

Click Next to proceed further.

Figure 3.3. Available Server Runtimes

A dynamic web application contains both web pages and Java code. The wizard will ask you where you want to put those files. You can just leave the default values.

Figure 3.4. Select Directory Names for Web Pages and Java Files

In the next screen, you will be able to select where those library JARs come from. The easiest is just to select the JARs provided by the JBoss AS runtime associated with this project. That is why it is important to chose the right JBoss AS 4.2 runtime in the project setup window.

Figure 3.5. Define JSF Implementation

We will also use a default Hibernate Dialect - org.hibernate.dialect.HSQLDialect and deploy as a war archive.

The project setup wizard also asks you to configure how Seam generates code for the project. The Seam Home Folder should point to a valid Seam distribution. By default, it is set to the Seam distribution bundled in your JBoss Developer Studio tool. If you need another one choose setting up the appropriate check box:

Figure 3.6. Enter Java Packages for Generated Code

If in this list there is no Seam runtime you want to use add it through Window > Preferences > JBoss Tools > Web > Seam or just click Add button near the Seam Runtime list:

Figure 3.7. Add New Seam Runtime

For the deployment format, choose WAR deployment if you want to use POJOs for UI event handling and business logic; choose EAR deployment if you want to EJB3 beans for added features. In most web applications, the WAR deployment option would suffice. You should also enter Java packages for the entity beans (for database mapping) and session beans (for action handlers). All generated code will be placed in those packages.

Click on Finish to generate a project. The generated project contains all the necessary library JARs, XML configuration files, the ANT build script, as well as simple XHTML web pages and Java classes for the skeleton web application. The project will be shown in Project Explorer as well as in Seam Components view. If Seam Components view is not open select Window > Show View > Seam Components.

Figure 3.8. Seam Components View

You can hide unused Seam components from this view.

Figure 3.9. Seam Components Filtering

Once the application is generated, you can use the "Run on server" menu to build and deploy it into the JBoss AS runtime associated with the project. All you need is to start JBoss AS in the server manager, and load the browser at URL http://localhost:8080/MySeamProj/. You should see the following web page.

Figure 3.10. The Generated Application in Action

To make simple changes to the page, you just need to double click on the WebContent/home.xhtml file and edit it in the visual editor. Notice that the visual editor lets you both the XHTML code and the rendered page. The rendered view is designed to make it easy to find stuff in a complex XHTML page.

Figure 3.11. Making Changes in the Visual Editor

Once you finished editing, save the file (File > Save), and reload the browser to see the changes.

Figure 3.12. The Front Page is Changed

Notice that we do not need to re-build and re-deploy the application. Just save the edited page and reload the browser.

To add a new page and related UI action to the project, use the New > Other ... > Seam > Seam Form wizard. You are prompted to enter the name of the project and seam component name, all the others fields will be filled by the wizard.

Figure 3.13. New Form for the Application

The wizard generate a web page with a single text input field and an action button. Notice that the generated page uses layout/template.xhtml as a template. The template page provides the page header, footer, side menu, and CSS styles (see the template.xhtml for more details). The simpleAction.xhtml is assembled into the template when the simpleAction.seam URL is loaded.

<!DOCTYPE composition PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 

                "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



  <ui:composition>  xmlns:s="http://jboss.com/products/seam/taglib"

                              xmlns:ui="http://java.sun.com/jsf/facelets"

                              xmlns:f="http://java.sun.com/jsf/core"

                              xmlns:h="http://java.sun.com/jsf/html"

                              template="layout/template.xhtml">



<ui:define name="body">



    <h:messages globalOnly="true" styleClass="message"/>



    <h:form id="simpleActionForm">

        <rich:panel>

            <f:facet name="header">simpleAction</f:facet>

                    <s:decorate id="valueDecoration" template="layout/edit.xhtml">

                        <ui:define name="label">Value</ui:define>

                        <h:inputText id="value" required="true"

                            value="#{simpleAction.value}"/>

                    </s:decorate>

                    <div style="clear:both"/>

         </rich:panel>

         

         <div class="actionButtons">

             <h:commandButton id="simpleAction" value="simpleAction"

                             action="#{simpleAction.simpleAction}"/>

        </div>

    </h:form>

</ui:define>



</ui:composition>

Figure 3.14. Generated Form

The #{simpleAction.value} notation on the web page maps to the "value" property in the backend component named "simpleAction", and the #{simpleAction.simpleAction} notation indicates that the simpleAction() method is called when the button is clicked on. Here is the "simpleAction" named backend Seam component generated by the wizard.

package org.domain.MySeamProj.session;

    

import org.jboss.seam.annotations.Name;

import org.jboss.seam.annotations.In;

import org.jboss.seam.annotations.Logger;

import org.jboss.seam.log.Log;

import org.jboss.seam.core.FacesMessages;

import org.hibernate.validator.Length;

    

@Name("simpleAction")

public class SimpleAction {



    @Logger private Log log;



    @In

    FacesMessages facesMessages;



    private String value;



    //seam-gen method

    public void simpleAction()

    {

        //implement your business logic here

        log.info("simpleAction.simpleAction() action called with: #{simpleAction.value}");

        facesMessages.add("simpleAction #{simpleAction.value}");

    }



    //add additional action methods



    @Length(max=10)

    public String getValue()

    {

        return value;

    }



    public void setValue(String value)

    {

        this.value = value;

    }



}

Load the Simplepage.seam in the web browser. Type something in the text field and click on the "simpleAction" button. A JSF message containing the input string is created by the simpleAction.simpleAction() method. The message is displayed on the page via the <h:message> tag.

Notice that in the generated SimpleAction class, there is a @Length annotation to validate the input when the input string is bound to #{simpleAction.value}. To see how this works, enter a text string longer than 10 chars and click on the button. This is what you should see.

Figure 3.15. The Input Validation in Action

Seam supports many different input validation annotations. To see an example, you can replace the @Length(max=10) annotation with the following. It would require the input string to have a first name and last name separated by a space. If the validation fails, the web page would print the customized error message.

@NotNull

@Pattern(regex="^[a-zA-Z.-]+ [a-zA-Z.-]+",

      message="Need a firstname and a lastname")

public String getValue()

{

        return value;

}      

Save the Java file, deploy the application, and reload the browser to see the new validation scheme in action.

Figure 3.16. More Input Validation

Now, let's add a little more logic to the application. We will add a new boolean property to the action component. If it is set to true, the action would capitalize the input string and display it on the web page. The following code in the SimpleAction class implements the logic.

@Name("simpleAction")

public class SimpleAction {



    private boolean convertToCap;

    

    public boolean getConvertToCap () { return convertToCap; }

    public void setConvertToCap (boolean b) { convertToCap = b; }

    

    public String hello()

    {

        if (convertToCap) {

          value = value.toUpperCase ();

        }

        return null;

    }   

    ... ...

}    

Next, on the web page, add the following line to display the value property on the simpleAction component. Notice that code completion is supported for the JSF EL expression.

<p><b>Hello, #{simpleAction.value}</b></p> 

Finally, on the web page, we add a boolean selection box component. It is bound to the convertToCap property on the backend component.

<h:selectBooleanCheckbox title="convertToCap"

  value="#{simpleAction.convertToCap}" /> 

Capitalize the input?

Deploy the application and see it in action now.

Figure 3.17. Add UI Components and Business Logic

You have probably noticed that the web page template has a login link at the top of the page. You can use the Seam security framework to secure access to any web page or web action. You can implement the login logic in the checkLoggedIn method. In the following example, we just use hardcoded username and password. But you can easily change it to use database, LDAP or any other means.

Then, on the action method, you can use the @AroundInvoke annotation to specify that it is only invoked by authenticated users.

public class LoggedInInterceptor 

    {

   @AroundInvoke

   public Object checkLoggedIn(InvocationContext invocation) throws Exception 

   {   

      boolean isLoggedIn = Contexts.getSessionContext().get("loggedIn")!=null;

      if (isLoggedIn) {

         //the user is already logged in

         return invocation.proceed();

      }

      else {

         //the user is not logged in, fwd to login page

         return "login";

      }

   }

}

Now, re-deploy the application and try the action button. The application redirects to the login page asking for login credentials. The method is invoked after you successfully logged in.

Figure 3.18. Access Control for Action Methods

We can also secure web pages. You can edit the Authenticator.java file to put an access constraint on the login page.

package.org.domain.MySeamProj.session;

import org.jboss.seam.annotations.In;

import org.jboss.seam.annotations.Logger;

import org.jboss.seam.annotations.Name;

import org.jboss.seam.log.Log;

import org.jboss.seam.security.identity;

    

    @Name ("authenticator")

    public class Authenticator

    {

      @Logger Log log;

      @In Identity identity;

      

      public boolean authenticate()

      {

        log.info("authenticating #0", identity.getUserName());

        //write your authentication logic here,

        //return true if the authentication was

        //successful, false otherwise

        identity.addRole("admin");

        return true;

        }

    }

You can try to load the http://localhost:8080/MySeamProj/ URL in the browser and it will redirect to ask for login.

Seam on JBoss: Seam Framework

Ten Good Reasons to use Seam: Why Seam

Getting Started: Getting Started with JBoss Seam

Wiki: JBoss Wiki

FAQ: JBoss Seam FAQ

Downloads: JBoss Seam Downloads

Jira: Jira issue tracker

Rules Framework: JBoss Rules

Seam Tools - New and Noteworthy: What's new and noteworthy

At first a new project for the application will be created.

Figure 4.1. Create New Web Project

A jspHello node should appear in the upper-left Package Explorer view.

Figure 4.2. New Web Project

In our simple application we need to create only one JSP page which displays a "Hello World!" message.

In the next window you can choose a template for your jsp page and see its preview.

Figure 4.3. Create JSP Page

Our hello.jsp page will now appear in Project Explorer.

4.2.1. Editing a JSP Page

Let's now make a little change so that a jsp page displays "Hello World!" message.

• Insert this line inside the <body></body> tag:

<% System.out.println("Hello World!"); %>

Notice that content assist functionality is always available when you are typing:

Figure 4.4. Content Assist in JSP Page

After changes made your hello.jsp page should look like this:

Figure 4.5. Hello.jsp Page

4.2.2. web.xml file

When you are creating web project the wizard creates the web.xml for you automatically. The web.xml file editor provided by JBoss Developer Studio is available in two modes: design and source.

Figure 4.6. Web.xml in Design Mode

Figure 4.7. Web.xml in Source Mode

Both modes are fully synchronized. Let's add mapping to our hello.jsp page in web.xml file.

• Switch to source mode.

• Add the next code into <welcome-file-list>:

<welcome-file>hello.jsp</welcome-file>

If you come back to design mode you will see that the changes made are automatically reflected in that mode.

Actually you don't really need any config right now. You can clear the web.xml file, save it and you'll still be able to launch your application.

4.2.3. Deploying the project

While creating any web project you could experience a pain writing ant scripts and managing the packaging even if a developer is writing the most trivial web applications. With JBoss Developer Studio you are saved from such a pain. All you need is to start JBoss server and launch your application in your favorite browser.

You can also create a war archive with JBDS's Archive Tools and export it to any web server.

4.2.3.1. WAR Config

Project archives managing is available through Project archives view.

• Select Window > Show view > Other > JBoss Tools > Project archives from menu bar

• Select a project in Package Explorer you want to be archived

In Project Archives you will see available archive types for the project:

Figure 4.8. Project Archives

• Click, for example, WAR option to create war archive

In the dialog New WAR you can see automatically selected default values

Figure 4.9. New WAR Archive

• Click Next to see a stub archive configuration for your project:

  

  Figure 4.10. Stub Archive Configuration

  
  

• Click Finish. The .war file will appear in Package Explorer and in Project archives view as structure tree:

  

  Figure 4.11. Archive is Created

  
  

  

  Figure 4.12. Archive in Project Archives View

  
  

Via Project archives view you could now edit your archive, add new folders, publish to server, and so on:

Figure 4.13. Configure Archive

4.2.3.2. Auto redeploy

When you are creating a web application and register it on JBoss server it is automatically deployed into /deploy directory of the server. JBDS comes with the feature of auto-redeploy. It means that you don't need to restart JBoss. Any changes made in the application in exploded format will trigger a redeployment on the server.

<%= new java.util.Date() %>

4.2.5. Launch JSP Project

Let's now launch our project on server. We'll use JBoss server that is shipped with JBoss Developer Studio.

• Start JBoss server from JBoss Server view by clicking the Start icon.

Figure 4.14. Starting Server

• Click the Run icon or right click your project folder and select Run As > Run on Server. If you haven't made any changes in web.xml file or cleared it out you can launch the application by right clicking the hello.jsp page and selecting Run on the Server.

Figure 4.15. Run Project

You should see the next page in a browser :

Figure 4.16. Running Project

We will create a JSF 1.2 project using an integrated JBDS's new project wizard and predefined templates.

Our project will appear in Project Explorer and Web Projects Views. As you can see Red Had Developer Studio has created for us the whole skeleton for the project with all needed libraries, faces-config.xml and web.xml files.

Figure 5.2. New JSF Project

The application has two pages. The first page is inputnumber.jsp. It prompts you to enter a number. If the guess is incorrect, the same page will be redisplayed with a message indicating whether a smaller or a larger number should be tried. The second page is success.jsp. This page will be shown after you guess the number correctly. From this page you also have the option to play the game again.

On the first page inputnumber.jsp you will enter a number.

Figure 5.3. Create New View

On the diagram you will see two created views.

Figure 5.4. New Views

We should now create connection between jsp pages.

A transition should appear between the two icons of views.

Figure 5.6. Created Connection

JBoss Developer Studio allows to create quickly a resource file. Using this feature you can collect text messages in one central place. A resource file is just a file with a .properties extension. The messages stored in resource file can be displayed to you on a Web page during application execution.

With resource file first, you don't hard code anything into the JSP pages. And second, it makes it easier to translate your application to other languages. All you have to do is to translate all your messages to the other language and save them in a new properties file with a name that ends with the appropriate ISO-639 language code.

It is a good idea to keep your resources inside the JavaSource folder, where you keep your .java files. Every time you build the project, all .properties files will then be copied to the classes folder by default.

We will store in this folder our resource file and java bean.

JBoss Developer Studio will automatically open messages.properties file for editing.

Figure 5.7. Messages.properties File

makeguess_button=Make Guess

trayagain_button=Play Again?

success_text=How cool.. You have guessed the number, {0} is correct! 

tryagain_smaller=Oops..incorrect guess. Please try a smaller number.

tryagain_bigger=Oops..incorrect guess. Please try a bigger number.

Your .properties file should now look like follows:

Figure 5.8. Properties are Added

Now we create a Java bean that will hold business logic of our application.

A java bean is created.

Integer userNumber;

JBDS allows to quickly generate getters and setters for java bean.

int randomNumber;

public NumberBean () 

{

    randomNumber = (int)(Math.random()*100);

    System.out.println ( "Random number: "+randomNumber);

  }

  public String playagain () 

  {

    FacesContext context = FacesContext.getCurrentInstance();

    HttpSession session = (HttpSession) context.getExternalContext().getSession(false);

    session.invalidate();

    return "playagain"; 

  }

  public String checkGuess () 

  {

     

    // if guessed, return 'success' for navigation

    if ( userNumber.intValue() == randomNumber ) 

    {

      return "success";

    }

else 

   {

      FacesContext context = FacesContext.getCurrentInstance();

      ResourceBundle bundle = ResourceBundle.getBundle("game.messages", context.getViewRoot().getLocale());

      String msg = "";

      // if number bigger, get appropriate message

      if ( userNumber.intValue() > randomNumber ) 

         msg = bundle.getString("tryagain_smaller");

      else // if number smaller, get appropriate message

         msg = bundle.getString("tryagain_bigger");      

      // add message to be displayed on the page via <h:messages> tag

      context.addMessage (null, new FacesMessage(msg)); 

      // return 'tryagain' for navigation

      return "tryagain";

    }

  }

import javax.faces.context.FacesContext;

import javax.servlet.http.HttpSession;

import javax.faces.application.FacesMessage;

import java.util.Locale;

import java.util.ResourceBundle;

The whole java bean should look as follows:

import javax.faces.context.FacesContext;

import javax.servlet.http.HttpSession;

import javax.faces.application.FacesMessage;

import java.util.Locale;

import java.util.ResourceBundle;



public class NumberBean 

{

  Integer userNumber; 

  int randomNumber; // random number generated by application

public Integer getUserNumber () 

  {

    return userNumber;

  }

  public void setUserNumber (Integer value)

  {

     this.userNumber = value;

  }

  

  // constructor, generates random number

  public NumberBean () 

  {

    randomNumber = (int)(Math.random()*100);

    System.out.println ( 

   "Random number: " + randomNumber);

  }

  

  public String playagain () 

  {

    FacesContext context = FacesContext.getCurrentInstance();

    HttpSession session = (HttpSession) context.getExternalContext().getSession(false);

    session.invalidate();

    return "playagain"; 

  }

  

  // check if user guessed the number

  public String checkGuess () 

  {

    // if guessed, return 'success' for navigation

    if ( userNumber.intValue() == randomNumber )

    {

      return "success";

    }

    // incorrect guess

    else 

   {

      // get a reference to properties file to retrieve messages

      FacesContext context = FacesContext.getCurrentInstance();

      ResourceBundle bundle = ResourceBundle.getBundle("game.messages", context.getViewRoot()