Creating a sample JBoss ESB Project


Step 1 : Download the ESB

Ok, now let's get our hands dirty: at first download the latest ESB from jboss site:

The jbossesb-server binary distribution is a pre-configured profile based on the JBoss Microkernel architecture. The ESB Server comes pre-installed with JBoss Messaging, JBoss Webservices, all of the base ESB capabilities and is the best choice for those who want to get started quickly.

Step 2: Install JBoss ESB plugin on Eclipse

For our example we have installed Eclipse IDE for Java Developers (Ganymede) which is the Enterprise Version of Eclipse foundation: check it here:

Once you have extracted Eclipse you need to update your plugins: from the Help Menu, select "Software Updates". In the "Available Software" Click on "Add site" and add JBoss plugins site:
Here there's a whole lot of plugins, however what you need is basically JBoss AS plugin and JBoss ESB plugin. Once installed you have to restart Eclipse.

Step 3: Create a new ESB Project from Eclipse:

If everything was correctly installed you should see from the Menu the Option "New-->ESB-->ESB Project".

jboss esb tutorial

Choose a conveniente project name, select the ESB version (for this sampple 4.4) and click on New button in the "Target Runtime" option. This will introduce on the next window where you choose the Home of your ESB

jboss esb tutorial

Browse to your ESB Home. Once you're done with this, click on "Done". This will bring you back to the "New ESB Project" window.
Click on the Next button and check on the "Install ESB Facet" window that you have selected "Server supplied ESB Runtime". Click on "Finish" and you're done with the configuration.

jboss esb tutorial

Step 4: Design your ESB project

At the beginning you have an empty project with "esbcontent" folder where you store your project configuration. The main configuration file of JBoss ESB is jboss-esb.xml. A blank version is provided under META-INF.

<?xml version = "1.0" encoding = "UTF-8"?>

        <jms-provider name="JBossMQ" connection-factory="ConnectionFactory">
            <jms-bus busid="quickstartGwChannel">
                <jms-message-filter dest-type="QUEUE"
                    dest-name="queue/quickstart_helloworld_Request_gw" />
            <jms-bus busid="quickstartEsbChannel">
                <jms-message-filter dest-type="QUEUE"
                    dest-name="queue/quickstart_helloworld_Request_esb" />


        <service category="FirstServiceESB" name="SimpleListener"
            description="Hello World">
                <jms-listener name="JMS-Gateway" busidref="quickstartGwChannel"
                    is-gateway="true" />
                <jms-listener name="helloWorld" busidref="quickstartEsbChannel" />
            <actions mep="OneWay">
                <action name="action1"
                    process="displayMessage" />


We'll install the HelloWorld sample from the distribution. At first paste into jboss-esb.xml the following configuration:

The plugin has a nice graphical editor which is visible in the Outline window. As you can see the configuration file is immediately converted into a tree view of the Service.

jboss esb tutorial

This configuration of every ESB service is divided into two main sections: the first section is the JMS provider configuration where you can find 2 configuration filters: one for the quickstartGwChannel and the other for the quickstartEsbChannel.

The second section describes the service itself and the listeners : as you can see there are
also 2 types of listeners: a pure JMS Gateway listener and a ESB aware Listener.

 As said before the JMS gateway listener is responsible for carrying the message to the ESB (adapting them to the ESB "style") while the ESB Aware listener is used to exchange message to ESB aware components.

The service itself boils down to a set of actions which are fired when one of the listener is activated. Since the listener for this service are JMS listeners, when a message is sent to the registered Queues the actions are fired.

The only action of this example is the "displayMessage" which recalls a Java class passing as argument the Message JMS itself. Add a new Java class to your project named MyJMSListenerAction:

package org.jboss.soa.esb.samples.quickstart.helloworld;

import org.jboss.soa.esb.actions.AbstractActionLifecycle;
import org.jboss.soa.esb.helpers.ConfigTree;
import org.jboss.soa.esb.message.Message;

public class MyJMSListenerAction extends AbstractActionLifecycle

    protected ConfigTree    _config;

    public MyJMSListenerAction(ConfigTree config) {
        _config = config;

    public Message displayMessage(Message message) throws Exception{

        System.out.println("Body: " +message.getBody().get());          
        return message;



This action does simply a dump of the JMS message which enters the Service Bus.

In order to complete our configuration we need just two more configuration files: jbm-queue-service.xml which contains the MBeans necessary to deploy the JMS queues to the service bus. This file needs to be created on the root of your project.

Finally we need a file which specifies the resources this esb archive depends on : this file is deployment.xml and needs to be placed into the META-INF folder: 


Finally the jbm-queue-service.xml where the Queues are defined:

<?xml version="1.0" encoding="UTF-8"?>
 <mbean code="org.jboss.jms.server.destination.QueueService"
   <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
 <mbean code="org.jboss.jms.server.destination.QueueService"
   <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>

Ok. now your ESB project is ready to rumble! Check that your project looks like this in your Project Explored window:

jboss esb tutorial