Chapter 4. Services and Messages

4.1. Services

4.1.1. Service

A service is a list of action classes that process an ESB Message in a sequential manner. Each service element consists of one or more listeners and one or more actions. These are set within the jboss-esb.xml configuration file.

4.1.2. Action Pipeline

The action pipeline consists of a list of action classes through which messages are processed. Use it to specify which actions are to be undertaken when processing the message. Actions can transform messages and apply business logic to them. Each action passes the message on to the next one in the pipeline or, at the conclusion of the process, directs it to the end-point listener specified in the ReplyTo address.
The action pipeline works in two stages: normal processing followed by outcome processing. In the first stage, the pipeline calls the process method(s) on each action (by default it is called "process") in sequence until the end of the pipeline has been reached or an error occurs. At this point the pipeline reverses (the second stage) and calls the outcome method on each preceding action (by default it is processException or processSuccess). It starts with the current action (the final one on success or the one which raised the exception) and travels backwards until it has reached the start of the pipeline.

4.1.3. ESB-Awareness

If application clients and services are referred to as being ESB-aware, this means that they can understand the message format and transport protocols used by the SOA Platform's enterprise service bus.

4.1.4. Message Listeners

Message listeners encapsulate the communications end-points needed to receive SB-aware messages. Listeners are defined by services and their role is to monitor queues. They receive any messages as they land in those queues. When a listener receives a message, the ESB server calls the appropriate action class defined in the action definition. The methods in this class process the message. In other words, listeners act as inbound routers, directing messages to the action pipeline. When the message has been modified by the actions on the pipeline, the listener sends the result to the replyTo end-point.
You can configure various parameters for listeners. For instance, you can set the number of active worker threads.
There are two types of listeners: ESB-aware listeners and gateway listeners. Gateway listeners are different from ESB-aware listeners in that they accept data in different formats (such as objects in files, SQL tables and JMS messages). They then convert them from these formats to the ESB messaging format. By contrast, ESB-aware listeners can only accept messages that are in the org.jboss.soa.esb.message.Message format. Each gateway listener must have a corresponding ESB listener defined.
With ESB-aware listeners, RuntimeExceptions can trigger rollbacks. By contrast, with a gateway listener, the transaction simply sends the message to the JBoss ESB. The message is then processed asynchronously. In this way, message failures are separated from message receipts.

4.1.5. ServiceInvoker

The ServiceInvoker (org.jboss.soa.esb.client.ServiceInvoker) manages the delivery of messages to the specified Services. It also manages the loading of end-point references and the selection of couriers, thereby providing a unified interface for message delivery.
The ServiceInvoker was introduced to help simplify the development effort as it hides much in the way of the lower-level details and works opaquely with the stateless service fail- over mechanisms. As such, ServiceInvoker is the recommended client-side interface for using services within the JBoss Enterprise SOA Platform.
You can create an instance of the ServiceInvoker for each service with which the client interacts. Once created, an instance examines the registry to determine the primary end-point reference and, in the case of fail-overs, any alternative end-point references.

4.1.6. InVM Transport

The InVM ("intra-virtual machine") Transport provides communication between services running on the same JVM.

4.1.7. Creating Your First Service

Here is a very simple JBoss ESB configuration that defines a single Service that outputs the contents of a message to the console.
<?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">

<services>
    <service category="Retail" name="ShoeStore" description="Acme Shoe Store
Service" invmScope="GLOBAL">
        <actions>
            <action name="println"
class="org.jboss.soa.esb.actions.SystemPrintln" />
        </actions>
     </service>
</services>

</jbossesb>
A service has “category” and “name” attributes. When the JBoss ESB deploys the service, it uses these attributes to register the listeners in the Service Registry. Clients can then invoke the service using the ServiceInvoker as per this next sample:
ServiceInvoker invoker = new ServiceInvoker(“Retail”, “ShoeStore”);
Message message = MessageFactory.getInstance().getMessage();

message.getBody().add(“Hi there!”);
invoker.deliverAsync(message);
The ServiceInvoker uses the Services Registry to look up the available endpoint addresses for the Retail:ShoeStore service. The registry automatically handles the process of sending the message from the client to one of the available endpoints. The process of transporting the message is completely transparent to the client.
The end point addresses made available to the ServiceInvoker will depend on the list of listeners configured on the Service such as JMS, FTP or HTTP. No listeners are configured on the service in the above example, but its InVM listener has been enabled using invmScope="GLOBAL"1. To add additional endpoints to the service, you must add them explicitly.

4.1.8. Types of Message Listener

There are two types of message listener:
Gateway Listener
This type of listener configure a gateway endpoint, which is used to push ESB-unaware messages into an ESB bus. It changes the message into a form the ESB can understand by wrapping it inside an ESB Message before sending it to the action pipeline.
ESB-Aware Listener
This type of listener creates an “ESB Aware” endpoint and is used to exchange ESB Messages between ESB-aware components.

4.1.9. Gateway Listener

A gateway listener is used to bridge the ESB-aware and ESB-unaware worlds. It is a specialized listener process that is designed to listen to a queue for ESB-unaware messages that have arrived through an external (ESB-unaware) end-point. The gateway listener receives the messages as they land in the queue. When a gateway listener "hears" incoming data arriving, it converts that data (the non-ESB messages) into the org.jboss.soa.esb.message.Message format. This conversion happens in a variety of different ways, depending on the gateway type. Once the conversion has occurred, the gateway listener routes the data to its correct destination.

4.1.10. Adding a Gateway Listener to a Service

This code demonstrates how to add a JMS Gateway listener to a service.
<?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">
<providers>
    <jms-provider name="JBossMQ" connection-factory="ConnectionFactory">
        <jms-bus busid="shoeStoreJMSGateway">
            <jms-message-filter dest-type="QUEUE" dest-name="queue/shoeStoreJMSGateway"/>
        </jms-bus>
    </jms-provider>
</providers>

<services>
    <service category="Retail" name="ShoeStore" description="Acme Shoe Store Service"             
                                                                   invmScope="GLOBAL">
<listeners>
    <jms-listener name="shoeStoreJMSGateway" busidref="shoeStoreJMSGateway" 
                  is-gateway="true"/>
</listeners>
        <actions>
            <action name="println" class="org.jboss.soa.esb.actions.SystemPrintln" />
        </actions>
     </service>
</services>

</jbossesb>
Observe that a bus <providers> section has been added to the configuration. Here you can configure the transport level details for endpoints. In this case, a <jms-provider> section has been added. Its purpose is to define a single <jms-bus> for the Shoe Store JMS queue. This bus is then referenced in the <jms-listener> defined on the Shoe Store Service. The Shoe Store is now "invocable" via the InVM and JMS Gateway endpoints. (The ServiceInvoker always prefers to use a service's local InVM endpoint if one is available.)