com.google.cloud.spanner.TransactionManager Maven / Gradle / Ivy
Show all versions of google-cloud-spanner Show documentation
/*
* Copyright 2017 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.cloud.spanner;
import com.google.cloud.Timestamp;
import com.google.cloud.spanner.Options.TransactionOption;
/**
* An interface for managing the life cycle of a read write transaction including all its retries.
* See {@link TransactionContext} for a description of transaction semantics.
*
* At any point in time there can be at most one active transaction in this manager. When that
* transaction is committed, if it fails with an {@code ABORTED} error, calling {@link
* #resetForRetry()} would create a new {@link TransactionContext}. The newly created transaction
* would use the same session thus increasing its lock priority. If the transaction is committed
* successfully, or is rolled back or commit fails with any error other than {@code ABORTED}, the
* manager is considered complete and no further transactions are allowed to be created in it.
*
*
Every {@code TransactionManager} should either be committed or rolled back. Failure to do so
* can cause resources to be leaked and deadlocks. Easiest way to guarantee this is by calling
* {@link #close()} in a finally block.
*
* @see DatabaseClient#transactionManager(TransactionOption...)
*/
public interface TransactionManager extends AutoCloseable {
/** State of the transaction manager. */
enum TransactionState {
// Transaction has been started either by calling {@link #begin()} or via
// {@link resetForRetry()} but has not been committed or rolled back yet.
STARTED,
// Transaction was successfully committed. This is a terminal state.
COMMITTED,
// Transaction failed during commit with an error other than ABORTED. Transaction cannot be
// retried in this state. This is a terminal state.
COMMIT_FAILED,
// Transaction failed during commit with ABORTED and can be retried.
ABORTED,
// Transaction was rolled back. This is a terminal state.
ROLLED_BACK
}
/**
* Creates a new read write transaction. This must be called before doing any other operation and
* can only be called once. To create a new transaction for subsequent retries, see {@link
* #resetForRetry()}.
*/
TransactionContext begin();
/**
* Commits the currently active transaction. If the transaction was already aborted, then this
* would throw an {@link AbortedException}.
*/
void commit();
/**
* Rolls back the currently active transaction. In most cases there should be no need to call this
* explicitly since {@link #close()} would automatically roll back any active transaction.
*/
void rollback();
/**
* Creates a new transaction for retry. This should only be called if the previous transaction
* failed with {@code ABORTED}. In all other cases, this will throw an {@link
* IllegalStateException}. Users should backoff before calling this method. Backoff delay is
* specified by {@link SpannerException#getRetryDelayInMillis()} on the {@code SpannerException}
* throw by the previous commit call.
*/
TransactionContext resetForRetry();
/**
* Returns the commit timestamp if the transaction committed successfully otherwise it will throw
* {@code IllegalStateException}.
*/
Timestamp getCommitTimestamp();
/** Returns the {@link CommitResponse} of this transaction. */
CommitResponse getCommitResponse();
/** Returns the state of the transaction. */
TransactionState getState();
/**
* Closes the manager. If there is an active transaction, it will be rolled back. Underlying
* session will be released back to the session pool.
*/
@Override
void close();
}