Basics of IBM webMethods Messaging

Overview

This chapter provides an overview of concepts common to the IBM webMethods Broker API for JMS client and the IBM webMethods Broker Client C# API. This chapter is for developers who are new to messaging architectures and for those wanting a review of JMS concepts and the JMS API. Experienced messaging developers and those looking for specific information about the IBM webMethods Broker APIs can skip this chapter.

An in-depth treatment of messaging architecture is beyond the scope of this programming guide.

IBM webMethods Messaging

IBM webMethods Broker APIs allow applications to communicate with each other using a common set of interfaces. Although you can write applications in both Java/JMS and C# .NET in IBM webMethods Broker, the programming or object model is virtually the same for both.

The IBM webMethods Broker API for JMS supports the Java Message Service standard and includes a few additional IBM webMethods Broker-specific enhancements.
The IBM webMethods Broker Client C# API is a Windows .NET API with an object model patterned after JMS.

JMS Messaging

The Java Message Service (JMS) is a Java API that allows applications to communicate with each other using a common set of interfaces. The JMS API provides messaging interfaces but not the implementations.

A JMS provider, such as the IBM webMethods Broker used as a JMS provider, is a messaging system that supports the JMS message interfaces and provides administrative and control features. It supports routing and delivery of messages by means of the JMS API on the client. A goal of JMS is to maximize the portability of JMS applications across different JMS providers.

JMS clients are the programs or components, written in Java, that produce and consume messages.

C# Messaging

The C# messaging API allows Windows messaging clients written as Microsoft .NET assemblies to communicate with the Broker as if they were JMS clients. Because the C# messaging API is based on the JMS programming model, and because the wire format is the same for both clients, .NET developers only need concern themselves with the client code and not the implementation details when connecting to Broker.

Messaging Styles

A messaging style refers to how messages are produced and consumed. IBM webMethods Broker supports the publish-subscribe (pub-sub) and point-to-point (PTP) messaging styles.

Point-to-Point (PTP) Messaging

In point-to-point (PTP) messaging, message producers and consumers are known as senders and receivers.

The central concept in PTP messaging is a destination called a queue. A queue represents a single receiver. Message senders submit messages to a receiver's queue and wait for the receiver to respond to the message.

In the PTP model, a queue may receive messages from many different senders and may deliver messages to multiple receivers; however, each message is delivered to only one receiver.

Publish-Subscribe Messaging

In publish-subscribe messaging, message producers and consumers are known as publishers and subscribers.

The central concept in the publish-subscribe messaging is a destination called a topic. Message publishers send messages of specified topics. Clients that want to receive that type of message subscribe to the topic.

The publishers and subscribers never communicate with each other directly. Instead, they communicate by exchanging messages through a message Broker.

Publishers and subscribers have a timing dependency. Clients that subscribe to a topic can consume only messages published after the client has created a subscription. In addition, the subscriber must continue to be active to consume messages.

The messaging APIs relax this dependency by making a distinction between durable subscriptions and non-durable subscriptions.

Durable Subscriptions

Durable subscriptions allow subscribers to receive all the messages published on a topic, including those published while the subscriber is inactive. When the subscribing applications are not running, the messaging provider holds the messages in nonvolatile storage. It retains the messages until either of the following situations occurs:

The subscribing application becomes active, identifies itself to the provider, and sends an acknowledgment of receipt of the message.
The expiration time for the messages is reached.

Non-durable Subscriptions

Non-durable subscriptions allow subscribers to receive messages on their chosen topic, only if the messages are published while the subscriber is active. You generally use this type of subscription for any kind of data that is time sensitive, such as financial information.

JMS API Programming Model

The following section summarizes the most important components of the JMS API. Since the same abstractions are used for IBM webMethods Broker APIs for JMS and C# APIs, the descriptions that follow are valid for both types of clients, except where noted.

The building blocks of a JMS application consist of the following:

Administered objects (connection factories and destinations)
Connections
Sessions
Message producers
Message consumers
Messages

Administered Objects

Administered objects are preconfigured objects that an administrator creates for use with C# and JMS client programs. Administered objects serve as the bridge between the client code and the .NET assembly or JMS provider.

By design, the messaging APIs separate the task of configuring administered objects from the client code. This architecture maximizes portability: the provider-specific work is delegated to the administrator rather than to the client code. However, the implementation must supply its own set of administrative tools (for example, the My webMethods user interface and the jmsadmin command-line utility) to configure the administered objects.

JMS administered objects are stored in a standardized namespace called the Java Naming and Directory Interface (JNDI). JNDI is a Java API that provides naming and directory functionality to Java applications. JNDI provides a way to store and retrieve objects by a user supplied name.

Types of Administered Object

There are two types of administered objects: connection factories and destinations.

Connection Factories

A connection factory is the object a client uses to create a connection with a JMS provider. It encapsulates the set of configuration parameters that a JMS administrator defines for a connection.

The type of connection factory determines whether a connection is made to a topic (in a publish-subscribe application), a queue (in a point-to-point application), or can be made to both (generic connection), and whether messages are managed like elements in a distributed transaction in the client application.

You use XA-based connection factories in JMS applications managed by an application server, in the context of a distributed transaction. You do not use XA-based connection factories in:

Standalone JMS messaging applications
IBM webMethods C# messaging applications

Following are the types of connection factories:

ConnectionFactory. The preferred connection factory object. This is a generic connection factory object, which can be used as either a QueueConnectionFactory or TopicConnectionFactory or both at run time.
Note: The IBM webMethods C# API only supports use of a generic ConnectionFactory. All other types of connection factory can only be used in JMS clients.
QueueConnectionFactory. Used to make connections in a point-to-point application.
TopicConnectionFactory. Used to make connections in a publish-subscribe application.
XAConnectionFactory. A generic connection factory object, where the object can be used in a transactional context.
XAQueueConnectionFactory. Used to make connections in a point-to-point application, where the object will be used in a transactional context.
XATopicConnectionFactory. Used to make connections in a publish-subscribe application, where the object will be used in a transactional context.

Destinations

Destinations are the objects that a client uses to specify the target of messages it produces and the source of messages it consumes. These objects specify the identity of a destination to a JMS API method. There are four types of destinations; only the first two (queues and topics) are administered objects:

Queue. A queue object covers a provider-specific queue name and is how a client specifies the identity of a queue to JMS methods.
Topic. A topic object covers a provider-specific topic name and is how a client specifies the identity of a topic to JMS methods.
TemporaryQueue. A queue object created for the duration of a particular connection (or QueueConnection). It can only be consumed by the connection from which it was created.
TemporaryTopic. A topic object that is created for the duration of a particular connection (or TopicConnection). It can only be consumed by the connection from which it was created.

Connections

A connection object is an active connection from a client to its JMS provider. In JMS, connections support concurrent use. A connection serves the following purposes:

A connection encapsulates an open connection with a JMS provider. It typically represents an open TCP/IP socket between a client and the service provider software.
The creation of a connection object is the point where client authentication takes place.
A connection object can specify a unique client identifier.
A connection object supports a user-supplied ExceptionListener object.

A connection should always be closed once its use is no longer required.

Sessions

A session object is a single-threaded context for producing and consuming messages. If a client uses different threads for different paths of message execution, a session must be created for each of the threads.

A session is used to create message producers, message consumers, temporary topics, and temporary queues; it also supplies provider-optimized message factories.

In JMS, a session provides the context for grouping a set of send and receive messages into a transactional unit.

Message Producer

A message producer is an object that a session creates to send messages to a destination (a topic or a queue).

Message Consumer

A message consumer is an object that a session creates to receive messages sent to a destination. A message consumer allows a client to register interest in a destination, which manages the delivery of messages to the registered consumers of that destination.

Message Listener

A message listener object is an asynchronous event handler for messages. This object implements the MessageListener interface, which contains the single method onMessage(). The implementation of onMessage() is a user-defined set of actions taken when a message arrives at its destination.

Message Selector

A client may want to receive subsets of messages. A message selector allows a client to filter the messages it wants to receive by use of a SQL92 string expression in the message header. That expression is applied to properties in the message header (not to the message body content) containing the value to be filtered.

If the SQL expression evaluates to true, the message is sent to the client; if the SQL expression evaluates to false, it does not send the message.

Messages

Messages are objects that communicate information between client applications. Following are descriptions of several key concepts related to JMS and C# messages.

Message Structure

Messages are composed of the following parts:

Header. All messages support the same set of header fields. Header fields contain predefined values that allow clients and providers to identify and route messages. Each of the fields supports its own set and get methods for managing data; some fields are set automatically by the send and publish methods, whereas others must be set by the client.
Examples of header fields include:
- JMSDestination, which holds a destination object representing the destination to which the message is to be sent.
- JMSMessageID, which holds a unique message identifier value and is set automatically.
- JMSCorrelationID, which is used to link a reply message with its requesting message. This value is set by the client application.
- JMSReplyTo, which is set by the client and takes as a value a Destination object representing where the reply is being sent. If no reply is being sent, this field is set to null.
Properties (optional). Properties are used to add optional fields to the message header. There are several types of message property fields.
- Application-specific properties are typically used to hold message selector values. Message selectors are used to filter and route messages.
- Standard properties. The API provides some predefined property names that a provider may support. Support for the JMSXGroupID and JMSXGroupSeq is required; however, support for all other standard properties is optional.
- Provider-specific properties are unique to the messaging provider and typically refer to internal values.
Body (optional). JMS defines various types of message body formats that are compatible with most messaging styles. Each form is defined by a message interface:
- StreamMessage. A message whose body contains a stream of Java primitive values. It is filled and read sequentially.
- MapMessage. A message whose body contains a set of name-value pairs where names are Strings and values are Java primitive types. The entries can be accessed sequentially by enumerator or randomly by name. The order of the entries is undefined.
- TextMessage. A message whose body contains a java.lang.String.
- ObjectMessage. A message that contains a Serializable Java object.
- BytesMessage. A message that contains a stream of uninterpreted bytes. This message type is for literally encoding a body to match an existing message format. In many cases, it will be possible to use one of the other, self-defining, message types instead.
  Both StreamMessage and MapMessage support the same set of primitive data types. Conversions from one data type to another are possible.

Message Delivery

A client can receive messages synchronously or asynchronously.

For synchronous receipt, a client can request the next message from a message consumer using one of its receive methods. Several variations of receive allow a client to poll or wait for the next message. receive() is a blocking method that blocks until the message arrives or times out.

For asynchronous receipt, a client can register a MessageListener object with a message consumer. As messages arrive at the message consumer, the client delivers them by calling the message listener's onMessage() method. The onMessage() method proceeds based on the contents of the message. You register the message listener with a specific message consumer using the setMessageListener() method.

Message Acknowledgment

A message is not considered to be successfully consumed until it is acknowledged. Depending on the session acknowledgment mode, the messaging provider may send a message more than once to the same destination. There are several message acknowledgment constants:

Value	Description
`AUTO_ACKNOWLEDGE`	Automatically acknowledges the successful receipt of a message. Message acknowledgements are sent asynchronously to Broker Server. Configure these properties to change the default behavior of message acknowledgements: autoAckBatchSize autoAckBatchSizeRetry autoAckServicePollInterval For information about the APIs available for configuring the asynchronous auto acknowledgements, see the descriptions of the WmJMSConfig class in the Javadoc.
`CLIENT_ACKNOWLEDGE`	Acknowledges the receipt of a message when the client calls the message's `acknowledge()` method.
`DUPS_OK_ACKNOWLEDGE`	Instructs the session to automatically, lazily acknowledge the receipt of messages. This reduces system overhead but may result in duplicate messages being sent.
`SESSION_TRANSACTED`	Used for transacted sessions. The acknowledgment mode is ignored.