About This Guide

What This Guide Contains

The goal of this book is assist you in getting up and running with test applications on JBoss ESB as quickly as possible. At the time of this writing, JBoss ESB was in beta release.

Audience

This guide is anyone who is responsible for using JBoss ESB 4.0 Beta 1 installations and wants to know how to install and use it.

Prerequisites

None.

Organization

This guide contains the following chapter:

1. Chapter 1, Installation: This chapter reviews Prerequisites (software needed to operate JBoss ESB), Downloading JBoss ESB, and Building JBoss ESB.
Documentation Conventions

The following conventions are used in this guide:

Table 1 Formatting Conventions

Additional Documentation

In addition to this guide, the following guides are available in the JBoss ESB 4.0 Beta 1 documentation set:

1. JBoss ESB 4.0 Beta 1 Programmer’s Guide: Provides guidance for writing applications.

2. JBoss ESB 4.0 Beta 1 TrailBlazer Guide: Provides a guide to understanding, configuring, deploying and running the LoanBroker TrailBlazer.

3. JBoss ESB 4.0 Beta 1 Configuring Hypersonic Guide: This is necessary for setting up the Hypersonic database if you want to use it within the trailblazer.

Contacting Us

Questions or comments about JBoss ESB 4.0 Beta 1 should be directed to our support team.

Chapter 1

Installation

Overview

JBoss Enterprise Service Bus (JBoss ESB) is being maintained as source code while in beta. This will offer you, the user, the opportunity to keep current with the status of changes as made from feedback from you. Consequently, it is important for you to have the appropriate Java development environment in place.

Prerequisites

Java

Before you download and run JBoss ESB make sure you have an up-to-date version of Java on your machine. JBoss ESB requires 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 ESB, but you will need a full JDK to build and run the JBoss ESB sources and examples.

We recommend JDK version 1.5.0.06. This version is available from the Sun website.

Before getting 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.

Apache Ant

The building of JBoss ESB is enabled through the use of Apache Ant. The use of Ant will make building JBoss ESB easy.

We recommend Ant version 1.6.5. This version is available from the Apache Ant website.

Before getting started, make sure you have the appropriate version of Ant installed and that your ANT_HOME environment variable is set to the directory where you installed Ant.

In addition, if you are building JBoss ESB from the command line, put the path ANT_HOME/bin into your environment’s “path”.

PostgreSQL Database

You may certainly utilize any database platform you wish, provided it is supported by JBoss. However, subsequent steps will employ the PostgreSQL database.

We recommend PostgreSQL version 8.1.3. This version is available from the PostgreSQL website.

We have provided pg74.216.jdbc2ee.jar in the conf/lib folder and you can use that one for testing purposes.

The recommended PostgreSQL is JDBC 2 EE 8.1 Build 407. This version is available from the PostgreSQL JDBC website.

Be sure and add the full path to the PostgreSQL_HOME/bin directory to your PATH environment variable.

JBoss Application Server

Because JBoss ESB includes Enterprise Java Bean version 3 (EJB3) support, make sure you have the generally-available 4.0.4 release of JBoss Application Server (JBoss AS) installed.

JBoss Application Server (JBoss AS) is available as a free download from the JBoss website.

We recommend downloading and installing jboss-4.0.4.GA-Patch1-installer.jar. During the installation of JBoss AS, be sure and select the EJB3 radio button in order to have EJB3 support.

Caution:When JBoss AS is installed using jboss-4.0.4.GA-Patch1-installer.jar, two files required to complete the JBoss ESB installation will be missing: JBOSS_HOME / server/ default / deploy / properties-service.xml and JBOSS_HOME / server / default / lib / properties-plugin.jar. These two files will have to be restored from jboss-4.0.4.GA.zip. This file is downloadable from the JBoss website.

Before getting started, make sure you have the appropriate version of JBoss AS installed and that your JBOSS_HOME environment variable is set to the directory in which JBoss AS was installed.

Downloading JBoss ESB

JBoss Enterprise Service Bus is available as a free download from the JBoss website. This website is a subversion (svn) repository found in JBoss Labs.

See the JBoss Wiki page for instructions on accessing the JBoss SVN Repository.

We recommend using “trunk” as the root directory for your JBoss ESB installation. Check the JBoss ESB Wiki page regularly for updates.

Figure 1-1 displays the directory structure for JBoss ESB within the JBoss SVN Repository.

Figure 1-1. JBoss ESB Directory Structure

Building JBoss ESB

This section will describe building JBoss ESB from the command line, using Apache Ant. A separate document will be developed describing the use of Eclipse for this build process.

Configuring the JBossESB Environment

Having downloaded the sub-folder “trunk” from the SVN Repository, you should now have a directory structure resembling

Configuration must be performed in the “product\config” sub-folder under “trunk”.

deployment.properties

Assuming a Windows environment, and further assuming the JBoss ESB source was downloaded to C:\jboss-esb, the file deployment.properties is located in C:\jboss-esb\product\config. Open this file in your favorite editor.

Caution:Particularly in a Windows environment, ensure that deployment directories have no spaces within a path node, as this could cause problems in operation. For example, avoid “Program Files” if at all possible for any of your configuration directories.

You will notice that there are four sections to this properties file, each containing parameters for controlling the rest of the deployment for each of four major components: the JBoss Application Server, including email configuration, JBoss ESB, the database to be used for production, and the database to be used for testing.

JBoss AS Configuration

There are two characteristics you may want to change for your installation:

Parameter	Value
org.jboss.esb.appserver.home	JBOSS_HOME
org.jboss.esb.appserver.config	The name of the server configuration where JBoss ESB should be deployed

JBoss ESB Configuration

There are five characteristics you may want to change to control JBoss ESB operation:

Parameter	Value
org.jboss.soa.esb.mail.smtp.host	The name of your email server
org.jboss.soa.esb.mail.smtp.port	The port number to be used for email
org.jboss.soa.esb.mail.smtp.user	The user for logging into the email server
org.jboss.soa.esb.mail.smtp.password	The password for logging into the email server
org.jboss.esb.config.objstore	The configuration file with the details of your Object Store.

JBoss ESB Database Configuration - Production

There are six possible characteristics you may want to change to select your specific JBoss ESB Production database:

Parameter	Value
org.jboss.esb.db.driver.jar	The name of the jar file containing your database driver
org.jboss.esb.db.driver	The class name of your database driver
org.jboss.esb.db.url	The URL used by JDBC to access your database instance
org.jboss.esb.db.user	The username that must be specified to access your database
org.jboss.esb.db.password	The password that must be specified in order to access your database
org.jboss.esb.db.create.db	USED FOR HYPERSONIC ONLY. TO BE USED ONE TIME ONLY. Set to “create” to create your JBoss ESB database instance in Hypersonic. Set to “off” after the first configuration is processed.

JBoss ESB Database Configuration - Test

There are six possible characteristics you may want to change to select your specific JBoss ESB Production database:

Parameter	Value
org.jboss.esb.test.db.driver.jar	The name of the jar file containing your database driver
org.jboss.esb.test.db.driver	The class name of your database driver
org.jboss.esb.test.db.url	The URL used by JDBC to access your database instance
org.jboss.esb.test.db.user	The username that must be specified to access your database
org.jboss.esb.test.db.password	The password that must be specified in order to access your database

Once you have saved your changes to deployment.properties, you should open a command window and change directories to C:\jboss-esb\product\config:

If ANT_HOME\bin has not been added to your PATH environment variable, type %ANT_HOME%\bin\ant configure.jboss to start the process.

If ANT_HOME\bin has been added to your PATH environment variable, type “ant configure.jboss” to start the process.

This operation will result in the following operations being performed:

Ø The jar file containing your database JDBC driver copied to the lib folder under your specified JBoss AS server configuration

Ø The properties-plugin.jar copied to the lib folder under your specified JBoss AS server configuration

Ø The jbossEsb.properties file copied to the conf folder under your specified JBoss AS server configuration (update with your email and objStore configurations)

Ø properties-service.xml copied to the deploy folder under you specified JBoss AS server configuration

Be sure and review the output from the process to ensure no errors occurred.

Building the Jars and Deploying the EAR to JBoss AS

After the configuration operation outlined above, change directories to the parent folder (JBESB_HOME\product).

Assuming ANT_HOME\bin has not been added to your PATH environment variable, type %ANT_HOME%\bin\ant deploy to start the process.

Assuming ANT_HOME\bin has been added to your PATH environment variable, simply type “ant deploy” to start the process.

This operation will result in all jar files being created in the build\dist\lib subfolder:

jbossesb-appl.ear

jbossesb-common.jar

jbossesb-listeners.jar

jbossesb-processors.jar

jbossesb-services.jar

jbossesb-appl.ear will be copied to the deploy folder under you specified JBoss AS server configuration.

Be sure and review the output from the build process to ensure no errors occurred.

Creating the JBoss ESB Database

Assuming a Windows environment, and further assuming the JBoss ESB source was downloaded to C:\jboss-esb, open a command window and change directories to C:\jboss-esb\product\docs\Install\database:

The database to be created is named rosetta. The script for performing this operation is JBossESB-DB-postgres.sql.

To execute this script and create the database for JBoss ESB, type

psql -U postgres -f JBossESB-DB-postgres.sql

To verify the database creation was successful, type

psql –U postgres jbossesb

You should receive a prompt from PostgresSQL: jbossesb-#.

At this prompt, type

This will list all databases for your server.

Again, at the PostgresSQL prompt, type

\dt

This will list the tables for your JBoss ESB database:

Provided your display approximates this illustration, your JBoss ESB database is ready for use.

You are now prepared to start JBoss AS as you normally would.

A Simple Standalone Test Example

This is a simple standalone test application to realize a simple file copying use-case while also verifying that the bus is configured correctly for standalone as well as JBoss Application Server usage. Note this example mostly runs outside the JBoss AS in a standalone fashion however all notifications that occur within the JBossESB are sent in a distributed manner via EJBs, as such this portion will utilize the JBoss AS.

Scenario

The premise of this example is to simply poll a directory of your choosing for files with an extension (suffix) of *.inp and once found it will invoke the FileCopier class and copy the file to a different directory of your choosing while also changing the suffix of the file.

Configuration

For this test example, all configuration settings can be found within the following file:

FileMoverConfigExample.xml

Located within the directory of:

<ESB_HOME>/docs/samples/TestJBossESB/paramsDir

<ESB_HOME> is the directory where the JBoss ESB was extracted.

Below is an outline of this file:

A couple of quick changes to this file and you will up and running.

For the test example we will change a couple of entries within this configuration file. There are a total of five directory paths that need to be changed to match your local environment. Below is a description of these entries. Please change these entries to match the path within your local environment such that each entry reflects the absolute path to each directory.

For example if your <ESB_HOME> is 'c:\dev\jbossesb' then the inputDirURI directory would be configured as such:

inputDirURI=”file:///c:/dev/jbossesb/docs/samples/TestJBossESB/inputDir”

Parameter	Value
inputDirURI	This is the directory that the test example will poll for a file with an extension of *.inp - change this directory to the directory reflecting your environment
postDirURI	Once the application has completed processing via the action class, the file will be copied to this directory due to the use of the FileCopier action class
errorDirURI	This represents the directory that will receive error output if the denoted action class encounters an error
copyToURI	This is the directory whereby the file from the inputDirURI is copied and will show up with a file extension (suffix) of *.outFile

Once all these entries are configured per your environment you are ready to run the example. For simplicity sake, it is recommended that you work with the predefined directory structure that is pre-existing within the JBoss ESB distribution under the samples directory.

Running the Simple Test Application

Depending on your operating system edit one of the two convenience files located within the <ESB_HOME>\docs\samples directory; either testJBossESB.bat or testJBossESB.sh. The purpose of this edit is to properly set the following entries:

Ø ESB_HOME

Ø JBOSS_HOME

Ø JAVA_HOME (testJBossESB.sh only)

Once set, from the command line navigate to the directory housing the testJBossESB convenience file (<ESB_HOME>/product/docs/samples/TestJBossESB).

Execute “testJBossESB” from the command line.

Working with the Test Example

Based on the above configuration file, this example is polling the directory denoted by the entry of inputDirURI for a file with a suffix denoted by the entry of inputSuffix. If a file is found within the directory the file suffix is changed to reflect the workSuffix entry. This working suffix is the suffix that will denote the file is being processed by the denoted actionClass, in this test example the FileCopier action class.

The FileCopier will copy this file to directory noted within the copyToDirURI with a suffix denoted within the copyToSuffix.

Depending on the outcome, in this case either type=”OK” or type=”err” the entries within the <NotificationList> are executed. A Notification List can have multiple entries, in this example there is one entry, a <target>, for both the happy path of type=”OK” or a <target> for when an error is encountered during the processing phase executed within the actionClass.

For type=”OK” in which the file is successfully copied to the copyToDirURI directory, the NotifyFiles target is called. This target will optionally append a message to the file denoted within the URI attribute. All options are denoted as attributes within the <File> child entry of the <target>. Likewise the same will occur for the error path of type=”err”.