|
|
The following sections describe how to use Unit-of-Work Message Groups to provide groups of messages when using WebLogic JMS:
Many applications need an even more restricted notion of a group than provided by the Message Unit-of-Order (UOO) feature. Therefore, release 9.2 introduces 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.
| Caution: | 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 Unit-of-Work to provide strict message grouping when using WebLogic JMS:
These sections provide basic conceptual information about UOW message groups.
Table 11-1 defines the terms used to define UOW.
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.
|
|
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.
|
|
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 and/or Producer For an Intermediate 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.
|
|
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.
|
The following rules apply to UOW messages.
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.
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:
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.
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.
ObjectMessage list for delivery to Megazon’s invoice consumer client.
The following sections describe how to create a Message Unit-of-Work.
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-2 set by the producer client.
|
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, BEA recommends using a Java universally unique identifier (UUID). See
http://java.sun.com/j2se/1.5.0/docs/api/java/util/UUID.html.
|
|
If the UnitOfWork property is not set, then SequenceNumber and End will be ignored.
The following sample client code sample sets the UOW properties defined in Table 11-2.
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);
}
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.| Tip: | 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. |
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-2.
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.
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).
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 Administration Console Online Help:
For more information about these parameters, see
DestinationBean and
TemplateBean in the WebLogic Server MBean Reference.
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 Destinationsin Programming WebLogic JMS.
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.
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.
{
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);
The following sections describe how Unit-of-Work processes messages in advanced or more complex situations.
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.
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:
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:
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:
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.
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.
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-Forwardin Programming WebLogic JMS.
This section provides additional general information to consider when using UOW.
|