Package de.aristaflow.adept2.core.transactionmanager

Interface TxManager<T>

Type Parameters:

T - The type of objects that start and end transactions.

public interface TxManager<T>

This class wraps a JDBCDataSource and provides the means for implicit hierarchical transactions and sharing connections. Each connection is bound to an object. If this object requests another connection, the very same connection (and thus the same transaction) will be used. This allows for spanning a transaction over several method calls without the need for the connection being a method parameter. This TxManager manages committing and rolling back appropriately, that is, a hierarchical connection will not be committed before the topmost starter commits.
There are two different operation modes for transactions: hierarchical and sharing. Hierarchical transactions are simulated via flat transactions (one top-level) where subtransactions use savepoints for rolling back. This isolates subtransactions from transactions on a higher level – as good as possible with the underlying flat transactions. In contrast sharing transactions are not hierarchical, the very same (top-level) transaction is used for subtransactions; subtransactions are only logical. The operation mode is specified when requesting the top-level transaction.
With hierarchical as well as sharing transactions, a failing substransaction needs to notify the caller! With hierarchical transactions, the caller has to either to compensate for the subtransaction going forward, or rolling back the own (sub-)transaction and propagating this upward. When rolling back a sharing subtransaction, this will implicitly rollback the top-level transaction and therefore no caller can work any more with this transaction.
Each started transaction can be explicitly committed or rolled back. But on each level a transaction has been started, it needs to be finished (which also commits) or closed (which rolls back). However, due to the hierarchical nature, the complete transaction will not be committed or rolled back before the topmost starter of the transaction finishes or closes it. For allowing rolling back transactions on a lower level, starting a transaction on a lower level will create a savepoint. When closing or rolling back such a transaction, only the savepoint will be rolled back.
Committing and rolling back can be done several times on the same level without starting a new transaction. You may also finish a transaction and start a new one. But this may be the very same connection in case the corresponding object has started a transaction on a higher level.

When starting a transaction, the caller can specify the desired isolation level and whether the transaction is read-only. If this is not specified, the default value set in the constructor or the default value from the underlying database will be used. If subsequent starters of the same transaction (using the same object) provide a more restrictive isolation level or want to get a writable transaction that is already read-only, an InvalidOptionsException will be thrown immediately. This also applies to hierarchical transactions. If subsequent starters want a hierarchical transaction but the top-level transaction has been started as non-hierarchical, an InvalidOptionsException will be thrown immediately. This does not apply for subsequent non-hierarchical based and a hierarchical top-level transaction.

Use the following usage pattern (or something similar) for appropriate clean-up of the resources:

 T ta; 
 Connection con = null;
 Statement stmt = null;
 ResultSet rs = null;
 try
 {
   con = txManager.startTransaction(ta);
   try
   {
     stmt = con.createStatement();
     rs = stmt.executeQuery(<query>);
   
     // read from the result set
   
     rs = txManager.close(rs);
     stmt = txManager.close(stmt);
     txManager.finishTransaction(ta);
     // These 3 lines may also be 1 line: txManager.finishTransaction(rs, stmt, ta);  
     // Now all three variables are null and the transaction will be finished
     // and cannot be used again. This will be handled appropriately in the finally-block.
   }
   finally
   {
     // This will only do something if the transaction has not been finished.
     txManager.closeTransaction(ta, stmt, rs);
   }
 }
 catch (SQLException ex) // the catch part is optional, depending on which exceptions your method may throw
 {
   throw new DataSourceException(ex);
 }
 

The minimal usage pattern is as follows:

 T ta;
 Connection con = null;
 try
 {
   con = txManager.startTransaction(ta);
   try
   {
   
     // do anything with the connection
   
     txManager.finishTransaction(ta);
   }
   finally
   {
     txManager.closeTransaction(ta);
   }
 }
 catch (SQLException ex) // the catch part is optional, depending on which exceptions your method may throw
 {
   throw new DataSourceException(ex);
 }
 

It is crucial for the hierarchical transaction handling that the transaction is finished and closed. If a transaction is closed without being finished, the transaction will be rolled back!

Transactions for remote iterators are potentially long-running and are therefore treated separately. Since they are used for retrieval of a lot of data, they are read-only and READ_COMMITTED. Each transaction will have its own connection. As soon as the remote iterator is created, it will handle closing the involved result set, statement and connection. However, before the remote iterator is created, the caller needs to handle clean-up. The usage pattern is similar:

 T ta;
 ManagedExtendedConnection con = null; 
 ManagedStatement stmt = null;
 ManagedResultSet rs = null;
 try
 {
   con = txManager.startIteratorTransaction(ta);
   try
   {
     stmt = con.createStatement();
     rs = stmt.executeQuery(<query>);
   
     // create the remote iterator
   
     // do not close result set or the statement and do not commit or rollback
     // the transaction
   
     // If you do not create a remote iterator, for instance, the result set is
     // empty, you will need to close explicitly.
     if (!creationSuccessful)
     {
       rs = txManager.close(rs);
       stmt = txManager.close(stmt);
       con = txManager.finishIteratorTransaction(con);
     }
   }
   finally
   {
     // This will only do something if the transaction has not been finished.
     // Otherwise the result set, statement and connection will be closed
     // when dropping all created remote iterator.
     txManager.closeIteratorTransaction(ta, rs, stmt);
   }   
 } 
 catch (SQLException ex) // the catch part is optional, depending on which exceptions your method may throw
 {
   throw new DataSourceException(ex);
 }
 

Note that the iterator transaction can be used for arbitrary read-only access before the remote iterator is created.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method	Description
<R extends ResultSet> R	close(R rs)	Closes the designated result set and returns null.
<S extends Statement> S	close(S stmt)	Closes the designated statement and returns null.
void	closeIteratorTransaction(ResultSet rs, Statement stmt, T o)	Closes the designated result set, the designated statement and the iterator transaction started for the designated object and rolls it back if no remote iterator exists.
void	closeIteratorTransaction(Statement stmt, T o)	Closes the designated statement and the iterator transaction started for the designated object and rolls it back if no remote iterator exists.
void	closeIteratorTransaction(T o)	Closes the iterator transaction started for the designated object and rolls it back if no remote iterator exists.
void	closeQuietly(ResultSet rs)	Closes the designated result set and ignores any exception.
void	closeQuietly(ResultSet rs, Statement stmt)	Closes the designated result set and the statement and ignores any exception.
void	closeQuietly(Statement stmt)	Closes the designated statement and ignores any exception.
void	closeTransaction(ResultSet rs, Statement stmt, T o)	Closes the designated result set, the designated statement and the transaction started for the designated object on the current level and rolls it back if not explicitly finished.
void	closeTransaction(Statement stmt, T o)	Closes the designated statement the transaction started for the designated object on the current level and rolls it back if not explicitly finished.
void	closeTransaction(T o)	Closes the transaction started for the designated object on the current level and rolls it back if not explicitly finished.
ExtendedConnection	commitTransaction(T o)	Commits the transaction started for the designated object.
<M extends ManagedExtendedConnection> M	finishIteratorTransaction(M con)	Finishes the iterator transaction of the designated connection.
void	finishTransaction(ResultSet rs, Statement stmt, T o)	Closes the designated result set, the designated statement and finishes the transaction started for the designated object on the current level.
void	finishTransaction(Statement stmt, T o)	Closes the designated statement and finishes the transaction started for the designated object on the current level.
void	finishTransaction(T o)	Finishes the transaction started for the designated object on the current level.
void	reserveConnection(T o, boolean readOnly)	Reserves a read-only or writable connection for the designated object.
void	reserveConnection(T o, boolean readOnly, boolean hierarchical)	Reserves a read-only or writable connection and possibly for a hierarchical transaction for the designated object.
void	reserveConnection(T o, boolean readOnly, boolean hierarchical, int isolation)	Reserves a read-only or writable connection and possibly for a hierarchical transaction for the designated object having the designated isolation level.
void	reserveConnection(T o, boolean readOnly, int isolation)	Reserves a read-only or writable connection for the designated object having the designated isolation level.
ExtendedConnection	rollbackTransaction(T o)	Rolls back the transaction started for the designated object.
ManagedExtendedConnection	startIteratorTransaction(T o)	Starts a new iterator transaction for the designated object and returns the corresponding connection.
ExtendedConnection	startTransaction(T o, boolean readOnly)	Starts a read-only or writable transaction for the designated object and returns the corresponding connection.
ExtendedConnection	startTransaction(T o, boolean readOnly, boolean hierarchical)	Starts a read-only or writable transaction and possibly a hierarchical transaction for the designated object and returns the corresponding connection.
ExtendedConnection	startTransaction(T o, boolean readOnly, boolean hierarchical, int isolation)	Starts a read-only or writable transaction and possibly a hierarchical transaction for the designated object having the designated isolation level.
ExtendedConnection	startTransaction(T o, boolean readOnly, int isolation)	Starts a read-only or writable transaction for the designated object having the designated isolation level.
void	unreserveConnection(T o)	Unreserves a connection for the designated object.

Method Detail

reserveConnection

void reserveConnection(T o,
                       boolean readOnly)
                throws SQLException

Reserves a read-only or writable connection for the designated object. This will use the default for the isolation level. If a read-only connection is requested, an existing writable connection may be reserved. If a new connection is used, it will be for sharing transactions.

Make sure to unreserve the connection!

Parameters:

o - The object for which to reserve a connection.

readOnly - A hint on whether the connection is read-only.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction/reserved connection is read-only but now a writable connection is requested, an InvalidOptionsException will be thrown.

reserveConnection

void reserveConnection(T o,
                       boolean readOnly,
                       boolean hierarchical)
                throws SQLException

Reserves a read-only or writable connection and possibly for a hierarchical transaction for the designated object. This will use the default isolation level. If a read-only connection is requested, an existing writable connection may be reserved. If a connection for sharing transaction is requested, an existing hierarchical connection may be reserved.

Make sure to unreserve the connection!

Parameters:

o - The object for which to start a transaction.

readOnly - A hint on whether the connection is read-only.

hierarchical - Whether subtransactions should be isolated from higher level transactions by using savepoints.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction/reserved connection is read-only but now a writable connection is requested or the previously created instance is sharing but now a connection for hierarchical transactions is requested, an InvalidOptionsException will be thrown.

reserveConnection

void reserveConnection(T o,
                       boolean readOnly,
                       int isolation)
                throws SQLException

Reserves a read-only or writable connection for the designated object having the designated isolation level. If a read-only connection is requested, an existing writable connection may be reserved. Additionally, the reserved connection may have a more restrictive isolation level. A new connection will be for a sharing transaction.

Make sure to unreserve the connection!

Parameters:

o - The object for which to start a transaction.

readOnly - A hint on whether the connection is read-only.

isolation - A hint on the desired isolation level.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction/reserved connection is read-only but now a writable connection is requested or the requested isolation level is more restrictive than the one already set previously for the connection, an InvalidOptionsException will be thrown.

reserveConnection

void reserveConnection(T o,
                       boolean readOnly,
                       boolean hierarchical,
                       int isolation)
                throws SQLException

Reserves a read-only or writable connection and possibly for a hierarchical transaction for the designated object having the designated isolation level. If a read-only connection is requested, an existing writable connection may be reserved. If a connection for sharing transaction is requested, an existing hierarchical connection may be reserved. Additionally, the reserved connection may have a more restrictive isolation level.

Make sure to unreserve the connection!

Parameters:

o - The object for which to reserve a connection.

readOnly - A hint on whether the connection is read-only.

hierarchical - A hint on whether subtransactions should be isolated from higher level transactions by using savepoints.

isolation - A hint on the desired isolation level.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction/reserved connection is read-only but now a writable connection is requested or the requested isolation level is more restrictive than the one already set previously for the connection or the previously created instance is sharing but now a connection for hierarchical transactions is requested, an InvalidOptionsException will be thrown.

unreserveConnection

void unreserveConnection(T o)
                  throws SQLException

Unreserves a connection for the designated object. This will release the connection from the designated object and close it unless there are transactions or connection reservations on higher levels.

Parameters:

o - The object for which to unreserve a connection.

Throws:

SQLException - If there are problems closing the connection, an SQLException will be thrown.

startTransaction

ExtendedConnection startTransaction(T o,
                                    boolean readOnly)
                             throws SQLException

Starts a read-only or writable transaction for the designated object and returns the corresponding connection. This is either a new connection or the connection for a transaction already started for the designated object. If a new connection is used, the default for the isolation level will be used. If a read-only transaction is requested, an existing writable connection may be returned. If a new connection is used, it will be a sharing transaction.

Parameters:

o - The object for which to start a transaction.

readOnly - A hint on whether the transaction is read-only.

Returns:

A new connection or the connection already started for the designated object.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction is read-only but now a writable transaction is requested, an InvalidOptionsException will be thrown.

startTransaction

ExtendedConnection startTransaction(T o,
                                    boolean readOnly,
                                    boolean hierarchical)
                             throws SQLException

Starts a read-only or writable transaction and possibly a hierarchical transaction for the designated object and returns the corresponding connection. This is either a new connection or the connection for a transaction already started for the designated object. If a new connection is used, the default for the isolation level will be used. If a read-only transaction is requested, an existing writable connection may be returned. If a sharing transaction is requested, an existing hierarchical connection may be returned.

Parameters:

o - The object for which to start a transaction.

readOnly - A hint on whether the transaction is read-only.

hierarchical - Whether subtransactions should be isolated from higher level transactions by using savepoints.

Returns:

A new connection or the connection already started for the designated object.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction is read-only but now a writable transaction is requested or the previously created instance is sharing but now a hierarchical transaction is requested, an InvalidOptionsException will be thrown.

startTransaction

ExtendedConnection startTransaction(T o,
                                    boolean readOnly,
                                    int isolation)
                             throws SQLException

Starts a read-only or writable transaction for the designated object having the designated isolation level. This is either a new connection or the connection for a transaction already started for the designated object. If a read-only transaction is requested, an existing writable connection may be returned. Additionally, the reused connection may have a more restrictive isolation level. A new connection will be a sharing transaction.

Parameters:

o - The object for which to start a transaction.

readOnly - A hint on whether the transaction is read-only.

isolation - A hint on the desired isolation level.

Returns:

A new connection or the connection already started for the designated object.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction is read-only but now a writable transaction is requested or the requested isolation level is more restrictive than the one already set previously for the transaction, an InvalidOptionsException will be thrown.

startTransaction

ExtendedConnection startTransaction(T o,
                                    boolean readOnly,
                                    boolean hierarchical,
                                    int isolation)
                             throws SQLException

Starts a read-only or writable transaction and possibly a hierarchical transaction for the designated object having the designated isolation level. This is either a new connection or the connection for a transaction already started for the designated object. If a read-only transaction is requested, an existing writable connection may be returned. If a sharing transaction is requested, an existing hierarchical connection may be returned. Additionally, the reused connection may have a more restrictive isolation level.

Parameters:

o - The object for which to start a transaction.

readOnly - A hint on whether the transaction is read-only.

hierarchical - A hint on whether subtransactions should be isolated from higher level transactions by using savepoints.

isolation - A hint on the desired isolation level.

Returns:

A new connection or the connection already started for the designated object.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidOptionsException - If the previously created transaction is read-only but now a writable transaction is requested or the requested isolation level is more restrictive than the one already set previously for the transaction or the previously created instance is sharing but now a hierarchical transaction is requested, an InvalidOptionsException will be thrown.

close

<S extends Statement> S close(S stmt)
                       throws SQLException

Closes the designated statement and returns null. This allows for the intended usage pattern (see class description).

Parameters:

stmt - The statement to be closed.

Returns:

null if closing was successful, the designated statement otherwise.

Throws:

SQLException - If there are problems closing the designated statement, an SQLException will be thrown.

close

<R extends ResultSet> R close(R rs)
                       throws SQLException

Closes the designated result set and returns null. This allows for the intended usage pattern (see class description). This does not need to be called for a result set that is part of a remote iterator.

Parameters:

rs - The result set to be closed.

Returns:

null if closing was successful, the designated result set otherwise.

Throws:

SQLException - If there are problems closing the designated result set, an SQLException will be thrown.

commitTransaction

ExtendedConnection commitTransaction(T o)
                              throws SQLException

Commits the transaction started for the designated object. In case a transaction is hierarchical and has been started for the designated object on a higher level, it will not commit yet but release the savepoint.

Parameters:

o - The object for which to commit a transaction.

Returns:

The connection for the designated object.

Throws:

SQLException - If there are problems committing the transaction (or releasing the savepoint), an SQLException will be thrown.

rollbackTransaction

ExtendedConnection rollbackTransaction(T o)
                                throws SQLException

Rolls back the transaction started for the designated object. In case a transaction is hierarchical and has been started for the designated object on a higher level, it will not rollback the transaction but the savepoint.
Since rolling back usually is done in case of problems, the rollback should either be handled directly which usually requires starting a new transaction. Or the problem has to be indicated to the caller so that the problem can be handled on a higher level. This in turn can lead to a rollback or calling an alternative method.

Parameters:

o - The object for which to rollback a transaction.

Returns:

The connection for the designated object.

Throws:

SQLException - If there are problems rolling back the transaction (or the savepoint), an SQLException will be thrown.

finishTransaction

void finishTransaction(T o)
                throws SQLException

Finishes the transaction started for the designated object on the current level. The transaction will be committed. This has to be called on the same level where the transaction has been started so that the transaction hierarchy can be handled appropriately.

Parameters:

o - The object for which to finish and commit a transaction.

Throws:

InvalidServiceUsageException - If no transaction has been started for the designated object, an InvalidServiceUsageException will be thrown.

SQLException - If there are problems finishing and committing the transaction (or releasing the savepoint), an SQLException will be thrown.

finishTransaction

void finishTransaction(Statement stmt,
                       T o)
                throws SQLException

Closes the designated statement and finishes the transaction started for the designated object on the current level. The transaction will be committed. This has to be called on the same level where the transaction has been started so that the transaction hierarchy can be handled appropriately.

Parameters:

stmt - The statement to be closed.

o - The object for which to finish and commit a transaction.

Throws:

InvalidServiceUsageException - If no transaction has been started for the designated object, an InvalidServiceUsageException will be thrown.

SQLException - If there are problems closing the statement or finishing and committing the transaction (or releasing the savepoint), an SQLException will be thrown.

finishTransaction

void finishTransaction(ResultSet rs,
                       Statement stmt,
                       T o)
                throws SQLException

Closes the designated result set, the designated statement and finishes the transaction started for the designated object on the current level. The transaction will be committed. This has to be called on the same level where the transaction has been started so that the transaction hierarchy can be handled appropriately.

Parameters:

rs - The result set to be closed.

stmt - The statement to be closed.

o - The object for which to finish and commit a transaction.

Throws:

SQLException - If there are problems closing the statement, the result set or finishing and committing the transaction (or releasing the savepoint), an SQLException will be thrown.

closeQuietly

void closeQuietly(Statement stmt)

Closes the designated statement and ignores any exception. This is for use in a finally-block and allows for the intended usage pattern (see class description).

Parameters:

stmt - The statement to be closed without exception.

closeQuietly

void closeQuietly(ResultSet rs)

Closes the designated result set and ignores any exception. This is for use in a finally-block and allows for the intended usage pattern (see class description).

Parameters:

rs - The result set to be closed without exception.

closeQuietly

void closeQuietly(ResultSet rs,
                  Statement stmt)

Closes the designated result set and the statement and ignores any exception. This is for use in a finally-block and allows for the intended usage pattern (see class description).

Parameters:

rs - The result set to be closed without exception.

stmt - The statement to be closed without exception.

closeTransaction

void closeTransaction(T o)

Closes the transaction started for the designated object on the current level and rolls it back if not explicitly finished. This has to be called in a finally-block to clean up the resources and will only apply in case an exception skipped the normal finishing.
No exception will leave this message to prevent hiding other exceptions that lead to skipping transaction finishing.

Parameters:

o - The object for which to close and rollback a transaction if not finished normally.

closeTransaction

void closeTransaction(Statement stmt,
                      T o)

Closes the designated statement the transaction started for the designated object on the current level and rolls it back if not explicitly finished. This has to be called in a finally-block to clean up the resources and will only apply in case an exception skipped the normal finishing.
No exception will leave this method to prevent hiding other exceptions that lead to skipping transaction finishing.

Parameters:

stmt - The statement to be closed without exception.

o - The object for which to close and rollback a transaction if not finished normally.

closeTransaction

void closeTransaction(ResultSet rs,
                      Statement stmt,
                      T o)

Closes the designated result set, the designated statement and the transaction started for the designated object on the current level and rolls it back if not explicitly finished. This has to be called in a finally-block to clean up the resources and will only apply in case an exception skipped the normal finishing.
No exception will leave this method to prevent hiding other exceptions that lead to skipping transaction finishing.

Parameters:

rs - The result set to be closed without exception.

stmt - The statement to be closed without exception.

o - The object for which to close and rollback a transaction if not finished normally.

startIteratorTransaction

ManagedExtendedConnection startIteratorTransaction(T o)
                                            throws SQLException

Starts a new iterator transaction for the designated object and returns the corresponding connection. An iterator transaction is a potentially long-lasting transaction for usage in remote iterator and therefore read-only and having isolation level READ_COMMITTED. It is always sharing.

Parameters:

o - The object for which to start an iterator transaction.

Returns:

A new connection or the connection already started for the designated object.

Throws:

SQLException - If there are problems creating a connection, an SQLException will be thrown.

InvalidServiceUsageException - If there is still an iterator transaction open for this object, an InvalidServiceUsageException will be thrown.

closeIteratorTransaction

void closeIteratorTransaction(T o)

Closes the iterator transaction started for the designated object and rolls it back if no remote iterator exists. This has to be called in a finally-block to clean up the resources and will only apply in case an exception skipped the normal finishing. If a remote iterator has been created successfully, the transaction will be closed when dropping its last remote iterator.
No exception will leave this message to prevent hiding other exceptions that lead to skipping transaction finishing.

Parameters:

o - The object for which to close and rollback an iterator transaction if no remote iterator exists.

closeIteratorTransaction

void closeIteratorTransaction(Statement stmt,
                              T o)

Closes the designated statement and the iterator transaction started for the designated object and rolls it back if no remote iterator exists. This has to be called in a finally-block to clean up the resources and will only apply in case an exception skipped the normal finishing. If a remote iterator has been created successfully, the statement and the transaction will be closed when dropping its last remote iterator.
No exception will leave this message to prevent hiding other exceptions that lead to skipping transaction finishing.

Parameters:

stmt - The statement to be closed without exception if no remote iterator exists.

o - The object for which to close and rollback an iterator transaction if no remote iterator exists.

closeIteratorTransaction

void closeIteratorTransaction(ResultSet rs,
                              Statement stmt,
                              T o)

Closes the designated result set, the designated statement and the iterator transaction started for the designated object and rolls it back if no remote iterator exists. This has to be called in a finally-block to clean up the resources and will only apply in case an exception skipped the normal finishing. If a remote iterator has been created successfully, the result set, the statement and the transaction will be closed when dropping its last remote iterator.
No exception will leave this message to prevent hiding other exceptions that lead to skipping transaction finishing.

Parameters:

rs - The result set to be closed without exception if no remote iterator exists.

stmt - The statement to be closed without exception if no remote iterator exists.

o - The object for which to close and rollback an iterator transaction if no remote iterator exists.

finishIteratorTransaction

<M extends ManagedExtendedConnection> M finishIteratorTransaction(M con)

Finishes the iterator transaction of the designated connection. The transaction will be committed. This is implicitly called by the connection as soon as its last remote iterator is dropped. Call this explicitly if no remote iterator has been created.

Parameters:

con - The connection for which all remote iterator have been dropped.

Returns:

null if closing was successful, the designated managed extended connection otherwise.