Programmers Guide

The next diagram illustrates how transformation can be injected into the same scenario using JBossESB.

In the next series of examples, we use a queuing system (e.g., a JMS implementation).

The diagram below shows transformation and queuing in the same situation.

JBossESB can be used in more than multi-party scenarios. For example, the diagram below shows basic data transformation via the ESB using the file system.

The final scenario is again a single party example using transformation and a queuing system.

In the following chapters we shall look at the core concepts within JBossESB and how they can be used to develop SOA-based applications.

There are many reasons why users may want disparate applications, services and components to interoperate, e.g., leveraging legacy systems in new deployments. Furthermore, such interactions between these entities may occur both synchronously or asynchronously. As with most ESBs, Rosetta was developed to facilitate such deployments, but providing an infrastructure and set of tools that could:

To date, Rosetta has been used in mission critical deployments using Oracle Financials. The multi platform environment included an IBM mainframe running z/OS, DB2 and Oracle databases hosted in the mainframe and in smaller servers, with additional Windows and Linux servers and a myriad of third party applications that offered dissimilar entry points for interoperation. It used JMS and MQSeries for asynchronous messaging and Postgress for object storage. Interoperation with third parties outside of the corporation’s IT infrastructure was made possible using IBM MQSeries, FTP servers offering entry points to pick up and deposit files to/from the outside world and attachments in e-mail messages to ‘well known’ e-mail accounts.

As we shall see when examining the JBossESB core, which is based on Rosetta, the challenge was to provide a set of tools and a methodology that would make it simple to isolate business logic from transport and triggering mechanisms, to log business and processing events that flowed through the framework and to allow flexible plug ins of ad hoc business logic and data transformations. Emphasis was placed on ensuring that it is possible (and simple) for future users to replace/extend the standard base classes that come with the framework (and are used for the toolset), and to trigger their own ‘action classes’ that can be unaware of transport and triggering mechanisms.

In the following chapters we shall look at the various components within JBossESB and show how they interact and can be used to develop SOA-based applications.

Each message is an implementation of the org.jboss.soa.esb.message.Message interface. Within that package are interfaces for the various fields within the Message as shown below:

public interface Message

{

    public Header getHeader ();

    public Context getContext ();

    public Body getBody ();

    public Fault getFault ();

    public Attachment getAttachment ();

    public URI getType ();

    public Properties getProperties ();


    public Message copy () throws Exception;

}

The Header contains routing and addressing information for this message. As we saw earlier, JBossESB uses an addressing scheme based on the WS-Addressing standard from W3C. We shall discuss the org.jboss.soa.esb.addressing.Call class in the next section.

public interface Header

{

    public Call getCall ();

    public void setCall (Call call);

}

The Context contains session related information, such as transaction or security contexts.

The Body typically contains the payload of the message. It may contain a list of Objects of arbitrary types. How these objects are serialized to/from the message body when it is transmitted is up to the specific Object type.

public interface Body

{

  public static final String DEFAULT_LOCATION = 

  "org.jboss.soa.esb.message.defaultEntry";


    public void add (String name, Object value);

    public Object get (String name);

    public byte[] getContents();

    public void add (Object value);

    public Object get ();

    public Object remove (String name);

    public void replace (Body b);

    public void merge (Body b);

  public String[] getNames ();

}

A Body can be used to convey arbitrary information types and arbitrary numbers of each type, i.e., it is not necessary to restrict yourself to sending and receiving single data items within a Body.

The Fault can be used to convey error information. The information is represented within the Body.

public interface Fault
{
	public URI getCode ();
	public void setCode (URI code);
	
	public String getReason ();
	public void setReason (String reason);
	
	public Throwable getCause ();
	public void setCause (Throwable ex);
}

A set of message properties, which can be used to define additional meta-data for the message.

public interface Properties

{

    public Object getProperty(String name);

    public Object getProperty(String name, Object defaultVal);

    

    public Object setProperty(String name, Object value);

    public Object remove(String name);

    

    public int size();

    public String[] getNames();

}

Messages may contain attachments that do not appear in the main payload body. For example, imagines, drawings, binary document formats, zip files etc. The Attachment interface supports both named and unnamed attachments.

public interface Attachment

{

    Object get(String name);

    Object put(String name, Object value);

    

    Object remove(String name);

    

    String[] getNames();

    

    Object itemAt (int index) throws IndexOutOfBoundsException;

    Object removeItemAt (int index) throws IndexOutOfBoundsException

    Object replaceItemAt(int index, Object value)

    throws IndexOutOfBoundsException;

    

    void addItem        (Object value);

    void addItemAt  (int index, Object value)

                                    throws IndexOutOfBoundsException;

    public int getUnnamedCount();

    public int getNamedCount();

}

Attachments may be used for a number of reasons (some of which have been outlined above). At a minimum, they may be used to more logically structure your message and improve performance of large messages, e.g., by streaming the attachments between endpoints.

Given that there are attachments, properties, and named objects, you may be wondering where should you put your payload? The answer is fairly straightforward:

The relationship between the Header and the various EPRs can be illustrated as follows in UML:

When working with Messages, you should consider the role of the header when developing and using your clients and services. For example, if you require a synchronous interaction pattern based on request/response, you will be expected to set the ReplyTo field, or a default EPR will be used; even with request/response, the response need not go back to the original sender, if you so choose. Likewise, when sending one-way messages (no response), you should not set the ReplyTo field because it will be ignored.

Message serialization implementations are uniquely identified by a URI. The type of implementation required may be specified when requesting a new instance, or the configured default implementation may be used. Currently JBossESB provides two implementations, which are defined in the org.jboss.soa.esb.message.format.MessageType class:

Other Message implementations may be provided at runtime through the org.jboss.soa.esb.message.format.MessagePlugin:

public interface MessagePlugin

{

    public static final String MESSAGE_PLUGIN = 

                         "org.jboss.soa.esb.message.format.plugin";

    public Object createBodyType(Message msg, String type);

    public Message getMessage ();

    public URI getType ();

}

Each plug-in must uniquely identify the type of Message implementation it provides (via getMessage), using the getType method. Plug-in implementations must be identified to the system via the jbossesb-properties.xml file using property names with the org.jboss.soa.esb.message.format.plugin extension.

By default the webservice endpoint does not support WS-Addressing but this can be enabled through use of the 'addressing' attribute.

When support for addressing is enabled, the WS-Addressing Message Id, Relates To URIs and relationship types will be added as properties of the incoming messages.

The following example illustrates the declaration of a service which wishes to validate the request/response messages but without exposing the service through a webservice endpoint.

<service category="ServiceCat" name="ServiceName" description="Test Service">

    <actions mep="RequestResponse" inXsd="/request.xsd" outXsd="/response.xsd"

            webservice="false" validate="true">

        <!-- .... >

    </actions>          

</service>

The following example illustrates the declaration of a service which wishes to validate the request/response messages and expose the service through a webservice endpoint. In addition the service expects the request to be provided in the named body location 'REQUEST' and will return its response in the named body location 'RESPONSE'.

<service category="ServiceCat" name="ServiceName" description="Test Service">

    <actions mep="RequestResponse" inXsd="/request.xsd" outXsd="/response.xsd"

            validate="true" requestLocation="REQUEST" responseLocation="RESPONSE">

        <!-- .... -->

    </actions>          

</service>

The <providers> part of the configuration defines all of the message <provider> instances for a single instance of the ESB. Two types of providers are currently supported:

A Bus Provider (e.g. <jms-provider>) can contain multiple <bus> definitions. The <provider> can also be decorated with <property> instances relating to provider specific properties that are common across all <bus> instances defined on that <provider> (e.g. for JMS - “connection-factory”, “jndi-context-factory” etc). Likewise, each <bus> instance can be decorated with <property> instances specific to that <bus> instance (e.g. for JMS - “destination-type”, “destination-name” etc).

As an example, a provider configuration for JMS would be as follows:

    <providers>

          <jms-provider name="JBossMQ" connection-factory="ConnectionFactory">

              <jms-bus busid="Reconciliation">

                  <jms-message-filter

                      dest-type="QUEUE"

                      dest-name="queue/B"

                   />

              </jms-bus>

          </jms-provider>

      </providers>

We recommend use of the specialized extensions of these types for creating configurations, namely <jms-provider> and <jms-bus> for JMS. The most important part of the above configuration is the busid attribute defined on the <jms-bus> instance. This is a required attribute on the <bus> element/type (including all of its specializations - <jms-bus> etc). This attribute is used within the <listener> configurations to refer to the <bus> instance on which the listener receives its messages. More on this later.

The <services> part of the configuration defines each of the Services under the management of this instance of the Enterprise Service Bus. It defines them as a series of <service> configurations. A <service> can also be decorated with the following attributes.

A <service> may define a set of <listeners> and a set of <actions>. The configuration model defines a “base” <listener> type, as well as specializations for each of the main supported transports (<jms-listener>, <sql-listener> etc.)

The “base” <listener> defines the following attribute. These attribute definitions are inherited by all <listener> extensions. As such, they can be set for all of the listeners and gateways supported by JBossESB, such as InVM.

Listeners can define a set of zero or more <property> elements (just like the <provider> and <bus> elements/types). These are used to define listener specific properties.

An example of a <listener> reference to a <bus> can be seen in the following example.

<?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"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd http://anonsvn.jboss.org/repos/labs/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="Reconciliation">

                  <jms-message-filter

                      dest-type="QUEUE"

                      dest-name="queue/B"

                   />

               </jms-bus>

<!-- busid --> <jms-bus busid="ReconciliationEsb">

                  <jms-message-filter

                      dest-type="QUEUE"

                      dest-name="queue/C"

               </jms-bus>

          </jms-provider>

      </providers>

      <services>

          <service category="Bank" name="Reconciliation"

                   description="Bank Reconciliation Service">

              <listeners>

<!-- busidref --> <jms-listener name="Bank-Listener"

                      busidref="Reconciliation"

                      is-gateway="true"/>

                  <jms-listener name="Bank-Esb"

                      busidref="ReconciliationEsb"/>

              </listeners>

              <actions>

                   ....

              </actions>

          </service>

      </services>

</jbossesb>

A Service will do little without a list of one or more <actions>. <action>s typically contain the logic for processing the payload of the messages received by the service (through its listeners). Alternatively, it may contain the transformation or routing logic for messages to be consumed by an external Service/entity.

The <action> element/type defines the following attributes.

In a list of <action> instances within an <actions> set, the actions are called (that is, their “process” method is called) in the order in which the <action> instances appear in the <actions> set. The message returned from each <action> is used as the input message to the next <action> in the list.

Like a number of other elements/types in this model, the <action> type can also contain zero or more <property> element instances. The <property> element/type can define a standard name-value-pair, or contain free form content (xsd:any). According to the XSD, this free form content is valid as child content for the <property> element/type, no matter where it is in the configuration (on any of <provider>, <bus>, <listener> and any of their derivatives). However, it is only on <action>- defined <property> instances that this free-form child content is used.

As stated in the <action> definition above, actions are implemented through implementing the org.jboss.soa.esb.actions.ActionProcessor class. All implementations of this interface must contain a public constructor of the following form:

public ActionZ(org.jboss.soa.esb.helpers.ConfigTree configuration);

It is through this constructor supplied ConfigTree instance that all of the action attributes are supplied, including the free form content from the action <property> instances. The free form content is supplied as child content on the ConfigTree instance.

So an example of an <actions> configuration might be as follows:

<actions>

    <action name="MyAction-1" class="com.acme.MyAction1"/>

    <action name="MyAction-2" class="com.acme.MyAction2">

        <property name="propA" value="propAVal" />

    </action>

    <action name="MyAction-3" class="com.acme.MyAction3">

        <property name="propB" value="propBVal" />

        <property name="propC">

            <!-- Free form child content... -->

            <some-free-form-element>zzz<some-free-form-element>

        </property>

    </action>

</actions> 

Example configuration:

 <jms-bus busid="quickstartGwChannel">

     <jms-message-filter

         dest-type="QUEUE"

         dest-name="queue/quickstart_jms_secured_Request_gw"

         jms-security-principal="esbuser"

         jms-security-credential="esbpassword"/>

</jms-bus>