The Source for Java Technology Collaboration
User: Password:
Register | Login help    



   
E-mail    Print    Discuss    Blog

JBoss At Work, Part 1: Installing and Configuring JBoss JBoss At Work, Part 1: Installing and Configuring JBoss

by Tom Marrs and Scott Davis
03/01/2005

Contents
What is an Application Server?
Installing JBoss
Running JBoss
Exploring the Directory Structure
Server Configurations
Configuring JBoss Services
Deploying Applications to JBoss
Summary

Editor's note: Tom Marrs and Scott Davis are currently finishing up their book JBoss At Work: A Practical Guide. The book will be available this summer from O'Reilly. In the meantime, they have written this series of articles that will make it easy to get up and running with JBoss if you are new to writing J2EE 1.4 applications, new to JBoss, or both.

JBoss is a popular J2EE application server. Several recent surveys put its market share at above 30 percent and single it out as the only application server whose market share is on the rise. JBoss is standards-compliant and a free download, making it an attractive choice whether you are running a production-quality site or looking for a learning tool.

The title of this article series, "JBoss At Work: A Practical Guide," is inspired by the authors' experience as back-to-back presidents of the Denver Java Users Group. In our time running the group, the most common refrain we heard was, "I don't want to be an expert in it--I just want to make it work." It didn't matter what technology or API we were talking about at the time; the comment was always the same.

This sentiment reflects the busy schedules and tight deadlines that most working professionals face. Digging through a 1,000-page book on each new technology that comes down the pike is, quite simply, a luxury that few of us can afford. Our goal is to get you up and running in JBoss as quickly as possible.

In this, the first of three articles, we show you how to download and install JBoss. We explore the directory structure and show you how to add and remove services. Finally, we show you how to deploy an application to JBoss.

The second article in the series introduces the different parts of a J2EE application. We show you how JSPs and servlets fit into the application. We show you how they interact with EJBs. We show you how to use XDoclet and Ant to generate key configuration files and create an EAR (Enterprise ARchive) suitable for deployment.

The third article focuses on web services. We take the application from the second article and wrap the existing functionality in web services. XDoclet once again comes into play, making it almost trivial to expose your application's functions as web services. We create SOAP (Simple Object Access Protocol) clients to consume the web services from both a servlet and the command line.

But before we can get to any of those advanced topics, we need to start at the very beginning.

What is an Application Server?

As you well know, compiled Java code cannot run on its own--it must be run inside of a JVM. J2EE classes require an additional step: they must be run inside of a J2EE container (which in turn runs inside of a JVM). The container provides an infrastructure and a framework in which your code runs. It handles the mundane low-level "plumbing" aspects of the application, freeing you to focus on the higher-level business development. An application server is nothing more than a loosely coupled collection of containers (or "services") that correspond to the various parts of the J2EE API.

The beauty of the J2EE is that it is a specification, not an implementation. In other words, Sun provides the technical guidelines for how each service should behave, but leaves it open for anyone to write a server that can host a J2EE application. This gives you, the developer, a wide variety of choices when it comes to selecting an application server. While the details of how to deploy a J2EE application may vary from server to server, you can rest assured that your compiled code will behave the same way regardless of the application server it is running in.

JBoss is an open source J2EE application server. It is J2EE 1.4 spec-compliant, which means that it offers the same level of functionality as its more expensive commercial counterparts. What this means to you is that the lessons learned here will be largely useful, regardless of the application server you are currently using. The most important thing to keep in mind is that cost does not equal value or reliability. The open source Apache web server runs more than two-thirds of all web sites today. JBoss isn't quite at that level of pervasiveness, but it shouldn't be ignored when considering enterprise-quality application servers just because it is free.

Installing JBoss

The latest JBoss release, 4.0.1, requires Java 1.4 or higher. Be sure that you have the 1.4 SDK (Software Development Kit) installed and not just the JRE (Java Runtime Environment). JBoss uses the compiler in the SDK to compile your JSP pages on the fly, among other things. To verify the version of Java you have installed, type java -version at a command prompt. Make sure that you have the SDK installed by typing javac at a command prompt. If necessary, go to Sun's web site for the latest JDK and installation instructions.

Once your Java environment is in place, you can go to the JBoss web site to download the application server. As you can see, there are a number of projects hosted at this site. Our focus is on the first one in the list, JBoss AS.

Since JBoss is written in Java, it can be run on any platform that has a working JVM. The download page has a long list of files archived in a variety of formats (.zip, .tar.gz, .bz2). The only difference between them is the utility used to bundle them up--there isn't a platform-specific JBoss distribution. Whichever one you download will work on Windows, Linux, Mac OS X, or any of the various flavors of Unix.

The current release is about 65MB, so make sure that you have a fast Internet connection or a lot of time on your hands. Don't download the source ("src") or the release candidate ("RC") bundles--look for the ones named jboss-4.0.1.*. Download one of them and unzip it to the directory of your choice. (For best results, avoid directory names with spaces in them like Program Files.) Create an environment variable called JBOSS_HOME that points to the directory.

There are no installation scripts to run. At this point, you are ready to fire up JBoss and take a look around.

Running JBoss

To start JBoss, change to the JBOSS_HOME/bin/ directory and type run (run.bat on Windows, run.sh on Linux/Mac OS X/Unix). You should see a long stream of output similar to the abbreviated version shown in Figure 1.

Figure 1
Figure 1. JBoss initialization output

Not surprisingly, the output shows the step-by-step process JBoss goes through when starting up. The first thing JBoss does is look for key environment variables such as JBOSS_HOME. It then begins booting the microkernel, the core JBoss process. Once the core is in place, it begins loading the individual J2EE services. After the services are loaded, JBoss deploys all WAR (Web ARchive) and EAR files it finds in the deploy/ directory. (More on this in just a moment.) JBoss is fully up and running when it reports Started in XXs:YYms.

Any service that can't be started will throw an exception during this process. One of the most common problems is trying to use default port assignments that conflict with applications already running on the system. For example, Tomcat comes bundled with JBoss. If you already have a running instance of Tomcat using the default ports (8005 and 8080), you will see a stream of errors in the console output from the embedded Tomcat instance, and it will fail to start. You'll learn how to change those ports after we get to know the directory structure.

Exploring the Directory Structure

There are a number of subdirectories under JBOSS_HOME (see Figure 2), but the two most important to the typical J2EE developer are the bin/ and server/ directories. The bin/ directory contains the startup and shutdown scripts for JBoss, and server/ contains the directories where we will eventually deploy our applications. The others are of secondary importance to us.

Figure 2
Figure 2. The JBoss directory structure

The client/ directory contains JARs used by remote clients. (We discuss remote clients in the third article of this series.) The docs/ directory contains various license and example files. The lib/ directory contains the core JBoss JARs.

You've already had a chance to look around the bin/ directory. The rest of this article focuses on the contents of the server/ directory.

Server Configurations

We said earlier that an application server is a collection of J2EE services. JBoss makes it easy to mix and match these services by grouping them in a directory structure called a Server Configuration. If you look in the JBOSS_HOME/server/ directory, you should see three named Server Configurations: all, default, and minimal.

If you don't specify a configuration on boot, JBoss uses the default configuration. The default configuration is the one that fulfills the J2EE 1.4 spec, so it is a reasonable place for most developers to start. The minimal configuration is bare dirt--nothing but a JNDI and a Log4j service. All is at the opposite end of the spectrum--everything in the minimal and default configurations, plus advanced services like clustering.

Let's shut down JBoss and start it with a different configuration. Press Ctrl-C in the JBoss console window to shut it down. Now type run -c minimal. You should see far fewer services launch and a dramatically shorter startup time.

It is easy to create your own Server Configuration. Simply copy one of the existing directory trees and give it a new name. For example, copy the default/ directory to a new one named myapp/. Now start JBoss using the new configuration--press Ctrl-C to stop the currently running configuration, and then type run -c myapp.

Configuring JBoss Services

A server configuration has three main subdirectories: conf/, deploy/, and lib/. The conf/ directory, as you might guess, contains configuration files. The main config file is jboss-service.xml. This is one place (but not the only place) where settings like port numbers can be found. The lib/ directory contains the JAR files that make up the JBoss services. The deploy/ directory contains the J2EE services, as well as any WAR and EAR files that should be deployed.

Services can be added and removed from a running JBoss instance through the magic of JMX (Java Management eXtensions). JMX is a framework that allows you to interact with live, running code. You can start and stop services, gather metrics, and even change parameters on the fly.

Services that implement the JMX interface are called "managed beans," or MBeans. Each of the J2EE services that run inside of JBoss is an MBean. (For more details on JMX, see this tutorial.)

To see JMX in action, open a new terminal window next to the JBoss console, change to JBOSS_HOME/server/myapp/deploy, and create an undeploy/ directory. (It can be named anything you'd like, but undeploy/ is a common choice.) Move hsqldb-ds.xml to the undeploy/ directory and watch the JBoss console. You should see the Hypersonic database service shut down and all of the related services reconfigure themselves. Now move the file back from the undeploy/ directory to the deploy/ directory. Once again, JBoss recognizes the change in configuration and adjusts itself accordingly.

The XML file defining the MBean is another good place to look for port numbers. For instance, if you look at hsqldb-ds.xml, line 16 shows the port number that Hypersonic is configured to use.

Complex MBeans that require more than a simple XML file and a JAR in the lib/ directory can be deployed as a SAR (Service ARchive). Tomcat is a good example of this. Change to the jbossweb-tomcat50.sar/ directory, and you'll find the traditional server.xml file used to configure Tomcat, along with all of its dependent libraries. (Tomcat ports can be changed here.)

Deploying Applications to JBoss

Your applications are deployed to the same directory as the MBeans. JBoss treats them as equals.

J2EE applications are generally bundled up as EARs or WARs. While each of these is technically nothing more than a simple JAR file, they have special internal directory structures and configuration files that must be present for the sake of the application server. (We discuss EARs and WARs in the next article in this series.)

Download test.war from here and copy it to the deploy/ directory. In the JBoss console window, you should see the test application being deployed. Open a web browser and go to http://localhost:8080/test (see Figure 3).

Figure 3
Figure 3. A custom application deployed to JBoss

If you move test.war to the undeploy/ directory, JBoss will dynamically unload it, just as it did Hypersonic earlier. You don't have to do anything special to your application to gain this level of functionality--JBoss does it for you automagically.

Summary

This was a whirlwind introduction to J2EE and JBoss. We downloaded and installed JBoss. We described the JBoss directory structure and how to start and stop the server. Finally, we deployed and undeployed both JBoss services and custom applications.

Next time, we'll introduce you to the basic pieces of a J2EE application and show you how to stick it in your EAR. (EAR file, that is.) Until then, have a great time using JBoss at work or on your open source project.

Tom Marrs is the principal and senior software architect at Vertical Slice, a consulting firm that designs and implements mission-critical business applications using the latest J2EE and open source technologies, along with providing architecture evaluation and developer training and mentoring services.

Scott Davis is a senior software engineer and instructor in the Denver, Colorado area.

View all java.net Articles.

 Feed java.net RSS Feeds
Feedback  | FAQ  | Press | Terms of Use
Privacy  |  Trademarks | Site Map
 
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Participation.
 
Copyright © 1995-2008 Sun Microsystems, Inc.
Oreilly LogoCollabnet Logo
Powered by Sun Microsystems, Inc.,
O'Reilly and CollabNet