manifold.sql.rt.api

Interface TxScope

All Known Subinterfaces:

OperableTxScope

public interface TxScope

All data source entities have a data source transaction scope (TxScope). When an entity changes in application code (created, updated, deleted) it is added to its tx scope. Entities manage their own state and keep track of changes. Tx scopes manage persistence of changed state. The commit() method persists changes to the data source whenever needed and as often as needed.

If entity types and queries are not used with an explicit TxScope, a default scope is provided. The default scope is a dependency, which can be customized.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	TxScope.RawChangeCtx This interface also ensures a raw change is not unintentionally committed to another TxScope
static interface	TxScope.ScopeConsumer

Method Summary

Modifier and Type	Method and Description
void	addRawChange(TxScope.ScopeConsumer rawChange) Add change[s] that are to be executed during the next call to commit().
void	commit() Commits entity changes in this tx scope to the data source specified in getDbConfig().
DbConfig	getDbConfig() Provides data source configuration info for this tx scope.
void	revert() Reverts all entity changes within this tx scope back to the last commit, or if no commits were made, back to the creation of this tx scope.

Method Detail

getDbConfig

DbConfig getDbConfig()

Provides data source configuration info for this tx scope.

commit

void commit()
     throws java.sql.SQLException

Commits entity changes in this tx scope to the data source specified in getDbConfig(). After the commit, this tx scope is ready to manage more entity changes. Note, if the commit fails, unless revert() is called during handling of the SQLException, the state of this tx scope is as it was immediately before the commit. Otherwise, if the commit succeeds, the state of this tx scope is clear of changes.

Throws:

java.sql.SQLException

revert

void revert()
     throws java.sql.SQLException

Reverts all entity changes within this tx scope back to the last commit, or if no commits were made, back to the creation of this tx scope.

Note, this method is not called when a commit fails. The state of the scope is carefully managed so that it is exactly as it was immediately before commit() was called. This behavior is intended to support another commit attempt, if desired.

However, catching the SQLException resulting from a failed commit is the place for the caller to decide whether to revert or amend the changes in the tx scope.

Throws:

java.sql.SQLException

addRawChange

void addRawChange(TxScope.ScopeConsumer rawChange)

Add change[s] that are to be executed during the next call to commit().

This method is primarily intended for executing raw SqlCommands as opposed to operations on entities, which are handled automatically.

 public void eraseHistoryNewerThan(Instant newerThan) {
   // The SQL delete statement executes the next time scope.commit() is called
   MyDatabase.addRawChange(txScope ->
     "[.sql] Delete From history Where created_on >= :newerThan"
       .execute(txScope, dateValue));
 }
 . . .
 // commit all entity changes and changes via addRawChange()
 MyDatabase.commit();
 

Parameters:

rawChange - Raw change to be executed during the next call to commit(). The change should normally involve a SqlCommand execution.