Home SOA & ESB JBoss ESB with JBoss Tools plugin
12 | 03 | 2010
JBoss 5 AS Book
"JBoss AS 5 development" reviews
Please share your feedback/review with other readers!
Banner
Dashboard
Advertise with Us
Banner
RSS Feed
Login
Sign here for the NewsLetter.



Poll
What book could be in your wish list next XMas ?
 
JBoss admin resources
Banner
JBoss howto

How can you solve deployment errors caused by large war/jar/ear files ?

jboss recipe of the day ...
Read More

How do you configure your .war to be deployed after your EJB ?

jboss recipe of the day ...
Read More

How do I configure a Queue/Topic to work in a cluster?

JBoss recipe of the day ...
Read More
JBoss ESB with JBoss Tools plugin
Written by F.Marchioni   

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.
jboss esb
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".

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.

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.

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 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:

jboss esb tutorial

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:


jboss esb

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();
    	
    }
    
}


As you can see from the picture below, sending a JMS message causes the interaction between the two listeners:

jboss esb

 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
Comments
Search
PrasadBSR   |2009-07-31 17:01:01
Tutorial is very much helpful. Could you please also help in setting up the
helloworld action project as well? I am having problems in configuring JNDI and
JUDDI and log4j properties.
Only registered users can write comments!

3.26 Copyright (C) 2008 Compojoom.com / Copyright (C) 2007 Alain Georgette / Copyright (C) 2006 Frantisek Hliva. All rights reserved."