11 Using Unit-of-Work Message Groups
Learn how to use Unit-of-Work Message Groups to provide groups of messages when using WebLogic JMS.
What Are Unit-of-Work Message Groups?
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.
The Unit-of-Work (UOW) Message Groups can be used when applications need an even more restricted notion of a group than provided by the Message Unit-of-Order (UOO) feature. For example, a JMS producer can designate a set of messages that must 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
Understand the basic UOW terminology and the rules for processing UOW messages.
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 must 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 shown 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 (that is 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 needs to 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 time to deliver 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.
-
All Messages Required For Processing
No message within the UOW will be available until all of them are available on the terminal destination.
-
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.
-
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).
-
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 make up 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 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, she 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 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.
Figure 11-1 and the 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 Workflow for Jill's Order Using Unit-of-Work"
-
Jill clicks the order button from her shopping cart.
-
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.
-
-
The terminal Megazon queue gathers the three UOW messages before forming them into an
ObjectMessage
list for delivery to Megazon's invoice consumer client. -
Jill receives an invoice that shows her entire order was processed.
How to Create a Unit-of-Work Message Group
Learn how to set UOW message properties for a message consumer and producer.
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:
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 |
JMS_BEA_UnitOfWorkSequenceNumber |
An integer property that is set by the standard JMS mechanism for setting properties. For example:
The valid 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:
When this property is set to 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 Example 11-2copies 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, butSequenceNumber
is not or (b) theSequenceNumber
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 theUnitOfOrder
property set and theUnitOfWork
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 WebLogic Server 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
|
Specifies whether the Unit-of-Work (UOW) feature is enabled for a destination.
|
Expiration time for incomplete UOW Messages
|
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 after the first UOW message arrives. This field is effective only if Unit-of-Work Handling Policy is set to Note: If an expiration time is not configured on terminal destination, then 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 about configuring unit-of-work parameters on standalone destinations, distributed destinations, or JMS templates using the WebLogic Server Administration Console, see the following sections in the Oracle WebLogic Server Administration Console Online Help:
For more information about these parameters, see DestinationBean
and TemplateBean
in the MBean Reference for Oracle WebLogic
Server.
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 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 sample UOW consumer code in Example 11-3 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
Learn 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 or not the messages are delivered as one message. 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, because the messages must 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 independently of the component messages. For example, the virtual message cannot get its value for delivery count from a component message. This is the list of property values that are system-generated:
-
Timestamp
-
Delivery count (redelivered)
-
Destination
Final Component Message Properties
The message properties will be derived from the component messages. However, different properties get values derived in different ways. 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 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
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, because this configuration may 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
Understand the limitations when using Unit-of-Work message groups.
-
JMS clients created using WebLogic Server earlier than 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, because 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 maximum 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 large giant message on the server before they are pushed to the consumer, rather than streamed.