From: Acme Head Offices
To: Francesco Marchioni
Can you meet at 4 PM in the boardroom? We are going to interview a few guys for the new JBoss Enterprise project.
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.
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 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.
JBoss is a pure Java application server, so as you might imagine it needs a virtual machine for the Java Platform to run on.
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
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
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
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.
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 192.168.10.1 # Windows Users run.sh -b 192.168.10.1 # Unix/linux Users
Here the server is bound to the IP address 192.168.10.1.
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
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 192.168.0.1 get "jboss.system:type=Server" Started
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
shutdown -S # Windows Users ./shutdown.sh -S # Unix/Linux Users
./shutdown.sh -s jnp://remoteHost:1099 Shutdown message has been posted to the server. Server shutdown may take a while - check logfiles for completion
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.
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 -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.
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
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.
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.
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.
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:
eclipse/ features/ plugins/
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
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.
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.
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.