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



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

    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 likeProgram Files.) Create an environment variable calledJBOSS_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 underJBOSS_HOME (see Figure 2), but the two most important to the typical J2EE developer are the bin/ andserver/ 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 theserver/ 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 theJBOSS_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 thedefault configuration. The defaultconfiguration is the one that fulfills the J2EE 1.4 spec, so it is a reasonable place for most developers to start. Theminimal 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 anddefault 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 namedmyapp/. Now start JBoss using the new configuration--pressCtrl-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 toJBOSS_HOME/server/myapp/deploy, and create anundeploy/ directory. (It can be named anything you'd like, but undeploy/ is a common choice.) Move hsqldb-ds.xmlto 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 athsqldb-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 thejbossweb-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 thedeploy/ 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.


    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. (EARfile, that is.) Until then, have a great time using JBoss at work or on your open source project.