com.scalar.db.sql.SqlTransactionManager 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 ScalarDB SQL API. You can execute a one-shot query (DDL and
* DML) with the {@code execute()} methods.
*/
public interface SqlTransactionManager extends SqlStatementExecutable, AutoCloseable {
/**
* Begins a transaction.
*
* @return an instance of {@link SqlTransaction} 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
*/
SqlTransaction 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 SqlTransaction} 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
*/
SqlTransaction begin(String transactionId);
/**
* Starts a transaction. This method is an alias of {@link #begin()}.
*
* @return an instance of {@link SqlTransaction} 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 SqlTransaction 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 SqlTransaction} 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 SqlTransaction start(String transactionId) {
return begin(transactionId);
}
/**
* Joins an ongoing transaction associated with the specified transaction ID.
*
* @param transactionId a transaction ID associated with the transaction to join
* @return an instance of {@link SqlTransaction} for the joined transaction
* @throws TransactionRetryableException if the transaction fails to join 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 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
*/
default SqlTransaction join(String transactionId) {
return resume(transactionId);
}
/**
* Resumes an ongoing transaction associated with the specified transaction ID.
*
* @param transactionId a transaction ID associated with the transaction to resume
* @return an instance of {@link SqlTransaction} for the resumed transaction
* @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
*/
SqlTransaction resume(String transactionId);
/**
* Returns a {@link Metadata} object.
*
* @return a {@link Metadata} object.
*/
Metadata getMetadata();
/** Closes this transaction manager. */
@Override
void close();
}