Class Transaction<T>
Allows for the syntactically simple use of database transactions within the
ActiveObjects API. This class's syntax is modeled after the transaction
do ... end
syntax provided by Rails's ActiveRecord ORM. The intention
is to provide the simplest possible encapsulation around the transaction
functionality. As such, AO transactions lack some of the power of the
underlying database transaction function (such as arbitrary save-points).
The design behind Transaction
is modeled after the
following code snippet:
new Transaction<Object>(manager) { public Object run() { Account a = getEntityManager().get(Account.class, 1); Account b = getEntityManager().get(Account.class, 2); a.setBalance(a.getBalance() - 1000); a.save(); b.setBalance(b.getBalance() + 1000); b.save(); return null; } }.execute();
The transaction will be committed only after the run()
method returns. Thus, a.save()
doesn't immediately modify
the database values, only upon the committal of the transaction. If any
conflicts are detected, JDBC will automatically throw an SQLException
.
Transaction
catches this exception and rolls back the
transaction, ensuring data integrity. Once the transaction is rolled back, the
exception is rethrown from the execute()
method.
In cases where the transaction generates data which must be returned, this
can be accomplished by returning from the run()
method against the
parameterized type. Thus if a transaction to create an account is utilized:
Account result = new Transaction<Account>(manager) { public Account run() throws SQLException { Account back = getEntityManager().create(Account.class); back.setBalance(0); back.save(): return back; } }.execute();
The value returned from run()
will be passed back up the call
stack to execute()
, which will return the value to the caller.
Thus in this example, result
will be precisely the back
instance from within the transaction. This feature allows data to escape the
scope of the transaction, thereby achieving a greater usefulness.
The JDBC transaction type used is Connection.TRANSACTION_SERIALIZABLE
.
- Author:
- Daniel Spiewak
- See Also:
-
Constructor Summary
ConstructorsConstructorDescriptionTransaction
(EntityManager manager) Creates a newTransaction
using the specifiedEntityManager
instance. -
Method Summary
-
Constructor Details
-
Transaction
Creates a newTransaction
using the specifiedEntityManager
instance. If the specified instance isnull
, an exception will be thrown.- Parameters:
manager
- TheEntityManager
instance against which the transaction should run.- Throws:
IllegalArgumentException
- If theEntityManager
instance isnull
.
-
-
Method Details
-
getEntityManager
-
execute
Executes the transaction defined within the overridden
run()
method. If the transaction fails for any reason (such as a conflict), it will be rolled back and an exception thrown. The value returned from therun()
method will be returned fromexecute()
.Custom JDBC code can be executed within a transaction. However, one should be a bit careful with the mutable state of the
Connection
instance obtained fromgetEntityManager().getProvider().getConnection()
. This is because it is this exact instance which is used in all database operations for that transaction. Thus it is technically possible to commit a transaction prematurely, disable the transaction entirely, or otherwise really mess up the internals of the implementation. You do not have to callsetAutoCommit(boolean)
on theConnection
instance retrieved from theDatabaseProvider
. The connection is already initialized and within an open transaction by the time it gets to your custom code within the transaction.- Returns:
- The value (if any) returned from the transaction
run()
- Throws:
SQLException
- If the transaction failed for any reason and was rolled back.- See Also:
-
run
Called internally by
execute()
to actually perform the actions within the transaction. AnySQLException(s)
should be allowed to propogate back up to the calling method, which will ensure that the transaction is rolled back and the proper resources disposed. If the transaction generates a value which must be passed back to the calling method, this value may be returned as long as it is of the parameterized type. If no value is generated,null
is an acceptable return value.Be aware that any operations performed within a transaction (even if indirectly invoked by the
run()
method) will use the exact sameConnection
instance. This is to ensure integrity of the transaction's operations while at the same time allowing custom JDBC code and queries within the transaction.- Returns:
- Any value which must be passed back to the calling point (outside
the transaction), or
null
. - Throws:
SQLException
- If something has gone wrong within the transaction and it requires a roll-back.
-