XML Transactions for Web Services, Part 2
by Faheem Khan | Pages: 1, 2

Exchange of Messages in Atomic Transactions

Look at Figure 1, which graphically depicts the exchange of messages that takes place in our AT scenario. Figure 1 shows all the actors that participate in the AT (the coordinator and the various modules of the PC assembler's enterprise). Messages are shown as numbered arrows. Each message of Figure 1 is explained below:

1. The sales module initiates a new AT by sending a CreateCoordinationContext SOAP message to the coordinator as shown in Listing 1. The CreateCoordinationContext message is sent inside the SOAP:Body element as a normal web service method invocation call.

The CreateCoordinationContext message contains three child elements, all of which belong to the WS-Coordination namespace. The WS-Transaction specification uses the WS-Coordination features for several jobs. The creation of a new coordination (or transactional) context is one such job.

The first child, the ActivationService element, contains the address of the activation server. The activation server is part of the coordinator (or you can say that activation is one of the services provided by the coordinator). The activation server is responsible for creating new transactional contexts.

The second child, the RequesterReference element, contains the address of the application that requested the creation of the new transaction context. In this case, the sales module is making this request, so the RequesterReference element refers to the sales module.

Notice the use of "http://schemas.xmlsoap.org/ws/2002/07/utility" namespace in these listings. It's just a helper namespace to wrap some low level information such as addresses. Both WS-Coordination and WS-Transaction often use this namespace.

The third child is the CoordinationType element, which contains the information about what type of coordination the new context will perform. The content of this element is a URI, "http://schemas.xmlsoap.org/ws/2002/08/wstx". This URI string is the identifier for AT. This means that the new context will coordinate an AT.

In the next part of this series, we'll see that the WS-Transaction specification also defines another type of transaction, a Business Activities (BA), which is very different from AT and is identified by a different URI.

2. The coordinator sends Listing 2 to the sales module in response to Listing 1. Listing 2 is a SOAP response which carries a CreateCoordinationContextResponse element in its body. The CreateCoordinationContextResponse element has two children.

The first child is the RequesterReference element, which is exactly the same as the one we mentioned in step 1 (address of the sales module).

The second child is the CoordinationContext element, which is perhaps the most important element in our discussion. This element is actually a wrapper for all the information that specifies the newly created coordination context. The CoordinationContext contains three child elements:

The first child is an Identifier element that carries a transaction identifier. Every transaction should have a unique identifier, which all participants will use in their activities relating to the particular transaction.

The second child is the CoordinationType element that is exactly the same as the one we explained in step 1 (the content of this element is a URI, which is an identifier for ATs).

The third child is the RegistrationService element that refers to an address. This address is the port where a registration server is listening. The requesting application (the sales module) and all other participants will use this address to register their respective roles in the transaction.

Activation and registration are two services provided by the coordinator. Participating applications use activation service to create a new transactional context and registration service to register their respective roles in the transaction.

The CoordinationContext element wraps three important bits of information: the transaction identifier, the type of transaction, and the address of the registration service.

3. On receipt of the SOAP response of Listing 2, the sales module needs to register for its role in the AT. So it sends a registration request to the coordinator. Listing 3 shows the registration request, which is a simple SOAP request carrying the Register method invocation call in its body. The Register request carries four bits of information, each as a child element.

The first child of the Register element is the RegistrationService element, which is the same as the one we came across in step 2. It carries the address of the port where the registration service of the coordinator can be reached.

The second child of the Register element is the RequesterReference element. Again this element is identical to the one we saw in steps 1 and 2.

The third child element is a ProtocolIdentifier element. It identifies the protocol (or the role) for which the participating application wants to register for. The content of the ProtocolIdentifier element is a URI (http://schemas.xmlsoap.org/ws/2002/08/wstx/Completion), which is the identifier for the completion protocol.

The fourth child is a ParticipantProtocolService element, which specifies the address of the port where the participating application has implemented its side of the protocol. Recall that all five protocols described in the last section are two-party communication protocols. One of the two parties is the coordinator and the other party is the participant. The ParticipantProtocolService element specifies the address of the second party.

4. The coordinator's registration service responds with a message that will mark the end of successful registration process. Listing 4 shows the RegisterResponse element wrapped inside the SOAP body. The RegisterResponse element has only two child elements.

The first child is the RequesterReference element, which is same as of steps 1, 2 and 3.

The second child is the CoordinatorProtocolService element, which specifies the address of the port at which the coordinator has implemented its side of the protocol. In step 3, the ParticipantProtocolService element specifies the participant side of the two-party communication protocol. In step 4, the CoordinatorProtocolService element specifies the coordinator side of the same protocol.

Some readers may object to Listings 3 and 4 for not containing enough information to uniquely identify the transaction instance that Listings 3 and 4 are meant to register for. This is an ambiguity that the current WS-Coordination and WS-Transaction specifications do not address. But the WS-Coordination specification does include an editor's note that suggests that this ambiguity will be addressed in a future update of the specification (refer to section 8.1, Appendix A of the WS-Coordination specification).

For now you can implement your own (application specific) methodology to identify the transaction instance. Perhaps the best way to do this is to include a transaction identifier within the ParticipantProtocolService element in Listing 3 and the CoordinatorProtocolService element in Listing 4. That would enhance the way port addresses are specified or referenced. In fact the editor's note mentioned suggests that the future update will enhance the way port addresses are referenced.

5. According to the business logic of our application, sales is not the only module that takes part in this AT. There are other intended participants of this AT. Now is time for the sales module to send some application specific messages to other intended participants. Listing 5 shows a generic message, which will be sent to the inventory, assembly line management, and account modules. Notice that Listing 5 wraps the application specific message in its body, while a CoordinationContext element (the same as the one we described in step 2) is wrapped inside the SOAP:Header element. The application specific body of the message will convey what the intended participant is supposed to do in the AT (e.g. that the inventory module is supposed to check the availability of components).

The SOAP:Header element is a part of the SOAP extensibility framework. This means that SOAP allows the development of SOAP-based protocols, which will use the SOAP:Header element to wrap protocol specific information. Many such protocols are emerging which use the SOAP:Header element to convey protocol specific information in application messages. WS-Coordination is one such protocol. Another is the Web Services Security (WSS) specification, which adds security information to the SOAP:Header element (refer to the Resources section for more information on WSS).

We have shown just one application specific message being sent by the sales module to other intended participants. In actual practice there may be any number of such messages. However, all messages should include the CoordinationContext element inside their SOAP:Header elements. This way the CoordinationContext element is used to propagate transaction information to other participants.

6. On receipt of Listing 5 the inventory module needs to register for the same transaction. So it sends a register message to the coordinator. Listing 6 shows that register message. Notice that the register message of Listing 6 is similar to the register message of Listing 3. The only differences are the address of the requesting application (this time the address is of the inventory module) and the protocol for which the inventory module wants to register (this time it is the PhaseZero protocol). Recall from our discussion in the last section that the inventory module will register for the PhaseZero protocol.

7. The coordinator will respond with the RegisterResponse message as shown in Listing 7. Listing 7 is similar to Listing 4, which is already explained in step 4.

8 and 9. These two steps are similar to 6 and 7. The PC assembler module also registers for the PhaseZero protocol. See the exchange of Listings 8 and 9.

10 and 11. The accounts module also registers for the same transaction. As already explained, the role of the accounts module is as a silent listener. So it registers for the OutcomeNotification protocol. See the exchange of Listings 10 and 11.

12. Now the inventory module sends an application specific message (Listing 12) to the database module. Notice that Listing 12 is similar to Listing 5 (the SOAP message that carries the coordination context in its header and an application specific message in its body).

13 and 14. The database module registers for the 2PC protocol in the same transaction. See the exchange of Listings 13 and 14.

15. Since all the relevant parties now know what they are supposed to do in this transactionm and they all have registered with the coordinator, it's time for the sales module to try to commit the AT. The sales module will send a commit request to the coordinator as shown in Listing 15. The Commit element in Listing 15 belongs to the WS-Transaction namespace (http://schemas.xmlsoap.org/ws/2002/08/wstx). Notice that there are only two child elements of the Commit element. The two child elements represent the two sides of the completion protocol that the sales module registered for in step 3. As the commit request is going from the sales module to the coordinator, so the source of the commit request is the sales module and the target of the request is the coordinator.

The first child of the Commit element is the TargetProtocolService element, which specifies the target of this commit request. The TargetProtocolService element contains the same address of the coordinator service that the coordinator exchanged with the sales module by sending the CoordinatorProtocolService element in Listing 4.

The second child is the SourceProtocolService element, which specifies the source of this request. The SourceProtocolService element contains the address of the port where the sales module has implemented its side of the completion protocol. Recall from step 3 that the sales module sent this address to the coordinator (the address was wrapped inside the ParticipantProtocolService element of Listing 3).

16. On receipt of the commit request of Listing 15, the coordinator initiates the commit sequence. The first step is the PhaseZero protocol. So the coordinator will check which of the participants have registered for the PhaseZero protocol. In our case, inventory and assembly line management modules have registered for the PhaseZero protocol. Therefore, the coordinator sends a PhaseZero message to the inventory module, as shown in Listing 16.

17. As already explained in the last section, the PhaseZero protocol provides an opportunity for middleware applications to flush outstanding data updates to resource managers. On receipt of Listings 16, the inventory module will flush any outstanding data to the database module in an application specific message as shown in Listing 17.

The SOAP:Header element in Listing 17 carries the CoordinationContext element of Listing 2, so that the database module knows which transactional context it should write to.

18. When the inventory module has successfully flushed the data to the database module, it will send a PhaseZeroCompleted message (Listing 18) to the coordinator, thus telling the coordinator that it has fulfilled its responsibility for the PhaseZero protocol.

19, 20 and 21. Similarly, the coordinator sends a PhaseZero message (Listing 19) to the assembly line management module. The assembly line management module flushes any outstanding data updates to the database module in an application specific message of Listing 20 and then sends a PhaseZeroComplete message (Listing 21) back to the coordinator.

22. Now the coordinator knows that PhaseZero is complete. So it will initiate the 2PC sequence. Only one participant (the database module) has registered for the 2PC protocol. So the coordinator will send a Prepare message (Listing 22) to the database module. Recall from our discussion in the last section that prepare is the first of the two phases in the 2PC sequence.

23. On receipt of the Prepare message of Listing 22, the database module will check if the changes required by the transaction will produce any problem in its back-end data storage. For example, if the assembly line is fully booked or the required components are not available in stock, the database module will not be able to commit the required transaction.

If everything is found to be in order, the inventory module will send a Prepared message (Listing 23) back to the coordinator.

24. Now the coordinator will issue a Commit message (Listing 24) to the database module (the second phase in the 2PC sequence).

25. The database module will make the actual changes in the database (book the components for this order and book the assembly line as well). Once the changes have been made, the database module will send a Committed message (Listing 25) back to the coordinator.

26. Now the coordinator sends a Committed message (Listing 26) back to the sales module, thus notifying that the transaction has been successfully completed.

27. The coordinator checks whether there is any participant which has registered for the OutcomeNotificaton protocol. The accounts module registered for the OutcomeNotification protocol. So the coordinator sends a Committed message (Listing 27) to the accounts module.

28. The accounts module responds with a Notified message (Listing 28), thus acknowledging receipt of the transaction outcome notification.

In the next part of this series, we will see what happens if things go wrong. Does AT rollback mean that we lose this business opportunity? There should be ways to compensate for rolled back transactions. For example, we might want to buy components from vendors if they are not available in stock. These questions lead us to Business Activities (BA), which I will examine in the next article, particularly how a BA crosses the boundaries of trusted domains.

Resources

• Check out the official WS-Coordination and WS-Transaction specifications.
• Business Transaction Protocol (BTP) by OASIS is another XML-based protocol that manages transactions. Check out the main BTP page at OASIS web site.
• This article discusses the use of database transactions in Java.
• This two-part series of articles (Part 1 and Part 2 ) gives a high level overview of WS-Coordination and WS-Transaction.
• We mentioned the Web Services Security (WSS) specification in this article. Check out the main page for the WSS specification at OASIS web site.

---

---

2. An interaction is missing ?
   2003-05-01 11:00:17 Jean-Philippe Martin