OpenSOAP Logo

OpenSOAP Project
The Middleware as Platform for IT Application Services


-About OpenSOAP


-Known Bugs


Japanese version

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.

  1. 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).
  2. 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.
  3. 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

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 "".
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 "".
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 "". 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.

OpenSOAP Transaction Request Message Specification

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.

SOAP Envelope sent to Bank A after request message divisioning

Ex. 2. The SOAP Envelope sent to Bank A after a division of the request message

Response from Bank A example

Ex. 3(A). Example response from Bank A

Communication with Bank B example

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.

Commit request to Bank A from transaction process

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.

Transaction process result returned to the client

Ex. 5 The transaction process result returned to the client.

Copyright (C) 2001-2004 Webmasters of All Rights Reserved.