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.BaseConsumer
static interface	TxScope.BatchScopeConsumer
static interface	TxScope.BatchSqlChangeCtx
static interface	TxScope.ScopeConsumer
static interface	TxScope.SqlChangeCtx This interface also ensures a raw change is not unintentionally committed to another TxScope

Method Summary

Modifier and Type	Method and Description
void	addBatchChange(TxScope.BatchScopeConsumer sqlChange)
void	addSqlChange(TxScope.ScopeConsumer sqlChange) 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().
void	commit(TxScope.ScopeConsumer changes) Commits entity changes in this tx scope to the data source specified in getDbConfig().
void	commitAsBatch(TxScope.BatchScopeConsumer change)
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.

In this mode of commit, queries and fetch methods each execute immediately in separate transactions against a durable state of the database while entity CRUD operations are collected and executed as a single batch of changes in this method.

To execute both queries and changes within the same transaction, use commit(ScopeConsumer) instead.

Throws:

java.sql.SQLException

commit

void commit(TxScope.ScopeConsumer changes)
     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.

In this mode of commit all SQL operations provided with changes execute together in the same transaction, directly as they appear in code.

Bear in mind this mode of commit creates a connection and leaves it open for the duration of the call to changes#accept(SqlChangeCtx). Alternatively, using the no arg commit() mode ensures connections are open briefly as queries and other direct SQL commands execute immediately in separate transactions, while entity CRUD operation execute in a single batched transaction during the call to commit().

Parameters:

changes - May contain any mix of SQL queries, CRUD, and other SQL commands. Executes within a single transaction. Persisted directly in order of execution.

Throws:

java.sql.SQLException

commitAsBatch

void commitAsBatch(TxScope.BatchScopeConsumer change)
            throws java.sql.SQLException

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

addSqlChange

void addSqlChange(TxScope.ScopeConsumer sqlChange)

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

This method is primarily intended for executing SqlCommands as opposed to CRUD 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.addSqlChange(txScope ->
     "[.sql] Delete From history Where created_on >= :newerThan"
       .execute(txScope, dateValue));
 }
 . . .
 // commit all entity changes and changes via addSqlChange()
 MyDatabase.commit();
 

Parameters:

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

addBatchChange

void addBatchChange(TxScope.BatchScopeConsumer sqlChange)