com.scalar.db.sql.SqlTwoPhaseCommitTransactionManager Maven / Gradle / Ivy
package com.scalar.db.sql;
import com.scalar.db.sql.exception.SqlException;
import com.scalar.db.sql.exception.TransactionRetryableException;
import com.scalar.db.sql.metadata.Metadata;
/**
* A transaction manager abstraction for two-phase commit transactions for ScalarDB SQL API. You can
* execute a one-shot query (DDL and DML) with the {@code execute()} methods.
*/
public interface SqlTwoPhaseCommitTransactionManager extends SqlStatementExecutable, AutoCloseable {
/**
* Begins a transaction.
*
* @return an instance of {@link SqlTwoPhaseCommitTransaction} for the begun transaction
* @throws TransactionRetryableException if the transaction fails to begin due to retryable
* faults. You can retry the transaction.
* @throws SqlException if the transaction fails to begin due to transient or nontransient faults.
* You can try retrying the transaction, but the transaction may still fail if the cause is
* nontranient
*/
SqlTwoPhaseCommitTransaction begin();
/**
* Begins a 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.
*
* @param transactionId a user-provided unique transaction ID
* @return an instance of {@link SqlTwoPhaseCommitTransaction} for the begun transaction
* @throws TransactionRetryableException if the transaction fails to begin due to retryable
* faults. You can retry the transaction.
* @throws SqlException 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
*/
SqlTwoPhaseCommitTransaction begin(String transactionId);
/**
* Starts a transaction. This method is an alias of {@link #begin()}.
*
* @return an instance of {@link SqlTwoPhaseCommitTransaction} for the started transaction
* @throws TransactionRetryableException if the transaction fails to start due to retryable
* faults. You can retry the transaction.
* @throws SqlException if the transaction fails to start due to transient or nontransient faults.
* You can try retrying the transaction, but the transaction may still fail if the cause is
* nontranient
*/
default SqlTwoPhaseCommitTransaction start() {
return begin();
}
/**
* Starts a transaction with the specified transaction ID. This method is an alias of {@link
* #begin(String)}.
*
* @param transactionId a user-provided unique transaction ID
* @return an instance of {@link SqlTwoPhaseCommitTransaction} for the started transaction
* @throws TransactionRetryableException if the transaction fails to start due to retryable
* faults. You can retry the transaction.
* @throws SqlException 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
*/
default SqlTwoPhaseCommitTransaction start(String transactionId) {
return begin(transactionId);
}
/**
* Joins the specified transaction.
*
* @return an instance of {@link SqlTwoPhaseCommitTransaction} for the joined transaction
* @param transactionId a transaction ID associated with the transaction to join
* @throws TransactionRetryableException if the transaction fails to join due to retryable faults.
* You can retry the transaction from the beginning.
* @throws SqlException if the transaction fails to join 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
*/
SqlTwoPhaseCommitTransaction join(String transactionId);
/**
* Resumes an ongoing transaction associated with the specified transaction ID.
*
* @return an instance of {@link SqlTwoPhaseCommitTransaction} for the resumed transaction
* @param transactionId a transaction ID associated with the transaction to resume
* @throws TransactionRetryableException if the transaction fails to resume due to retryable
* faults (e.g., the transaction not found). You can retry the transaction from the beginning.
* @throws SqlException if the transaction fails to resume 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
*/
SqlTwoPhaseCommitTransaction resume(String transactionId);
/**
* Returns a {@link Metadata} object.
*
* @return a {@link Metadata} object.
*/
Metadata getMetadata();
/** Closes this transaction manager. */
@Override
void close();
}