11 Using Unit-of-Work Message Groups

The following sections describe how to use Unit-of-Work Message Groups to provide groups of messages when using WebLogic JMS:

What Are Unit-of-Work Message Groups?

Many applications need an even more restricted notion of a group than provided by the Message Unit-of-Order (UOO) feature. If this is the case for your applications, WebLogic JMS provides the Unit-of-Work (UOW) Message Groups, which allows applications to send JMS messages, identifying some of them as a group and allowing a JMS consumer to process them as such. For example, an JMS producer can designate a set of messages that need to be delivered to a single client without interruption, so that the messages can be processed as a unit. Further, the client will not be blocked waiting for the completion of one unit when there is another unit that is already complete.

Note:

It is a programming error to use both the Unit-of-Order and Unit-of-Work features on the same JMS message.

The following sections describe how to use Message UOW to provide strict message grouping when using WebLogic JMS:

Understanding Message Processing With Unit-of-Work

These sections provide basic conceptual information about UOW message groups.

Basic UOW Terminology

Table 11-1 defines the terms used to define UOW.

Table 11-1 Unit-of-Work Terminology

Term Definition

Unit-of-Work (UOW)

A set of JMS messages that need to be processed as a single unit.

UOW Component Message

A message that is part of a UOW. In order for WebLogic JMS to identify a message as part of a UOW, the message must have the JMS properties described in How To Write a Producer to Set UOW Message Properties.

UOW Producer

A producer that needs to split its work into multiple parts (i.e., a creator of a UOW). Multiple producers can concurrently contribute component messages to a UOW message, as illustrated in Message Unit-of-Work Case Study.

If fact, a UOW producer can close midway through a UOW and a new producer can complete the UOW message, while maintaining the same strict component message integrity (e.g., detect duplicates, etc.).

Intermediate Destination

A destination whose consumers have the job of processing component messages separately rather than as a unit. No special UOW configuration is required for intermediate destinations.

When a component message arrives on an intermediate destination it will be made available without waiting for other component messages to arrive. Further, if the intermediate destination is a distributed destination, no special routing need occur. See How to Write a UOW Consumer/Producer For an Intermediate Destination.

Terminal Destination

A destination whose consumers have the job of processing a full UOW. A destination is identified as a terminal destination by the Unit-of-Work Message Handling Policy parameter on standalone destinations, distributed destinations, or JMS templates. See Configuring Terminal Destinations.

Available/Visible Messages

Equivalent JMS terms that refer to a message becoming ready for consumption, pending the reception of any messages that precede it. For example, a JMS message is not available until its birth time has been reached or a JMS message that is sent as part of a transaction is not visible until that transaction is committed.


Rules For Processing UOW Messages

The following rules apply to UOW messages.

  • Rule One: All Messages Required For Processing

    No message within the UOW will be available until all of them are available on the terminal destination.

  • Rule Two: Message Reordering

    No matter what order the messages arrive to the terminal destination, they will be put into the order specified by the UOW producer.

  • Rule Three: Gap Freedom

    The group of messages will be delivered to the user without gaps. That is, all messages in the group will be delivered to the user before messages from any other group (or part of no group at all).

  • Rule Four: Single Consumer Consumption

    The group of messages will be delivered to the same consumer.

Message Unit-of-Work Case Study

This section provides a simple case study for Message Unit-of-Work based on an online order that requires a variety of merchandise from multiple companies.

Jill Orders Miscellaneous Items From an Online Retailer

The Megazon online retailer implements a processing design that uses JMS to process customer orders for a variety of merchandise, some of which need to be routed to Megazon's partner companies to complete the order. For example, Megazon can directly fulfill book orders, but must re-route some parts of the order for certain electronics or houseware items. Since Megazon is configured to use UOW, items in an order can be routed as UOW messages to these intermediate company destinations before being passed onto Megazon's terminal destination where all the UOW messages that comprise the order are gathered before a final invoice can be processed.

The Megazon JMS processing system is composed of:

  • A UOW producer sending order fulfillment component messages with the required UOW properties to the appropriate intermediate and/or terminal destinations.

  • Intermediate destinations for non-book items, where UOW component messages are processed by consumer and/or producer clients before being passed onto the final UOW destination.

  • A UOW terminal destination where the component messages are gathered for final processing.

Jill logs into her Megazon account and does some holiday shopping. She chooses a book, flash drive, MP3 player, and a lava lamp and then proceeds to the checkout, and completes the sales transaction.

How Message Unit-of-Work Completes the Order

To ensure that all messages in Jill's order are processed as a single unit, the order-taking JMS producer client sets UOW properties on her order messages to indicate that they are part of a single unit. These UOW message properties must also be copied by any consumer and/or producer clients listening on the intermediate Gadget Planet, Widget World, and Desperate Housewares destinations before they pass the UOW messages onto the terminal destination. Last, the system administrator for Megazon configures the terminal destination to UOW Message Handling Policy parameter to Single Message Delivery. See How to Create a Unit-of-Work Message Group.

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

Figure 11-1 Workflow for Jill's Order Using Unit-of-Work

Description of Figure 11-1 follows
Description of "Figure 11-1 Workflow for Jill's Order Using Unit-of-Work"

  1. Jill clicks the order button from her shopping cart.

  2. The order is split into three messages that use the same unique UOW name:

    • SEQ#1, which is routed to the intermediate Gadget Planet queue, where a consumer processes the Flash Drive order before passing SEQ#1 onto a producer who then routes it to the intermediate Widget World queue, where a consumer processes the MP3 player order before passing SEQ#1 to the terminal Megazon queue for final invoice processing.

    • SEQ#2, which is routed to the intermediate Desperate Housewares queue, where a consumer processes the lava lamp order before passing SEQ#1 onto a producer who routes it to the Megazon terminal processing queue for final invoice processing.

    • SEQ#3, which is routed directly to Megazon's terminal queue for book order fulfillment and for final invoice processing.

  3. The terminal Megazon queue gathers the three UOW messages before forming them into an ObjectMessage list for delivery to Megazon's invoice consumer client.

  4. Jill receives an invoice that shows her entire order has been processed.

How to Create a Unit-of-Work Message Group

The following sections describe how to create a Message Unit-of-Work.

How To Write a Producer to Set UOW Message Properties

UOW enables a producer to split its work into multiple parts to accomplish its goal. UOW is, in effect, taking these multiple messages and joining them into one. Whether component messages are delivered as parts of a single message or as many messages, it is easiest to envision them as a single virtual message, as well as individual messages.

In order for WebLogic JMS to identify a message as part of a UOW, the message must have the JMS properties in Table 11-1 set by the producer client.

Table 11-2 Unit-of-Work Properties

Type Description
JMS_BEA_UnitOfWork

A string property that is set by the standard JMS mechanism for setting properties. For example:

message.setStringProperty("JMS_BEA_UnitOfWork", "MyUnitOfWorkName")

To avoid naming conflicts, the UOW ID should never be reused. For example, if messages are lost or retransmitted, then they may be perceived as part of a separate UOW. For this reason, Oracle recommends using a Java universally unique identifier (UUID). See http://java.sun.com/j2se/1.5.0/docs/api/java/util/UUID.html.

JMS_BEA_UnitOfWorkSequenceNumber

An integer property that is set by the standard JMS mechanism for setting properties. For example,

message.setIntProperty("JMS_BEA_UnitOfWorkSequenceNumber", 5)

The legal values are integers greater than or equal to 1

JMS_BEA_IsUnitOfWorkEnd

A boolean property that is set by the standard JMS mechanism for setting properties. For example:

message.setBooleanProperty("JMS_BEA_IsUnitOfWorkEnd", true)

When this property is true, the message is the last in the unit-of-work. When this property is false or nonexistent, the message is not last in the unit-of-work.


If the UnitOfWork property is not set, then SequenceNumber and End will be ignored.

Example UOW Producer Code

The following sample client code sample sets the UOW properties defined in Table 11-1.

Example 11-1 Sample UOW Producer Message Properties

  for (int i=1; i<=100; i++)
  {
    sendMsg.setStringProperty("JMS_BEA_UnitOfWork","joule");
    sendMsg.setIntProperty("JMS_BEA_UnitOfWorkSequenceNumber",i);
    if (i == 100)
    {
      System.out.println("set the end of message flag for message # " + i);
      sendMsg.setBooleanProperty("JMS_BEA_IsUnitOfWorkEnd",true);
    }
    qSender.send(sendMsg, DeliveryMode.PERSISTENT,7,0);
  }

UOW Exceptions

The following exceptions may be thrown to the producer when sending JMS messages to a terminal destination. When a UOW exception is town, the UOW message is not delivered.

Except for the last one, they are all in the weblogic.jms.extensions package and are subclasses of JMSException.

  • BadSequenceNumberException – This will occur if (a) UnitOfWork is set on the message, but SequenceNumber is not or (b) the SequenceNumber is less than or equal to zero.

  • OutOfSequenceRangeException – This will be thrown if (a) a message is sent with a SequenceNumber that is higher than the sequence number of the message which has already been marked as the end of the unit or (b) a message is sent with a sequence number which is lower than a message which has already arrived in the same unit, yet the new message is marked as the end message.

  • DuplicateSequenceNumberException – This will be thrown to the producer if it sends a message with a sequence number which is the same as a previously sent message in the same UOW.

  • JMSException – A JMS exception will be thrown if a message has both the UnitOfOrder property set and the UnitOfWork property set.

    Note:

    As a programming best-practice, consider having your UOW producers send all component messages that comprise a new UOW under a single transaction. This way, either all of the work is completed or none of it is. For example, if a UOW producer gets an exception or crashes partway through a UOW and wants to then cancel the current UOW, then the entire transaction will be rolled back and the application will not need to make a decision for each message after a failure.

How to Write a UOW Consumer/Producer For an Intermediate Destination

An intermediate destination is one whose consumers have the job of processing component messages separately rather than as a unit. A JMS ForwardHelper extension API is available to assist developers who are writing producers and/or consumers at intermediate destinations. This is because there are many message properties that need to be copied from the incoming message to the outgoing message. For example, the message properties that control the behavior of UOW need to be copied.

The following intermediate consumer code sample copies the UOW properties defined in Table 11-1.

Example 11-2 Sample Client Code for UOW Intermediate Destination

    msg = qReceiver1.receive();
    try
    {
      text = msg.getText();
      TextMessage forwardmsg = qsess.createTextMessage();
      forwardmsg.setText(text);
      forwardmsg.setStringProperty("JMS_BEA_UnitOfWork",
                  msg.getStringProperty("JMS_BEA_UnitOfWork"));
      forwardmsg.setIntProperty("JMS_BEA_UnitOfWorkSequenceNumber",
                     msg.getIntProperty("JMS_BEA_UnitOfWorkSequenceNumber"));
      if (tm.getBooleanProperty("JMS_BEA_IsUnitOfWorkEnd"))
        forwardmsg.setBooleanProperty("JMS_BEA_IsUnitOfWorkEnd",
                  msg.getBooleanProperty("JMS_BEA_IsUnitOfWorkEnd"));
      qsend.send(forwardmsg);
    }

Note that the three UOW properties are copied from the incoming message to the outgoing message.

Configuring Terminal Destinations

A destination is identified as a terminal destination by the Unit-of-Work Message Handling Policy parameter on standalone destinations, distributed destinations, or JMS templates. There is also a parameter that allows for expiration of incomplete work on terminal destinations.

Using the Administration Console, these Advanced configuration options are available on the General Configuration page for all destination types (or by using the DestinationBean API), as well as on JMS templates (or by using the TemplateBean API).

Table 11-3 Unit-of-Work Configuration Options

Console Label/MBean Name Description

Unit-of-Work (UOW) Message Handling Policy

UnitOfWorkHandlingPolicy

Specifies whether the Unit-of-Work (UOW) feature is enabled for a destination.

  • Pass-Through – By default, destinations do not treat messages as part of a UOW.

  • Single Message Delivery – Select this option if UOW consumers are receiving component messages on this terminal destination. When selected, component UOW messages are formed into a list and are consumed as an ObjectMessage containing the java.util.list.

Expiration Time for Incomplete UOW Messages

IncompleteWorkExpirationTime

The maximum length of time, in milliseconds, before undeliverable messages in an incomplete UOW are expired. Such messages will then follow the expiration policy defined for undeliverable messages. Message expiration begins once the first UOW message arrives.

This field is effective only if Unit-of-Work Handling Policy is set to Single Message Delivery. The default value of -1 means that UOW messages will never expire.

Note: If an expiration time is not configured on terminal destination, it is possible for a UOW message to wait indefinitely on the destination when a component message was either: (A) never sent/committed, (B) expired, or (C) manually deleted).


For instructions on configuring unit-of-work parameters on a standalone destinations, distributed destinations, or JMS templates using the Administration Console, see the following sections in the Oracle WebLogic Server Administration Console Help:

For more information about these parameters, see DestinationBean and TemplateBean in the Oracle WebLogic Server MBean Reference.

UOW Message Routing for Terminal Distributed Destinations

The Unit-of-Order Routing field is used to determine the routing of UOW messages for uniform distributed destinations, using either the Path Service or Hash-based Routing. And similar to UOO, when a UOW terminal destination is also a distributed destination, all messages within a UOW must go to the same distributed destination member. For more information on the UOO routing mechanisms, see Using Unit-of-Order with Distributed Destinations.

However, basic UOO routing and UOW routing are not exactly the same. Strictly, all messages within a single UOO do not have to go to the same member: when there are no more unconsumed messages for a certain UOO, newly arrived messages can go to any member. In UOW, message routing must be guaranteed until the whole UOW has arrived at the physical destination and consumption is irrelevant.

How to Write a UOW Consumer For a Terminal Destination

The following sample UOW consumer code shows how a consumer listening on a terminal destination verifies that all component messages sent are contained within the final UOW message.

Example 11-3 Sample Client Code For UOW Terminal Destination

       {
        msg = qReceiver1.receive();
        if (msg != null)
        {
          count++;
          System.out.println"Message received: " + msg);
          //Check that this one message contains all the messages sent.
          ArrayList msgList = (ArrayList)(((ObjectMessage)msg).getObject());
          numMsgs = msgList.size();
          System.out.println("no. of messages in the msg = " + numMsgs);
        } 
       } while (msg != null);

Message Unit-of-Work Advanced Topics

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

Message Property Handling

UOW is, in effect, taking multiple messages and joining them into one. This is true whether the messages are delivered as one message or not. For example, each message will have an independent expiration time, but if one expires, none of them will ever be delivered. Therefore, as a best practice your message producers should make sure that messages that make up a UOW are as uniform as possible.

Whether component messages are delivered as parts of a single message or as many messages, it is easiest to envision them as a single virtual message, as well as individual messages. For example, since the messages need to be seen consecutively, UOW's effect on message sorting can be viewed as determining the correct placement of the virtual message. The same is true of message selection (a consumer must see the whole group or not see the group at all); WebLogic JMS must determine whether "consumer A must see the virtual message" before deciding to deliver all of the messages to consumer A.

System-Generated Properties

Some fields of the virtual message will need to be populated independent of the component messages. For example, the virtual message cannot get its value for delivery count from a component message. This is the complete list of property values that are system-generated:

  • Timestamp

  • Delivery count (redelivered)

  • Destination

Final Component Message Properties

Otherwise, the message properties will be derived from the component messages. However, different properties get values derived in different ways, as suits their nature. One way to derive virtual message properties is to get their values directly from one of the component messages (this simplifies the handling of component messages with different property values). For simplicity, the last message in the UOW is the message from which the values are derived. For example, the message priority for the virtual message will be the priority of the message marked as last (by having the property JMS_BEA_IsUnitOfWorkEnd set to true).

This is the complete list of virtual message properties that are derived from the values contained in the last message in the UOW:

  • Message ID

  • Correlation ID

  • Priority

  • User Properties

  • User ID

Component Message Heterogeneity

Another method for handling component message heterogeneity is to coerce all component messages into the same value. For example, as mentioned earlier, a mixture of expiration times doesn't make sense. This is the complete list of message properties that are handled in this way:

  • Delivery Mode

  • Expiration

ReplyTo Message Property

The ReplyTo property value is not reflected in the virtual message because it isn't used in message selection or sorting and is only useful to the application, and is therefore ignored.

UOW and Uniform Distributed Destinations

As discussed in UOW Message Routing for Terminal Distributed Destinations, the Unit-of-Order Routing field is used to determine the routing mechanism for UOW messages. One other requirement for UOW in distributed destinations is that all member destinations must have the same value for the UOW Handling Policy. A configuration that is configured otherwise is invalid.

As a best practice, the use of topics (especially distributed topics) is discouraged for use as intermediate UOW destinations, as this configuration may possibly lead to duplicate component messages.

UOW and Store-and-Forward Destinations

The WebLogic Store-and-Forward service supports UOW, with the exception that a store-and-forward (SAF) imported destination cannot be a terminal destination. However, SAF obeys the routing rules of UOW messages, just as it does for UOO messages. See Using Unit-of-Order with WebLogic Store-and-Forward.

Limitations of UOW Message Groups

This section provides additional general information to consider when using UOW.

  • JMS clients created using WebLogic Server prior to 9.0 cannot create messages that will be processed as part of a UOW.

  • The JMS C JNI client is not able to process UOW messages at a terminal destination, since they are object messages. It can, however, be used as a UOW producer or on an intermediate destination.

  • UOW is poorly suited for sets of large file transfers. Ideally, your messaging environment is configured for lower max message sizes and to facilitate the streaming transfer of large chunks of data (such as large files) from a single producer to a single consumer. UOW doesn't handle this use-case because the individual messages are accumulated back into one giant message on the server before they are pushed to the consumer, rather than streamed.