This tutorial is a rewritten version of JBoss ESB tutorial: a new stable version of JBoss Tools has been released with the ESB plugin so we'll use it to set up a JBoss ESB project.

 A Bit of theory first

 As you certainly know, the word SOA has become recentely one of the most hyped in the IT. Almost everyone wants to offer a SOA as a solution to all your problems, but is it true ? well for SOA to be embraced and deliver on its promises, businesses must be able to develop and launch their services in ways that match their organizational and financial realities. 

If SOA is too expensive, complex or politically challenging, the technology won’t take off. How, then, is it possible to build an SOA that overcomes political and cost constraints? Driving an SOA strategy to success in a large organization requires a corporate-level CIO with the power to drive a vision, enforce a set of architectural goals and blueprints, and mediate financial allocations.

 To get a manageable SOA, you’ll need to start with SOA platforms that represent a relatively low investment. That’ll likely mean tools and platforms that are open source, with support and ecosystem benefits available at a low cost.

JBoss team have designed their own Service Bus: JBoss Enterprise Service Bus  is a robust SOA solution designed since the release 4.2 with build-in fail-over, load balancing and delayed message redelivery. JBossESB allows you to distribute service instances across many nodes. Each node can be a virtual or physical machine running one or more instances of JBossESB.

How the physical implementation of the architecture is achieved -however- is not fundamental: in fact many different implementations and sub-architectures could be used. So what is the fundamental concept or idea in which to work when considering SOA?

The fundamental of SOA is a unitary event bus which is triggered by receipt of a Message: a service registers with this bus to be informed when messages arrive. Next up the chain is a handler (dispatcher), that allows for sub-services (sub-components) to register for sub-documents (sub-messages) that may be logically or physically embedded in the initially received message. This is an entirely recursive architecture.

JBossESB does not impose restrictions on what constitutes a service: this allows for the implementations to change without requiring clients/users to change. Only changes to the message definitions necessitate updates to the clients.

As such, JBossESB uses a message driven pattern for service definitions and structures: clients send Messages to services and the basic service interface is essentially a single doSomething method that operates on the Message received. Internally a service is structured from one or more Actions, that can be chained together to process incoming the incoming Message. What an Action does is implementation dependent, e.g., update a database table entry, or call an EJB.

So when developing your services, you first need to determine the conceptual interface/contract that it exposes to users/consumers. This contract should be defined in terms of Messages, e.g., what the payload looks like, what type of response Message will be generated (if any) etc.

How is made up a Service in JBoss ESB?

A service in JBossESB is defined a list of Action classes that process an ESB Message in a sequential manner. This list of Action classes is referred to as an Action Pipeline. A Service can define a list of Listeners, which act as inbound routers for the Service, routing messages to the Action Pipeline.

Picture 1: Action pipeline

JBossESB supports two forms of listener configuration:
1. Gateway Listeners: These listener configurations configure a Gateway Endpoint.
These Endpoint types can be used to get messages onto an ESB bus. It is responsible for adapting the message payload by wrapping it into an ESB Message before shipping it to the Service's Action Pipeline.
2. ESB Aware Listeners: These listener configurations configure an ESB Aware Endpoint. These Endpoint types are used to exchange ESB Messages between ESB Aware components i.e. exchanging messages on the bus.
 

Step 1 : Download the ESB

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

http://www.jboss.org/downloading/?projectId=jbossesb&url=/jbossesb/downloads/4.4.GA/src/jbossesb-4.4.GA-src.zip

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:
http://www.eclipse.org/downloads/

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:
http://download.jboss.org/jbosstools/updates/nightly/trunk/
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".



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



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.


 

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.

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

;?xml version = "1.0" encoding = "UTF-8"?>
<jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd" parameterReloadSecs="5">

    <providers>
          <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>
              <jms-bus busid="quickstartEsbChannel">
                  <jms-message-filter
                      dest-type="QUEUE"
                      dest-name="queue/quickstart_helloworld_Request_esb"
                  />
              </jms-bus>

          </jms-provider>
      </providers>
      
      <services>
        <service 
        	category="FirstServiceESB" 
        	name="SimpleListener" 
        	description="Hello World">
            <listeners>
                <jms-listener name="JMS-Gateway"
                    busidref="quickstartGwChannel"
                    is-gateway="true"
                />
                <jms-listener name="helloWorld"
                              busidref="quickstartEsbChannel"
                />
            </listeners>
            <actions mep="OneWay">
                   <action name="action1" 
                   	class="org.jboss.soa.esb.samples.quickstart.helloworld.MyJMSListenerAction" 
                   	process="displayMessage" 
                   />      
        </service>
      </services>
     
</jbossesb>

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.



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 with the package org.jboss.soa.esb.samples.quickstart.helloworld.
 

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.
 

<?xml version="1.0" encoding="UTF-8"?>
<server>
  <mbean code="org.jboss.jms.server.destination.QueueService"
    name="jboss.esb.quickstart.destination:service=Queue,name=quickstart_helloworld_Request_esb"
    xmbean-dd="xmdesc/Queue-xmbean.xml">
	<depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
	<depends>jboss.messaging:service=PostOffice</depends>
  </mbean>
  <mbean code="org.jboss.jms.server.destination.QueueService"
    name="jboss.esb.quickstart.destination:service=Queue,name=quickstart_helloworld_Request_gw"
    xmbean-dd="xmdesc/Queue-xmbean.xml">
    <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
	<depends>jboss.messaging:service=PostOffice</depends>
  </mbean>
</server>

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: 
 

<jbossesb-deployment>
<depends>jboss.esb.quickstart.destination:service=Queue,name=quickstart_helloworld_Request_esb</depends> 
  <depends>jboss.esb.quickstart.destination:service=Queue,name=quickstart_helloworld_Request_gw</depends>
</jbossesb-deployment>

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

Deploy your project:

In order to deploy your project to the Service Bus all you have to do is Right-Click on your server window and choose "Add-Remove Project". Add your project to the list of deployments. Now everytime you change your project, just take care to "Republish" it, again from the server window.

The deployed archive will be packaged with the .esb extension and contains the same structure you can see in your  "esbcontent" branch , plus the Java classes. Here's an example of .esb project file:

Creating a Test Client

As you can see from your configuration file, you have two active channels which are active on your Service Bus, so you can receive Messages in two ways:
 

• sending an ESB aware message to the queue queue/eclipse_quickstart_helloworld_Request_esb. 
• sending a plain JMS message to the queue queue/quickstart_helloworld_Request_gw. 

For the purpose of this tutorial we'll see how to connect with a simple JMS message (the ESB aware message can be found in the same folder of the HelloWorld sample)
 

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

import java.util.Properties;

import javax.jms.JMSException;
import javax.jms.ObjectMessage;
import javax.jms.Queue;
import javax.jms.QueueConnection;
import javax.jms.QueueConnectionFactory;
import javax.jms.QueueSender;
import javax.jms.QueueSession;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public class SendJMSMessage {
    QueueConnection conn;
    QueueSession session;
    Queue que;
    
    
    public void setupConnection() throws JMSException, NamingException
    {
        Properties properties1 = new Properties();
		properties1.put(Context.INITIAL_CONTEXT_FACTORY,
				"org.jnp.interfaces.NamingContextFactory");
		properties1.put(Context.URL_PKG_PREFIXES,
				"org.jboss.naming:org.jnp.interfaces");
		properties1.put(Context.PROVIDER_URL, "jnp://127.0.0.1:1099");
		InitialContext iniCtx = new InitialContext(properties1);

    	Object tmp = iniCtx.lookup("ConnectionFactory");
    	QueueConnectionFactory qcf = (QueueConnectionFactory) tmp;
    	conn = qcf.createQueueConnection();
    	que = (Queue) iniCtx.lookup("queue/quickstart_helloworld_Request_gw");
    	session = conn.createQueueSession(false, QueueSession.AUTO_ACKNOWLEDGE);
    	conn.start();
    	System.out.println("Connection Started");
    }
    
    public void stop() throws JMSException 
    { 
        conn.stop();
        session.close();
        conn.close();
    }
    
    public void sendAMessage(String msg) throws JMSException {
    	
        QueueSender send = session.createSender(que);        
        ObjectMessage tm = session.createObjectMessage(msg);
        
        send.send(tm);        
        send.close();
    }
       
    
    public static void main(String args[]) throws Exception
    {        	    	
    	SendJMSMessage sm = new SendJMSMessage();
    	sm.setupConnection();
    	sm.sendAMessage(args[0]); 
    	sm.stop();
    	
    }
    
}

 In step 1, the JMS client send a raw JMS message to the queue "queue/eclipse_quickstart_helloworld_Request_gw".

The JMS listener receives the raw JMS message (step 2) and adapts the message to the ESB aware message format, but before doing this, it needs to know the endpoint of the Service. So the JMS listener first contact (step 3) the Service Registry  (that keeps track of all Service Endpoints References), then normalize the message and place in the the JMS queue "queue/eclipse_quickstart_helloworld_Request_esb"  (step 4)

When the message is placed in this queue the Service "MyJMSListenerAction" is triggered and the content of the Message is extracted and passed to the displayMessage (see step 5).

If all steps performed are successfull you should see a dump on the Server Console of the JMS message sent to the Queue.

That's all! 

Enjoy JBoss ESB !

 

JBoss.org Search

Custom Search