Create new JBDS Documentation Jira issue

This will launch the JBDS Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.comEnterprise Documentation

Getting Started with JBoss Developer Studio

Version: 3.0.0.GA

1. Getting Started with JBoss Developer Studio
1.1. What is JBDS?
1.2. Key Features of JBoss Developer Studio and Requirements
1.3. Configuring Your Java Environment
1.3.1. Installing and Configuring 32-bit Sun JDK 5.0 on Linux
1.3.2. Installing and Configuring 32-bit Sun JDK 5.0 on Microsoft Windows
1.4. JBoss Developer Studio Installation
1.5. JBoss Developer Studio and JBoss Tools
1.5.1. What is the difference?
1.5.2. JBoss Tools Installation and Update
1.6. Welcome to JBoss Developer Studio
1.7. Upgrading
1.8. Uninstalling
1.9. Support
1.10. Other relevant resources on the topic
2. Manage JBoss AS from JBoss Developer Studio
2.1. How to Manage the JBoss AS Bundled in JBDS
2.1.1. Starting JBoss Server
2.1.2. Stopping JBoss Server
2.1.3. Server Container Preferences
2.2. How to Use Your Own JBoss AS Instance with JBDS
2.2.1. JBoss AS Installation
2.2.2. Adding and Configuring JBoss Server
3. Write Your First Project with JBoss Developer Studio
3.1. Create a Seam Application
3.1.1. Start Development Database
3.1.2. Create and deploy Seam Web Project
3.1.3. Start JBoss Application Server
3.1.4. Workshop Project Code Overview
3.2. Seam Action Development
3.2.1. Create a New Seam Action
3.2.2. Test Seam Action
3.2.3. Modify Seam Action User Interface
3.3. Declarative Security
3.3.1. Edit Login Authentication Logic
3.3.2. Secure Seam Page Component
3.4. Browsing Workshop Database
3.4.1. Database Connectivity Setup
3.4.2. Browse Workshop Database
3.5. Database Programming
3.5.1. Reverse Engineer CRUD from a Running Database
3.5.2. Use Hibernate Tools to Query Data via JPA
3.5.3. Use Hibernate Tools to visualize the Data Model
3.6. Rich Components
3.6.1. Add a Richfaces component to the CRUD Application
4. Developing a simple JSP web application
4.1. Setting Up the Project
4.2. Creating JSP Page
4.2.1. Editing a JSP Page
4.2.2. web.xml file
4.2.3. Deploying the project
4.2.4. JSP Page Preview
4.2.5. Launch JSP Project
5. RAD development of a simple JSF application
5.1. Setting up the project
5.2. Creating JSP Pages
5.3. Creating Transition between two views
5.4. Creating Resource File
5.5. Creating Java Bean
5.6. Editing faces-config.xml File
5.7. Editing the JSP View Files
5.7.1. Editing inputnumber.jsp page
5.7.2. Editing success.jsp page
5.8. Creating index.jsp page
5.9. Running the Application
6. Project Examples
6.1. User Sites
6.2. Downloading a Project Example
6.3. Quick Fixes
7. FAQ
7.1. What should I do if Visual Page Editor does not start under Linux
7.2. Do I need to have JBoss Server installed to run JBoss Developer Studio?
7.3. I have an existing Seam 1.2.1 project. Can I migrate/import the project to a JBDS Seam project?
7.4. I have an existing Struts or JSF project. Can I open the project in JBDS?
7.5. Can I import a .war file?
7.6. Is it possible to increase the performance of Eclipse after installing your product?
7.7. How can I add my own tag library to the JBoss Tools Palette?
7.8. How to get Code Assist for Seam specific resources in an externally generated project?
7.9. How to import an example Seam project from jboss-eap directory?
7.10. Is a cross-platform project import possible for JBDS?
8. Further Reading

For a start, we propose you to look through the table of main features of JBoss Developer Studio:

Table 1.1. Key Functionality of JBoss Developer Studio


JBoss Enterprise Application Platform

JBoss Developer Studio includes and integrates JBoss Enterprise Application Platform, the same version of the middleware platform that Red Hat supports in production for 5 years.

New Seam Tools

JBoss Developer Studio includes brand new tools for Seam. They provide wizards for creating new Seam projects, validation tools, expression language code completion, testing tools, and wizards for generating entity objects.

Visual Page Editor

JBoss Developer Studio includes a Visual Page Editor for combined visual and source editing of Web pages. The Visual Page Editor even renders AJAX-enabled RichFaces components.

AJAX Capabilities

JBoss Developer Studio includes a Technology Preview of JBoss RichFaces. RichFaces provides nearly 70 skinnable components, including calendar, tree, dropdown menu, drag-and-drop components, and more. JBoss Developer Studio’s Visual Page Editor can render RichFaces components.

JBoss Tools Palette

The JBoss Tools Palette contains a developer’s project tag libraries and enables inserting tags into a JSP with one click. The Tools Palette supports custom and 3rd party tags.

JBoss jBPM Tools

JBoss Developer Studio includes jBPM tooling for defining Seam page flows.

Spring Tools

JBoss Developer Studio includes Spring IDE for developing Spring applications.

Struts Tools

JBoss Developer Studio includes Struts tools for Struts 1.x applications.

Optimized JBoss Application Server adapter

JBoss Developer Studio’s advanced JBoss AS adapter includes features like incremental deployment for fast development and is pre-configured for the included JBoss Application server.

Red Hat Enterprise Linux and RHN Access

JBoss Developer Studio includes access to Red Hat Enterprise Linux, Linux development tools, and Red Hat Network for development purposes.

Project Examples

Tooling for easy installation of Examples.

JBossWeb Service

JBoss WS is a web service framework developed as a part of the JBoss Application Server. It implements the JAX-WS specification that defines a programming model and run-time architecture for implementing web services in Java, targeted at the Java Platform, Enterprise Edition 5 (Java EE 5).

JBDS requires JDK 5+ (JDK 6 in case of EAP 5.0). Also it's important that the JVM's architecture matches the particular JBDS build, i.e. if you're on a 64-bit system and use the 64-bit JVM, you need the 64-bit JBDS.

For the 32-bit version of JBDS use the 32-bit JVM or just use -vm flag to tell JBDS to use 32-bit java if the 64-bit one is found as the default.

You must have a working installation of JDK before you install JBoss Developer Studio. 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.

To install 32-bit Sun JDK 5.0 on Linux and configure it, you should follow the next steps:

  • Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website. Choose "JDK 5.0 Update <x>" (where "x" is the latest update number) for download and then select "Red Hat Package Manager in self-extracting" file for Linux. Read the instructions on Sun's website for installing the JDK.

  • If you don't want to use SysV service scripts you can install the "self-extracting file" for Linux instead of choosing the "RPM in self-extracting" file. In that case you can skip the next step mentioned here. But it is recommended to use the SysV service scripts for production servers.

  • Download and install the appropriate -compat RPM from JPackage here. Please ensure you choose a matching version of the -compat package to the JDK you've installed.

  • Create an environment variable that points to the JDK installation directory and call it JAVA_HOME. Add $JAVA_HOME/bin to the system path to be able to run java from the command line. You can do this by adding the following lines to the .bashrc file in your home directory.

    #In this example /usr/java/jdk1.5.0_11 is the JDK installation directory.
    export JAVA_HOME=/usr/java/jdk1.5.0_11
    export PATH=$PATH:$JAVA_HOME/bin


If you have JDK already installed and added in your system path, you should add $JAVA_HOME/bin before the old $PATH (not after it) so that the new version of JDK can be found first, i. e. export PATH=$JAVA_HOME/bin:$PATH This way, the machine will pick up the new JVM first. You only need to run "alternative" as a safe guard for the right JVM.

Set this variable for your account doing the installation and also for the user account that will run the server.

  • If you have more than one version of JVM installed on your machine, make sure you are using the JDK 1.5 installation as the default java and javac. You can do this using the alternatives system. The alternatives system allows different versions of Java from different sources to co-exist on your system.

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

Make sure the Sun version [jre-1.5.0-sun in this case] is selected (marked with a '+' in the output), or select it by entering its number as prompted.

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

You should verify that java, javac and java_sdk_1.5.0 all point to the same manufacturer and version.

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

To install and configure 32-bit Sun JDK 5.0 on Microsoft Windows, follow these steps:

  • Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website. Choose "JDK 5.0 Update <x>" (where "x" is the latest update number) for download and then select your Windows Platform options to perform the installation.

  • Create an environment variable called JAVA_HOME that points to the JDK installation directory, for example: C:\Program Files\Java\jdk1.5.0_11\

In order to run java from the command line, add the jre\bin directory to your path, for example:

C:\Program Files\Java\jdk1.5.0_11\jre\bin

To do this, open the Control Panel from the Start menu, switch to Classic View if necessary, open the System Control Panel applet ( System ), select the Advanced Tab, and click on the Environment Variables button.

Now, when 32-bit Sun JDK 5.0 has been successfully installed, we can pass on to the next step.

This chapter will provide you with detailed information on how to install JBoss Developer Studio.

JBDS comes with a simple installer, bundled with tested/pre-configured versions of Eclipse, WTP, JBossEAP, Seam, and SpringIDE. Thus, to start perform the next steps:

  • Provide the installation path

  • Select Java VM


By selecting Default Java VM you set default Java VM of your system (to verify your Java environment, type "java -version" in console).

Selecting Specific Java VM you can provide the path to non-default Java VM.


JBoss Developer Studio needs Java 5 and "gij" isn't available on every platform.

  • Installation process includes JBoss Enterprise Application Platform. Select Yes to use it in JBoss Developer Studio.


    JBDS 2.0.0.GA comes integrated with JBoss EAP 4.3, while the current 2.1.0.GA release of JBDS comes with JBoss EAP 5 that support EAP 5 adapter and Seam 2.2.

    This step lets you configure locally available JBoss Application Servers:

  • You can fill the list automatically using the Find button: click Find, select a folder where search of available JBoss Application Servers should be started and click on Ok:

  • All available servers in the selected directory will be added to the list with the following information specified: Name, Type, Version and Location.

  • You can also add servers one by one using the Add button:

Click on Browse and select the server location. Fields Name, Type and Version will be filled in automatically:

Click on Ok. The server is added to the list with the details on its type, version and location.

The Remove button will the remove the selected server from the list. If necessary, you can edit the server details clicking on the Edit button:

  • Click Next. Check your installation paths and see the components to install. If you'd like to change something, press the Previous button. Click Next to start installation.

This section uncovers the points on the differences between JBoss Developer Studio and JBoss Tools and provides the steps on JBoss Tools installation as well.

Here, let's consider the installation of the JBoss Tools modules.

JBoss Tools is an umbrella project for the JBoss developed plugins that will make it into JBoss Developer Studio. The JBoss Tools modules are:

To install the JBoss Tools plugins for Eclipse, you need the following:

The current version of JBoss Tools (3.1.M2) targets at Eclipse 3.5/Galileo which is available from


We recommend you do not use update site to go from old version of Eclipse to new one. Instead we suggest that you download the full binary from here.

If you can only use Eclipse 3.3 use JBoss Tools 2.1.2, but JBoss Tools 2.x will not have any of the new features.


Remember to choose the download that matches your OS and use Java 5 when you run it.

Some of our newer plugins, like TPTP and BIRT, need additional drivers. On the left side of the download page you can find all of the required drivers for chosen build and their versions.

If you need to install any standalone plug-in from JBoss Tools visit a JBoss Tools Wiki page to read about dependencies between standalone plug-ins.

Instead of downloading installation/updating manually, it's also possible to get the latest release of JBoss Tools from one of our update sites:

To install/update Jboss Tools from one of the update sites you should follow the steps:

You can download Jboss tools in a zip file from one of the pages below:

When you downloaded Jboss Tools Zip please DO NOT UNZIP IT and follow the steps described below:

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:

  1. JBoss Developer Studio version

  2. Exact error message

  3. Steps to reproduce the issue

JBDS subscribers can get necessary support on our Support Portal.

In this chapter we'll focus more on how to operate the JBoss AS from JBoss Developer Studio.

JBoss Developer Studio 2.1.0.GA is shipped with JBoss EAP 5 . When you followed the default installation of JBoss Developer Studio, you should already have a JBoss EAP 5 Server installed and defined. To run JBoss AS you need JDK 1.5, JDK 6 is not formally supported yet, although you may be able to start the server with it.

This section covers the basics of working with the JBoss Server supported directly by JBDS via bundled AS plug-in. The server points to the JBoss Enterprise Application Platform 5.0 Runtime shipped with JBDS.

To read more about AS plug-in, refer to the Server Manager guide.

Although JBoss Developer Studio works closely with JBoss EAP 5 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.3 server. First of all you need to install it.

It does not matter where on your system you install JBoss server.


The installation of JBoss server into a directory that has a name containing spaces provokes problems in some situations with Sun-based VMs. Try to avoid using installation folders that have spaces in their names.

There is no requirement for root access to run JBoss Server on UNIX/Linux systems because none of the default ports are within the 0-1023 privileged port range.

  • After you have the binary archive you want to install, use the JDK jar tool (or any other ZIP extraction tool) to extract the archive contents into a location of your choice. The jboss-4.2.3.GA.tgz archive is a gzipped tar file that requires a gnutar compatible tar which can handle the long pathnames in the archive. The extraction process will create a jboss-4.2.3.GA directory.

This chapter is a set of hands-on labs. You get step-by-step information about how the JBoss Developer Studio can be used during the development process.

In this section you get to know how to create a Seam project in JBDS, how to start the server and what a structure your project has after creating.

Before opening the JBoss Developer studio you need to download and start a Workshop Database.

To start the database just run ./ or runDBServer.bat from the database directory.

The end result should be a console window that looks like:

Minimize the terminal window and run the JBoss Developer Studio from Applications Menu or from the desktop icon.

First of all you get the Workspace Launcher. Change the default workspace location if it's needed. Click on Ok.

After startup, you see the welcome page. You could read how to work with welcome pages in previous chapter. Now select Create New... icon and then press on Create Seam Project link.

The New Seam Project wizard is started. You need to enter a name (e.g., "workshop") 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 allows the wizard to correctly identify where the needed datasource and driver libraries need to go.

All settings are already specified here, you can just modify the Configuration. Click on the Modify... button to configure your custom facets pattern:

On the whole the dialog allows to select the "features" you want to use in your project. Doing this JBoss Developer Studio setups 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 the default configuration, Dynamic Web Module, Java, JavaServer Faces (JSF), and Seam Facet are already selected for a typical database-driven web application. The default project facets should suffice.

In the Project Facets form you can also bring up server runtimes panel by clicking Runtimes tab on the right corner. This panel shows available server runtimes.

Click on Ok and then Next to proceed further.

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 or choose another folder.

On the next form, 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.

Next wizard step needs more settings that previous. Let's start with General section.

Leave the default Seam runtime and check a WAR deployment.

Next Database section is a little tricky. The Connection Profile needs to be edited so that the new project works properly with the external HSQLDB server. By default the project wizard tries to use the JBoss embedded HSQLDB, but the tutorial uses an external database to replicate a more real world development scenario. Click on Edit to modify the Connection Profile.

Select JDBC Connection Properties. Make sure the URL is set to jdbc:hsqldb:hsql://localhost:1701

Try click on Test Connection button. It probably won’t work. This happens if the hsql jdbc driver is not exactly the same. This can be worked around by modifying the HSQLDB database driver settings. To modify the settings, click the “...” next to the drop-down box.

The proper Driver JAR File should be listed under Driver File(s). Select the hsqldb.jar file found in the database/lib directory and click on Ok.

Select Hypersonic DB and click on Ok. Again, this only happens if the selected hsqldb.jar is different from the running database.

Now, the Test Connection should succeed. After testing the connection, click on Ok.

You can leave the Code Generation section as is. It refers to Java packages in which the generated code will be placed.

Click on Finish button. Now, there should be a new Seam project called “workshop” listed in Package Explorer view.

The complete information on how to manage JBoss AS from JBoss Developer Studio you can read in a corresponding chapter.

Now you just need to start the server by clicking on the Start the server icon ( ) in the JBoss Server View.

Then run the project by selecting the project and use Run As... > Run on Server.


If the project does not show up, then you can use a normal browser and use http://localhost:8080/workshop/home.seam as the url.

Your project looks like this:

Now let's examine the project and its structure. Go back to the Package Explorer view in JBoss Developer Studio.

It seems like it's not much for project but this shell application contains a login screen with default login logic, a menu template that can be further modified, and other layout templates.

It's important to note that the business logic will reside in the src/hot folder, by default. And, the package naming conventions that were used in New Seam project wizard could have been changed to something different from org.domain.workshop.session. Also, notice that there is a default Authenticator. java file. This is where custom security logic can be added. Seam has a nice declarative security model that we will explore in a bit more detail later on. The src/main folder is a model directory. It stores the project's JPA entity beans.

The view tier of the application is also important. Seam uses facelets and there is a built-in facelets GUI editor that has some nice WYSIWYG and component drag/drop functionality. Try this out by opening home.xhtml from WebContent folder.

Notice that the templates reside in the WebContent/layout folder. There is a stylesheet in the WebContent/stylesheet folder. There is also a login and default error page. The Facelet editor will be explored in more detail later in the lab.

The project already has a datasource that was created per the Seam project wizard database settings. And, obviously all of the Seam specific configuration files and JAR dependencies are included and placed in the proper locations. On last noteworthy line item is related to the build script. There isn’t a build script because the Eclipse WTP(Web Tools Project) plugin is used to publish web application changes. As you can see, JBoss Developer Studio is removing a great deal of complexity from the enterprise Java project setup/deployment process. The end result is a developer that is writing code, not spending days/weeks trying to figure out how to get a decent development environment and project build process.

Now, it’s time to write some code. The good news is that JBoss Developer Studio can also help out in this respect. In this section, we will create a new Seam Action POJO and facelet with some custom business logic and some GUI changes.

In this section you will see how it’s easy to secure the facelets and facelet components in Seam. Let’s go ahead and secure the action button, then we will secure the entire page.

Now, it’s time to reverse engineer the workshop database into a fully functioning Seam CRUD(Create Read Update Delete) application.

In JBoss Developer Studio, switch to Seam perspective, and then right-click the project and select New > Seam Generate Entities.

"workshop" project in the Seam Generate Entities wizard will be selected automatically. There is no need to change something more, click Next to proceed further.

On the next page use the Include button to include all the tables from the database and click Finish.

After running the Generate Entities action, you will see new org.domain.workshop.entity classes. These classes represent insert/update/delete/query logic.

There are also org.domain.workshop.entity package that contains the JPA classes. These are the entity beans that are mapped to database tables.Note,that you can use Seam refactoring tools with Seam components. Read more about it in Seam refactoring tools chapter of Seam Dev Tools Reference Guide.

Last, but not least, there are facelets for all of the CRUD screens. The best way to get a feel for the generated code is to open a browser and play around with the application. Go to http://localhost:8080/workshop and insert/update/delete/query a few records. There is quite a bit of AJAX in this application, but which we will explore further later on in the lab. For now, take note of the page tabs, required field logic and data table sorting in the list pages.

Congratulations! You now have a fully functioning CRUD application that is already AJAX enabled.

Now, it's time to write some JPA queries using the Hibernate perspective in JBoss Developer Studio.

In the upper right corner of the workbench there is a small icon (see the figure below), click on it and choose Hibernate.

Look at the Hibernate Configurations view. In the "workshop" project, drill down on the Session Factory and notice that the JPA entities/attributes are listed in a nice tree view.

Right click on the Session Factory and select HQL Editor. This will open a JPA query scratch pad window.

Write your query and click on the "Hibernate Dynamic SQL Preview" tab. You should see the SQL that will be executed if this JPA query is run.

Run the query by clicking on the green run icon.

The results are listed in the "Hibernate Query Result" tab. There is a "Properties" tab in the workbench that can be used to see a specific JPA result. These results represent the JPA objects because our query did not specify column names.

The query can be refined, and take note that there is nice code completion in the JPA query editor.

A refined query will return results that are more ResultSet oriented. Notice the join logic that JPA supports.

There was no need to specify an Employees table in the from part of the JPA query because JPA supports reference traversal via Java class attribute references. Not only are JPA and HQL queries fully supported, but Criteria based queries can also be written in the Criteria Editor. You should spend some time tinkering with different queries and possibly Criteria based queries, even though the instructions are not provided in this lab.


We highly recommend developing in Seam. This chapter is for users who for some reason cannot use Seam.

In this chapter you'll find out how to create a simple JSP application using the JBoss Developer Studio. The application will show a classic "Hello World!" on the page.

We'll assume that you have already launched JBoss Developer Studio and also that the Web Development perspective is the current perspective. If not, make it active by selecting Window > Open Perspective > Web Development from the menu bar or by selecting Window > Open Perspective > Other... from the menu bar and then selecting Web Development from the Select Perspective dialog box.

This section covers all the points how to create, edit and then preview JSP page.

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.

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

While creating any web project you could experience a pain writing ant scripts and managing the packaging even when 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.

JBDS comes with JSP design-time preview features. When designing JSP pages you can easily preview how they will look during runtime. You can even attach your stylesheet to the Preview.

  • Make a little change to hello.jsp page, e.g. put this code snippet:

<%= new java.util.Date() %>
  • Click Save button.

  • Switch to Preview page by clicking Preview tab at the bottom of the page. You will see how the page will look at runtime.

Let's now launch our project on server. We'll use JBoss Server that is shipped with JBoss Developer Studio. You can do it by performing one of the following actions:

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

You should see the next page in a Browser :

Thus with the help of this chapter you've learnt how to organize a Dynamic Web Project with a minimal configuration, add any staff to it (in our case it's just one jsp page) and deploy and run it on the JBoss Server shipped with JBDS.


We highly recommend developing in Seam. This chapter is for users who for some reason cannot use Seam.

In this chapter you will see how to create a simple JSF application being based on "RAD" philosophy. We will create the familiar Guess Number application. The scenario is the following. You are asked to guess a number between 0 and 100. If the guess is correct, a success page is displayed with a link to play again. If the guess is incorrect, a message is printed notifying that a smaller or a larger number should be entered and the game continues.

We'll show you how to create such an application from scratch, along the way demonstrating powerful features of JBoss Developer Studio such as project templating, Visual Page Editor, code completion and others. You will design the JSF application and then run the application from inside JBoss Developer Studio using the bundled JBoss server.

A resource file is just a file with a .properties extension for collecting text messages in one central place. JBoss Developer Studio allows you to create quickly a resource file. 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.

Your resource file and java bean will be stored in this folder.

JBoss Developer Studio will automatically open file for editing.

  • Click Add button for adding new attribute to your resource file

  • Type how_to_play for "name" and Please pick a number between 0 and 100. for value

  • Click Finish

  • In such a way add the next properties:

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.
  • Click File > Save from the menu bar

Your .properties file should now look like follows:

Up and Down buttons allow you to move you attribute on the list. For delete the attribute, choose it and press Delete button.

If you want to change a value or a name of your attribute, click on it and than on Edit button.

If the .properties file is rather big and there are a lot of entries in it, you can use filtering and regular expressions to find the necessary ones. The Filter and Regular Expressions Search is implemented by an expandable panel, closed by default:

When "Expression" is not selected (as by default), filter is case insensitive. When "Expression" is selected, filter uses regular expressions which are case sensitive

Enter the characters that should be searched for in the entries to the 'name' or 'value' input fields accordingly. The filtered results will be displayed in the table below:

When using regular expressions please note, that regular expression syntax does not use "*" for any characters and "?" for any one character. It's necessary to use "." for any one character and ".*" for any characters. Symbols "*" and "?" are used to show that the preceding token is not required, for example, "a.a" matches "aba" but not "aa", while "a.?a" or a.*a" matches both; besides "a.*a" matches "abcda".

To find the exact match, use sequences \A and \z in expression. For example, expression "\Adate\z" matches only string "date"; expression "\Adate" matches "date" and "dateline", expression "date\z" matches "date" and "Begin date", and expression "date" matches all of them.

In this section you'll see how to 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);
    return "playagain"; 
  public String checkGuess () 
    // if guessed, return 'success' for navigation
    if ( userNumber.intValue() == randomNumber ) 
      return "success";
      FacesContext context = FacesContext.getCurrentInstance();
      ResourceBundle bundle = ResourceBundle.getBundle("game.messages", 
      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);
    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
      // get a reference to properties file to retrieve messages
      FacesContext context = FacesContext.getCurrentInstance();
      ResourceBundle bundle = 
      String msg = "";
      // if number is 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";

In this section you know about faces-config.xml file.

This file holds two navigation rules and defines the backing bean used.

<?xml version="1.0" encoding="UTF-8"?>
<faces-config version="1.2" xmlns="


The first navigation rule states that from any page (* stands for any page) an outcome of playagain will take you to /pages/inputnumber.jsp . Outcome values are returned from backing bean methods in this example. The second navigation rule states that if you are at the page /pages/inputnumber.jsp , and the outcome is success, then navigate to the /pages/success.jsp page.

Now, we will continue editing the JSP files for our two "views" using Visual Page Editor.

First, let's dwell on how to edit inputnumber.jsp.

On this page we will have an output text component displaying a message, a text field for user's number entering and a button for input submission.

The Visual Page Editor will open in a screen split between source code along the top and a WYSIWIG view along the bottom. You can see that some JSF code will be already generated as we choose a template when creating the page.

At the beginning it's necessary to create a <h:form> component where all others components are put.

In source view you can see the declaration of a form.

First let's declare the properties file in inputnumber.jsp page using the loadBundle JSF tag.

  • Put this declaration on the top of a page, right after the first two lines:

<f:loadBundle basename="game.messages" var="msg"/>

As always JBDS provides code assist:

  • Switch to Visual tab, so it could be possible to work with the editor completely in its WYSIWYG mode

  • Click on outputText, drag the cursor over to the editor, and drop it inside the blue box in the editor

  • Select value and click on this line below "value" header

  • Click ... button next to the value field

JBDS will nicely propose you to choose within available values:

The text will appear on the page:

  • Switch to Source mode and insert <br/> tag after <h:outputText> component to make a new line.

  • Click Save button.

  • On the Palette click on inputText, drag the cursor over to the editor, and drop it inside the editor after the text.

  • Switch to a Source mode and insert <br/> tag after <h:outputText> component to make a new line

  • Click Save button

  • On the Palette click on inputText, drag the cursor over to the editor, and drop it inside the editor after the text

  • Select value and click on this line below "value" header

  • Click ... button next to the value field

  • Expand Managed Beans > NumberBean

  • Select userNumber value and click Ok

  • Switch Advanced tab

  • Select id and click on this line below "value" header

  • Type userNumber in text field

  • Select required and click on this line below "value" header

  • Click ... button next to the value field

  • Expand Enumeration and select true as a value

  • Click Ok, then click Finish

  • Go to Source mode

  • Add the validation attribute to <f:validateLongRange> for user input validation

<h:inputText id="userNumber" value="#{NumberBean.userNumber}" required="true">
           <f:validateLongRange minimum="0" maximum="100"/>
  • Click Save button

  • Again select Visual mode

  • On the Palette, click on commandButton, drag the cursor over to the editor, and drop it inside the editor after the inputText component.

  • In the editing dialog select value and click on this line below "value" header

  • Click ... button next to the value field

  • Expand Resource Bundles > msg and select makeguess_button as a value

  • Click Ok

  • Select action and click on this line below "value" header

  • Type NumberBean.checkGuess in text field

  • Click Finish

  • In Source mode add <br/> tags between <outputText> , <inputText> and <commandButton> components to place them on different lines

inputnumber.jsp page should look like this:

<%@ taglib uri="" prefix="h" %>
<%@ taglib uri="" prefix="f" %>
<f:loadBundle basename="game.messages" var="msg" />
            <h:form id="inputNumbers">
                <h:outputText value="#{msg.how_to_play}" />
                <br />
                <h:messages style="color: blue" />
                <br />
                <h:inputText value="#{NumberBean.userNumber}" id="userNumber"
                    <f:validateLongRange minimum="0" maximum="100" />
                <br />
                <br />
                <h:commandButton value="#{msg.makeguess_button}"
                    action="#{NumberBean.checkGuess}" />

In the same way like inputnumber.jsp, edit success.jsp page. Its whole source should be the next:

<%@ taglib uri="" prefix="h" %>
<%@ taglib uri="" prefix="f" %>
<f:loadBundle basename="game.messages" var="msg"/>

            <h:form id="result">
                <h:outputFormat value="#{msg.success_text}">
                <f:param value="#{NumberBean.userNumber}" />
                <br />
                <br />
                <h:commandButton value="#{msg.trayagain_button}"
                    action="#{NumberBean.playagain}" />

Again you can use code assist provided by JBDS when editing jsp page:

This page, success.jsp, is shown if you correctly guessed the number. The <h:outputFormat> tag will get the value of success_text from the properties file. The {0} in success_text will be substituted for by the value of the value attribute within the <f:param> tag during runtime.

At the end, you have a button which allows you to replay the game. The action value references a backing bean method. In this case, the method only terminates the current session so that when you are shown the first page, the input text box is clear and a new random number is generated.

  • Switch to Preview mode to see how this page will look in a browser:

JBoss Developer Studio provides an option to download and import a ready-made project that you can explore and derive some useful technology implementation lessons from.

To adjust the settings of the Project Examples feature you need to navigate to Windows> Preferences > JBoss Tools > Project Examples .

The Show experimental sites checkbox serves to enable/disable representing the user sites in the Project Example dialog ( Help > Project Examples).

As you can see from the Project Examples Preferences image you can add a custom project example that can be provided by anyone. This feature can, for example, facilitate project testing.

In oder to add a new project example you need to select the User sites option and press the Add button to the right.

When the Add button is pressed the Add Project Example Site dialog is displayed. The dialog contains 2 input fields: Name where you need to specify the name of the new entry and URL that has to point to the xml file that contains example project(s) properties. In more detail the structure of the xml file is discussed further in the chapter of the guide. Alternatively, if the xml is stored on your local machine, you can hit the Browse button to select the file in the file system.

Here is an example of the xml file that holds project example settings:

        <category>User Examples</category>
        <name>User Project Example</name>
        Short project description.
        Full project description.

Once you define the location of the xml file with projects settings you will see a new user site entry added. Please note now if you select the entry you can edit and remove it with the corresponding buttons to the right. You can not do such operations with the Plugin provides sites.

When the user sites location is set up you can download and install the project(s). Please see the next chapter of the guide.

To download a project example and start working with it you need to take a few steps:

Alternatively, you should navigate to New > Other.., scroll down to find the JBoss Tools option (or just type in the first letters of the word "JBoss" for quick search), expand the option and select Project Examples, click Next.

  • Now in the New Project Example dialog you can select a project you would like to explore and a site to download it from

    Project Examples Wizard provides a filter field to more easily locate the project examples you want, so you can type in the project you would like to explore in the field.

If you have previously specified user sites (see the User Sites chapter) they also will be displayed in the list of project examples in the category that was defined in the xml file with user sites settings.

Pleas note that to view the user sites you need to have Show experimental sites checked.

  • Press Finish to start downloading the project from the repository

When downloading is finished the project will be imported automatically and you will be able to see it in the Package Explorer.

Now you can run the application on the server.

For more information on JBoss Developer Studio features, refer to the following FAQ to get the answers on the most "popular" questions.

If there's anything we didn't cover in this guide, please feel free to visit our JBoss Developer Studio Users Forum or JBoss Tools Users Forum to ask questions. There we are also looking for your suggestions and comments.

  • Seam Dev Tools Reference Guide (html)

    This guide helps you to understand what Seam is and how to install Seam plug-in into Eclipse. It tells you the necessary steps to start working with Seam Framework and assists in a simple Seam Project creation. Also you will learn how to create and run the CRUD Database Application with Seam as well as find out what Seam Editors Features and Seam Components are.

  • Visual Web Tools Reference Guide (html) provides general orientation and an overview of JBDS visual web tools functionality. This guide discusses the following topics: editors, palette, web properties view, openOn, content assist, RichFaces support.

  • JBoss Server Manager Reference Guide (html)

    This guide covers the basics of working with the JBoss server manager. You will read how to install runtimes and servers and quickly learn how to configure, start, stop the server and know how deployment and archiving process. You will find out how to manage installed JBoss Servers via JBoss AS Perspective. You will also read how to deploy modules onto the server.

  • jBPM Tools Reference Guide (html)

    With jBPM Tools Reference Guide we'll help you to facilitate a cross-product learning and know how you can speed your development using special editors and visual designers. We'll also guide you through the steps on how to create a simple process and test it within jBPM jPDL perspective.

  • Hibernate Tools Reference Guide (html)

    Throughout this guide you will learn how to install and use Hibernate Tools bath via Ant and through Eclipse. We'll supply you with the information on how to create mapping files, configuration file as well as a file for controlling reverse engineering by using specific wizards that Hibernate tooling provides. Also you will know about Code Generation and peculiarities of work within Hibernate Console Perspective.

  • ESB Editor Reference Guide (html)

    This guide provides you with the information on ESB Editor and all necessary wizards for ESB files development.

  • JBoss Portal Tools Reference Guide (html)

    The guide gives a detail look at how you can easily build a Portlet Web Application with JBoss Tools and deploy it onto JBoss Portal.

  • JBoss WS User Guide (html)

    This guide gives you practical help on JBossWS usage. You will learn how to create a web service using JBossWS runtime, find out how to create a web service client from a WSDL document using JBoss WS and also see how to set your development environment.

  • Smooks Tools Reference Guide (html)

    This guide is packed with useful and easy-to-understand information about graphical, configuration and source editor pages.

  • Drools Tools Reference Guide (html)

    The guide help you to discover how to create a new Drools project, use debugging rules and work with different editors.

  • JMX Tools Reference Guide (html)

    With the help of this guide you'll explore the best practices to follow when working with MBean Explorer, MBean Editor, Connections and etc.

  • Eclipse Guvnor Tools Reference Guide (html)

    The purpose of this guide is to describe briefly the functionality present in the Eclipse Guvnor Tools (EGT) for Drools 5.

  • JSF Tools Tutorial (html)

    This tutorial will describe how to deal with classic/old style of JSF development and how to create a simple JSF application using the JBoss Developer Studio.

  • JSF Tools Reference Guide (html)

    From this guide you'll discover all peculiarities of work at a JSF project. You'll learn all shades that cover the process of project creation and take a closer look at the JSF configuration file. Also you'll get to know managed beans and how to work with them and find out, how to create and register a custom converter, custom validator and referenced beans in a JSF project.

  • Struts Tools Reference Guide (html)

    In Struts Tools Reference Guide you will learn how to create and work with a new struts project. This guide also provides information about graphical editor for struts configuration files, tiles files, and struts validation files.

  • Struts Tools Tutorial (html)

    This tutorial will describe the classical style of Struts development, and will step-by-step show you how to create a simple Struts application in JBoss Developer Studio.

  • Exadel Studio Migration Guide (html)

    This document is intended to help you to migrate an existing Exadel JSF or Struts projects from Exadel Studio into JBoss Developer Studio.