Deploying BIRT on JBoss

Introduction

BIRT is one of the best projects I have found in the past few years. In a nutshell, it's a reporting framework that allows you to easily create visual reports (that include graphs, charts, and tables) from any Java-compatible data source (JDBC, for example).

BIRT reports are created and viewed with Eclipse. The only downside to this is that everyone who wants to view a BIRT report needs the actual report on their PC plus Eclipse installed. To get around this, BIRT has a Viewer that is able to be run from any Java EE container such as Tomcat or JBoss.

This article will cover JBoss.

Introduction
JBoss
The BIRT Viewer
Conclusion

JBoss

For this article, I used CentOS 5.5, Java 1.6, and JBoss 6.

Installing Java

Java is a prerequisite to JBoss. I downloaded the Java 1.6 JDK from its homepage. The exact file name was jdk-6u24-linux-i586-rpm.bin.

When the download finishes, run the file as a shell script:

# sh jdk-6u24-linux-i586-rpm.bin

This installs the various Java components as RPM packages.

Installing JBoss

The JBoss download page can be found here. I downloaded version 6.0 Final. The exact file name was jboss-as-distribution-6.0.0.Final.zip which contained the JBoss binaries as opposed to downloading the source and compiling it.

Once the download is finished, installation is as easy as unzipping the file and moving it to wherever you want JBoss to be installed:

# sh jdk-6u24-linux-i586-rpm.bin
# unzip jboss-as-distribution-6.0.0.Final.zip
# mv jboss-as-distribution-6.0.0.Final /usr/local/jboss

Configuring JBoss

There isn't much configuration needed for JBoss. The most important thing is to make sure the environment of the user that will run JBoss has some proper variables set. For this test installation I am just using the root user, so in /root/.bashrc, I have the following set:

# sh jdk-6u24-linux-i586-rpm.bin
export JAVA_HOME=/usr/java/jdk1.6.0_24/
export PATH=$PATH:$JAVA_HOME/bin
export JBOSS_HOME=/usr/local/jboss
export PATH=$PATH:$JBOSS_HOME/bin

Running JBoss

To start JBoss, just run the run.sh script. By default, JBoss will only listen on the localhost interface, so use the -b switch to change this:

# sh jdk-6u24-linux-i586-rpm.bin
# cd /usr/local/jboss
# ./bin/run.sh -b 192.168.255.2

Once JBoss is running, you can go to http://192.168.255.2:8080 to view the running server. There's a link to the Administration Console from this page. The authentication information for this console can be found in /usr/local/jboss/server/default/conf/props/jmx-console-users.properties.

The BIRT Viewer

Installing the BIRT Viewer

The BIRT Viewer can be downloaded from here as the Runtime package. Once it has downloaded, unzip the package and then copy the WebViewerExample directory to /usr/local/jboss/server/default/deploy as birt.war:

# sh jdk-6u24-linux-i586-rpm.bin
# unzip birt-runtime-2_6_2.zip
# cd birt-runtime-2_6_2.zip
# cp -a WebViewerExample /usr/local/jboss/server/default/deploy/birt.war

Then restart JBoss.

Once JBoss has been restarted, you can verify that the BIRT Viewer works by going to http://192.168.255.2:8080/birt.

Deploying Reports

Once the BIRT Viewer is working, you can now copy reports to the server anywhere under the /usr/local/jboss/server/default/deploy/birt.war directory and view them online through the URL http://192.168.255.2:8080/birt/frameset?__report=whatever.rptdesign. I usually put all reports under the existing /usr/local/jboss/server/default/deploy/birt.war/report directory and then access the report through http://192.168.255.2:8080/birt/frameset?__report=report/whatever.rptdesign.

Enabling JDBC Access

If the data of your reports is located in a database, you will need to install the appropriate JDBC driver for BIRT. I'll use MySQL for this example.

You can get the MySQL JDBC driver from here.

Once the download is finished, copy the mysql-connector-java-3.1.14-bin.jar file to BIRT:

# sh jdk-6u24-linux-i586-rpm.bin
# tar xzvf mysql-connector-java-3.1.14.tar.gz
# cd mysql-connector-java-3.1.14
# cp mysql-connector-java-3.1.14-bin.jar /usr/local/jboss/server/default/deploy/birt.war/WEB-INF/platform/plugin/org.eclipse.birt.report.data.oda.jdbc_2.6.2.r262_v20110127/drivers/

Note, depending on the version of BIRT being used, the actual destination directory could be different. I use the following method to find the right destination:

# sh jdk-6u24-linux-i586-rpm.bin
# find /usr/local/jboss/server/default/deploy/birt.war -iname \*jdbc\*

Conclusion

BIRT is a great package that can be used to create professional reports from almost any type of data source. Having these reports available on a central server for everyone to view is a very handy asset – especially for management departments. This article covered how to configure such a central server using JBoss and CentOS.

terrarum