XML Transactions for Web Services, Part 3
by Faheem Khan
|
Pages: 1, 2, 3
Listing 1
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<SOAP:Body>
<wscoor:CreateCoordinationContext>
<wscoor:ActivationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/activation
</wsu:Address>
</wscoor:ActivationService>
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
</wscoor:CreateCoordinationContext>
</SOAP:Body>
</SOAP:Envelope>
Listing 1 is very similar to step 1 of Exchange of Messages in Atomic Transactions section in the second article, where we created a new AT. The only differences are the following:
-
This time the address of the coordinator's activation
service is
http://www.AFictitiousDistributor.com/WSTM/activation(look at the content of thewsu:Addresselement within thewscoor:ActivationServiceelement in Listing 1). -
Similarly, this time the address of the requester is
http://www.AFictitiousDistributor.com/purchase(look at the content of thewsu:Addresselement within theRequesterReferenceelement). -
Also notice the contents of the
wscoor:CoordinationTypeelement. This time the content ishttp://schemas.xmlsoap.org/ws/2002/08/wsba, which is the identifier string for business activities.
2. The coordinator's activation service responds with a
CreateCoordinationContextResponse message as
shown in Listing 2. The
CreateCoordinationContextResponse element in Listing 2 wraps two child
elements. The first child is a
RequesterReference element, while the second
child is a CoordinationContext element. We
described both these elements in detail in the second article
in step 2 of the Exchange of Messages in Atomic
Transactions section, when the coordinator responded
after instantiating a new AT.
Listing 2
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:CreateCoordinationContextResponse
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationContext>
<wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786
</wsu:Identifier>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/registration
</wsu:Address>
</wscoor:RegistrationService>
</wscoor:CoordinationContext>
</wscoor:CreateCoordinationContextResponse>
</SOAP:Body>
</SOAP:Envelope>
3. Now the purchase module of the distributor creates a new BA,
representing the first item of the purchase order. For this
purpose, it sends another
CreateCoordinationContext message (as shown in
Listing 3) to the
coordinator's activation service.
Listing 3
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:CreateCoordinationContext
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:ActivationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/activation
</wsu:Address>
</wscoor:ActivationService>
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<pcdc:NestedCreate
wsu:MustUnderstand="true"
xmlns:pcdc=
"http://www.AFictitiousDistributor.com/schemas/coordinator"
parentIdentifer=
"http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786"
relationship="PurchaseActivityToItem" />
</wscoor:CreateCoordinationContext>
</SOAP:Body>
</SOAP:Envelope>
Listing 3 is similar to Listing 1, except that the
CreateCoordinationContext element in Listing 3 has a
NestedCreate child element. Notice that the
NestedCreate element belongs to the distributor's
own namespace
(http://www.AFictitiousDistributor.com/schemas/coordinator). This
is an extensibility mechanism allowed by the WS-Transaction
specification. Applications can use their own elements within
the CreateCoordinationContext message to identify
the relationship between parent and child business activities.
The NestedCreate element in Listing 3 specifies that the
CreateCoordinationContext message is requesting to
create a child activity of an existing parent BA whose
identifier is
http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786. The
relationship attribute of the
NestedCreate element. belongs to the distributor's
own namespace and states that the relationship between the
parent and child business activities will be that of a purchase
order and an item of a purchase order.
I have also included a wsu:MustUnderstand attribute
in the NestedCreate element. It is mandatory for
this extension element to contain the
wsu:MustUnderstand="true" attribute, so that
implementations who do not understand this attribute return a
standard SOAP Misunderstood fault. The purpose of
including this NestedCreate element is to let the
coordinator know that we want to create a new child activity of
the parent BA whose identifier is
http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786.
4. The coordinator responds with a
CreateCoordinationContextResponse message as
shown in Listing 4.
Listing 4
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:CreateCoordinationContextResponse
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationContext>
<wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item1OfPurchaseOrderActivity786
</wsu:Identifier>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/registration
</wsu:Address>
</wscoor:RegistrationService>
</wscoor:CoordinationContext>
</wscoor:CreateCoordinationContextResponse>
</SOAP:Body>
</SOAP:Envelope>
5--8. Similarly, the purchase module creates two more child
activities within the scope of the parent activity that the
purchase module created in steps 1 and 2. Listing 5 is the
CreateCoordinationContext request for a business
activity related to item 2, while Listing 6 is the corresponding
response. Listing 7 is the
CreateCoordinationContext request for a business
activity related to item 3, while Listing 8 is the corresponding
response.
Listing 5
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:CreateCoordinationContext
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:ActivationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/activation
</wsu:Address>
</wscoor:ActivationService>
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<pcdc:NestedCreate
wsu:MustUnderstand="true"
xmlns:pcdc=
"http://www.AFictitiousDistributor.com/schemas/coordinator"
parentIdentifer=
"http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786"
relationship="PurchaseActivityToItem" />
</wscoor:CreateCoordinationContext>
</SOAP:Body>
</SOAP:Envelope>
Listing 6
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:CreateCoordinationContextResponse
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationContext>
<wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item2OfPurchaseOrderActivity786
</wsu:Identifier>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/registration
</wsu:Address>
</wscoor:RegistrationService>
</wscoor:CoordinationContext>
</wscoor:CreateCoordinationContextResponse>
</SOAP:Body>
</SOAP:Envelope>
Listing 7
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:CreateCoordinationContext
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:ActivationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/activation
</wsu:Address>
</wscoor:ActivationService>
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<pcdc:NestedCreate
wsu:MustUnderstand="true"
xmlns:pcdc=
"http://www.AFictitiousDistributor.com/schemas/coordinator"
parentIdentifer=
"http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786"
relationship="PurchaseActivityToItem" />
</wscoor:CreateCoordinationContext>
</SOAP:Body>
</SOAP:Envelope>
Listing 8
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:CreateCoordinationContextResponse
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousDistributor.com/purchase
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinationContext>
<wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item3OfPurchaseOrderActivity786
</wsu:Identifier>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/registration
</wsu:Address>
</wscoor:RegistrationService>
</wscoor:CoordinationContext>
</wscoor:CreateCoordinationContextResponse>
</SOAP:Body>
</SOAP:Envelope>
I have created four business activities so far. The identifier
for the parent purchase order activity is
http://www.AFictitiousDistributor.com/WSTM/ids/PurchaseOrderActivity786. The
purchase order business activity contains three child
activities, one for each item to be procured. The identifiers
for the three child business activities are
http://www.AFictitiousDistributor.com/WSTM/ids/Item1OfPurchaseOrderActivity786,
http://www.AFictitiousDistributor.com/WSTM/ids/Item2OfPurchaseOrderActivity786,
and
http://www.AFictitiousDistributor.com/WSTM/ids/Item3OfPurchaseOrderActivity786
for items 1, 2, and 3 respectively.
9. Now the purchase module of the PC distributor sends an
application specific message (shown in Listing 9) to the sales module
of the PC assembler. The message will convey that the distributor
wants to order item 1 to the PC Assembler. Notice from Listing 9 that the SOAP Body
contains the application specific message, while the SOAP Header
contains a CoordinationContext element related to
the business activity representing the purchase of first item of
the purchase order.
Listing 9
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<SOAP:Header>
<wscoor:CoordinationContext>
<wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item1OfPurchaseOrderActivity786
</wsu:Identifier>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/registration
</wsu:Address>
</wscoor:RegistrationService>
</wscoor:CoordinationContext>
</SOAP:Header>
<SOAP:Body>
<!--An application specific message from the distributor’s purchase module
to the PC assembler's sales module.-->
</SOAP:Body>
</SOAP:Envelope>
10. The PC assembler's sales module now registers the business
activity for item 1, so that it can perform
the actual in-house AT as described in the second article. So it
sends a Register message to the coordinator. The
Register message is shown in Listing 10, which is very
similar to the Register message that we discussed
in point number 3 of the section Exchange of Messages in
Atomic Transactions in the second article. Why did the
sales module register for the business activity
related to the first item? The simple reason is that the sales
module has a role to play in this activity. And WS-Coordination
does not allow participants to play roles (i.e. participate) in
coordinated activities without registering.
Listing 10
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:Register
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/registration
<wsu:Address>
</wscoor:RegistrationService>
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousPCAssembler.com/sales
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:ProtocolIdentifier>
http://schemas.xmlsoap.org/ws/2002/08/wsba/BusinessAgreement
</wscoor:ProtocolIdentifier>
<wscoor:ParticipantProtocolService>
<wsu:Address>
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
</wsu:Address>
</wscoor:ParticipantProtocolService>
</wscoor:Register>
</SOAP:Body>
</SOAP:Envelope>
Notice the ProtocolIdentifier element in Listing 10, which wraps the
URI
http://schemas.xmlsoap.org/ws/2002/08/wsba/BusinessAgreement. This
URI is the identifier of the BusinessAgreement protocol. The PC
assembler's sales module wants to register for the
BusinessAgreement protocol. The WS-Transaction specification
defines two BA protocols, BusinessAgreement and
BusinessAgreementWithComplete.
11. The coordinator sends a RegisterResponse
message (Listing 11) in
response to the Register request of Listing 10.
Listing 11
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:RegisterResponse
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousPCAssembler.com/sales
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinatorProtocolService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/coordinationservice
</wsu:Address>
</wscoor:CoordinatorProtocolService>
</wscoor:RegisterResponse>
</SOAP:Body>
</SOAP:Envelope>
12. Now the sales module of the PC Assembler is ready to perform an in-house AT to fulfill the requirements of supplying item 1 to the distributor. Notice that I'm assuming that the AT concludes successfully, so that the PC Assembler can tell the distributor that it can deliver item 1 on time.
The PC assembler registered for the BusinessAgreement protocol in step 10. This protocol means that the application registering for the protocol will immediately start working on the task, without waiting to receive any further instructions. That's why the sales module started working on the in-house AT immediately after getting registered.
On the other hand, if the sales module had registered for the
BusinessAgreementWithComplete protocol, the coordinator would
have sent a Complete message to the sales module,
without which the sales module would not have started performing
any work on the business task. This is the only difference
between BusinessAgreement and BusinessAgreementWithComplete
protocols. (In an attempt to match step numbers with listing
numbers, I am omitting some listing numbers. There is neither a
Listing nor a step 12.)
13. Now the PC Assembler's sales module sends a
Completed message (Listing 13) to the
purchase module of the distributor. Notice that Listing 13 contains only
two child elements namely TargetProtocolService
and SourceProtocolService. We have already
discussed these two elements in point number 15 of the
section Exchange of Messages in Atomic Transactions
in the second article.
Listing 13
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<SOAP:Body>
<wsba:Completed
xmlns:wsba="http://schemas.xmlsoap.org/ws/2002/08/wsba">
<wsba:TargetProtocolService>
<wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
</wsu:Address>
</wsba:TargetProtocolService>
<wsba:SourceProtocolService>
<wsu:Address>
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
</wsu:Address>
</wsba:SourceProtocolService>
</wsba:Completed>
</SOAP:Body>
</SOAP:Envelope>
14--16. Listing 14, Listing 15, and Listing 16 perform the same operation for item 2 of the purchase order that Listing 9, Listing 10, and Listing 11 did for item 1. The distributor's purchase module sends an application specific message (Listing 14) to of the PC assembler's sales module and the sales module registers for the business activity (Listing 15 and Listing 16).
Listing 14
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<SOAP:Header>
<wscoor:CoordinationContext>
<wsu:Identifier>
http://www.AFictitiousDistributor.com/WSTM/ids/Item2OfPurchaseOrderActivity786
</wsu:Identifier>
<wscoor:CoordinationType>
http://schemas.xmlsoap.org/ws/2002/08/wsba
</wscoor:CoordinationType>
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousDistributor.com/WSTM/registration
</wsu:Address>
</wscoor:RegistrationService>
</wscoor:CoordinationContext>
</SOAP:Header>
<SOAP:Body>
<!--An application specific message from the distributor’s purchase module
to the PC assembler's sales module.-->
</SOAP:Body>
</SOAP:Envelope>
Listing 15
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:Register
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RegistrationService>
<wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/registration
<wsu:Address>
</wscoor:RegistrationService>
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousPCAssembler.com/sales
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:ProtocolIdentifier>
http://schemas.xmlsoap.org/ws/2002/08/wsba/BusinessAgreement
</wscoor:ProtocolIdentifier>
<wscoor:ParticipantProtocolService>
<wsu:Address>
http://www.AFictitiousPCAssembler.com/sales/BusinessAgreement
</wsu:Address>
</wscoor:ParticipantProtocolService>
</wscoor:Register>
</SOAP:Body>
</SOAP:Envelope>
Listing 16
<?xml version="1.0"?>
<SOAP:Envelope
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<wscoor:RegisterResponse
xmlns:wscoor="http://schemas.xmlsoap.org/ws/2002/08/wscoor"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<wscoor:RequesterReference>
<wsu:Address>
http://www.AFictitiousPCAssembler.com/sales
</wsu:Address>
</wscoor:RequesterReference>
<wscoor:CoordinatorProtocolService>
<wsu:Address>
http://www.AFictitiousPCDistributor.com/WSTM/coordinationservice
</wsu:Address>
</wscoor:CoordinatorProtocolService>
</wscoor:RegisterResponse>
</SOAP:Body>
</SOAP:Envelope>