de.tif.jacob.core.data
Interface IDataTransaction

public interface IDataTransaction

A data transaction provides the ability to flush (commit) multiple record modifications at once by means of calling commit(). With a single transaction record modifications in multiple data sources could be performed.

Note that the actual implementation does not support 2-phase commit functionality so far. This means that there is no guarantee for atomic modifications across multiple data sources, i.e. if commit fails not all modifications might be rolled back completely. Nevertheless, this functionality is guaranteed for modifications on a single data source which supports transaction handling as most relational databases do.

There is no (explicit) rollback method nor functionality, since modifications are not written to a data source until commit() is called. Nevertheless, a rollback is executed implicitly on data source transactions obtained during commit, in case any underlying data source operation fails.

Data transaction can not be reused, i.e. data transactions are invalid after commit() or close() has been invoked.

close() should be called explicitly on data transactions obtained by IDataAccessor.newTransaction() to ensure that transaction resources (i.e. record locks) are released properly in error case. Please, look at the following example how to do this correctly:

 IDataTransaction transaction = accessor.newTransaction();
 try
 {
   IDataTable requestTable = accessor.getTable("request");
   IDataTableRecord requestRecord = requestTable.newRecord(transaction);
 
   requestRecord.setValue(transaction, "createtime", "now");
   // do further modifications..
 
   // try to commit
   transaction.commit();
 }
 finally
 {
   // in case of an exception close() will be called as well   
   transaction.close();
 }
 

A data transaction instance could be obtained by means of

IDataAccessor.newTransaction(),

IDataTableRecord.getCurrentTransaction(),

IDataTable.getTableTransaction(),

IDataTable.startNewTransaction().

Method Summary

void	close() Closes the transaction which ensures that all transaction resources are released properly.
void	commit() Flushes all modifications to the underlying data sources and commits them as well.
long	getId() Returns the unique transaction id.
IUser	getUser() Returns the user who has initiated this transaction.
boolean	isValid() Checks whether this transaction is valid.
void	lock(IDataRecord record) Locks the given record within the context of this transaction.

Method Detail

lock

void lock(IDataRecord record)
          throws RecordLockedException

Locks the given record within the context of this transaction. The lock will be implicitly released again, if the transaction is either committed or closed.

Parameters:

record - the record to lock

Throws:

RecordLockedException - if the record is already locked within the context of another transaction.

commit

void commit()
            throws UserException,
                   java.lang.Exception

Flushes all modifications to the underlying data sources and commits them as well.

Throws:

UserException - This kind of exception (normally) indicates that the commit operation is aborted due to a failed consistency check. Consistency checks could be performed in table hooks as well and should always lead to a UserException, if the data to be committed is not consistent in a certain way. See also DataTableRecordEventHandler.beforeCommitAction(IDataTableRecord, IDataTransaction).

java.lang.Exception - in case of any other error

close

void close()

Closes the transaction which ensures that all transaction resources are released properly.

getId

long getId()

Returns the unique transaction id.

Note: This id is unique for the respective jACOB application server instance, but not unique across a jACOB application server cluster!

Returns:

the transaction id.

isValid

boolean isValid()

Checks whether this transaction is valid.

Returns:

true if the transaction is valid, otherwise false

getUser

IUser getUser()

Returns the user who has initiated this transaction.

Returns:

the transaction user