In this article I illustrate how you could install and setup BlazeDS in a JBoss AS 5 application server instance. A number of new developers have difficulty installing and setting up BlazeDS in JBoss. I hope this article will provide answers to their questions and also help all those others who are seeking similar help.
First lets download and install JBoss AS 5. If you already have an instance installed then you can skip this step. If you have a prior version of JBoss (a 4.x version) installed then you could possibly avoid upgrading the installation, unless you need one of the newer features in version 5. You can read “What’s new in JBoss AS 5” to understand the new features in JBoss AS 5.
To download JBoss AS 5.1.0.GA (which is the latest stable release at the time of this writing), go to http://jboss.org/jbossas/downloads/. Once you have downloaded the distribution expand the archive file to a folder in your file system. JBoss AS is distributed in .zip and .tar.gz archive formats. If you are on windows, use the .zip distribution. Whereas, if you are on Mac OS X or Linux then get the .tar.gz version.
JBoss AS 5.1.0.GA needs JDK 6. If you don’t have JDK 6 on your machine please download and install it from http://java.sun.com/javase/6/.
Once you expand the JBoss distribution and you have the correct version of Java running on your machine, you are ready to start using JBoss. One of the thoughest things for a JBoss newbie is to understand the following:
- the JBoss directory structure
- the deployment model
- the application server configuration
- the startup and shutdown process
Therefore, in this write-up I will atttempt to explain the very basics of each of the topics in the list above and see how it applies to BlazeDS.
The JBoss AS 5.x directory structure
First look at the Figure 1 below.
Figure 1: JBoss main directory structure
The “bin” and “server” folders are what you will need most. The “bin” folder has all the executables, including those to start and stop a server. The “server” is the core of the appplication server. This is where all the application server modules are and this where you deploy your application. The BlazeDS application, that you will download shortly will be deployed in a sub-folder of this folder.
The “lib”, “client” and “common” folders have all the jar files that JBoss server and client applications may need. The “docs” folder has the documentation.
Within the “server” folder you will find the following sub-folders:
- all
- default
- minimal
- standard
- web
Each of these are built-in server profiles that you could use to deploy your application to. In most likelihood going with “default” will suffice. If none of these available server profiles are sufficient or suitable, you can also create your own custom server profile. For example I created a custom server profile called “sandbox” and started out by copying over all the contents of the “default” folder into it.
I will stick to the “default” server profile for the rest of this post and will not talk about custom server profiles for now. Within the “default” folder is a folder called “deploy”. The “deploy” folder is where you deploy an application within JBoss AS. This is a good time to download and deploy BlazeDS to show what deployment of a application in JBoss involves.
Downloading and deploying BlazeDS
Go to http://opensource.adobe.com/wiki/display/blazeds/Downloads and download the latest BlazeDS release build (which as of now is a 3.x version). BlazeDS can be downloaded either in source or binary formats. In addition, you have the option to download a BlazeDS turnkey distribution, which includes an Apache Tomcat instance and a set of sample applications that leverage BlazeDS, as a part of the distribution. I would recommend downloading the turnkey distribution to get hold of the sample applications. At the time of this writing the latest BlazeDS tunrkey release is “blazeds-turnkey-3.2.0.3978″.
Once downloaded, unzip the zipped up distribution. Once you expand the archive you will find the following “war” files in the root of the distribution:
- blazeds.war
- ds-console.war
- samples.war
Next, copy over all the three “war” files to the server/default/deploy folder. Now, you are ready to start the JBoss application server.
Starting and stopping JBoss AS
The JBoss AS “bin” folder has start and stop scripts. Scripts are available for multiple platforms, sepcially windows and the linux/unix/mac os x platforms. To start and stop a JBoss instance use “run.bat” and “shutdown.bat” on windows and “run.sh” and “shutdown.sh” on the linux/unix/mac os x platform. When using “run.bat” on Vista you may encouter problems with the script’s ability to locate findstr. Read more about this problem: Findstr Command Not Found.
Once the server starts, open up a browser instance and go to http://localhost:8080/samples to access the sample applications that come with the BlazeDS turnkey distribution. In addition, you could point your browser to http://localhost:8080/ds-console and access the administration console that helps monitor the state of your BlazeDS instance.
At this stage if you peek into your JBoss server logs you are likely to see a trace that says its unable to connect to the sampledb. The error output on the command line is as shown in Figure 2.
Figure 2 : JBoss server log snippet
To correct this problem, go to the place where you unzipped your blazeds turnkey distribution and run the “startdb” script within the “sampledb” folder.
BlazeDS is now installed and ready for use with a JBoss AS instance. More accurately you have taken the first few steps to start with more configuration and serious development. In later posts I will explain numerous configuration options around JMS, clustering, remoting and more. For now, I hope the write-up helps those who have had trouble with getting started with BlazeDS on JBoss.
