Chapter 1. Getting Started

1.1. Downloading and Installing JBoss

The JBoss application server is available as a free download from the JBoss website. (http://www.jboss.org/downloads/index) We provide both a binary and source distribution, but if you are just getting started with JBoss, stick to the binary distribution, which can be run straight out of the box.

The binary versions are available as either .zip, .tar.gz, .bz2 files. The contents are the same so grab whichever flavor is most convenient for the platform you’re running on. 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.2. 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 only additional requirement to run JBoss is to have an up-to-date version of Java on your machine. JBoss 4.0 requires at least a Java 1.4 or Java 1.5 JVM. (the JDK is no longer required to run JBoss) You should also make sure the JAVA_HOME environment variable is set to point to your JDK installation.

1.2. Starting the Server

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.

12:31:23,996 INFO  [Server] JBoss (MX MicroKernel) [4.0.2 (build: CVSTag=JBoss_4_0_2 date=
200504191712)] Started in 47s:608ms

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.

1.3. The JMX Console

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.

View of the JMX Management Console Web Application

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.

1.4. Stopping the Server

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.

1.5. Running as a Service

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.



[1] Note that on some machines, the name localhost won’t resolve properly and you should use the local loopback address 127.0.0.1 instead.

[2] Javaservice is freely available from http://www.alexandriasc.com/software/JavaService/index.html.