2 Client Programming Model

Point-To-Point Messaging

In the point-to-point domain, message producers are called senders and consumers are called receivers. They exchange messages by means of a destination called a queue: senders produce messages to a queue; receivers consume messages from a queue. What distinguishes point-to-point messaging is that a message can be consumed by only one consumer.

Figure 2-1 shows the simplest messaging operation in the point-to-point domain. MyQueueSender sends Msg1 to the queue destination MyQueue1. Then, MyQueueReceiver obtains the message from MyQueue1.

Figure 2-1 Simple Point-to-Point Messaging

Description of "Figure 2-1 Simple Point-to-Point Messaging"

Figure 2-2 shows a more complex picture of point-to-point messaging to illustrate the possibilities offered by this domain. Two senders, MyQSender1 and MyQSender2, use the same connection to send messages to MyQueue1. MyQSender3 uses an additional connection to send messages to MyQueue1. On the receiving side, MyQReceiver1 consumes messages from MyQueue1, and MyQReceiver2 and MyQReceiver3, share a connection in order to consume messages from MyQueue1.

Figure 2-2 Complex Point-to-Point Messaging

Description of "Figure 2-2 Complex Point-to-Point Messaging"

This more complex picture exemplifies a number of additional points about point-to-point messaging.

• More than one sender can produce and send messages to a queue. Senders can share a connection or use different connections, but they can all access the same queue.

• More than one receiver can consume messages from a queue, but each message can be consumed by only one receiver. Thus Msg1, Msg2, and Msg3 are consumed by different receivers. (This is a Message Queue extension.)

• Receivers can share a connection or use different connections, but they can all access the same queue. (This is a Message Queue extension.)

• Senders and receivers have no timing dependencies: the receiver can consume a message whether or not it was running when the sender produced and sent the message.

• Messages are placed in a queue in the order they are produced, but the order in which they are consumed depends on factors such as message expiration date, message priority, whether a selector is used in consuming messages, and the releative message processing rate of the consumers.

• Senders and receivers can be added and deleted dynamically at runtime, thus allowing the messaging system to expand or contract as needed.

The point-to-point domain offers a number of advantages:

• Messages destined for a queue are always retained, even if there are no receivers.

• Java clients can use a queue browser object to inspect the contents of a queue. They can then consume messages based on the information gained from this inspection. That is, although the consumption model is normally FIFO (first in, first out), receivers can consume messages that are not at the head of the queue by using message selectors. Administrative clients can also use the queue browser to monitor the contents of a queue.

• The fact that multiple receivers can consume messages from the same queue allows you to use load-balancing to scale message consumption if the order in which messages are received is not important.

Publish/Subscribe Messaging

In the publish/subscribe domain, message producers are called publishers and message consumers are called subscribers. They exchange messages by means of a destination called a topic: publishers produce messages to a topic; subscribers subscribe to a topic and consume messages from a topic.

Figure 2-3 shows a simple messaging operation in the publish/subscribe domain. MyTopicPublisher publishes Msg1 to the destination MyTopic. Then, MyTopicSubscriber1 and MyTopicSubscriber2 each receive a copy of Msg1 from MyTopic.

Figure 2-3 Simple Publish/Subscribe Messaging

Description of "Figure 2-3 Simple Publish/Subscribe Messaging"

While the publish/subscribe model does not require that there be more than one subscriber, two subscribers are shown in the figure to emphasize the fact that this domain allows you to broadcast messages. All subscribers to a topic get a copy of any message published to that topic.

Subscribers can be durable or non-durable. If a durable subscriber becomes inactive, the broker retains messages for it until the subscriber becomes active and consumes the messages. If a non-durable subscriber becomes inactive, the broker does not retain messages for it.

Figure 2-4 shows a more complex picture of publish/subscribe messaging to illustrate the possibilities offered by this domain. Several producers publish messages to the Topic1 destination. Several subscribers consume messages from the Topic1 destination. Unless, a subscriber is using a selector to filter messages, each subscriber gets all the messages published to the topic to which it is subscribed. In Figure 2-4, MyTSubscriber2 has filtered out Msg2.

Figure 2-4 Complex Publish/Subscribe Messaging

Description of "Figure 2-4 Complex Publish/Subscribe Messaging"

This more complex picture exemplifies a number of additional points about publish/subscribe messaging.

• More than one publisher can publish messages to a topic. Publishers can share a connection or use different connections, but they can all access the same topic.

• More than one subscriber can consume messages from a topic. Subscribers consume all messages published to a topic unless they use selectors to filter out messages or the messages expire before they are consumed.

• Subscribers can share a connection or use different connections, but they can all access the same topic.

• For durable subscribers, the broker retains messages for the subscribers while these subscribers are inactive.

• Messages are placed in a topic in the order they are produced, but the order in which they are consumed depends on factors such as message expiration date, message priority, and whether a selector is used in consuming messages.

• Publishers and subscribers have a timing dependency: a topic subscriber can consume only messages published after the subscriber has subscribed to the topic.

• Publishers and subscribers can be added and deleted dynamically at runtime, thus allowing the messaging system to expand or contract as needed.

The main advantage of the publish/subscribe model is that it allows messages to be broadcast to multiple subscribers.

Domain-Specific and Unified APIs

The JMS API defines interfaces and classes that you can use to implement either of the point-to-point or the publish/subscribe domains. These are the domain-specific API's shown in columns 2 and 3 of Table 2-1. The JMS API defines an additional unified domain, which allows you to program a generic messaging client. The behavior of such a client is determined by the type of the destination to which it produces messages and from which it consumes messages. If the destination is a queue, messaging will behave according to the point-to-point pattern; if the destination is a topic, messaging will behave according to the publish/subscribe pattern.

The unified domain was introduced with JMS version 1.1. The domain-specific API also provides a clean programming interface that prevents certain types of programming errors: for example, creating a durable subscriber for a queue destination. However, the domain-specific APIs have the disadvantage that you cannot combine point-to-point and publish/subscribe operations in the same transaction or in the same session. If you need to do that, you should choose the unified domain API. See The Request-Reply Pattern for an example of combining the two domains.

Connection Factories and Connections

A client uses a connection factory object (ConnectionFactory) to create a connection. A connection object ( Connection) represents a client's active connection to the broker. It uses the underlying Message Queue connection service that is either started by default or is explicitly started by the administrator for this client.

Both allocation of communication resources and authentication of the client take place when a connection is created. It is a relatively heavyweight object, and most clients do all their messaging with a single connection. Connections support concurrent use: any number of producers and consumers can share a connection.

When you create a connection factory, you can configure the behavior of all connections derived from it by setting its properties. For Message Queue, these specify the following information:

• The name of the host on which the broker resides, the connection service desired, and the port through which the client is to access that service.

• How automatic reconnection to the broker should be handled if the connection fails. This feature reconnects the client to the same (or, in a broker cluster, to a different broker) if a connection is lost.

• The ID of any client that needs the broker to track its durable subscription.

• The default name and password of any user attempting the connection. This information is used to authenticate the user and authorize operations if a password is not specified at connection time.

• Whether broker acknowledgements should be suppressed for any clients that are not concerned with reliability.

• How to manage the flow of control and payload messages between the broker and the client runtime.

• How queue browsing should be handled (Java clients only).

• Whether certain message header fields should be overridden.

It is possible to override connection factory properties from the command line used to start the client application. It is also possible to override properties for any given connection by explicitly setting properties for that connection.

You can use a connection object to create session objects, to set up an exception listener, or to obtain JMS version and JMS provider information.

Sessions

If the connection represents a communication channel between the client and the broker, a session marks a single conversation between them. Mainly, you use a session object to create messages, message producers, and message consumers. When you create a session, you configure reliable delivery through a number of acknowledgement options or through transactions. For more information, see Reliable Message Delivery.

According to the JMS specification, a session is a single-threaded context for producing and consuming messages. You can create multiple message producers and consumers for a single session, but you are restricted to using them serially. The threading implementation varies slightly for Java and C clients. Consult the appropriate developer's guide for additional information about threading implementation and restrictions.

You can also use a session object to do the following:

• Create and configure destinations for those clients that do not use administered objects to obtain references to existing destinations.

• Create and configure temporary topics and queues; these are used as part of the request-reply pattern. See The Request-Reply Pattern.

• Support transaction processing.

• Define a serial order for producing or consuming messages.

• Serialize the execution of message listeners for asynchronous consumers (see Consuming a Message).

• Create queue browsers (Java clients only).

• Define when messages are considered processed.

Messages

A message is composed of three parts: a header, properties, and a body. You must understand this structure in order to compose a message properly and to configure certain messaging behaviors.

Synchronous and Asynchronous Consumers

A message consumer can support either synchronous or asynchronous consumption of messages.

• Synchronous consumption means the consumer explicitly requests a message that has been delivered to the client runtime and then consumes it.

  Depending on the method used to request messages, a synchronous consumer can choose to wait (indefinitely) until a message is delivered to the client runtime, to wait a specified amount of time for a message, or to return immediately if there is no message available to be consumed (messages that were successfully produced but which the broker has not finished processing).

• Asynchronous consumption means that the message is automatically handed off to a message listener object (MessageListener) that has been registered with the consumer. The client consumes the message when a session thread invokes the onMessage() method of the message listener object.

Using Selectors to Filter Messages

A message consumer can use a message selector to have the message service deliver only those messages whose properties (see Message Properties) match specific selection criteria. You specify this criteria when you create the consumer.

Selectors use an SQL-like syntax to match against message properties. For example,

color = "red'
size> 10

Java clients can also specify selectors when browsing a queue; this allows you to see which selected messages are waiting to be consumed.

Using Durable Subscribers

A durable subscriber is one for which the broker retains messages even when the subscriber becomes inactive.

Because the broker must maintain state for the subscriber and resume delivery of messages when the subscriber is reactivated, the broker must be able to identify a given subscriber throughout its comings and goings. The subscriber's identity is constructed from the ClientID property of the connection that created it and the subscriber name specified when you create the subscriber.

Acknowledgements

Acknowledgements are messages sent between a client and the message service to ensure reliable delivery of messages. Acknowledgements are used differently for producers and for consumers.

In the case of message production, the broker confirms that it has received the message, placed it in its destination, and stored it persistently. The producer's send() method blocks until it receives this broker acknowledgement. Broker acknowledgements are transparent to the client when persistent messages are sent.

In the case of message consumption, the client acknowledges that it has received delivery of a message from a destination and consumed it, before the broker can delete the message from that destination. JMS specifies different client acknowledgement modes that represent different degrees of reliability.

• In the AUTO_ACKNOWLEDGE mode, the session automatically acknowledges each message consumed by the client. The session thread blocks, waiting for the broker to confirm that it has processed the client acknowledgement for each consumed message.

• In the CLIENT_ACKNOWLEDGE mode, the client explicitly acknowledges after one or more messages have been consumed by calling the acknowledge() method of a message object. This causes the session to acknowledge all messages that have been consumed by the session since the previous invocation of the method. The session thread blocks, waiting for the broker to confirm that it has processed the client acknowledgement.

  Message Queue extends this mode by providing a method that allows a client to acknowledge receipt of one message only.

• In DUPS_OK_ACKNOWLEDGE mode, the session acknowledges after a specified number of messages (default is 10) have been consumed. The session thread does not block waiting for the broker to confirm it has processed the client acknowledgement, because no broker confirmation is required in this mode. Although this mode guarantees that no message will be lost, it does not guarantee that no duplicate messages will be received, hence its name: DUPS_OK.

For clients that are more concerned with performance than reliability, the Message Queue service extends the JMS API by providing a NO_ACKNOWLEDGE mode. In this mode, the broker does not track client acknowledgements, so there is no guarantee that a message has been successfully processed by the consuming client. Choosing this mode may give you better performance for non persistent messages that are sent to non-durable subscribers.

Transactions

A transaction is a way of grouping the production and/or consumption of one or more messages into an atomic unit. The client and broker acknowledgement process described above applies, as well, to transactions. In this case, however, when a transaction commits, it implicitly performs the relevant broker or client acknowledgements. You cannot have an end-to-end transaction encompassing both the production and consumption of the same message.

The JMS specification supports both local and distributed transactions, as described below.

Persistent Storage

The other aspect of reliability is ensuring that the broker does not lose persistent messages before they are delivered to consumers. This means that when a message reaches its physical destination, the broker must place it in a persistent data store. If the broker fails for any reason, it can recover the message later and deliver it to the appropriate consumers.

The broker must also persistently store durable subscriptions. Otherwise, in case of failure, it would not be able to deliver messages to durable subscribers who become active after a message has arrived in a topic destination.

Messaging applications that want to guarantee message delivery must specify messages as persistent and deliver them either to topic destinations with durable subscribers or to queue destinations.

The Message Queue Broker describes the default message store supplied by the Message Queue service and how an administrator can set up and configure an alternate store.

Message Production

1. The client runtime delivers the message over the connection from the message producer to the broker.

Message Handling and Routing

2. The broker reads the message from the connection and places it in the appropriate destination.

3. The broker places the (persistent) message in the data store.

4. The broker confirms receipt of the message to the client runtime of the message producer.

5. The broker determines the routing for the message.

6. The broker writes out the message from its destination to the appropriate connection, tagging it with a unique identifier for the consumer.

Message Consumption

7. The message consumer's client runtime delivers the message from the connection to the message consumer.

8. The message consumer's client runtime acknowledges consumption of the message to the broker.

Message End-of-Life

9. The broker processes the client acknowledgement, and deletes the (persistent) message when all acknowledgements have been received.

10. The broker confirms to the consumer's client runtime that the client acknowledgement has been processed.

The broker can discard a message before it is consumed if the administrator deletes the message from a destination or if the administrator removes or redefines a durable subscriber, thereby causing a message in a topic destination to be removed without it being delivered. The broker can also discard a message before it is consumed if the message has expired, if memory limits have been reached, or if delivery fails due to a client exception. If you don't want a message discarded in these situations, you can have the broker store the messages in a special destination called the dead message queue. Storing messages in the dead message queue allows you to troubleshoot the system and recover messages in any of these situations.