Programming WebLogic JMS

Using Message Unit-of-Order

The following sections describe how to use Message Unit-of-Order to provide strict message ordering when using WebLogic JMS:

What Is Message Unit-Of-Order?

Message Unit-of-Order is a WebLogic Server value-added feature that enables a stand-alone message producer, or a group of producers acting as one, to group messages into a single unit with respect to the processing order. This single unit is called a Unit-of-Order and requires that all messages from that unit be processed sequentially in the order they were created.

Understanding Message Processing with Unit-of-Order

The following sections compare message processing as described by the JMS specification with message processing enhanced by using WebLogic Server's Message Unit-of-Order feature.

Message Processing According to the JMS Specification

While the Java Message Service Specification provides an ordered message delivery, it does so in a very strict sense. It defines order between a single instance of a producer and a single instance of a consumer, but does not take into account the following common situations:

Many consumers on one queue. See Using Distributed Destinations.
Multiple producers within a single application acting as a single producer. See Using Distributed Destinations.
Message recoveries or transaction rollbacks where other messages from the same producer can be delivered to another consumer for processing. See What Happens When a Message Is Delayed During Processing?.
Use of filters and destination sort keys. See Message Unit-of-Order Advanced Topics.

Message Processing with Unit-of-Order

The WebLogic Server Unit-of-Order feature enables a message producer or group of message producers acting as one, to group messages into a single unit that is processed sequentially in the order the messages were created. The message processing of a single message is complete when a message is acknowledged, committed, recovered, or rolled back. Until message processing for a message is complete, the remaining unprocessed messages for that Unit-of-Order are blocked.

This section provides information on rules for JMS acknowledgement modes when using Message Unit-of-Order:

No messages from a Unit-of-Order are processed in parallel when the acknowledgement mode is CLIENT_ACKNOWLEDGE, AUTO_ACKNOWLEDGE, or DUPS_OK_ACKNOWLEDGE.
When the consumer is closed, the current message processing is completed, regardless of the session's acknowledge mode.
CLIENT_ACKNOWLEDGE - The application calling Message.acknowledge and Session.recover indicate which messages are completely processed in the Unit-of-Order.
AUTO_ACKNOWLEDGE - The session automatically acknowledges a client's receipt of a message when it has either successfully returned from a call to receive or when the MessageListener that was called returns successfully.

Asynchronous mode: Successful completion or exception of onMessage(msg) indicates when a message is completely processed.
Synchronous mode: For a given consumer, such as consumer A, consumerA.receive is completed when one of the following occurs: consumerA.receive, consumerA.setMessageListener, or consumerA.close.

DUPS_OK_ACKNOWLEDGE - The session automatically acknowledges a client's receipt of a message when it has either successfully returned from a call to receive or when the MessageListener that was called returns successfully.

Asynchronous mode: Successful completion or exception of onMessage(msg) indicates when a message is completely processed.
Synchronous mode: For a given consumer, such as consumer A, consumerA.receive() is completed when one of the following occurs: consumerA.receive(), consumerA.setMessageListener(), or consumerA.close().

NO_ACKNOWLEDGE - The session provides no order processing guarantees. Messages can be processed in parallel to different available consumers.

Message Delivery with Unit-of-Order

Message Unit-of-Order provides that messages are delivered in accordance with the following rules:

Member messages of a Unit-of-Order are delivered to queue consumers sequentially in the order they were created. The message order within a Unit-of-Order will not be affected by sort criteria, priority, or filters. However, messages that are uncommitted, have a Redelivery Delay, or have an unexpired TimetoDeliver timer will delay messages that arrive after them.
Unit-of-Order messages are processed one at a time. The processing completion of one message allows the next message in the Unit-of-Order to be delivered.
Unit-of-Order messages sent to a distributed queue reside on only one physical member of the distributed queue. For more information, see Using Unit-of-Order with Distributed Destinations.
All uncommitted or unacknowledged messages from the same Unit-of-Order must be in the same transaction, or if non-transactional, the same JMSSession. When one message in the Unit-of-Order is uncommitted or unacknowledged, the other messages are deliverable only to the same transaction or JMSSession. This keeps all unacknowledged messages from the same Unit-of-Order in one recoverable operation and allows order to be maintained despite rollbacks or recoveries.
A queue that has several messages from the same Unit-of-Order must complete processing all of them before they can be delivered to any queue consumer or the next message can be delivered to the queue.

For Example, when Messages M1 through Mn are delivered:

as part of a transaction and the transaction is rolled back (processing is complete). Then messages M1 through Mn are delivered to any available consumer.
outside of a transaction and the messages are recovered (processing is complete). Then messages M1 through Mn are delivered to any available consumer.
outside of a transaction and the messages are acknowledged (processing is complete). Then the undelivered message Mn+1 is delivered to any available consumer.

Message Unit-of-Order Case Study

This section provides a simple case study for Message Unit-of-Order based on ordering a book from an online bookstore.

Joe Orders a book

XYZ Online Bookstore implements a simple processing design that uses JMS to process customer orders. The JMS processing system is composed of:

A message producer sending to a queue (Queue1).
Multiple message driven beans (MDBs), such as MdbX and MdbY, that process messages from Queue1.
A database (myDB) that contains order and order status information.

Joe logs into his XYZ Online Bookstore account and searches his favorite book topics. He chooses a book, proceeds to the checkout, and completes the sales transaction. Then Joe realizes he has previously purchased this same item, so he cancels the order. One week later, the book is delivered to Joe.

What Happened to Joe's Order

In Joe's ordering scenario, his cancel order message was processed before his purchase order message. The result was that Joe received a book he did not wish to purchase. The following steps demonstrate how Joe's order was processed.

The following diagram and corresponding actions demonstrate how Joe's order was processed.

Figure 10-1 Workflow for Joe's Order

Workflow for Joe's Order

Joe clicks the order button from his shopping cart.

The order message (message A) is placed on Queue1.

Joe cancels the order.

The cancel order (message B) is placed on Queue1.

MdbX takes message A from Queue1.

MdbY takes message B from Queue1.

MdbY writes the cancel message to the database. Because there is no corresponding order message, there is no order message to remove from the database.

MdbX writes the order message to the database.

An application responsible for shipping books reads the database, sees the order message, and initiates shipment to Joe's home.

Although the Java Message Service Specification provides an ordered message delivery, it only provides ordered message delivery between a single instance of a producer and a single instance of a consumer. In Joe's case, multiple MDBs where available to consume messages from Queue1 and the processing order of the messages was no longer guaranteed.

How Message Unit-of-Order Solves the Problem

To ensure that all messages in Joe's order are processed correctly, the system administrator for XYZ Bookstore configures a Message Unit-of-Order based on a user session, such that all messages from a user session have a Unit-of-Order name attribute with the value of the session id. See How to Create a Unit-of-Order. All messages created during Joe's user session are processed sequentially in the order they were created because WebLogic Server guarantees that messages in a Unit-of-Order are not processed in parallel.

The following diagram and corresponding actions demonstrate how Joe's order was processed using Message Unit-of-Order.

Figure 10-2 Workflow for Joe's Order Using Unit-of-Order

Workflow for Joe's Order Using Unit-of-Order

Joe clicks the order button from his shopping cart.

The order message (message A) is placed on Queue1.

Joe cancels the order.

The cancel order (message B) is placed on Queue1.

MdbX takes message A from Queue1.

MdbY takes message B from Queue1.

Message B on MdbY is blocked until MdbX acknowledges the order message. See What Happens When a Message Is Delayed During Processing?.

Message A is committed and written to the database.

Message B is committed and written to the database.

Because there is a corresponding order message, Joe's order is removed from the database and he does not receive a book.

How to Create a Unit-of-Order

The following sections describe how to create a Message Unit-of-Order. Also see Message Delivery with Unit-of-Order and Message Unit-of-Order Advanced Topics.

Creating a Unit-of-Order Programmatically

Use the setUnitOfOrder() method of the WLMessageProducer interface to associate a producer with a Unit-of-Order name.

For example:

getProducer().setUnitOfOrder("myUOOname");

The Unit-of-Order name attribute value is set to myUOOname.

Once a producer is associated with a Unit-of-Order, all messages sent by this producer are processed as a Unit-of-Order until either the producer is closed or the association between the producer and the Unit-of-Order is dissolved.

The following code provides an example of how to associate a producer with a Unit-of-Order:

Listing 10-1 Using the WLMessageProducer Interface to Create a Unit-of-Order

.
.
.
queue = (Queue)(ctx.lookup(destName));
qsender = (WLMessageProducer) qs.createProducer(queue);
qsender.setUnitOfOrder();
uooname = qsender.getUnitOfOrder();
System.out.println("Using UnitOfOrder :" + uooname);
.
.
.

Creating a Unit-of-Order Administratively

The following section provides information on how to configure JMS connection factories or JMS destinations to enable Message Unit-of-Order.

Configuring Unit-of-Order for a Connection Factory

Use one of the following methods to configure JMS connection factories to enable Message Unit-of-Order:

Configure a connection factory to always use a user-generated Unit-of-Order name. As a result, all producers created from such a connection factory have Unit-of-Order enabled. See Configure unit-of-order parameters in the Administration Console Help.
Configure a connection factory to always use a system-generated Unit-of-Order name for each session. See Configure unit-of-order parameters in the Administration Console Help.
A client can call WLProducer.setUnitOfOrder(name) and change the initial connection factory setting on the producer.
Configure a destination to always use a system-generated Unit-of-Order name. See Configure unit-of-order parameters in the Administration Console Help.

You should administratively configure a Unit-of-Order on a connection factory or destination when interoperating with legacy JMS applications. This method provides a simple mechanism to ensure messages are processed in the order they are created without making any code changes.

Unit-of-Order Naming Rules

A Unit-of-Order is identified by a name attribute. Within a destination, messages that have the same value for the Unit-of-Order name attribute belong to the same Unit-of-Order. The name can be provided by either the system or the application. Messages in the same Unit-of-Order all share the same name. See How to Create a Unit-of-Order.

The name attribute for a Unit-of-Order must adhere to the following rules:

A valid value for the Unit-of-Order name attribute is any non-null and non-empty string.
System-generated Unit-of-Order names are timestamp-based and statistically unique.
Applications can supply their own Unit-of-Order names. For example, WebLogic Integration applications can use Workflow names and Web Services applications can use conversation names.
Message Unit-of-Order has its own name space. A Unit-of-Order does not need to be unique with respect to other named objects. For instance, it is valid to have a Unit-of-Order named Foo and a queue named Foo.
The scope of a Message Unit-of-Order is limited to a single destination. Two different Units of Order on two destinations can have the same name.
One or more producers can send messages with the same Unit-of-Order name by using the same string to create the Unit-of-Order. The Unit-of-Order name can be extracted from a delivered message. Example:

msg.getStringProperty("JMS_BEA_UnitOfOrder");

So a system-generated Unit-of-Order name can be used by more than one producer. This paradigm works just as well for application-assigned Unit-of-Order names. It will be most efficient if the information is serialized in only one place, so a property like Conversation ID can be stored only as the Unit-of-Order name. This paradigm does not work when the message has been sent through a non-Unit-of-Order JMS provider (releases prior to WebLogic 9.0 or non-WebLogic JMS providers).

Message Unit-of-Order Advanced Topics

The following sections describe how Unit-of-Order processes messages in advanced or more complex situations:

What Happens When a Message Is Delayed During Processing?

There are many situations that can occur during message processing that would normally change the order in which a message is processed. The following is a short list of typical message processing states that make a message not ready for delivery:

A message is within an uncommitted transaction.
A message's TimeToDeliver value prevents it from being delivered until the TimeToDeliver interval has elapsed.
A consumer calls a recover or rollback that prevents a message from being re-delivered until the RedeliveryDelay interval has elapsed.

Suppose messages A and B arrive respectively in the same Unit-of-Order, and message A cannot be delivered for any reason listed above. Even though nothing is delaying the delivery of message B, it is not deliverable until message A in its Unit-of-Order has been delivered.

What Happens When a Filter Makes a Message Undeliverable

Using a filter and a Unit-of-Order can provide unexpected behaviors. Suppose messages A through Z are in the same Unit-of-Order in the same Queue. Consumer1 has a filter, and messages A, B, and C satisfy the filter, and they are delivered to Consumer1.

Messages D through Z are undeliverable until messages A, B, and C are acknowledged.

Messages A, B, and C are acknowledged or recovered.

Message D is available to the message delivery system.

Message D does not pass the filter and can never be presented to Consumer1.

Messages E through Z are undeliverable until message D is processed.

The transaction that contains message D must be rolled back.
Once message D is processed, messages E through Z can be delivered.

For more information, see Filtering Messages.

What Happens When Destination Sort Keys are Used

Destination sort keys control the order in which messages are presented to consumers when messages are not part of a Unit-of-Order or are not part of the same Unit-of-Order.

For example:

Messages A and B arrive and in the same Unit-of-Order on a queue that is sorted by priority and the sort order is decending, but message B has a higher priority than A.

Even though message B has a higher priority than message A, message B is still not deliverable until message A has been processed because they are in the same Unit-of-Order. If a message C arrives and either does not have a Unit-of-Order or is not in the same Unit-of-Order as message A, the priority setting of message C and the priority setting of message A determine the delivery order. See Configuring JMS System Resources in Configuring and Managing WebLogic JMS.

Using Unit-of-Order with Distributed Destinations

As previously discussed in the Message Processing According to the JMS Specification, the Java Message Service Specification does not guarantee ordered message delivery when applications use distributed queues. WebLogic JMS directs messages with the same Unit-of-Order and having a distributed destination target to the same distributed destination member. The member is selected by the destination's Unit-of-Order configuration:

Using the Path Service

You can configure the WebLogic Path Service to provide a persistent map that can store the information required to route the messages contained in a Unit-of-Order to its destination resource—a member of a distributed destination. If the WebLogic Path Service is configured for a distributed destination, the routing path to a member destination is determined by the server using the run-time load balancing heuristics for the distributed queue. See Using WebLogic Path Servicein Configuring and Managing WebLogic JMS.

Using Hash-based Routing

If the WebLogic Path Service is not configured, the default routing path to a member queue is chosen by the server based on the hash codes of the Message Unit-of-Order name and the distributed queue members. An advantage of this routing mechanism is that routes to a distributed queue member are calculated quickly and do not require persistent storage in a cluster.

Consider the following when implementing Message Unit-of-Order in conjunction with Hash-based routing:

If a distributed queue member has an associated Unit-of-Order and is removed from the distributed queue, new messages are sent to a different distributed queue member and the messages will not be continuous with older messages.
If a distributed Queue member has an associated Unit-of-Order and is unreachable, the producer sending the message will throw a JMSOrderException and the messages are not routed to other distributed Queue members. The exception is thrown because the JMS messaging system can not meet the quality-of-service required — only one distributed destination member consumes messages for a particular Unit-of-Order.

Using Unit-of-Order with Topics

Assigning a Unit-of-Order does not prohibit parallel processing of a message by two subscribers on the same topic. Since individual subscribers for a topic have their own destination and message list, similar to a queue with one consumer, messages are processed by all subscribers according to the Unit-of-Order assigned at the time of production.

If messages are sent to a distributed topic, the order of the messages on a particular physical member is defined by the order the messages arrive at the member. See Publish/Subscribe Messaging.

Using Unit-of-Order with JMS Message Management

JMS message management allows a JMS administrator to move and delete most messages in a running JMS Server. This allows an administrator to violate the delivery rules specified in Message Delivery with Unit-of-Order.

If messages A, B, C, and D are produced and sent to destination D1 and belong to Unit-of-Order foo, consider the following:

Moving messages C and D to destination D2 may allow parallel processing of messages from both destinations.
Moving messages B and C to destination D2 may allow parallel processing of message A and messages B and C. After message A is processed, message D is deliverable.

For applications that depend on maintaining message order, a best practice is to move all of the messages in a Unit-of-Order as a single group.

To ensure Unit-of-Order delivery rules are maintained, use the following steps:

Pause the source destination and the target destination.

Select all of the messages with the Unit-of-Order you would like to move.

Move the selected messages to the target destination. If necessary, sort them according to the order that you want them processed.

Resume the source and target destinations.

For more information, see Troubleshooting WebLogic JMS in Configuring and Managing WebLogic JMS.

Using Unit-of-Order with WebLogic Store-and-Forward

WebLogic Store-and-Forward supports Message Unit-of-Order. For example, a Store-and-Forward producer sends messages with a Unit-of-Order named Foo. If the producer disconnects and reconnects through a different connection, the producer creates another Unit-of-Order with the name Foo and continues sending messages. All messages sent before and after the reconnect are directed through the same Store-and-Forward agent. See Configuring and Managing WebLogic Store-and-Forward.

Using Unit-of-Order with WebLogic Messaging Bridge

If both the source and target destinations are WebLogic Server 9.0 Messaging Bridge instances, you can enable PreserveMsgProperty on the Messaging Bridge to preserve the Unit-of Order name and set the producer's Unit-of-Order accordingly. See Configuring and Managing WebLogic Messaging Bridge.

Limitations to Message Unit-of-Order

This section provides additional general information to consider when using Message Unit-of-Order:

A browser enumeration contains the current queue messages in the order they are to be received by the browser, where current is defined as those messages that are deliverable. At most, the first message within a Unit-of-Order is deliverable. Subsequent messages in the same Unit-of-Order are not deliverable.
Some combinations of Unit-of-Order features can result in the starvation of competing Unit-of-Order message streams, including the under utilization of resources when the number of consumers exceed the number of in-flight messages with different Unit-of-Order names. You will need to test your applications under maximum loads to optimize your system's performance and eliminate conditions that under utilize resources.
This release of WebLogic Server Message Unit-of-Order does not support clients connecting to a non-Unit-of-Order JMS provider (releases prior to WebLogic 9.0 or non-WebLogic JMS providers).