Oracle GlassFish Message Queue 4.4.2 Technical Overview

Chapter 2 Client Programming Model

This chapter describes the basics of Message Queue client programming. It covers the following topics:

This chapter focuses on the design and implementation of Java clients. By and large, C client design roughly parallels Java client design. The final section of this chapter summarizes the differences between Java and C clients. For a detailed discussion of programming Message Queue clients, see Oracle GlassFish Message Queue 4.4.2 Developer’s Guide for Java Clients and Oracle GlassFish Message Queue 4.4.2 Developer’s Guide for C Clients.

Messaging Domains

Messaging middleware allows components and applications to communicate by producing and consuming messages. The JMS API defines two patterns or messaging domains that govern this communication: point-to-point messaging and publish/subscribe messaging. The JMS API is organized to support these patterns. The basic JMS objects: connections, sessions, producers, consumers, destinations, and messages are used to specify messaging behavior in both domains.

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

Message travels from sender to receiver via a queue destination.
Figure described in text.

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.

Note –

Support for multiple-consumer queues is a Message Queue feature (the JMS specification defines messaging behavior in the case of only one consumer accessing a queue). When multiple consumers access a queue, the load-balancing among them takes into account each consumer’s capacity and message processing rate.

Figure 2–2 Complex Point-to-Point Messaging

Two senders use one connection to send messages to one
receiver. Two consumers getting messages from same queue. Figure explained
in text.

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

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

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

Figure shows one publisher sending the same message to
two subscribers via a topic destination. Figure described in text.

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

Figure shows three publishers sending messages to three
subscribers via one topic destination. Figure described in text.

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

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.

Table 2–1 JMS Programming Domains and Objects

Base Type(Unified Domain) 

Point-to-Point Domain 

Publish/Subscribe Domain 

Destination (Queue or Topic)


















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.

Programming Objects

The objects used to implement JMS messaging remain essentially the same across programming domains: connection factories, connections, sessions, producers, consumers, messages, and destinations. These objects are shown in Figure 2–5. The figure shows, from the top down, how objects are derived, starting with the connection factory object.

Two of the objects, connection factories and destinations, are shown to reside in an object store. This is to underline the fact that these objects are normally created, configured, and managed as administered objects. We assume that connection factories and destinations are created administratively (rather than programmatically) throughout this chapter.

Figure 2–5 JMS Programming Objects

Figure shows relationship between connection factory,
connection, session, producer, consumer, message, and destination. Figure
described in text.

Table 2–2 summarizes the steps required to send and receive messages. Note that steps 1 through 6 are the same for senders and receivers.

Table 2–2 Producing and Consuming Messages.

Producing a Message 

Consuming a Message 

1. The administrator creates a connection factory administered object. 

2. The administrator creates a physical destination and the administered object that corresponds to it. 

3. The client obtains a connection factory object through a JNDI lookup. 

4. The client obtains a destination object through a JNDI lookup. 

5. The client creates a connection. 

5. The client sets the ClientID, as necessary. 

6. The client creates a session and sets the properties that govern messaging reliability. 

7. The client creates a message producer for a specified destination. 

The client creates a message consumer for a specified destination. 

8. The client starts the connection. 

9. The client sends a message. 

The client consumes a message. 

The following sections describe the objects used by producers and consumers: connections, sessions, messages, and destinations. We will then complete the discussion of JMS objects by describing the production and consumption of messages.

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:

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.


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:


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.

Message Header

A header is required of every JMS message. The header contains ten predefined fields, which are listed and described in Table 2–3.

Table 2–3 JMS-Defined Message Header

Header Field 


Set By 


Specifies the name of the destination to which the message is sent.

JMS provider 


Specifies whether the message is persistent.

Client, per producer or per individual message produced. 


Specifies the time when the message will expire.

Client, per producer or per individual message produced.. 


Specifies the priority of the message within a 0 (low) to 9 (high) range.

Client, per producer or per individual message produced. 


Specifies a unique ID for the message within the context of a JMS provider installation.

JMS provider 


Specifies whether the message has already been delivered but not acknowledged.

JMS provider 


Specifies the time when the JMS provider received the message.

JMS provider 


A value that allows a client to define a correspondence between two messages.

Client, if needed 


Specifies a destination where the consumer should send a reply.

Client, if needed 


A value that can be evaluated by a message selector.

Client, if needed 

As you can see from reading through this table, message header fields serve a variety of purposes: identifying a message, configuring the routing of messages, providing information about message handling, and so on.

One of the most important fields, JMSDeliveryMode, determines the reliability of message delivery. This field indicates whether a message is persistent.

Some message header fields are set by the JMS provider (the Message Queue broker and/or client runtime) and others are set by the client. Message producers may need to configure header values to obtain certain messaging behaviors; message consumers may need to read header values in order to understand how the message was routed and what further processing it might need.

Three of the header fields (JMSDeliveryMode, JMSExpiration, and JMSPriority) can be set at two different levels:

If these fields are set at more than one level, values set when producing a message override those set for the message’s producer.

Names of constant used for message header fields vary with the language implementation. See Oracle GlassFish Message Queue 4.4.2 Developer’s Guide for Java Clients or Oracle GlassFish Message Queue 4.4.2 Developer’s Guide for C Clients for more information.

Message Properties

A message can also include optional header fields, called properties, specified as property name and property value pairs. Properties allow clients and providers to extend the message header and can contain any information that the client or the JMS provider finds useful to identify and process a message. Message properties allow a consuming client to ask that only those messages be delivered which fit a given criteria. For instance, a consuming client might indicate an interest for payroll messages concerning part-time employees located in New Jersey. The JMS provider will not deliver messages that do not meet the specified criteria.

The JMS specification defines nine standard properties. Some of these are set by the client and some by the JMS provider. Their names begin with the reserved characters “JMSX.” The client or the JMS provider can use these properties to determine who sent a message, the identity of the application sending a message, the state of the message, how often and when it was delivered, tansaction identification, and so forth. These properties are useful to the JMS provider in routing messages and in providing diagnostic information.

Message Queue defines a number of additional message properties. These properties are used to identify compressed messages and how messages should be handled if they cannot be delivered. For more information see Managing Message Size in Oracle GlassFish Message Queue 4.4.2 Developer’s Guide for Java Clients.

Message Body

The message body contains the data that clients want to exchange.

The JMS message body type determines what the body may contain and how it should be processed by the consumer, as specified in Table 2–4. The Session object includes a create method for each type of message body.

Table 2–4 Message Body Types

Message Body Type 



A message whose body contains a stream of Java primitive values. It is filled and read sequentially. 


A message whose body contains a set of name-value pairs. The order of entries is not defined. 


A message whose body contains a Java string, for example an XML message. 


A message whose body contains a serialized Java object. 


A message whose body contains a stream of uninterpreted bytes. 


A message that contains a header and properties but no body. 

Java clients can set a property to have the client runtime compress the body of a message being produced. The Message Queue runtime on the consumer side decompresses the message before delivering it.

Producing a Message

Messages are sent or published by a message producer, within the context of a connection and session. Producing a message is fairly straightforward: a client uses a message producer object (MessageProducer) to send messages to a physical destination, represented in the API by a destination object.

When you create the producer, you can specify a default destination that all the producer’s messages are sent to. You can also specify default values for the message header fields that govern persistence, priority, and time-to-live. These defaults are then used by all messages issuing from that producer unless you override them by specifying an alternate destination when sending the message or by setting alternate values for the header fields for a given message.

The message producer can also implement a request-reply pattern by setting the JMSReplyTo message header field. For more information, see The Request-Reply Pattern.

In addition,Message Queue producers can specify symbolic topic destination names that use wildcard characters. Messages issueing from such wildcard producers are sent to all destinations that match the symbolic destination name. See Supported Topic Destination Names in Oracle GlassFish Message Queue 4.4.2 Administration Guide.

Consuming a Message

Messages are received by a message consumer, within the context of a connection and session. A client uses a message consumer object (MessageConsumer) to receive messages from a specified physical destination, represented in the API as a destination object.

When you create a consumer, you specify the destination from which it consumes messages.

Three factors affect how the broker delivers messages to a consumer:

These factors are described in the following sections.

Another factor that affects message delivery, the degree of reliability required by the messaging application, is described in Reliable Message Delivery.

In addition,Message Queue consumers can specify symbolic topic destination names that use wildcard characters. Messages are delivered to such wildcard consumers from all destinations that match the symbolic destination name. See Supported Topic Destination Names in Oracle GlassFish Message Queue 4.4.2 Administration Guide.

Synchronous and Asynchronous Consumers

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

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.

The Request-Reply Pattern

You can combine producers and consumers in the same connection (or even session when using the unified API). In addition, the JMS API allows you to implement a request-reply pattern for your messaging operations by using temporary destinations. Temporary destinations are explicitly created and destroyed programmatically. They are maintained by the broker only for the duration of the connection in which they are created.

To set up the request-reply pattern you need to do the following:

  1. Programmatically create a temporary destination where the consumer can send replies.

  2. In the message to be sent, set the JMSReplyTo field of the message header to that temporary destination.

When the message consumer processes the message, it examines the JMSReplyTo field of the message to determine if a reply is required and sends the reply to the specified destination.

The request-reply mechanism saves an administrator the trouble of creating a destination administered object or a physical destination for the reply, and makes it easy for the consumer to respond to the request. This pattern is useful when the producer must be sure that a request message has been handled before proceeding.

Figure 2–6 illustrates a request-reply pattern that sends messages to a topic and receives replies in a temporary queue.

Figure 2–6 Request/Reply Pattern

A publisher sends a message to two subscribers via a
topic destination and receives replies via a queue. Figure is explained in

As the figure shows, MyTopicPublisher produces Msg1 to the destination MyTopic. MyTopicSubsriber1 and MyTopicSubscriber2 consume the message and send a reply to MyTempQueue, from which MyTempQueueReceiver retrieves it. This pattern might be useful for an application that publishes pricing information to a large number of subscribers and which queues their (reply) orders for sequential processing.

Temporary destinations last only as long as the connection in which they are created. While any producer can produce messages to a temporary destination, the only consumers that can access a temporary destination are those created in the same connection in which the temporary destination was created.

Since the request/reply pattern depends on creating temporary destinations, you should not use this pattern in the following cases:

Reliable Message Delivery

Message delivery occurs in two hops: the first hop takes the message from the producer to a physical destination on the broker; the second hop takes the message from that destination to the consumer. Thus, a message can be lost in one of three ways: on its hop from the producer to the broker, on its hop from the broker to the consumer, and while it’s in broker memory (if the broker fails). Reliable delivery guarantees that delivery will not fail in any of these ways.

Two mechanisms are used to ensure reliable delivery:

The following sections describe these two aspects of ensuring reliability.

Note –

Reliable delivery only applies to messages for which the JMSDeliveryMode message header field indicates a persistent message.


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.

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.


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.

Local Transactions

A session can be configured as transacted, and the JMS API provides methods for initiating, committing, or rolling back local transactions.

As messages are produced or consumed within a local transaction, the message service tracks the various sends and receives, completing these operations only when the JMS client issues a call to commit the transaction. If a particular send or receive operation within the transaction fails, an exception is raised. The client code can handle the exception by ignoring it, retrying the operation, or rolling back the entire transaction. When a transaction is committed, all its operations are completed. When a transaction is rolled back, all successful operations are cancelled.

The scope of a local transaction is always a single session. That is, one or more producer or consumer operations performed in the context of a single session can be grouped into a single local transaction.

Distributed Transactions

The JMS specification also supports distributed transactions. That is, the production and consumption of messages can be part of a larger, distributed transaction that includes operations involving other resource managers, such as database systems. A distributed transaction manager, like the one supplied by GlassFish Server, must be available to support distributed transactions.

In distributed transactions, the distributed transaction manager tracks and manages operations performed by multiple resource managers (such as a message service and a database manager) using a two-phase commit protocol defined in the Java Transaction API (JTA), XA Resource API Specification. In the Java world, interaction between resource managers and a distributed transaction manager are described in the JTA specification.

Support for distributed transactions means that messaging clients can participate in distributed transactions through the XAResource interface defined by JTA. This interface defines a number of methods used in implementing two-phase commit. While the API calls are made on the client side, the JMS message service tracks the various send and receive operations within the distributed transaction, tracks the transactional state, and completes the messaging operations only in coordination with a distributed transaction manager—provided by a Java Transaction Service (JTS). As with local transactions, the client can handle exceptions by ignoring them, retrying operations, or rolling back an entire distributed transaction.

Note –

Message Queue supports distributed transactions only when it is used as a JMS provider in a Java Enterprise Edition (Java EE) application server. For additional information on how to use distributed transactions, please consult the Java EE documentation furnished by your application server provider.

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.

Chapter 3, 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.

A Message’s Journey Through the System

By way of summarizing the material presented so far, this section describes how a message is delivered using the Message Queue service, from a producer to a consumer. In order to paint a complete picture, a further detail is needed: The messages handled by the system in the course of delivery fall into two categories:

Message delivery is illustrated in Figure 2–7.

Figure 2–7 Message Delivery Steps

Diagram showing steps in the message delivery process
in case of a persistent, reliably delivered message. Figure is described in

Message delivery steps for a persistent, reliably delivered message are as follows:

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.

Design and Performance

The behavior of a Message Queue application depends on many factors: client design, connection configuration, broker configuration, broker tuning, and resource management. Some of these are the responsibility of the application developer; others are the concern of the Message Queue administrator.

In the best of possible worlds the developer should be aware of how the Message Queue service can support and scale the application design, and the administrator should be aware of the application's design goals when it comes time to tune the application. Messaging behavior can be optimized through redesign as well as through careful monitoring and tuning. Thus, a key aspect of creating a good Message Queue application is for the developer and the administrator to understand what can be realized at each stage of the application life cycle and to share information about desired and observed behavior.

Chapter 3, The Message Queue Broker explains how you can use the Message Queue service to support, manage, and tune messaging performance.

Working with SOAP Messages

Simple Object Access Protocol (SOAP) allows for the exchange of structured data (specified by an XML schema) between two peers in a distributed environment. Sun’s implementation of SOAP does not currently support reliable SOAP messaging nor does it support publishing SOAP messages. However, you can use the Message Queue service to achieve reliable SOAP messaging and, if desired, to publish SOAP messages. The Message Queue service does not deliver SOAP messages directly, but it allows you to wrap SOAP messages into JMS messages, to produce and consume these messages like normal JMS messages, and to extract the SOAP message from the JMS message.

Message Queue provides SOAP support through two packages: javax.xml.messaging and com.sun.messaging.xml. You can use classes implemented in these libraries to receive a SOAP message, to wrap a SOAP message as a JMS message, and to extract a SOAP message from a JMS message. The Java EE platform provides the package java.xml.soap, which you can use to assemble and disassemble a SOAP message.

To achieve reliable SOAP messaging you need to implement the following sequence of actions:

  1. Use the Message Transformer utility to convert the SOAP message into a JMS message.

  2. Send the JMS message to the desired destination.

  3. Consume the JMS message asynchronously or synchronously.

  4. After the JMS message is consumed, use the Message Transformer utility to convert it into a SOAP message.

  5. Use the SOAP with Attachments API for Java (SAAJ) API (defined in the java.xml.soap package) to disassemble the SOAP message.

For detailed information about SOAP messages and their processing, see Chapter 5, Working with SOAP Messages, in Oracle GlassFish Message Queue 4.4.2 Developer’s Guide for Java Clients.

Java and C Clients

Message Queue provides a C API to its messaging services to enable legacy C applications and C++ applications to participate in JMS-based messaging.

The JMS programming model is the foundation for the design of a Message Queue C client. Oracle GlassFish Message Queue 4.4.2 Developer’s Guide for C Clients explains how this model is implemented by the C data types and functions.

Like the Java interface, the C interface supports the following features:

However, it is important to understand that the Java Message Service specification is a standard for Java clients only; thus the C Message Queue API is specific to the Message Queue provider and cannot be used with other JMS providers. A messaging application that includes a C client cannot be handled by another JMS provider.

The C interface, does not support the following features: