JBoss.orgCommunity Documentation

Getting Started Guide

Version: 4.0.0


1. Installation Instructions
1.1. Installing JBoss Tools Plugins
1.2. Usage Reporting
1.2.1. Collected usage information guide
2. JBoss Central
2.1. Getting Started with JBoss Central
2.2. Software installation and updates from within JBoss Central
2.3. Project Example Installation
3. JBoss Perspective
4. Setting up a JBoss runtime and managing the server
4.1. Adding and configuring a JBoss server runtime
4.2. Starting JBoss Server
4.3. Stopping the JBoss Server
4.4. Server Container Preferences
5. Developing a simple JSP web application
5.1. Setting Up the Project
5.2. Creating JSP Page
5.2.1. Editing a JSP Page
5.2.2. web.xml file
5.2.3. Deploying the project
5.2.4. JSP Page Preview
5.2.5. Launch JSP Project
6. Rapid Application Development of a JSF application
6.1. Setting up the project
6.2. Creating JSP Pages
6.3. Creating Transition between two views
6.4. Creating Resource File
6.5. Creating a Java Bean
6.6. Editing faces-config.xml File
6.7. Editing the JSP View Files
6.7.1. Editing inputnumber.jsp page
6.7.2. Editing success.jsp page
6.8. Creating index.jsp page
6.9. Running the Application
7. Uninstalling the JBoss Developer Studio
8. FAQ
8.1. What should I do if the Visual Page Editor does not start under Linux
8.2. Visual Editor starts OK, but the Missing Natures dialog appears
8.3. I have an existing Seam 1.2.1 project. Can I migrate or import the project into a JBoss Developer Studio Seam project?
8.4. I have an existing Struts or JSF project. Can I open the project in JBoss Developer Studio?
8.5. Can I import a WAR file?
8.6. Is it possible to increase the performance of Eclipse after installing your product?
8.7. How can I add my own tag library to the JBoss Tools Palette?
8.8. How to get Code Assist for Seam specific resources in an externally generated project?
8.9. How to import an example Seam project from jboss-eap directory?
8.10. Is a cross-platform project import possible for JBoss Developer Studio?
9. Further Reading

The JBoss Tools plugins can be installed in Eclipse from the JBoss.org update site. JBoss Tools 4.0 requires Eclipse 4.2, which can be downloaded from the Eclipse web site.

To install the JBoss Tools plugins start Eclipse and select HelpInstall New Software...


Click the Add... button.


This will display the Add Repository dialog. Enter JBoss.org Tools in the Name field, and http://download.jboss.org/jbosstools/updates/stable/juno/ in the Location field. Click the OK button to save the changes and close the dialog.


The JBoss.org Tools site will be selected in the Work with drop down list, and after a moment the list of plugins that are included in the JBoss Tools package will be listed. From this list you can individually select the desired plugin, or select the Abridged JBoss Tools 4.0 option to install all the plugins.


Click the Next button to calculate the system requirements and dependencies (this may take a little while). You will then be given an opportunity to review the plugins that will be installed.


Click the Next button to install the selected plugins. You will be prompted to accept the various license agreements that cover the plugins that are to be installed. Review the licenses, select the I accept the terms of the license agreements option, and click the Finish button to install the plugins.


Wait while the plugins are downloaded and installed.


You may be prompted with a warning informing you that you are attempting to install unsigned content. Click the OK button to continue.


You will then have to restart Eclipse to apply the new plugins. When prompted click the Yes button to restart Eclipse.


The plugin is now installed and ready to use.

JBoss Tools now includes a usage plug-in that anonymously reports information back to JBoss. The plug-in is not enabled by default. To enable, click the Yes button.


Once enabled, the plug-in will remain active until turned off. To turn the active plug-in off, navigate to WindowPreferencesJBoss ToolsUsage Reporting.

The gathered data allows JBoss to see how the tools are being used and where they are being used geographically. Currently we are looking into the operating systems being used, screen resolution and how often the tooling environment is started. In the future geographic information will assist in focusing translation resources to areas where the developer environment is most used.

The plug-in uses Google Analytics to track and report data by acting as if you were visiting the site http://jboss.org/tools/usage/. To view the type of information being collected, refer to Section 1.2.1, “Collected usage information guide”.

To view the source code of the usage plug-in visit http://anonsvn.jboss.org/repos/jbosstools/trunk/usage/.

Below you will find an outline of the information that is reported and the Goolge Analytics fields that are used to gather this information.

Version

The Content field has been modified to report the installed JBoss Developer Studio version. Sample returned values include: jbdevstudio-linux-gtk-x86_64-4.0.0.v201009301221R-H20-Beta1.jar and jbdevstudio-linux-gtk-3.0.2.v201009161622R-H138-GA.jar.

Installed components

The Keyword field has been modified to report the installed JBoss Developer Studio components. Sample returned values include: JBoss AS, Drools, Teiid and ModeShape.

Visitor type

The Visitor type field reports if the current user is new or returning.

Language

The Language field reports the localized language the product is being used in. Sample returned values include: en-US, de-DE and fr-FR.

Location fields

The location fields report the geographical location where the product is being used based on the continent, country and city. Sample returned values include: Europe (continent), Germany (country) and Munich (city).

Eclipse interface and version

The Browser field has been modified to report the Eclipse interface and version being used. Sample returned values include: JBoss Developer Studio: 5.0.0 and JBoss Developer Studio: 5.0.1.

Operating System

The Operating System field reports the operating system and its version that the product is running on (with Linux distribution version reporting conducted through the User Defined Value field). Sample returned values include: Linux, Macintosh 10.6, Macintosh 10.7 and Windows 7.

Linux distribution version

The User Defined Value field reports the distribution and version of Linux, if one is being used as the operating system. Sample returned values include: Red Hat Enterprise Linux 6 and Fedora 16

Screen colors

The Screen colors field reports the color depth being used. Sample returned values include: 32-bit and 24-bit.

Screen resolution

The Screen resolution field reports the resolution being used. Sample returned values include: 2048x1536 and 1920x1080.

Java version

The Flash version field has been modified to report the Java version used. Sample returned values include: 1.6.0_20.

Connection speed

The Connection speed field reports the type of internet connection being used. Sample returned values include: T1, Cable and DSL.

JBoss Central Enabled

The JBoss Central Enabled field reports whether JBoss Central is set to be seen upon startup or not. Returned value is either true or false.

When viewing the workbench for the first time you will be greeted with JBoss Central. JBoss Central assists you in getting started and keeps you up to date with JBoss technologies.


The Getting Started tab of JBoss Central is the first tab you will see. It is set up as a functional starting point for developers.

At the top of the tab is a search box. By clicking the down arrow to the left you can select to perform a search on either the Red Hat Customer Portal or the JBoss Community.


Performing a search will launch a web browser as a new tab, displaying the results page. You can interact with the browser as you would any other web browser.


From the Create Projects section you can create a Dynamic Web Project, OpenShift Express Application, Java EE Web Project, Java EE Project, HTML5 Project, Spring MVC Project, RichFaces Project, GWT Web Project, or any one of many Project Examples. To access a complete list of projects you can create, click on the window icon at the top-right of the Create Projects section .

Note

All wizards generate Maven based projects, except for the Dynamic Web Project wizard.


GWT (Google Web Toolkit) Web Project creation

To create a GWT web project, the latest m2e-wtp and Google plug-ins have to be installed. If these plug-ins have not been previously installed, the first page of the GWT web project wizard will provide you with the ability to install the plug-ins.


Under the Project Examples section you can expand and view JBoss Quickstarts. Each quickstart is an example to assist first time users.


For an in-depth look into the installation of project examples see Section 2.3, “Project Example Installation”.

You can also download other examples and install and set runtime preferences through the Project Examples section by using the five buttons at the top-right. The first button launches a New Project Examples wizard. Here you can search and download project examples to assist you with getting started.


By clicking on the second button you will be taken directly to the JBoss Tools Runtime Detection dialog within Preferences.


The third button takes you directly to the Server Runtime Environments preferences dialog.


The final button refreshes the Project Examples list.

The Documentation section of JBoss Central contains links to help materials such as reference guides, user forums and documentation concerning new features.


If you do not wish to see JBoss Central at every startup, you can deselect the checkbox Show on Startup in the Settings section.


The News and Blogs sections are updated automatically, bringing you the latest information concerning JBoss technologies.


Note

After using JBoss Central once, the current content will be available offline. This includes project example archives and descriptors, maven artifacts, and news and blog feeds.

The Software/Update tab at the bottom of JBoss Central switches to a screen where you can install and update your software.


To install or update software, select the checkbox beside one or more components.


Once you have selected all the components to update or install, click the Install button at the bottom left of the tab window. A window will then open offering you the option of deselecting a part of the component if you wish.


You will then be asked to confirm the selection of components to install. To accept the selection press the Next button. You can change the components by pressing the Back button.


After pressing the Next button you will need to accept the terms of the license agreement for the associated software being installed. To do this select the corresponding radio button.

Click Finish to begin installation.


As the installation process takes place you can choose to have further details displayed or run the installation in the background.


After the software has been downloaded, you will be asked to verify the installation of the components if the contents are unsigned. Install unsigned third-party components with discretion.


Once installation is complete, restart JBoss Developer Studio by pressing the Restart Now button in the window that opens.


The JBoss perspective is designed to incorporate the views most often used by developers using JBoss, while also changing standard menu items to reflect what a JBoss devleoper would want and need.


The JBoss perspective views include: Project Explorer, Outline, Palette, Properties and Servers.

Certain menus also see a change in available items. These menus include FileNew, WindowShow View and the context menu for a project.

A selection of the menu items for FileNew can be seen in Figure 3.2, “JBoss Perspective: FileNew ”.


A selection of the menu items for WindowShow View can be seen in Figure 3.3, “JBoss Perspective: WindowShow View ”.


A selection of the menu items for the context menu of a project can be seen in Figure 3.4, “JBoss Perspective: Context MenuNew ”.


Although JBoss Developer Studio works closely with JBoss Enterprise Application Platform 6 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 chapter we discuss how to manage a JBoss server.

Note

This chapter assumes you have a JBoss application server installed on your system. If you do not, consult the installation instructions that accompanied your server.

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

It will be assumed 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 WindowOpen PerspectiveWeb Development from the menu bar or by selecting WindowOpen PerspectiveOther... from the menu bar and then selecting Web Development from the Select Perspective dialog box.

This section outlines how to create, edit and then preview a 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 the Project Explorer view.

Writing any scripts and managing the packaging process can be quite a complicated and time consuming task for even the most trivial web applications. However, JBoss Developer Studio relieves you of this burden. All you need is to start your JBoss Server and launch your application in your favorite browser.

You can also create a JAR archive with JBoss Developer Studio's Archive Tools and export it to any web server.

In this chapter you will learn how to create a JSF application being based on the Rapid Application Development (RAD) philosophy. We will create the familiar Guess Number application. The game is played according to the following rules. 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.

You will now learn how to create such an application from scratch, along the way demonstrating the powerful features included in 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 a JBoss server.

A resource file is 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 a resource file can be displayed to you on a Web page during application execution.

With resource file you don't hard code anything into the JSP pages. It also 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 messages.properties file for editing.


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

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

  • Click the Finish button

  • Add the following properties using the same process:

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.
  • Select FileSave from the menu bar

Your .properties file should now look like follows:


The Up and Down buttons allow you to move the attributes in the list. To delete the attribute, select it and press the Delete button.

If you want to change a value or a name of your attribute, select it and then click the 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 narrow down the list. 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 learn how to create a Java bean that will hold business logic of our application.

A java bean is created.

Integer userNumber;

JBoss Developer Studio allows for quick generation of 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.ResourceBundle;

The Java Bean contains the following code:

package game;

import javax.faces.context.FacesContext;
import javax.servlet.http.HttpSession;
import javax.faces.application.FacesMessage;
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().getLocale());
      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 will learn about the 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="http://java.sun.com/xml/ns/javaee"
	xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
    http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2_.xsd">
  
  <navigation-rule>
    <from-view-id>*</from-view-id>
    <navigation-case>
      <from-outcome>playagain</from-outcome> 
      <to-view-id>/pages/inputnumber.jsp</to-view-id>
    </navigation-case>
  </navigation-rule>

  <navigation-rule>
    <from-view-id>/pages/inputnumber.jsp</from-view-id>
    <navigation-case>
      <from-outcome>success</from-outcome> 
      <to-view-id>/pages/success.jsp</to-view-id>
    </navigation-case>
  </navigation-rule>
  
  <managed-bean>
    <managed-bean-name>NumberBean</managed-bean-name>
    <managed-bean-class>game.NumberBean</managed-bean-class>
    <managed-bean-scope>session</managed-bean-scope>
  </managed-bean>
                 
</faces-config>

The first navigation rule states that from any page (* stands for any page) an outcome of playagain will take you to the /pages/inputnumber.jsp file. 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 the Visual Page Editor.

First, edit the inputnumber.jsp file.

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 have already been generated since we chose a template when creating the page.

At the beginning it's necessary to create a <h:form> component that will hold the other components.

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


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

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

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

As always JBoss Developer Studio provides code assist:


  • Switch to Visual tab, where it is possible to work with the editor through a WYSIWYG interface

  • Click the outputText item from the JSF HTML group in the JBoss Tools Palette view, drag the cursor over to the editor, and drop it inside the blue box in the editor

  • Select the second column in the value row.

  • Click the ... button next to the value field

JBoss Developer Studio will display a list of possible values:


The text will appear on the page:


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

  • Click the 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 the value row and click in the second column

  • Click the ... button next to the value field

  • Expand Managed BeansNumberBean

  • Select userNumber value and click the OK button

  • Select the Advanced tab

  • Select the id row and click in the second column

  • Type userNumber in the text field

  • Select the required row and click in the second column

  • Click ... button next to the value field

  • Expand Enumeration and select true as a value


  • Click the OK button, then click the Finish button

  • 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"/>
</h:inputText>
  • Click the 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 the value row and click on the second column

  • Click the ... button next to the value field

  • Expand Resource Bundlesmsg and select makeguess_button as a value

  • Click the OK button

  • Select the action row and click in the second column

  • Type #{NumberBean.checkGuess} in the text field

  • Click the Finish button

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

inputnumber.jsp page should look like this:

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<%@ taglib prefix="f"  uri="http://java.sun.com/jsf/core"%>
<%@ taglib prefix="h"  uri="http://java.sun.com/jsf/html"%>
<f:loadBundle basename="game.messages" var="msg"/>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
		<title>Insert title here</title>
	</head>
	<body>
		<f:view>
			<h:form id="inputNumbers">
				<h:outputText value="#{msg.how_to_play}"/>
				<br/>
				<h:messages style="color: blue" />
				<br/>
				<h:inputText id="userNumber" required="true" value="#{NumberBean.userNumber}">
					<f:validateLongRange minimum="0" maximum="100" />
				</h:inputText>
				<br/>
				<br/>
				<h:commandButton action="#{NumberBean.checkGuess}" value="#{msg.makeguess_button}"/>			
			</h:form>
	</f:view>
	</body>
</html>

Refer to the following FAQ to get the answers on the most "popular" questions concerning JBoss Developer Studio.