Adapter Development Kit 9.12 | webMethods Adapter Development Kit Documentation | webMethods Adapter Development Kit Installation and User’s Documentation | Integration Server Transaction Support | Explicit Transaction Usage Cases
 
Explicit Transaction Usage Cases
Adapter users must explicitly start and end each transaction, except the first one to include multiple local transactions in a single flow.
Depending on what the flow needs to accomplish, adapter users may explicitly start and end XAResource transactions as well. This way, the adapter users can create a flow that includes multiple local transactions and multiple XAResource transactions.
Integration Server provides the following built-in services to support multiple local transactions and multiple XAResource transactions:
*pub.art.transaction.startTransaction
*pub.art.transaction.commitTransaction
*pub.art.transaction.rollbackTransaction
*pub.art.transaction.setTransactionTimeout
For more information, see Built-In Services For Explicit Transactions.
For example, the following flow includes a local transaction nested within another local transaction:
BEGIN FLOW // start transaction 1
.
.
.
INVOKE startTransaction(2) // start transaction 2
.
.
.
INVOKE commitTransaction(2) // commit transaction 2
END FLOW // commit transaction 1
A nested transaction must adhere to the same rules that apply to container-manager transactions. That is, a nested transaction can contain one of the following:
*One local transaction, interacting with one resource.
*One or more XAResource transactions; each transaction can interact with one or more resources.
*One or more XAResource transactions and one local transaction.
Following are some examples of explicit transactions.
Two Local Transactions
To make this flow work properly, explicitly start and commit the nested local transaction, using the startTransaction and commitTransaction services as follows:
BEGIN FLOW // start transaction 1
INVOKE interactWithResourceA // service for transaction 1

INVOKE startTransaction(2) // start transaction 2
INVOKE interactWithResourceB // service for transaction 2
INVOKE commitTransaction(2) // commit transaction 2

END FLOW // commit transaction 1
The flow executes as follows:
1. When interactWithResourceA is invoked, Integration Server starts transaction 1 and enlists ResourceA.
2. Transaction 2 executes as follows:
a. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
b. When interactWithResourceB is invoked, ResourceB is enlisted in transaction 2.
c. When commitTransaction(2) is invoked, the connection to ResourceB is closed, and transaction 2 is committed. At this point, only the work done on ResourceB is committed; transaction 1 is still open, and the work done with ResourceA is not yet committed.
3. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to ResourceA.
Note:
Each transaction is a separate unit of work. Transaction 1 could be rolled back (or the commit could fail), while transaction 2 remains committed (or vice versa).
Alternatively, to achieve the same result, you can explicitly start transaction 1 before the adapter service is invoked, and explicitly commit it as follows:
BEGIN FLOW
INVOKE startTransaction(1) // start transaction 1
INVOKE interactWithResourceA // service for transaction 1
INVOKE startTransaction(2) // start transaction 2
INVOKE interactWithResourceB // service for transaction 2
INVOKE commitTransaction(2) // commit transaction 2
INVOKE commitTransaction(1) // commit transaction 1
END FLOW
Two XAResource Transactions
The following flow includes two XAResource transactions: one that interacts with ResourceA, and a nested transaction that interacts with ResourceB and ResourceC.
BEGIN FLOW // start transaction 1
INVOKE interactWithResourceA // service for transaction 1

INVOKE startTransaction(2) // start transaction 2
INVOKE interactWithResourceB // service for transaction 2
INVOKE interactWithResourceC // service for transaction 2
INVOKE commitTransaction(2) // commit transaction 2

END FLOW // commit transaction 1
The flow executes as follows:
1. When interactWithResourceA is invoked, Integration Server starts transaction 1 and enlists ResourceA.
2. Transaction 2 executes as follows:
a. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
b. When interactWithResourceB and interactWithResourceC are invoked, both resources are enlisted in transaction 2.
c. When commitTransaction(2) is invoked, the connections to ResourceB and ResourceC are closed, and transaction 2 is committed. At this point, only the work done on ResourceB and ResourceC is committed; transaction 1 is still open, and the work done with resourceA is not yet committed.
3. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to ResourceA.
One XAResource Transaction and Two Nested Local Transactions
The following flow includes three transactions: one XAResource transaction that interacts with two resources, and two nested local transactions that interact with one resource each.
BEGIN FLOW // start XAResource transaction 1
INVOKE interactWithXAResourceA // service for XAResource transaction 1
INVOKE interactWithXAResourceB // service for XAResource transaction 2
INVOKE startTransaction(2) // start local transaction 1
INVOKE interactWithLocalResourceA // service for local transaction 1
INVOKE commitTransaction(2) // commit local transaction 1
INVOKE startTransaction(3) // start local transaction 2
INVOKE interactWithLocalResourceB // service for local transaction 2
INVOKE commitTransaction(3) // commit local transaction 2
END FLOW // commit XAResource transaction 1
The flow executes as follows:
1. When interactWithXAResourceA is invoked, Integration Server starts transaction 1 and enlists XAResourceA.
2. When interactWithXAResourceB is invoked, Integration Server enlists XAResourceB in transaction 1.
3. Transaction 2 is executed as follows:
a. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
b. When interactWithLocalResourceA is invoked, LocalResourceA is enlisted in transaction 2.
c. When commitTransaction(2) is invoked, the connection to LocalResourceA is closed, and transaction 2 is committed. At this point, only the work done on LocalResourceA is committed; transaction 1 is still open, and the work done with XAResourceA and XAResourceB is not yet committed.
4. Transaction 3 is executed as follows:
a. When startTransaction(3) is invoked, Integration Server starts a new, nested transaction.
b. When interactWithLocalResourceB is invoked, LocalResourceB is enlisted in transaction 3.
c. When commitTransaction(3) is invoked, the connection to LocalResourceB is closed, and transaction 3 is committed. At this point, only the work done on LocalResourceA and LocalResourceB is committed; transaction 1 is still open, and the work done with XAResourceA and XAResourceB is not yet committed.
5. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to XAResourceA and XAResourceB.
One XAResource Transaction and One Nested Local and XAResource Transaction
The following flow includes two transactions: one XAResource transaction that interacts with two resources, and one nested transaction that interacts with one local resource and one XAResource.
BEGIN FLOW // start XAResource transaction 1
INVOKE interactWithXAResourceA // service for XAResource transaction 1
INVOKE interactWithXAResourceB // service for XAResource transaction 2

INVOKE startTransaction(2) // start transaction 2
INVOKE interactWithLocalResourceA // service for transaction 2
INVOKE interactWithXAResourceC // service for transaction 2
INVOKE interactWithLocalResourceA // service for transaction 2
INVOKE commitTransaction(2) // commit transaction 2

END FLOW // commit XAResource transaction 1
The flow executes as follows:
1. When interactWithResourceA is invoked, Integration Server starts an XAResource transaction 1 and enlists ResourceA.
2. When interactWithXAResourceB is invoked, Integration Server enlists XAResourceB in transaction 1.
3. Transaction 2 is executed as follows:
a. When startTransaction(2) is invoked, Integration Server starts a new, nested transaction.
b. When interactWithLocalResourceA is invoked, LocalResourceA is enlisted in transaction 2.
c. When interactWithXAResourceC is invoked, XAResourceC is enlisted in transaction 2.
d. When interactWithLocalResourceA is invoked, LocalResourceA is enlisted in transaction 2.
e. When commitTransaction(2) is invoked, the connection to both resources of transaction 2 is closed, and transaction 2 is committed. At this point, only the work done on LocalResourceA and XAResourceC is committed; transaction 1 is still open, and the work done with XAResourceA and XAResourceB is not yet committed.
4. When the flow ends, Integration Server closes the connection for transaction 1 and commits its work to XAResourceA and XAResourceB.