2016/05/28 - Apache Tuscany has been retired.

Overview

A typical enterprise application accesses and stores information in one or more databases. Data integrity is
the most essential aspect of correct business functioning. Transactions control the concurrent access of data
by multiple programs. In the event of a system failure, transactions make sure that after recovery the data will
be in a consistent state. This document helps to understand transaction management in RDB DAS.

One DAS instance is always associated with one database and one Connection. DAS participates in
A> DAS managed and B> Externally managed transactions.

DAS managed transactions

By default, the RDB DAS assumes responsibility for managing transaction boundaries by executing commit and
rollback operations against the database. A configuration attribute managedtx is assumed with default value
TRUE. This signals DAS to control the transaction. The boundaries of these transactions are as follows:

Reading Data
Queries to the database are always made by calling DAS command's "executeQuery()" method. The associated
transaction lives for the duration of this method execution. That is, the transaction can be thought to start
when control is transferred to "executeQuery" and the transaction ends just prior to return from this method.

Writing Data
Writes can be accomplished by two DAS APIs. First is calling the DAS "execute()" command against a command the
will perform write operations and, in this case, the transaction boundaries are the same as read queries. That
is the transaction life matches the life of the "execute" processing. If the method returns without exception
then the application can assume that any changes were successfully committed to the database. If an exception is
returned then the changes will have all been rolled back.

The second API used by clients is the DAS applyChanges() method (see ChangeSummaryProcessing). Again, the
boundaries of the transaction match the boundaries of the call to the method. The DAS will create a set of
INSERT/UPDATE and DELETE statements to flush the graph changes to the database and all of these statements
will be executed as part of a single transaction. If the method returns without exception then the application
can assume that all changes were successfully committed to the database. If an exception is returned then the changes
will have all been rolled back.

Use

This mode is useful for simple data operations, where there is no need of having group of SQL statements or group of DAS
Commands in one transaction unit. At the maximum one applyChanges() call having multiple INSERT/UPDATE/DELETE executes
under one transaction. Cases where multiple applyChanges() method calls or multiple executeQuery() method calls are
required to be part of one transaction, this mode is not useful. In this mode, the database Connection can be internally
obtained using DAS Config ConnectionInfo settings or database Connection can also be passed from the client to DAS instance.
When DAS obtains database Connection internally, in Config ConnectionInfo, settings can either specify DataSource name or
Database Driver related information. Typical examples -

• When using Tomcat based web app with DAS, Tomcat configured DataSource name is set in the DAS Config.
• When using J2SE application client with DAS, Database Driver related information from DAS Config is used to form a database Connection.

When multiple SQL statements/DAS commands need to be part of one transaction and also when multiple DAS instances need to participate
in one transaction, the other mode "Externally managed transactions" is useful.

Externally managed transactions

The RDB DAS provides a straightforward mechanism for working with external transactions. In this mode, DAS is configured to not issue
commit/rollback. This behavior is needed to have the DAS participate in a larger transaction since some external party is responsible
for these actions.

Use

The scope of transaction support is a blend of Supports and Mandatory transaction attributes in J2EE scenario. i.e. DAS will use the
client's transaction if it is available. DAS does not throw exception if external client transaction is not available, but the end result
without external transaction is unpredictable. So, when using DAS in this mode, client needs to ensure availability of external transaction
encompassing required DAS/s commands. External transaction can be JDBC transaction or JTA transaction.

When JDBC transaction, it is possible to group multiple Commands from single DAS instance in one transaction. Also nested transactions using
multiple DAS instances can be carried out. AS JTA does not support nested transactions, if nested transactions is the requirement, JDBC
Transactions should be used. For example:-

Das1 = DAS.FACTORY.createDAS(jdbcconn1);
Das2 = DAS.FACTORY.createDAS(jdbcconn2);

try {
     doSomeDAS1Stuff();
        doSomeDAS2Stuff();
        jdbcconn2.commit();
     doSomeDAS1Stuff();
     jdbcconn1.commit();
} catch (AnyException ex) {
     jdbcconn1.rollback();
     jdbcconn2.rollback();
}

When JTA transaction, multiple units like JMS, DAS1(derbydatabase1), DAS2(derbydatabase2/mysqldatabase2) can be part of single transaction.
See example:-

tx.begin();
try {
     doSomeJMSStuff();
     doSomeDAS1Stuff();
     doSomeDAS2Stuff();
     tx.commit();
} catch (AnyException ex) {
     tx.rollback();
}

In both the examples above, the DAS1 and DAS2 have been configured to not manage transactions since this is handled by the calling program.
The DAS is set to behave this way by a piece of configuration (typically via a configuration xml file). The following config file snippet
illustrates this setting:

<Config xsi:noNamespaceSchemaLocation="http:///org.apache.tuscany.das.rdb/config.xsd"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

        <ConnectionInfo managedtx="false"/>

</Config>

Note When using DAS with "Externally managed transactions", it is required by the client to pass appropriate Connection object to DAS
instance. There is no meaning to forming Connection internally in DAS using Config info, as such Connections will not be part of external
Transaction Control.

Methods Not Used in Externally managed transactions
DAS does not invoke any method that might interfere with the transaction boundaries set by the Transaction Manager. The list of prohibited
methods follows:

• The commit, setAutoCommit, and rollback methods of java.sql.Connection
• The getUserTransaction method of javax.ejb.EJBContext
• Any method of javax.transaction.UserTransaction

Note DAS never allows AutoCommit(TRUE) for the Connection it is using and throws Exception if this mode is detected.