OpenSOAP Transaction Document
The Transaction Management Service can be found at src/tools/Transaction in the OpenSOAP package distribution.
A sample client money transaction service is included in the samples/Transaction directory.
1. Outline
Simply, the OpenSOAP Transaction Service (transaction service) is realized as a 2-phase commitment transaction as outlined in the following procedure.
- In accordance with the specification, several request messages in their respective SOAP Bodyblocks contained in the
SOAP message(SOAP Envelope) are received from the client(Ex. 1). These request messages are used to generate their respective
Envelopes(Ex. 2) and are sent to their specified URLs(endpoint).
- The transaction service receives a response message in accordance with the specification from each of its corresponding
services, and based on the success or failure of the service process resends a COMMIT request or ROLLBACK request.
- The response message from each service and the overall process result (COMMIT or ROLLBACK) is sent to the client.
The Transaction Service has the following characteristics.
- In conjunction with the OpenSOAP Server, the client is capable of receiving the final response message asynchronously.
- Allows future compatiblity for long transactions or complex processing based on independent extensible message specification.
- The OpenSOAP Security functionality can be used as is.
OpenSOAP Transaction Overview
To use the Transaction Service, the client and the services connected to the Transaction Service
must be compatible with the Transaction Service.
2. Client Specification (Request Message)
The client must be capable of sending a request message in accordance to the following specifications.
2.1. Transaction Control Description Block
The first Bodyblock <TransactionControl> contained in the Body of the request message (<SOAP-ENV:Body>) is required (Ex. 1).
It is desireable that the namespace of the <TransactionControl> Block be set to "http://services.opensoap.jp/transaction/".
The block contains the exact number of services relevant to the transaction processing, and it
is required to list these sub-elements in the order required for processing these requests.
The <endpoint> element, for each service, contains the URL to which is sent the SOAP message used for the transaction process.
Also, a characteristic optional attribute value "transactionRequestID" is added to each request process.
Also, the process settings having to do with the transaction processing are described in this block.
(In the Beta Version, only the element is implemented)
2.2. Transaction Header Block
If message header part that is to be sent to each service exists, then the transaction header block <TransactionHeaderBlock>
elements can be defined(Ex. 1). The elements defined in this part are included as the SOAP message header block
(immediately below the <SOAP-ENV:Header> block) to be sent to each service. It is desired that namespace of the
<TranscationHeaderBlock> be set to "http://services.opensoap.jp/transaction/".
Each <TransactionHeaderBlock> block is required to have a corresponding "transactionRequestID" attribute value
of the <TransactionControl> block <endpoint> element added to it. For the 2nd and successive Bodyblocks of the
<TransactionHeaderBlock>, the ordering is irrelevant.
2.3. Transaction Body Block
The message body part that should be sent to each of the services, is defined as transaction body block
<TransactionBodyBlock> element. The elements defined in this part are inserted as SOAP message body blocks
(immediately below the <SOAP-ENV:Body> block)to be sent to each service.
It is desired that namespace of the <TransactionBodyBlock> be set to "http://services.opensoap.jp/transaction/".
It is required that corresponding <endpoint> "transactionRequestID" attribute value of the <TransactionControl>
block be added to each <TransactionBodyBlock>. As for the <TransactionHeaderBlock>, in the <TransactionBodyBlock>,
2nd and successive Bodyblock ordering is irrelevant.
Ex. 1. OpenSOAP Transaction Request Envelope
Example of a transaction illustrating a withdrawl request to Bank A, followed by a deposit request to Bank B.
3. Transaction Compatible Service Specification
The services relevant to the OpenSOAP Transaction Service, the specification for the client generated SOAP message
(Header Block, Body Block Content), and the service functions made available to the client along with connecting
to the transaction service must comply with the specification listed below.
3.1. Request Processing Response
Every Envelope, generated seperately according to the transaction service(Ex. 2) is sent to its corresponding endpoint.
Every service performs its request processing according to the Envelope, saves the process status so a Rollback is possible,
and returns a response message(Ex. 3) to the transaction service.
The specification of the response message from every service can be independent, however, a process result
description element <TranscationResult> must be included immediately below the first Body Block.
The <TransactionResult>, conveys the success of that services and is defined as "SUCCESS".
Any other character sequence, or the return of a <SOAP-ENV:Fault> from the service, is an indication of
service failure or rejection by the service.
Also, the distinguishing characteristic ID attribute value "transactionID" of the service can be appended to the
<TransactionResult>. If this "transactionID" attribute is used, if a COMMIT or ROLLBACK request is received from
the transaction service in the next step, it is possible to make adjustment within the service.
Ex. 2. The SOAP Envelope sent to Bank A after a division of the request message
Ex. 3(A). Example response from Bank A
Ex. 3(B). Example of communication with Bank B
3.2. COMMIT or ROLLBACK request
On receiving a successful response("SUCCESS") from the service process, the transaction service sends the next request
to the corresponding service in the order defined by the <TransactionControl> Block.
In the case where all services return a SUCCESS response, the transaction service again sends, to each of the service
endpoints, a COMMIT request message with the attached "transactionID" attribute(Ex. 4) and makes a decision to execute the series of processes.
If a failure is returned before all the services have responded with a SUCCESS message, the group of services that had responded with
a SUCCESS are sent a ROLLBACK request message with the attached "transactionID" attribute.
3.3. Process Conclusion
On receiving a COMMIT request, the service executes the requested operation and terminates.
On receiving a ROLLBACK request, the service deletes the requested operation and does not execute it.
Furthermore, the transaction service returns a SOAP message indicating the outcomes of all completed processes.
Ex. 4. COMMIT Request to Bank A from transaction service
4. Client Response
The transaction service combines the results of a series of process into 1 Envelope (Ex. 5), ans is returns it to the client.
The first Body Block of the SOAP Message, the <TransactionResponse> BLOCK, contains an account of the overall result of the
transaction and is indicated as a COMMIT or ROLLBACK.
Subsequent Body Blocks are comprised of the corresponding blocks returned from each of the services as follows:
Response Message Header Block ->
Body Block ->
Furthermore, on the transmission of a COMMIT or ROLLBACK, the same attribute value as that in the attached request
message attribute "transactionRequestID" is added to the of the response message body block.
Ex. 5 The transaction process result returned to the client.
Copyright (C) 2001-2004 Webmasters of www.opensoap.jp. All
Rights Reserved.
|