11 Using the Message Unit-of-Order

Learn 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 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

Understand how the message processing by WebLogic Server's Message Unit-of-Order feature is different from the message processing as described by the JMS specification.

Message Processing According to the JMS Specification

While the Java Message Service Specification, at http://www.oracle.com/technetwork/java/jms/index.html, 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:

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 about rules for JMS acknowledgement modes, described at http://www.oracle.com/technetwork/java/jms/index.html, 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 the 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 with 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:

    • when Messages M1 through Mn are delivered outside of a transaction and the messages are recovered (processing is complete). Then messages M1 through Mn are delivered to any available consumer.

    • when Messages M1 through Mn are delivered 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

Learn the features of Message Unit-of-Order through a case study 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 in 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 Figure 11-1 and the corresponding actions demonstrate how Joe's order was processed.

Figure 11-1 Workflow for Joe's Order

Description of Figure 11-1 follows
Description of "Figure 11-1 Workflow for Joe's Order"
  1. Joe clicks the order button from his shopping cart.

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

  3. Joe cancels the order.

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

  5. MdbX takes message A from Queue1.

  6. MdbY takes message B from Queue1.

  7. 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.

  8. MdbX writes the order message to the database.

  9. 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, at http://www.oracle.com/technetwork/java/jms/index.html, 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 were 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.

In Figure 11-2 and the corresponding actions demonstrate how Joe's order was processed using Message Unit-of-Order.

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

Description of Figure 11-2 follows
Description of "Figure 11-2 Workflow for Joe's Order Using Unit-of-Order"
  1. Joe clicks the order button from his shopping cart.

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

  3. Joe cancels the order.

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

  5. MdbX takes message A from Queue1.

  6. MdbY takes message B from Queue1.

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

  8. Message A is committed and written to the database.

  9. 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

Learn how to create a Message Unit-of-Order programmatically and administratively.

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.

In the following example, the Unit-of-Order name attribute value is set to myUOOname:

getProducer().setUnitOfOrder("myUOOname");

After 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 Example 11-1 shows how to associate a producer with a Unit-of-Order:

Example 11-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 about how to configure JMS connection factories or JMS destinations to enable Message Unit-of-Order.

Configuring Unit-of-Order for a Connection Factory and Destinations

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

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.

    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 is sent through a non-Unit-of-Order JMS provider (releases before WebLogic 9.0 or non-WebLogic JMS providers).

Getting the Current Unit-of-Order

You can extract the Unit-of-Order name from a delivered message.

For example:

msg.getStringProperty("JMS_BEA_UnitOfOrder");

Message Unit-of-Order Advanced Topics

Understand 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 operation 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 of the previously listed reason. Even though nothing is delaying the delivery of message B, it is not deliverable until message A in its Unit-of-Order is 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.

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

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

  3. Message D is available to the message delivery system.

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

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

  • The transaction that contains message D must be rolled back.

  • After 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 depending, 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 is 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, then the priority setting of message C and the priority setting of message A determine the delivery order. See Configuring Basic JMS System Resources in Administering JMS Resources for Oracle WebLogic Server.

Using Unit-of-Order with Distributed Destinations

As previously discussed in the Message Processing According to the JMS Specification, the Java Message Service Specification (at http://www.oracle.com/technetwork/java/jms/index.html) 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 uniform distributed destination. If the WebLogic Path Service is configured for a uniform distributed destination, then the routing path to a member destination is determined by the server using the run-time load balancing heuristics for the distributed queue.

Using Hash-Based Routing

If the WebLogic Path Service is not configured, then the default routing path to a uniform queue member is chosen by the server based on the hash codes of the Message Unit-of-Order name and the uniform 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, then 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.

Configuring Routing on Uniform Distributed Destinations

See the following topics to configure either the Path service or hash-based routing mechanism on uniform distributed destinations using Message 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. Because 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.

Unit-of-Order and Distributed Topics

The routing of messages between physical topics can affect Unit-of-Order if an application directly sends to a member of a distributed topic. To ensure correct order of processing, the application must ensure the messages are sent using the logical distributed topic (that is, the destination is obtained using the JNDI name of the distributed topic). WebLogic Server then ensures messages with the same Unit-of-Order take the same path to the distributed topic member.

Unit-of-Order, Topics, and Message Driven Beans

The WebLogic Server message-driven bean implementation goes beyond the requirements of the EJB and JMS specifications to provide parallel processing of an incoming message stream for a single topic subscription and JMS session. This parallel processing does not take Unit-of-Order into account by default for the non-transactional case, so care is required to ensure that the processing is still ordered correctly.

When using Unit-of-Order with topics and non-transactional message driven beans, apply one or more of the following to ensure that the UOO ordering contract is honored:

  • Use a Non-Default Message Distribution Policy: Set the Topic Message Distribution Policy to either One Copy Per Server or One Copy Per Application. See Setting Message Distribution Tuning in Developing Message-Driven Beans for Oracle WebLogic Server.

  • Enable Container-Managed Transactions: See Configuring Transaction Management Strategy for an MDB in Developing Message-Driven Beans for Oracle WebLogic Server. If performance is a concern, you may want to consider additionally enabling transaction batching, which can mitigate the performance impact and often yields better performance than the non-transactional case. See Use Transaction Batching in Tuning Performance of Oracle WebLogic Server.

  • Set Pool Size to One: Setting the pool size to one has a drastic effect on parallelism. See the description for max-beans-in-free-pool element in Deployment Elements and Annotations for MDBs in Developing Message-Driven Beans for Oracle WebLogic Server.

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 enables 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:

  1. Pause the source destination and the target destination.

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

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

  4. Resume the source and target destinations.

For more information, see "Troubleshooting WebLogic JMS" in Administering JMS Resources for Oracle WebLogic Server.

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 Administering the Store-and-Forward Service for Oracle WebLogic Server.

Using Unit-of-Order with WebLogic Messaging Bridge

If both the source and target destinations are WebLogic Server 9.0 or later 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 Administering WebLogic Tuxedo Connector for Oracle WebLogic Server.

Limitations of Message Unit-of-Order

Understand the limitations 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 before than WebLogic 9.0 or non-WebLogic JMS providers).