JBoss AS 5 Development

By Francesco Marchioni
    Advance your knowledge in tech with a Packt subscription

  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Installing Core Components

About this book

JBoss AS is the most used Java application server on the market meeting high standards of reliability, efficiency, and robustness and is used to build powerful and secure Java EE applications. It supports the most important areas of Java Enterprise programming including EJB 3.0, dependency injection, web services, the security framework, and more. Getting started with JBoss application server development can be challenging; however, with the right approach and guidance, you can easily master it and this book promises that.

Written in an easy-to-read style, this book will take you from the basics of JBoss AS—such as installing core components and plug-ins—to the skills that will make you a JBoss developer to be reckoned with, covering advanced topics such as developing applications with JBoss Messaging service, JBoss web services, clustered applications, and more.

You will learn the necessary steps to install a suitable environment for developing enterprise applications on JBoss AS. Then, your journey will continue through the heart of the application server, explaining how to customize each service for optimal usage. You will learn how to design Enterprise applications using Eclipse and JBoss plug-ins. You will then learn how to enable distributed communication using JMS. Storing and retrieving objects will be made easier using Hibernate. The core section of the book will take you into the programming arena with tested, real-world examples. The example programs have been carefully crafted to be easy to understand and useful as starting points for your applications.

This book will kick-start your productivity and help you to master JBoss AS development. The author's experience with JBoss enables him to share insights on JBoss AS development, in a clear and friendly way. By the end of the book, you will have the confidence to apply all the newest programming techniques to your JBoss applications.

Publication date:
December 2009


Chapter 1. Installing Core Components



From: Acme Head Offices

To: Francesco Marchioni

Hi Francesco,

Can you meet at 4 PM in the boardroom? We are going to interview a few guys for the new JBoss Enterprise project.


Monty Burns

JBoss Application Server has been around since the beginning of the new millennium and, in personal resumes, it is common to find people who have acquired some experience on it.

Before every job interview, I have the expectation that high caliber Java/Java EE candidates surely know the core concepts of JBoss AS. Often, companies don't consider hiring just the best techie guy, but a well-rounded profile with a "situation-action-result" mind.

One thing I personally like to ask to identify smart developers is: Why have you chosen to learn JBoss and not XYZ? How does it differentiate from the competitors? The most habitual answer is: JBoss is free, so I chose to learn Java EE on this platform. Although there is some truth in this answer, I think it's a partial truth and the concept needs to be elaborated.

First, let's define what is free. Today there's a common misconception of open source products being like "free lunch". They can be so for a student who's learning these technologies, but for the real world, open source means you don't pay a license fee to develop/roll in production certain software.

This obviously doesn't mean that the software hasn't got a cost. Moreover, if you don't want to risk breaking your service level agreement, you usually sign a contract with the owner of the open source software so that it guarantees quick and decisive support.

From the financial point of view, this is the first important difference with a commercial product. If you start a project, running a product such as JBoss AS, you don't have an immediate entrance fee. You can even dispense with commercial assistance if you are confident that your technicians will be able to solve any issue. Whatever you choose, this policy is much more flexible than a commercial contract, which requires an immediate financial commitment.

That's better than simply saying: I like JBoss because it's free.

The second and, in my opinion, the most important reason is the worldwide spread of the product. Today JBoss is the most used application server and it has been not only built with the collaborative efforts of many developers around the world, but also with simple contributions of users who request new features. This boils down to the actual nature of the success of JBoss. The real driving force of this product is its community of users, while vendor products are usually designed around commercial or marketing schemas.

As an example of this, you can see that JBoss Application Server is a Java EE compatible server, but you can freely add or remove modules from the application server, thus creating a customized product for your specific needs. It is the flexibility and willingness to adapt that has brought JBoss AS this far, and it will be this trait that will drive the application server full speed into the future.

What you will get in this book

This book is an intense guide to creating professional Java EE applications with JBoss AS 5.0. Packed with example code and written in a friendly, earthy style, this book will act as a handy guide to take you from the basics to the skills that will make you a JBoss developer to be reckoned with.

We think that studying good code samples is one of the best ways to learn, so we included as many as we could. We also wanted this book to be a quick reference to solve most common issues—a book you can have on your desk and turn to when you have a doubt.

JBoss big bang

JBoss AS is an open source Java EE-based application server. The project's first milestone dates back to early 1999, when Marc Fleury developed an open source product named JBoss that was a simple EJB 1.0 container. Since then, the project has been incorporated in a company named JBoss Group. In April 2006 the company was acquired by Red Hat Inc., which started providing professional services to the product. As a matter of fact, you now have two main references for JBoss products—http://www.jboss.org, which is the community of developers where you can freely download products and join forums, and the commercial site http://www.jboss.com, which is targeted at commercial support for the product.



This is where our journey begins. In this chapter, we'll learn how to set up our environment for developing applications on JBoss AS correctly. Installation of the components is not particularly tricky, but it needs a few steps to be performed and quite a lot of Kbytes to be downloaded.

This is our checklist:

  • Install the appropriate Java Development Kit (JDK) for running JBoss AS

  • Install JBoss AS 5.0

  • Install the Eclipse development environment

  • Install the JBoss Tools plugins needed for developing applications

The products listed in this chapter are the latest versions at the time of writing and we diligently updated it at every new release. Don't worry if a new stable release of these products is released in the next months; all you have to do is adapt the chapter instructions to the newest file names.


Installing the Java environment

JBoss is a pure Java application server, so as you might imagine it needs a virtual machine for the Java Platform to run on.

At the time of writing, JBoss AS 5 is distributed in two flavors, one that is suited for Java 1.5 and another version that has been specifically designed for Java 1.6.

The choice of Java Virtual Machine (JVM) is yours otherwise, but we do recommend considering the Java 1.6, that has just undergone the 16th update at the time of writing. Most benchmarks available on the Internet exhibit a roughly 40 percent performance improvement by upgrading from Java 1.5 to Java 1.6. Additionally, Java SE 5.0 reached its End of Service Life (EOSL) on November 3, 2009, which is the date of the final publicly available update of version 5.0. So you are highly encouraged to design your applications with Java 1.6.


Java 1.6 has enhanced performance in many areas of the platform. Improvements include synchronization, performance optimizations, compiler performance optimizations, the new Parallel Compaction Collector, better ergonomics for the Concurrent Low Pause Collector, and application startup performance.


So let's move on to the Sun download page: http://java.sun.com/javase/downloads/index.jsp.

Choose to download the latest JDK/JRE, which is for JDK 1.6 Update 16.


Is JRE enough ?

Yes! JBoss 5 ships with a set of libraries called Eclipse Java development tools (JDT) that allow dynamic compilation of classes at runtime. However, we still suggest you to download the full JDK installation, in case you need to compile your classes with plain javac anywhere else.

Once the download is complete, run the executable file to start the installation.

jdk-6-windows-i586.exe       # Windows
sh jdk-6u12-linux-i586.bin   # Linux

If you are installing on a Linux/Unix box, you can safely accept all the defaults given to you by the setup wizard. Windows users should stay away from the default C:\Program Files that leads to some issues when you are referencing the core libraries. An installation path such as C:\Software\Java or simply C:\Java is a better alternative.

When the installation is complete, we need to update a couple of settings on the computer so that it can interact with Java.

The most important setting is JAVA_HOME that is directly referenced by JBoss startup script.

Windows XP/2000 users should right-click on My Computer and select Properties from the context menu. On the Advanced tab, click the Environment Variables button. Then, in the System variables box click New. Give the new variable a name of JAVA_HOME, and a value of the path to your JDK installation, probably something like C:\Java\jdk1.6.0_16.


For Windows Vista users

Because of increased security in Windows Vista, standard users must have User Account Control (UAC) turned on to change environment variables and the change must be completed through User Accounts. In the User Accounts window, under Tasks, select Change my environment variables. Use the New, Edit, or Delete buttons to add, change, or delete environment variables.

Now it's the turn of the Path variable. Double-click on the Path system variable. In the box that pops up, navigate to the end of the Variable value line, add a semicolon to the end, then add the path to your JDK. This will be something like %JAVA_HOME% \bin.

Unix/Linux users can add the following commands in the user's profile scripts:

export JAVA_HOME=/installDir/jdk1.6.0_16
export PATH=$JAVA_HOME/bin:$PATH

As a final note, you should consider setting the JBOSS_HOME environment variable, which points to the root of the application server. (In our case, it would be C:\jboss-5.0.0.GA for Windows users.)

If you don't set this variable, the startup script simply guesses the location of JBoss AS by climbing one step up from the bin folder.


Installing JBoss AS 5

JBoss Application Server can be freely downloaded from the community site:


Then, you'll soon be redirected to the SourceForge site where the project is hosted.

JBoss 5 is released in two different versions: jboss-5.0.0.GA.zip and jboss-5.0.0-jdk6.zip. The former version is the appropriate distribution if you are using JDK 1.5; the latter is the targeted release for JDK 1.6. Choose the appropriate distribution and start downloading.


At the time of writing, the newer stable release 5.1.0 of JBoss AS is available. The most important changes introduced by the new release include a new web administration console and the reactivation of the cluster farming option. For the purpose of running the examples of this book, you can safely use both the releases 5.0.0 and 5.1.0.

The installation of JBoss is simply a matter of extracting the compressed archive. Windows users can simply use any uncompressed utility, such as WinZip or WinRAR, taking care to choose a folder which doesn't contain empty spaces. Unix/Linux should use the unzip shell command to explode the archive:

$ unzip jboss5.0.0.GA-jdk6.zip


Security warning:

Unix/Linux users should be aware that JBoss AS does not require root privileges, as none of the default ports used by JBoss are below the 1024 privileged port range. To reduce the risk of users gaining root privileges through the JBoss AS, install and run JBoss as a non-root user.

Starting up JBoss AS

After you have installed JBoss, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, move to the bin directory of your JBOSS_HOME directory. Once there, issue the following command:

run.bat    # Windows users
$ run.sh   # Linux/Unix users

Here's a sample JBoss AS 5 startup console:

The previous command starts up JBoss AS and binds the application server to the localhost network interface. This means JBoss cannot be accessed from another machine in your network. The first thing you should learn is how to bind JBoss to the IP address of your machine; this can be achieved with the -b option as follows:

run.bat -b     # Windows Users
run.sh -b      # Unix/linux Users

Here the server is bound to the IP address


Using the IP address of the machine will also exclude the "localhost" network interface, which will no longer be accessible. If you want to bind your server to all available network interfaces, you can use –b

You can verify that the server is reachable from the network by simply pointing the browser to


Introducing the twiddle utility

One useful command-line utility that ships with JBoss is twiddle. This is a needful shell command located inside the JBOSS_HOME/bin folder. It can be used if you don't have a graphical terminal where you can manage JBoss, or if you want to control JBoss with shell scripts.

The syntax of twiddle is basically built into 3 pieces:

twiddle [options] <command> [command_arguments]

Here's an example command line for checking JBoss status:

twiddle -s get "jboss.system:type=Server" Started

Stopping JBoss

Probably the easiest way to stop JBoss is sending an interrupt signal with the Ctrl + C key combination.

However, if your JBoss process was launched in the background or is running on another machine (see the next section), then you have to use the shutdown command from the bin folder:

shutdown -S         # Windows Users
./shutdown.sh -S    # Unix/Linux Users

Stopping JBoss on a remote machine

The shutdown script can also be used to shut down a remote JBoss server, contacting the JBoss naming provider on the remote host.

./shutdown.sh -s jnp://remoteHost:1099
Shutdown message has been posted to the server.
Server shutdown may take a while - check logfiles for completion


Unexpected shutdown?

Unix users sometimes reported unexpected shutdown of JBoss server.

For those who are not familiar with the Unix environment, when the terminal hangs up (drops the connection) the operating system sends a SIGHUP signal to all the programs that are launched from that terminal.

As Sun JVM monitors for SIGHUP signal, it can be interpreted as a signal to shut down. The workaround is to add the -Xrs option when launching JBoss. This is an option of the JVM, which reduces the use of operating system signals by the Java Virtual Machine.


Installing Eclipse

Eclipse is the most popular environment for developing Java Enterprise applications. You can explore the Eclipse universe at www.eclipse.org.

The download area is reachable at http://www.eclipse.org/downloads/.

As you can see, there are several distributions available—what we suggest for your best programming experience is the Eclipse IDE for Java EE Developers. This will cost your hard disk a bit more in terms of space, but your productivity will benefit a lot from it.

Now choose the distribution that's appropriate for your OS. Once the download is complete, Windows users can simply unzip the eclipse-jee-galileo-win32.zip, while Linux users can use the tar command to uncompress the .tar.gz archive.

tar -zxvf eclipse-jee-galileo-linux-gtk.tar.gz

Unzipping the archive will create a root directory named eclipse. In that folder, you will find the Eclipse application (a big blue dot). We recommend that you create a shortcut on the desktop to simplify the launching of Eclipse.

Running Eclipse is simply a matter of executing the following command:


This command is executed from the root directory of Eclipse.

When you launch Eclipse, you'll be prompted to enter your workspace location. That's the repository where your projects are stored. If you check the option Use this as the default and do not ask again, Eclipse will not bother asking you about your workspace location every time you launch Eclipse. However, you can change it from the menu at anytime, by going to File | Switch Workspace | Other.


How much memory should I give to Eclipse?

By default, Eclipse will allocate up to 256 megabytes of Java heap memory. This should be enough for most development tasks. However, depending on the JRE that you are running, the number of additional plugins you are using, and the number of files you will be working with, you could conceivably have to customize Eclipse settings.

Open the eclipse.ini file located under the Eclipse home directory, and add the following lines before starting Eclipse:

-vmargs -Xms512m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=128m

The above configuration is suggested for a machine running 1024 MB of memory. As performance boost, you should consider also turning off some inessential options such as:

  • Uncheck the Enable Capture option in Window | Preferences | Usage Data Collector.

  • Still under Eclipse Preferences, in the Validation menu, turn on the Suspend all validators option.

  • Ignore the spell checking features by checking out the Enable spell checking option in Window | Preferences | General | Editors | Text Editors | Spelling.


Plugins: The heart of Eclipse

The most important architectural characteristics of Eclipse is the plugin architecture. A plugin in Eclipse is a component that provides a certain type of service within the context of the Eclipse workbench. The Eclipse IDE itself is built with a number of plugins, which are dependent on each other, so that you can customize your development environment exactly for your needs.

Installing JBoss Tools plugins

JBoss plugins for Eclipse are part of the JBoss suite. You can find them in the JBoss Tools project, which is an umbrella project for all the JBoss developer plugins. JBoss Tools plugins can be downloaded from:


The installation of the JBoss tools can be performed in two ways—one is directly from your Eclipse IDE, the other choice (covered in the next section) is the manual installation of single plugin files.

So, once you have started Eclipse, move onto the last menu option Help, and select Install New Software (former releases of Eclipse name this menu option Software Updates). In the upper combo box, you need to select the repository for your Eclipse plugins. JBoss Tools is not installed by default, so you need to add a link to JBoss Tools trunk. The list of available update sites can be found at http://www.jboss.org/tools/download.

Once there, select the release that matches with your Eclipse distribution. For example, if you have downloaded the Eclipse 3.5 (Galileo) release, there's a development update available at http://download.jboss.org/jbosstools/updates/development/.


For learning, it is appropriate to use a development update. However, consider sticking to a stable release of JBoss Tools for your cutting-edge software projects.

Once added, expand the JBoss Tools update site and you'll see the list of available plugins. For the purpose of this book, all you need is the JBoss AS plugin, the Hibernate plugin, and JBoss Tools RichFaces plugin.

Check them and click on the Next button, which will confirm your selections. Finish and wait for the time necessary to download the tools. Once the download is completed you will be prompted to restart Eclipse.

Installing JBoss Tools plugins manually

You can mimic the behavior of the Update Manager by installing the JBoss Tools plugins manually into your Eclipse installation.

The list of JBoss Tools plugins is available at http://www.jboss.org/tools/download.

Download the single JBoss AS plugin and Hibernate plugin zip files.

The structure of the single plugin's archive resembles the same structure of your Eclipse installation:


Once the download completes, you simply need to extract the plugins into the Eclipse installation directory.

For example, if you are using the command line and your Eclipse installation directory is named eclipse, navigate to the directory above your Eclipse installation and extract the archive using the unzip command.

 unzip JBossTools-2.1.2.GA-ALL-linux-gtk.zip


Automatic versus manual installation

Automatic installation is the easiest solution because the wizard takes care to place all the necessary files in the right place, so we recommend it for developers who are approaching Eclipse with JBoss. However, manual setup is the preferred choice if you have to perform lots of installations for your developers because you can easily create a script that simply extracts the required files on multiple partitions. Manual installation is also the preferred choice when you need to change the plugin versions because switching from one release to another merely requires a file substitution.

If you are not too confident with shell commands, you might consider a third alternative of downloading the .zip files containing the plugins, and pointing to the archive from the Software Updates menu as New Local Site.

Connecting Eclipse with JBoss

We're almost done with the configuration. The last piece of the puzzle is connecting Eclipse with our installation of JBoss. Eclipse enterprise provides some out of the box facets to manage most application servers. However, we'll use the features of JBoss Perspective , which offers a richer set of options.


What is an Eclipse perspective?

A perspective is a visual container for a set of views and editors. These components are specific to that perspective and are not shared with other perspectives. You can think about it like a page within a photo book.

Therefore, the JBoss Perspective is a special view designed specifically for JBoss AS.

You can reach it from the menu. Select Window, then Open Perspective and Other. Select JBoss AS from the next menu.

Now a tiny little panel will appear in left-corner section of the screen. This panel holds the JBoss Server View. Right-click on it and select New | Server.

You'll be guided by an intuitive wizard that will at first ask you to select the Server's host name, the JBoss Community AS release, and the Runtime Environment.


Deploy-only servers

Notice that among the available servers there's a Deploy-Only option that will simply point to the deploy directory. You can use this option if you don't need to start/stop/debug your AS, but simply deploy applications.

In the next window, you will have to complete your server configuration by adding a JBoss Runtime.

What is a Runtime Environment ? Put it simply, it is a pointer to the JBoss server installation. It provides to Eclipse all classpath information that is required for each kind of project. It also communicates to the server’s components, all the necessary information to start and stop the server.

Basically, we need to choose a Name for our environment, point to the Home Directory where JBoss AS has been unpacked, and finally select the location where JDK/JRE has been installed.


More is better

It is a good idea to create several runtime environments if you are going to test your project across different configurations. Remember to give a meaningful description to your runtime environment. For example, it's better to have a "JBoss Development" and "JBoss Production" rather than "JBoss Runtime 1" and "JBoss Runtime 2"

Once you have completed the selections, click Finish and your new runtime will be added to the list and can now be targeted by a JBoss server. Right-click on your new server icon and verify that the application server starts correctly.



In this chapter, we've completed all the required steps to set up our environment. Most of the installation process was completed using intuitive wizards and so should be accessible to inexperienced users.

Your initial configuration will be suited for an initial tour of JBoss. However, in real-world projects you may benefit from proper customization of the application server. In the next chapter, we will dissect JBoss Application Server structure.

About the Author

  • Francesco Marchioni

    Francesco Marchioni is a Red Hat Certified JBoss Administrator (RHCJA) and Sun Certified Enterprise Architect working at Red Hat in Rome, Italy. He started learning Java in 1997, and since then he has followed the path to the newest Application Program Interfaces released by Sun. In 2000, he joined the JBoss community when the application server was running the 2.X release.

    He has spent years as a software consultant, where he has envisioned many successful software migrations from vendor platforms to open source products, such as JBoss AS, fulfilling the tight budget requirements of current times.

    Over the last 10 years, he has authored many technical articles for OReilly Media and ran an IT portal focused on JBoss products (http://www.mastertheboss.com).

    Browse publications by this author
Book Title
Unlock this book and the full library for FREE
Start free trial