JBossESB 4.2.1 GA

Programmers Guide

JBESB-PG-11/1/07

Legal Notices

The information contained in this documentation is subject to change without notice.

JBoss Inc. makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. JBoss Inc. shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.

Java™ and J2EE is a U.S. trademark of Sun Microsystems, Inc. Microsoft® and Windows NT® are registered trademarks of Microsoft Corporation. Oracle® is a registered U.S. trademark and Oracle9™, Oracle9 Server™ Oracle9 Enterprise Edition™ are trademarks of Oracle Corporation. Unix is used here as a generic term covering all versions of the UNIX® operating system. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

Copyright

JBoss, Home of Professional Open Source Copyright 2006, JBoss Inc., and individual contributors as indicated by the @authors tag. All rights reserved.

See the copyright.txt in the distribution for a full listing of individual contributors. This copyrighted material is made available to anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the GNU General Public License, v. 2.0. This program is distributed in the hope that it will be useful, but WITHOUT A WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the GNU General Public License for more details. You should have received a copy of the GNU General Public License, v. 2.0 along with this distribution; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Software Version

JBossESB 4.2.1 GA

Restricted Rights Legend

Use, duplication, or disclosure is subject to restrictions as set forth in contract subdivision (c)(1)(ii) of the Rights in Technical Data and Computer Software clause 52.227-FAR14.

© Copyright 2007 JBoss Inc.

Contents

About This Guide

What This Guide Contains

The Programmers Guide contains information on how to use JBossESB 4.2.1 GA.

Audience

This guide is most relevant to engineers who are responsible for using JBossESB 4.2.1 GA installations and want to know how it relates to SOA and ESB principles.

Prerequisites

None.

Organization

This guide contains the following chapters:

• Chapter 1, The ESB: an overview of the ESB concept.

• Chapter 2, JBossESB: a description of the core components within JBossESB and how they are intended to be used.

• Chapter 3, Services and Messages: a discussion on the two core concepts within JBossESB.

• Chapter 4, Building and Using Services: How to use listeners and actions to develop services and consumers.

• Chapter 5, Other Components: An overview of the other services within JBossESB.

• Chapter 6, Example: A worked example using some of the principles examined so far.

• Chapter 7, Advanced Topics: Some advanced concepts available within JBossESB, such as automatic fail-over and scheduling.

• Chapter 8, Fault-tolerance and Reliability: A discussion of how failures may affect applications developed on an ESB and how JBossESB can help tolerate them.

• Chapter 9, Configuration: a description of the configuration options within JBossESB.

Documentation Conventions

The following conventions are used in this guide:

Convention	Description
Italic	In paragraph text, italic identifies the titles of documents that are being referenced. When used in conjunction with the Code text described below, italics identify a variable that should be replaced by the user with an actual value.
Bold	Emphasizes items of particular importance.
Code	Text that represents programming code.
Function | Function	A path to a function or dialog box within an interface. For example, “Select File | Open.” indicates that you should select the Open function from the File menu.
( ) and |	Parentheses enclose optional items in command syntax. The vertical bar separates syntax items in a list of choices. For example, any of the following three items can be entered in this syntax: persistPolicy (Never | OnTimer | OnUpdate | NoMoreOftenThan)
Note: Caution:	A note highlights important supplemental information. A caution highlights procedures or information that is necessary to avoid damage to equipment, damage to software, loss of data, or invalid test results.

Table 1 Formatting Conventions

Additional Documentation

In addition to this guide, the following guides are available in the JBossESB 4.2.1 GA documentation set:

1. JBossESB 4.2.1 GA Trailblazer Guide: Provides guidance for using the trailblazer example.

2. JBossESB 4.2.1 GA Getting Started Guide: Provides a quick start reference to configuring and using the ESB.

3. JBossESB 4.2.1 GA Administration Guide: How to manage JBossESB.

4. JBossESB 4.2.1 GA Release Notes: Information on the differences between this release and previous releases.

5. JBossESB 4.2.1 GA Services Guides: Various documents related to the services available with the ESB.

Contacting Us

Questions or comments about JBossESB 4.2.1 GA should be directed to our support team.

The Enterprise Service Bus

What is an ESB?

The ESB is seen as the next generation of EAI – better and without the vendor-lockin characteristics of old. As such, many of the capabilities of a good ESB mirror those of existing EAI offerings. Traditional EAI stacks consist of: Business Process Monitoring, Integrated Development Environment, Human Workflow User Interface, Business Process Management, Connectors, Transaction Manager, Security, Application Container, Messaging Service, Metadata Repository, Naming and Directory Service, Distributed Computing Architecture.

As with EAI systems, ESB is not about business logic – that is left to higher levels. It is about infrastructure logic. Although there are many different definitions of what constitutes an ESB, what everyone agrees on now is that an ESB is part of an SOA infrastructure. However, SOA is not simply a technology or a product: it's a style of design, with many aspects (such as architectural, methodological and organisational) unrelated to the actual technology. But obviously at some point it becomes necessary to map the abstract SOA to a concrete implementation and that's where the ESB comes in to play.

1. You can learn more about SOA principles and ESB architectures in the SOA Background Concepts document.

When would you use JBossESB?

The figures below illustrate some concrete examples where JBossESB would be useful. Although these examples are specific to interactions between participants using non-interoperable JMS implementations, the principles are general and can be applied to other transports such as FTP and HTTP.

The first diagram shows simple file movement between two systems where messaging queuing is not involved.

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.

JBossESB

Rosetta

The core of JBossESB is Rosetta¹, an ESB that has been in commercial deployment at a mission critical site for over 3 years. The architecture of Rosetta is shown below in Figure 1:

2. In the diagram, processor classes refer to the Action classes within the core that are responsible for processing on triggered events.

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:

• Be easily configured to work with a wide variety of transport mechanisms (e.g., email and JMS).

• Offer a general purpose object repository.

• Enable pluggable data transformation mechanisms.

• Support logging of interactions.

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

3. Within JBossESB source we have two trees: org.jboss.internal.soa.esb and org.jboss.soa.esb. You should limit your use of anything within the org.jboss.internal.soa.esb package because the contents are subject to change without notice. Alternatively anything within the org.jboss.soa.esb is covered by our deprecation policy.

1. The core of JBossESB in a nutshell

Rosetta is built on three core architectural components:

• Message Listener and Message Filtering code. Message Listeners act as “inbound” message routers that listen for messages (e.g. on a JMS Queue/Topic, or on the filesystem) and present the message to a message processing pipeline that filters the message and routes it (“outbound” router) to another message endpoint.

• Data transformation via the SmooksTransformer action processor. See the Message Transformation Guide.

• A Content Based Routing Service. See the CBR Guide.

• A Message Repository, for saving messages/events exchanged within the ESB. See the Message Store Guide for further details.

These capabilities are offered through a set of business classes, adapters and processors, which will be described in detail later. Interactions between clients and services are supported via a range of different approaches, including JMS, flat-file system and email.

A typical JBossESB deployment is shown below. We shall return to this diagram in subsequent sections.

4. Some of the components in the diagram (e.g., LDAP server) are configuration choices and may not be provided out-of-the-box. Furthermore, the Processor and Action distinction shown in the above diagram is merely an illustrative convenience to show the concepts involved when an incoming event (message) triggers the underlying ESB to invoke higher-level services.

Figure 2: ESB Core components.

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.

Services and Messages

Introduction

In keeping with SOA principles, everything within JBossESB is considered to be either a service or a message. Services encapsulate the business logic or points of integration with legacy systems. Messages are the way in which clients an d services communicate with each other.

In the following sections we shall look at how Services and Messages are supported within JBossESB.

The Service

All clients and services within JBossESB are addressed using Endpoint References (EPRs). An EPR is essentially an address, to which messages are delivered by the ESB. How the message is delivered (e.g., FTP or JMS) is part of the binding of the EPR to messaging infrastructure and is typically reflected within the To component of the EPR, e.g., jms://foo.bar. The binding aspect is important because it imparts important semantic information as to the delivery characteristics for the message. For example, if using HTTP and the ultimate recipient of the message (e.g., business object) is not available, attempts to deliver the message will fail. If using JMS, it may be possible to deposit the message within a queue without delivery to the ultimate destination taking place. Obviously failure to deliver the message may subsequently occur, but unlike in the case of HTTP the sender will not be immediately notified of such a failure.

An EPR has the following XML-based composition:

• [address] : URI (mandatory). An address URI that identifies the endpoint. This may be a network address or a logical address.

• [reference properties] : xs:any (0..unbounded). A reference may contain a number of individual properties that are required to identify the entity or resource being conveyed. Reference identification properties are element information items that are named by QName and are required to properly dispatch messages to endpoints at the endpoint side of the interaction. Reference properties are provided by the issuer of the endpoint reference and are otherwise assumed to be opaque to consuming applications. The interpretation of these properties (as the use of the endpoint reference in general) is dependent upon the protocol binding and data encoding used to interact with the endpoint. Consuming applications should assume that endpoints represented by endpoint references with different [reference properties] may accept different sets of messages or follow a different set of policies, and consequently may have different associated metadata (e.g., WSDL, XML Schema, and WS-Policy policies ).

• [reference parameters] : xs:any (0..unbounded). A reference may contain a number of individual parameters which are associated with the endpoint to facilitate a particular interaction. Reference parameters are element information items that are named by QName and are required to properly interact with the endpoint. Reference parameters are also provided by the issuer of the endpoint reference and are otherwise assumed to be opaque to consuming applications. The use of reference parameters is dependent upon the protocol binding and data encoding used to interact with the endpoint. Unlike [reference properties], the [reference parameters] of two endpoint references may differ without an implication that different XML Schema, WSDL or policies apply to the endpoints.

5. It should already be apparent that EPRs are a low-level type of address and not something that most applications will have to deal with. You may have to deal with them for more advanced techniques such as direction of responses to recipients other than the sender, or routing failure notifications elsewhere. However, in general you should use the higher level Service Name and ServiceInvoker approach in conjunction with the Registry.

JBossESB uses the org.jboss.soa.esb.addressing.EPR and org.jboss.soa.esb.addressing.PortReference classes to represent endpoint references.

public class EPR
{
public EPR ();
public EPR (PortReference addr);
public EPR (URI uri);

public void setAddr (PortReference uri);
public PortReference getAddr () throws URISyntaxException;

public void copy (EPR from);

public boolean equals (Object obj);
}

6. The use of EPRs is based on the WS-Addressing specification from the W3C. However, in the 4.2 release the JBossESB implementation of EPRs is closer to the 2004 version of the specification from IBM, Microsoft et al.

1. Mapping of EPR to Service

How services map to EPRs can be a very important aspect of any application based on Service Oriented Architecture principles. Too tight a coupling can lead to brittle applications, whereas too loose a coupling can result in more development effort at the higher levels of the application. This section gives some general hints and tips on developing services, particularly when working with sessions. If you already have a good understanding of how your back-end implementation choices (e.g., EJB3) should map to services, then you can skip this section.

It has long been recognized that the World Wide Web is probably the most successful distributed system created. It is inherently loosely coupled (clients and servers frequently interact across the globe) and highly scaleable (many thousands of Web sites). There are a number of factors that can be attributed to the Web’s success, but two of the most important are:

• Sessions between clients and servers are maintained only long enough to transfer an HTML page and are dropped immediately afterward. This means that costly resources (e.g., TCP/IP connections, threads, processes) are not maintained for long durations, particularly when there are many users interacting with a service.

• Server interactions are either stateless, meaning that any instance of a Web server offering a particular service, e.g., airline reservation, can field the request, or information required to identify a previous user (and possibly state) is propagated with the invocation, e.g., the cookie.

Both of these factors mean that clusters of servers can relatively easily be used to distribute the load and provide improved availability/fault-tolerance to users. Web servers offering critical services are typically deployed over a cluster of machines. A locally distributed cluster of machines with the illusion of a single IP address and capable of working together to host a Web site provides a practical way of scaling up processing power and sharing load at a given site. Commercially available server clusters rely on a specially designed gateway router to distribute the load using a mechanism known as network address translation (NAT). The mechanism operates by editing the IP headers of packets so as to change the destination address before the IP to host address translation is performed. Similarly, return packets are edited to change their source IP address. Such translations can be performed on a per session basis so that all IP packets corresponding to a particular session are consistently redirected.

The Message

All interactions between clients and services within JBossESB occur through the exchange of Messages. In order to encourage loose coupling we recommend a message-exchange pattern based on one-way messages, i.e., requests and responses are independent messages, correlated where necessary by the infrastructure or application. Applications constructed in this way are less brittle and can be more tolerant of failures, giving developers more flexibility in their deployment and message delivery requirements.

To ensure loose coupling of services and develop SOA applications, it is necessary to:

• Use one-way message exchanges rather than request-response.

• Keep the contract definition within the exchanged messages. Try not to define a service interface that exposed back-end implementation choices, because that will make changing the implementation more difficult later.

• Use an extensible message structure for the message payload so that changes to it can be versioned over time, for backward compatibility.

• Do not develop fine-grained services: this is not a distributed-object paradigm, which can lead to brittle applications.

In order to use a one-way message delivery pattern with requests and responses, it is obviously necessary to encode information about where responses should be sent. That information may be present in the message body (the payload) and hence dealt with solely by the application, or part of the initial request message and typically dealt with by the ESB infrastructure.

Therefore, central to the ESB is the notion of a message, whose structure is similar to that found in SOAP:

<xs:complexType name="Envelope">
<xs:attribute ref="Header" use="required"/>
<xs:attribute ref="Context" use="required"/>
<xs:attribute ref="Body" use="required"/>
<xs:attribute ref="Attachment" use="optional"/>
<xs:attribute ref="Properties" use="optional"/>
<xs:attribute ref="Fault" use="optional"/>
</xs:complexType>

Pictorially the basic structure of the Message can be represented as shown below. In the rest of this section we shall examine each of these components in more detail.

In UML, the Message structure can be represented as:

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

7. In JBossESB, Attachments and Properties are not treated differently from the Body. The general concepts they embody are currently being re-evaluated and may change significantly in future releases. As such, we recommend developers do not use Attachments.

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.

8. The 4.x release of JBossESB does not support user-enhanced Contexts. This will be a feature of the 5.0 release.

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.

9. You should be extremely careful about sending Serialized objects within the Body: not everything that can be Serialized will necessarily be meaningful at the receiver, e.g., database connections.

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 void add (Object value);
public Object get ();
public Object remove (String name);
public void replace (Body b);
public void merge (Body b);
}

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.

10. The byte array component of the Body was deprecated in JBossESB 4.2.1. If you wish to continue using a byte array in conjunction with other data stored in the Body, then simply use add with a unique name.If your clients and services want to agree on a location for a byte array, then you can use the one that JBossESB uses: ByteBody.BYTES_LOCATION.

11. The default named Object (DEFAULT_LOCATION) should be used with care so that multiple services or Actions do not overwrite each other's data.

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

12. In JBossESB, Attachments and Properties are not treated differently from the Body. The general concepts they embody are currently being re-evaluated and may change significantly in future releases. As such, we recommend developers do not use Attachments or Properties.

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

13. JBossESB does not implement Properties as java.util.Properties for the same reason Web Services stacks do not: it places restrictions on the types of clients and services that can used. If you need to send java.util.Properties then you can embed them within the current abstraction.

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

14. At present JBossESB does not support specifying other encoding mechanisms for the Message or attachment streaming. This will be added in later releases and where appropriate will be tied in to the SOAP-with-attachments delivery mechanism. Therefore, currently attachments are treated in the same was as named objects within the Body.

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

• As a service developer, you define the contract that clients use in order to interact with your service. As part of that contract, you will specific both functional and non-functional aspects of the service, e.g., that it is an airline reservation service (functional) and that it is transactional (non-functional). You'll also define the operations (messages) that the service can understand. As part of the message definition, you stipulate the format (e.g., Java Serialized message versus XML) and the content (e.g., transaction context, seat number, customer name etc.) When defining the content, you can specify where in the Message your service will expect to find the payload. That can be in the form of attachments or specific named objects (even the default named object if you so wish). It is entirely up to the service developer to determine. The only restrictions are that objects and attachments must be globally uniquely named, or one service (or Action) may inadvertently pick up a partial payload meant for another if the same Message Body is forwarded across multiple hops.

• As a service users, you obtain the contract definition about the service (e.g., through UDDI or out-of-band communication) and this will define where in the message the payload must go. Information placed in other locations will likely be ignored and result in incorrect operation of the service.

There is more information about how to define your Message payload in the Message Payload section of this document.

1. Getting and Setting Data on the Message Body

By default, all JBossESB 4.2.1GA+ components (Actions, Listeners, Gateways, Routers, Notifiers etc) get and set data on the message through the messages “Default Payload Location”. This simple means that, by default, all components will get the payload to be processed (transformed, routed etc) by calling Message.getBody().get() and will set the processed result into the outgoing message by calling Message.getBody().add().

This default behavior can be overridden by all components in exactly the same way; by setting the “get-payload-location” and/or “set-payload-location” properties on the relevant component's configuration.

Prior to JBossESB 4.2.1GA there was no default message payload exchange pattern in place. JBossESB 4.2.1GA+ can be configured to exchange payload data according to the pre 4.2.1GA approach (i.e. is backward compatible with) by setting the “use.legacy.message.payload.exchange.patterns” property to “true” in the “core” section/module of the jbossesb-properties.xml file (found in the jbossesb.sar).

Extensions to Body

Although you can manipulate the contents of a Message Body directly in terms of bytes or name/value pairs, it is often more natural to use one of the following predefined Message structures, which are simply different views onto the data contained in the underlying Body.

As well as the basic Body interface, JBossESB supports the following interfaces, which are extensions on the basic Body interface:

• org.jboss.soa.esb.message.body.content.TextBody: the content of the Body is an arbitrary String, and can be manipulated via the getText and setText methods.

• org.jboss.soa.esb.message.body.content.ObjectBody: the content of the Body is a Serialized Object, and can be manipulated via the getObject and setObject methods.

• org.jboss.soa.esb.message.body.content.MapBody: the content of the Body is a Map<String, Serialized), and can be manipulated via the setMap and other methods.

• org.jboss.soa.esb.message.body.content.BytesBody: the content of the Body is a byte stream that contains arbitrary Java data-types. It can be manipulated using the various setter and getter methods for the data-types. Once created, the BytesMessage should be placed into either a read-only or write-only mode, depending upon how it needs to be manipulated. It is possible to change between these modes (using readMode and writeMode), but each time the mode is changed the buffer pointer will be reset. In order to ensure that all of the updates have been pushed into the Body, it is necessary to call flush when finished.

You can create Messages that have Body implementations based on one of these specific interfaces through the XMLMessageFactory or SerializedMessageFactory classes. The need for two different factories is explained in the section on Message Formats, which is described later in the document.

For each of the various Body types, you will find an associated create method (e.g., createTextBody) that allows you to create and initialize a Message of the specific type. Once created, the Message can be manipulated directly through the raw Body or via the specific interface. If the Message is transmitted to a recipient, then the Body structure will be maintained, e.g., it can be manipulated as a TextBody.

The XMLMessageFactory and SerializedMessageFactory are more convenient ways in which to work with Messages than the MessageFactory and associated classes, which are described in the following sections.

15. these extensions to the base Body interface are provided in a complimentary manner to the original Body. As such they can be used in conjunction with existing clients and services. Message consumers can remain unaware of these new types if necessary because the underlying data structure within the Message remains unchanged.

2. The Message Header

As we saw above, the Header of a Message contains a reference to the org.jboss.soa.esb.addressing.Call class:

public class Call
{
public Call ();
public Call (EPR epr);

public void setTo (EPR epr);
public EPR getTo () throws URISyntaxException;

public void setFrom (EPR from);
public EPR getFrom () throws URISyntaxException;

public void setReplyTo (EPR replyTo);
public EPR getReplyTo () throws URISyntaxException;

public void setFaultTo (EPR uri);
public EPR getFaultTo () throws URISyntaxException;

public void setRelatesTo (URI uri);
public URI getRelatesTo () throws URISyntaxException;

public void setAction (URI uri);
public URI getAction () throws URISyntaxException;

public void setMessageID (URI uri);
public URI getMessageID () throws URISyntaxException;

public void copy (Call from);
}

The properties below support both one way and request reply interaction patterns:

• [To] : URI (mandatory). The address of the intended receiver of this message.

• [From] : endpoint reference (0..1). Reference of the endpoint where the message originated from.

• [ReplyTo] : endpoint reference (0..1). An endpoint reference that identifies the intended receiver for replies to this message. If a reply is expected, a message must contain a [ReplyTo]. The sender must use the contents of the [ReplyTo] to formulate the reply message. If the [ReplyTo] is absent, the contents of the [From] may be used to formulate a message to the source. This property may be absent if the message has no meaningful reply. If this property is present, the [MessageID] property is required.

• [FaultTo] : endpoint reference (0..1). An endpoint reference that identifies the intended receiver for faults related to this message. When formulating a fault message the sender must use the contents of the [FaultTo] of the message being replied to to formulate the fault message. If the [FaultTo] is absent, the sender may use the contents of the [ReplyTo] to formulate the fault message. If both the [FaultTo] and [ReplyTo] are absent, the sender may use the contents of the [From] to formulate the fault message. This property may be absent if the sender cannot receive fault messages (e.g., is a one-way application message). If this property is present, the [MessageID] property is required.

• [Action] : URI (mandatory). An identifier that uniquely (and opaquely) identifies the semantics implied by this message.

• [MessageID] : URI (0..1). A URI that uniquely identifies this message in time and space. No two messages with a distinct application intent may share a [MessageID] property. A message may be retransmitted for any purpose including communications failure and may use the same [MessageID] property. The value of this property is an opaque URI whose interpretation beyond equivalence is not defined. If a reply is expected, this property must be present.

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.

1. Default FaultTo

When sending Messages, it is possible that errors will occur, either during the transmission or reception/processing of the Message. JBossESB will route any faults to the EPR mentioned in the FaultTo field of the incoming message. If this is not set, then it will use the ReplyTo field or, failing that, the From field. If no valid EPR is obtained as a result of checking all of these fields, then the error will be output to the console. If you do not wish to be informed about such faults, such as when sending a one-way message, you may wish to use the DeadLetter Queue Service EPR as your FaultTo. In this way, any faults that do occur will be saved for later processing.

2. Default ReplyTo

Because the recommended interaction pattern for within JBossESB is based on one-way message exchange, responses to messages are not necessarily automatic: it is application dependent as to whether or not a sender expects a response. As such, a reply address (EPR) is an optional part of the header routing information and applications should be setting this value if necessary. However, in the case where a response is required and the reply EPR (ReplyTo EPR) has not been set, JBossESB supports default values for each type of transport. Some of these ReplyTo defaults require system administrators to configure JBossESB correctly.

• For JMS, it is assumed to be a queue with a name based on the one used to deliver the original request: <request queue name>_reply

• For JDBC, it is assumed to be a table in the same database with a name based on the one used to deliver the original request: <request table name>_reply_table. The new table needs the same columns as the request table.

• For files (both local and remote), no administration changes are required: responses will be written into the same directory as the request but with a unique suffix to ensure that only the original sender will pick up the response.

3. The Message payload

From an application/service perspective the message payload is a combination of the Body and Attachments. In this section we shall give an overview of best practices when constructing and using the message payload.

16. In JBossESB, Attachments and Properties are not treated differently from the Body. The general concepts they embody are currently being re-evaluated and may change significantly in future releases. As such we shall not be considering the Attachments as part of the payload in the rest of this discussion.

The UML representation of the payload is shown below:

More complex content may be added through the add method, which supports named Objects. Names must be unique on behalf of a given Message or an appropriate exception will be thrown. Using <name, Object> pairs allows for a finer granularity of data access. The type of Objects that can be added to the Body can be arbitrary: they do not need to be Java Serializable. However, in the case where non-Serializable Objects are added, it is necessary to provide JBossESB with the ability to marshal/unmarshal the Message when it flows across the network. See the section of Message Formats for more details.

If no name is supplied to set or get, then the default name defined by DEFAULT_LOCATION will be used.

17. be careful when using Serialized Java objects in messages because it constrains the service implementations.

In general you will find it easier to work with the Message Body through the named Object approach. You can add, remove and inspect individual data items within the Message payload without having to decode the entire Body. Furthermore, you can combine named Objects within the payload with the byte array.

18. in the current release of JBossESB only Java Serialized objects may be attachments. This restriction will be removed in a subsequent release.

4. The MessageFactory

Internally to an ESB component, the message is a collection of Java objects. However, messages need to be serialized for a number of reasons, e.g., transmitted between address spaces (processes) or saved to a persistent datastore for auditing or debugging purposes. The external representation of a message may be influenced by the environment in which the ESB is deployed. Therefore, JBossESB does not impose a specific normalized message format, but supports a range of them.

All implementations of the org.jboss.soa.esb.message.Message interface are obtained from the org.jboss.soa.esb.message.format.MessageFactory class:

public abstract class MessageFactory
{
public abstract Message getMessage ();
public abstract Message getMessage (URI type);

public static MessageFactory getInstance ();
}

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:

• MessageType.JBOSS_XML: this uses an XML representation of the Message on the wire. The schema for the message is defined in the message.xsd within the schemas directory. The URI is urn:jboss/esb/message/type/JBOSS_XML.

• MessageType.JAVA_SERIALIZED: this implementation requires that all components of a Message are Serializable. It obviously requires that recipients of this type of Message have sufficient information (the Java classes) to be able to de-serialize the Message. The URI is urn:jboss/esb/message/type/JAVA_SERIALIZED.

19. You should be wary about using the JAVA_SERIALIZED version of the Message format because it more easily ties your applications to specific service implementations, i.e., it breaks loose coupling.

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

20. The default Message type is JBOSS_XML. However, this can be changed by setting the property org.jboss.soa.esb.message.default.uri to the desired URI.

5. Message Formats

As mentioned previously, JBossESB supports two serialized message formats: MessageType.JBOSS_XML and MessageType.JAVA_SERIALIZED. In the following sections we shall look at each of these formats in more detail.

1. MessageType.JAVA_SERIALIZED

This implementation requires that all contents are Java Serializable. Any attempt to add a non-Serializable object to the Message will result in a IllegalParameterException being thrown.

2. MessageType.JBOSS_XML

This implementation uses an XML representation of the Message on the wire. The schema for the message is defined in the message.xsd within the schemas directory. Arbitrary objects may be added to the Message, i.e., they do not have to be Serializable. Therefore, it may be necessary to provide a mechanism to marshal/unmarshal such objects to/from XML when the Message needs to be serialized. This support can be provided through the org.jboss.soa.esb.message.format.xml.marshal.MarshalUnmarshalPlugin:

public interface MarshalUnmarshalPlugin
{
public static final String MARSHAL_UNMARSHAL_PLUGIN =
"org.jboss.soa.esb.message.format.xml.plugin";

public boolean marshal (Element doc, Object param)
throws MarshalException;

public Object unmarshal (Element doc) throws UnmarshalException;

public URI type ();
}

21. Java Serialized objects are supported by default.

Plug-ins can be registered with the system through the jbossesb- properties.xml configuration file. They should have attribute names that start with the MARSHAL_UNMARSHAL_PLUGIN. When packing objects in XML, JBossESB runs through the list of registered plug-ins until it finds one that can deal with the object type (or faults). When packing, the name (type) of the plug-in that packed the object is also attached to facilitate unpacking at the Message receiver.

Now that we have looked at the concepts behind services and Messages, we shall examine how to construct services using the framework provided by Rosetta in the following Chapter.

Building and Using Services

Listeners, Couriers and Actions

Listeners encapsulate the endpoints for message reception. Upon receipt of a message, a Listener feeds that message into a “pipeline” of message processors that process the message before routing the result to the “replyTo” endpoint. The action processing that takes place in the pipeline may consist of steps wherein the message gets transformed in one processor, some business logic is applied in the next processor, before the result gets routed to the next step in the pipeline, or to another endpoint. Listeners rely on the Courier interface to pick up and deliver Messages.

The Courier interface encapsulates transport details from listeners.

public interface Courier
{
public boolean deliver(Message message) throws CourierException;
}

The TwoWayCourier class that extends Courier, can also pickup Messages from an EPR. It is useful when a response is expected from the target of the outgoing Message (see for example org.jboss.soa.esb.actions.CbrProxyAction).

public interface TwoWayCourier extends Courier
{
...
public Message pickup(long waitTime, EPR epr) throws CourierException, CourierTimeoutException;
...
}

The CourierFactory class will return an appropriate Courier (or TwoWayCourier) class for specific EPRs.

public class CourierFactory
{
....

public static Courier getCourier(EPR toEPR) throws
CourierException
{

...
}

public static TwoWayCourier getCourier(EPR toEPR, EPR replyToEPR)
throws CourierException
{
...
}
...
}

The default internal TwoWayCourierImpl checks if the transport specific courier has a public 'void cleanup()' method and if so, invokes it to do housekeeping that need not be implemented for all transports. See org.jboss.internal.soa.esb.couriers.JmsCourier for example.

Transport specific classes that implement the Courier or TwoWayCourier interfaces can publish other utility methods that are specific for that particular transport.

As outlined above, the responsibility of a listener is to act as a message delivery endpoint and to deliver messages to an “Action Processing Pipeline”. Each listener configuration needs to supply information for:

• the Registry (see service-category, service-name, service-description and EPR-description tag names)

• instantiation of the listener class (see listenerClass tag name)

• the EPR that the listener will be servicing. This is transport specific. The following example corresponds to a JMS EPR (see connection-factory, destination-type, destination-name, jndi-type, jndi-URL and message-selector tag names)

• the “action processing pipeline”. One or more <action> elements each that must contain at least the 'class' tagname that will determine which action class will be instantiated for that step in the processing chain

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

jndi-URL="jnp://127.0.0.1:1099"

jndi-context-factory="org.jnp.interfaces.NamingContextFactory"

jndi-pkg-prefix="org.jboss.naming:org.jnp.interfaces">

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

maxThreads="1"

is-gateway="true"

/>

<jms-listener name="helloWorld"

busidref="quickstartEsbChannel"

maxThreads="1"

/>

</listeners>

<actions>

<action name="action1" class="org.jboss.soa.esb.samples.quickstart.helloworld.MyJMSListenerAction"

process="displayMessage"

/>

<action name="notificationAction" class="org.jboss.soa.esb.actions.Notifier">

<property name="okMethod" value="notifyOK" />

<property name="notification-details">

<NotificationList type="ok">

<target class="NotifyConsole"/>

</NotificationList>

<NotificationList type="err">

<target class="NotifyConsole"/>

</NotificationList>

</property>

</action>

</actions>

</service>

</services>

</jbossesb>

This example configuration will instantiate a listener object (jms-listener attribute) that will wait for inconimg ESB Messages, serialized within a javax.jms.ObjectMessage, and will deliver each incoming message to an ActionProcessingPipeline consiting of two steps (<action> elements):

1. action1. MyJMSListenerActionAction (a trivial example follows)

2. notificationAction. An org.jboss.soa.esb.actions.SystemPrintln

The following trivial action class will prove useful for debugging your XML action configuration