Package org.apache.polaris.persistence.nosql.api.commit

Interface Committer<REF_OBJ extends BaseCommitObj,RESULT>

Type Parameters:

REF_OBJ - type of the Obj referenced

RESULT - the commit result type for successful commits including non-changing

public interface Committer<REF_OBJ extends BaseCommitObj,RESULT>

A Committer performs an atomic change against a named reference. This is a higher-level functionality building on top of the low-level RetryLoop.

Committing use cases ensure that a reference always points to a consistent state, and that the change is atomic.

Committing use cases usually need to write more objects than just the referenced one. Implementations must use UpdateState.writeIntent(Object, Obj) to get those objects being persisted. Retries can check whether an object has already been written to prevent unnecessary write operations against the backend database.

A committing use case creates a Committer instance using a CommitRetryable implementation, which receives the object pointed in the reference and returns the new object to which the reference shall point to.

Method Summary

Modifier and Type	Method	Description
Optional<RESULT>	commit(CommitRetryable<REF_OBJ,RESULT> commitRetryable)	Perform an atomic change.
default Optional<RESULT>	commitRuntimeException(CommitRetryable<REF_OBJ,RESULT> commitRetryable)	Same as commit(CommitRetryable), but wraps the checked exceptions in a RuntimeException.
Committer<REF_OBJ,RESULT>	synchronizingLocally()	When called, commits to the same reference will be synchronized locally.

Method Details

synchronizingLocally

Committer<REF_OBJ,RESULT> synchronizingLocally()

When called, commits to the same reference will be synchronized locally.

Using local reference-synchronization prevents commit retries. When using this feature, the actual CommitRetryable.attempt(CommitterState, Supplier) implementation must not block and complete quickly.

commit

Optional<RESULT> commit(CommitRetryable<REF_OBJ,RESULT> commitRetryable)
                 throws CommitException,
RetryTimeoutException

Perform an atomic change.

The given CommitRetryable is called to perform the actual change. The implementation of the CommitRetryable must be side-effect-free and prepared to be called multiple times.

Parameters:

commitRetryable - performs the state change, must be side-effect-free

Returns:

the result as returned via CommitterState.commitResult(Object, BaseCommitObj.Builder, Optional) or an empty optional if no change happened

Throws:

CommitException

RetryTimeoutException

commitRuntimeException

default Optional<RESULT> commitRuntimeException(CommitRetryable<REF_OBJ,RESULT> commitRetryable)

Same as commit(CommitRetryable), but wraps the checked exceptions in a RuntimeException.