JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server Message Queue 4.5 Developer's Guide for Java Clients
search filter icon
search icon

Document Information


1.  Overview

2.  Using the Java API

3.  Message Queue Clients: Design and Features

Client Design Considerations

Developing Portable Clients

Choosing Messaging Domains

Connections and Sessions

Producers and Consumers

Assigning Client Identifiers

Message Order and Priority

Using Selectors Efficiently

Balancing Reliability and Performance

Managing Client Threads

JMS Threading Restrictions

Thread Allocation for Connections

Managing Memory and Resources

Managing Memory

Managing Message Size

Message Compression

Advantages and Limitations of Compression

Compression Examples

Managing the Dead Message Queue

Managing Physical Destination Limits

Programming Issues for Message Consumers

Using the Client Runtime Ping Feature

Preventing Message Loss for Synchronous Consumers

Synchronous Consumption in Distributed Applications

Factors Affecting Performance

Delivery Mode (Persistent/Nonpersistent)

Use of Transactions

Acknowledgment Mode

Durable vs. Nondurable Subscriptions

Use of Selectors (Message Filtering)

Message Size

Message Body Type

Connection Event Notification

Connection Events

Creating an Event Listener

Event Listener Examples

Consumer Event Notification

Consumer Events

Creating a Consumer Event Listener

Consumer Event Listener Examples

Client Connection Failover (Auto-Reconnect)

Enabling Auto-Reconnect

Single-Broker Auto-Reconnect

Parallel Broker Auto-Reconnect

Clustered-Broker Auto-Reconnect

Auto-Reconnect Behaviors

Auto-Reconnect Limitations

Handling Exceptions When Failover Occurs

Handling Exceptions in a Transacted Session

Transacted Session: Failover Producer Example

Transacted Session: Failover Consumer Example

Handling Exceptions in a Non-Transacted Session

Failover Producer Example

Failover Consumer Example

Custom Client Acknowledgment

Using Client Acknowledge Mode

Using No Acknowledge Mode

Schema Validation of XML Payload Messages

Communicating with C Clients

Client Runtime Logging

Logging Name Spaces, Levels, and Activities

Using the JRE Logging Configuration File

Using a Logging Configuration File for a Specific Application

Setting the Logging Configuration Programmatically

4.  Using the Metrics Monitoring API

5.  Working with SOAP Messages

6.  Embedding a Message Queue Broker in a Java Client

A.  Warning Messages and Client Error Codes


Client Design Considerations

The choices you make in designing a JMS client affect portability, allocating work between connections and sessions, reliability and performance, resource use, and ease of administration. This section discusses basic issues that you need to address in client design. It covers the following topics:

Developing Portable Clients

The Java Messaging Specification was developed to abstract access to message-oriented middleware systems (MOMs). A client that writes JMS code should be portable to any provider that implements this specification. If code portability is important to you, be sure that you do the following in developing clients:

Choosing Messaging Domains

As described in Messaging Domains in Oracle GlassFish Server Message Queue 4.5 Technical Overview, JMS supports two distinct message delivery models: point-to-point and publish/subscribe. These two message delivery models can be handled using different API objects—with slightly different semantics—representing different programming domains, as shown in Table 3-1, or they can be handled by base (unified domain) types.

Table 3-1 JMS Programming Objects

Unified Domain
Point-to-Point Domain
Publish/Subscribe Domain
Destination (Queue or Topic)

Using the point-to-point or publish/subscribe domains offers the advantage of a clean API that prevents certain types of programming errors; for example, creating a durable subscriber for a queue destination. However, the non-unified domains 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.

The JMS 1.1 specification continues to support the separate JMS 1.02 programming domains. (The example applications included with the Message Queue product as well as the code examples provided in this book all use the separate JMS 1.02 programming domains.) You can choose the API that best suits your needs. The only exception are those developers needing to write clients for the Sun Java System Application Server 7 environment, as explained in the following note.

Note - Developers of applications that run in the Sun Java System Application Server 7 environment are limited to using the JMS 1.0.2 API. This is because Sun Java System Application Server 7 complies with the J2EE 1.3 specification, which supports only JMS 1.0.2. Any JMS messaging performed in servlets and EJBs—including message-driven beans must be based on the domain-specific JMS APIs and cannot use the JMS 1.1 unified domain APIs. Developers of J2EE applications that will run in J2EE 1.4-compliant servers can, however, use the simpler JMS 1.1 APIs.

Connections and Sessions

A connection is a relatively heavy-weight object because of the authentication and communication setup that must be done when a connection is created. For this reason, it’s a good idea to use as few connections as possible. The real allocation of work occurs in sessions, which are light-weight, single-threaded contexts for producing and consuming messages. When you are thinking about structuring your client, it is best to think of the work that is done at the session level.

A session

The requirement that sessions be operated on by a single thread at a time places some restrictions on the combination of producers and consumers that can use the same session. In particular, if a session has an asynchronous consumer, it may not have any other synchronous consumers. For a discussion of the connection and session’s use of threads, see Managing Client Threads. With the exception of these restrictions, let the needs of your application determine the number of sessions, producers, and consumers.

Producers and Consumers

Aside from the reliability your client requires, the design decisions that relate to producers and consumers include the following:

Assigning Client Identifiers

A connection can have a client identifier. This identifier is used to associate a JMS client’s connection to a message service, with state information maintained by the message service for that client. The JMS provider must ensure that a client identifier is unique, and applies to only one connection at a time. Currently, client identifiers are used to maintain state for durable subscribers. In defining a client identifier, you can use a special variable substitution syntax that allows multiple connections to be created from a single ConnectionFactory object using different user name parameters to generate unique client identifiers. These connections can be used by multiple durable subscribers without naming conflicts or lack of security.

Message Queue allows client identifiers to be set in one of two ways:

Message Order and Priority

In general, all messages sent to a destination by a single session are guaranteed to be delivered to a consumer in the order they were sent. However, if they are assigned different priorities, a messaging system will attempt to deliver higher priority messages first.

Beyond this, the ordering of messages consumed by a client can have only a rough relationship to the order in which they were produced. This is because the delivery of messages to a number of destinations and the delivery from those destinations can depend on a number of issues that affect timing, such as the order in which the messages are sent, the sessions from which they are sent, whether the messages are persistent, the lifetime of the messages, the priority of the messages, the message delivery policy of queue destinations (see Chapter 18, Physical Destination Property Reference, in Oracle GlassFish Server Message Queue 4.5 Administration Guide), and message service availability.

Using Selectors Efficiently

The use of selectors can have a significant impact on the performance of your application. It’s difficult to put an exact cost on the expense of using selectors since it varies with the complexity of the selector expression, but the more you can do to eliminate or simplify selectors the better.

One way to eliminate (or simplify) selectors is to use multiple destinations to sort messages. This has the additional benefit of spreading the message load over more than one producer, which can improve the scalability of your application. For those cases when it is not possible to do that, here are some techniques that you can use to improve the performance of your application when using selectors:

Balancing Reliability and Performance

Reliable messaging is implemented in a variety of ways: through the use of persistent messages, acknowledgments or transactions, durable subscriptions, and connection failover.

In general, the more reliable the delivery of messages, the more overhead and bandwidth are required to achieve it. The trade-off between reliability and performance is a significant design consideration. You can maximize performance and throughput by choosing to produce and consume nonpersistent messages. On the other hand, you can maximize reliability by producing and consuming persistent messages in a transaction using a transacted session. For a detailed discussion of design options and their impact on performance, see Factors Affecting Performance.