com.scalar.db.api

Interface TwoPhaseCommitTransactionManager

All Superinterfaces:

java.lang.AutoCloseable, CrudOperable<TransactionException>, TransactionManagerCrudOperable

All Known Implementing Classes:

AbstractTwoPhaseCommitTransactionManager, ActiveTransactionManagedTwoPhaseCommitTransactionManager, DecoratedTwoPhaseCommitTransactionManager, GrpcTwoPhaseCommitTransactionManager, TransactionDecorationTwoPhaseCommitTransactionManager, TwoPhaseCommitTransactionService, TwoPhaseConsensusCommitManager

public interface TwoPhaseCommitTransactionManager
extends TransactionManagerCrudOperable, java.lang.AutoCloseable

A transaction manager based on a two-phase commit protocol.

Just like a well-known two-phase commit protocol, there are two roles, a coordinator and a participant, that execute a single transaction collaboratively. A coordinator process first starts a transaction with start() or start(String), and participant processes join the transaction with join(String) with the transaction ID. Also, participants can resume the transaction with resume(String) with the transaction ID.

Method Summary

Modifier and Type	Method and Description
default TransactionState	abort(java.lang.String txId) Aborts a given transaction.
TwoPhaseCommitTransaction	begin() Begins a new transaction.
TwoPhaseCommitTransaction	begin(java.lang.String txId) Begins a new transaction with the specified transaction ID.
void	close() Closes connections to the cluster.
java.util.Optional<java.lang.String>	getNamespace() Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
TransactionState	getState(java.lang.String txId) Returns the state of a given transaction.
java.util.Optional<java.lang.String>	getTable() Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
TwoPhaseCommitTransaction	join(java.lang.String txId) Joins a transaction associated with the specified transaction ID.
TwoPhaseCommitTransaction	resume(java.lang.String txId) Resumes an ongoing transaction associated with the specified transaction ID.
TransactionState	rollback(java.lang.String txId) Rolls back a given transaction.
default TwoPhaseCommitTransaction	start() Starts a new transaction.
default TwoPhaseCommitTransaction	start(java.lang.String txId) Starts a new transaction with the specified transaction ID.
void	with(java.lang.String namespace, java.lang.String tableName) Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
void	withNamespace(java.lang.String namespace) Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
void	withTable(java.lang.String tableName) Deprecated. As of release 3.6.0. Will be removed in release 5.0.0

Methods inherited from interface com.scalar.db.api.TransactionManagerCrudOperable

delete, delete, get, insert, mutate, put, put, scan, update, upsert

Method Detail

with

@Deprecated
void with(java.lang.String namespace,
                      java.lang.String tableName)

Deprecated. As of release 3.6.0. Will be removed in release 5.0.0

Sets the specified namespace and the table name as default values in the instance.

Parameters:

namespace - default namespace to operate for

tableName - default table name to operate for

withNamespace

@Deprecated
void withNamespace(java.lang.String namespace)

Deprecated. As of release 3.6.0. Will be removed in release 5.0.0

Sets the specified namespace as a default value in the instance.

Parameters:

namespace - default namespace to operate for

getNamespace

@Deprecated
java.util.Optional<java.lang.String> getNamespace()

Deprecated. As of release 3.6.0. Will be removed in release 5.0.0

Returns the namespace.

Returns:

an Optional with the namespace

withTable

@Deprecated
void withTable(java.lang.String tableName)

Deprecated. As of release 3.6.0. Will be removed in release 5.0.0

Sets the specified table name as a default value in the instance.

Parameters:

tableName - default table name to operate for

getTable

@Deprecated
java.util.Optional<java.lang.String> getTable()

Deprecated. As of release 3.6.0. Will be removed in release 5.0.0

Returns the table name.

Returns:

an Optional with the table name

begin

TwoPhaseCommitTransaction begin()
                         throws TransactionNotFoundException,
                                TransactionException

Begins a new transaction. This method is assumed to be called by a coordinator process.

Returns:

DistributedTransaction

Throws:

TransactionNotFoundException - if the transaction fails to begin due to transient faults. You can retry the transaction

TransactionException - if the transaction fails to begin due to transient or nontransient faults. You can try retrying the transaction, but you may not be able to begin the transaction due to nontransient faults

begin

TwoPhaseCommitTransaction begin(java.lang.String txId)
                         throws TransactionNotFoundException,
                                TransactionException

Begins a new transaction with the specified transaction ID. It is users' responsibility to guarantee uniqueness of the ID, so it is not recommended to use this method unless you know exactly what you are doing. This method is assumed to be called by a coordinator process.

Parameters:

txId - an user-provided unique transaction ID

Returns:

DistributedTransaction

Throws:

TransactionNotFoundException - if the transaction fails to begin due to transient faults. You can retry the transaction

TransactionException - if the transaction fails to begin due to transient or nontransient faults. You can try retrying the transaction, but you may not be able to begin the transaction due to nontransient faults

start

default TwoPhaseCommitTransaction start()
                                 throws TransactionNotFoundException,
                                        TransactionException

Starts a new transaction. This method is an alias of begin().

Returns:

DistributedTransaction

Throws:

TransactionNotFoundException - if the transaction fails to start due to transient faults. You can retry the transaction

TransactionException - if the transaction fails to start due to transient or nontransient faults. You can try retrying the transaction, but you may not be able to start the transaction due to nontransient faults

start

default TwoPhaseCommitTransaction start(java.lang.String txId)
                                 throws TransactionNotFoundException,
                                        TransactionException

Starts a new transaction with the specified transaction ID. This method is an alias of begin(String).

Parameters:

txId - an user-provided unique transaction ID

Returns:

DistributedTransaction

Throws:

TransactionNotFoundException - if the transaction fails to start due to transient faults. You can retry the transaction

TransactionException - if the transaction fails to start due to transient or nontransient faults. You can try retrying the transaction, but you may not be able to start the transaction due to nontransient faults

join

TwoPhaseCommitTransaction join(java.lang.String txId)
                        throws TransactionNotFoundException,
                               TransactionException

Joins a transaction associated with the specified transaction ID. The transaction should be started by a coordinator process. This method is assumed to be called by a participant process.

Parameters:

txId - the transaction ID

Returns:

TwoPhaseCommitTransaction

Throws:

TransactionNotFoundException - if joining the transaction fails due to transient faults. You can retry the transaction from the beginning

TransactionException - if joining the transaction fails due to transient or nontransient faults. You can try retrying the transaction from the beginning, but the transaction may still fail if the cause is nontranient

resume

TwoPhaseCommitTransaction resume(java.lang.String txId)
                          throws TransactionNotFoundException

Resumes an ongoing transaction associated with the specified transaction ID.

Parameters:

txId - the transaction ID

Returns:

TwoPhaseCommitTransaction

Throws:

TransactionNotFoundException - if the transaction associated with the specified transaction ID is not found. You can retry the transaction from the beginning

getState

TransactionState getState(java.lang.String txId)
                   throws TransactionException

Returns the state of a given transaction.

Parameters:

txId - a transaction ID

Returns:

TransactionState

Throws:

TransactionException - if getting the state of a given transaction fails

rollback

TransactionState rollback(java.lang.String txId)
                   throws TransactionException

Rolls back a given transaction.

Parameters:

txId - a transaction ID

Returns:

TransactionState

Throws:

TransactionException - if rolling back the given transaction fails

abort

default TransactionState abort(java.lang.String txId)
                        throws TransactionException

Aborts a given transaction. This method is an alias of rollback(String).

Parameters:

txId - a transaction ID

Returns:

TransactionState

Throws:

TransactionException - if aborting the given transaction fails

close

void close()

Closes connections to the cluster. The connections are shared among multiple services such as StorageService and TransactionService, thus this should only be used when closing applications.

Specified by:

close in interface java.lang.AutoCloseable