Before you download and run JBoss make sure you have an up-to-date version of Java on your machine. JBoss 4.0 requires either a Java 1.4 or Java 5 JVM. We recommend Java 5 for overall performance and the ability to work with the newer EJB3/Java EE 5 technologies. A full JDK install is not required to run JBoss, but you will need a full JDK to build and run the tutorial examples. Before gettings started, make sure you have an appropriate JDK installed and that your JAVA_HOME environment variable is set to the directory where you installed Java.

The JBoss application server is available as a free download from the JBoss website. (http://www.jboss.org/downloads/index) We provide both binary, source, and Web Start distributions. If you are just getting started with JBoss, the easiest way to get going is to use the Java Web Start Installer.

The binary versions are available as a .zip archive, jboss-4.0.4.zip for example. Once it's downloaded, unpack the archive to a suitable location on your machine. It should all unpack into a single directory named jboss-4.0.4. Of course the version number suffix will be different if you are running a later release. Make sure you don't use a directory which has any spaces in the path (such as the Program Files directory on Windows) as this may cause problems.

The installer versions are available as executable JAR files. The installer can also be launched using Web Start by following the Run Installer links from the JBoss AS downloads page. Follow the instructions of each page of the installer wizard and make sure you choose the All option on the Server Profile page, the configuration name default on the Configuration Name page and go ahead and select all the check boxes and then set a password for the admin account on the JMX Security page. The rest of the pages are pretty self explanatory.

Our first step is to try running the server. You'll find a bin directory inside the main JBoss directory which contains various scripts. Execute the run script (run.bat if you're on Windows, run.sh if you're on Linux, OS X, or another UNIX-like system). You should then see the log messages from all the JBoss components as they are deployed and started up. The last message (obviously with different values for the time and start-up speed) should look like the following.

13:52:00,183 INFO  [Server] JBoss (MX MicroKernel)
[4.0.4.GA (build: CVSTag=JBoss_4_0_4_GA date=200605111311)] Started in 31s:941ms

            

You can verify that the server is running by going the JBoss web server, which is running on port 8080. (Make sure you don't have anything else already on your machine using that port) The default page has links to a few useful JBoss resources.

You can get a live view of the server by going to the JMX console application at http://localhost:8080/jmx-console ^[1]. You should see something similar to Figure 1.1, “View of the JMX Management Console Web Application”.

This is the JBoss Management Console which provides a raw view of the JMX MBeans which make up the server. You don't really need to know much about these to begin with, but they can provide a lot of information about the running server and allow you to modify its configuration, start and stop components and so on.

For example, find the service=JNDIView link and click on it. This particular MBean provides a service to allow you to view the structure of the JNDI namespaces within the server. Now find the operation called list near the bottom of the MBean view page and click the invoke. The operation returns a view of the current names bound into the JNDI tree, which is very useful when you start deploying your own applications and want to know why you can’t resolve a particular EJB name.

Figure 1.1. View of the JMX Management Console Web Application

Look at some of the other MBeans and their listed operations; try changing some of the configuration attributes and see what happens. With a very few exceptions, none of the changes made through the console are persistent. The original configuration will be reloaded when you restart JBoss, so you can experiment freely and shouldn’t be able to do any permanent damage.

To stop the server, you can type Ctrl-C or you can run the shutdown script (shutdown.bat or shutdown.sh) from the bin directory. Alternatively, you can use the management console. Look for type=Server under the jboss.system domain and invoke the shutdown operation.

In a real deployment scenario, you won’t want to stop and start JBoss manually but will want it to run in the background as a service or daemon when the machine is booted up. The details of how to do this will vary between platforms and will require some system administration knowledge and root privileges.

On Linux or other UNIX-like systems, you will have to install a startup script (or get your system administrator to do it). There are examples in the JBoss bin directory called jboss_init_redhat.sh and jboss_init_suse.sh which you can modify and use. On a Windows system, you can use a utility like Javaservice ^[2] to manage JBoss as a system service.