com.palantir.atlasdb.transaction.api

Interface TransactionManager

All Superinterfaces:

AutoCloseable

public interface TransactionManager
extends AutoCloseable

Method Summary

Modifier and Type	Method and Description
void	clearTimestampCache() Clear the timestamp cache.
void	close() Frees resources used by this TransactionManager, and invokes any callbacks registered to run on close.
Cleaner	getCleaner() Returns the cleaner used by this transaction manager.
long	getImmutableTimestamp() Most AtlasDB TransactionManagers will provide Transaction objects that have less than full serializability.
KeyValueService	getKeyValueService() Returns the KVS used by this transaction manager.
KeyValueServiceStatus	getKeyValueServiceStatus() Provides a KeyValueServiceStatus, indicating the current availability of the key value store.
com.palantir.lock.LockService	getLockService() Returns the lock service used by this transaction manager.
LockWatchManager	getLockWatchManager()
com.palantir.lock.v2.TimelockService	getTimelockService() Returns the timelock service used by this transaction manager.
TimelockServiceStatus	getTimelockServiceStatus() Provides a TimelockServiceStatus, indicating the current availability of the timelock service.
com.palantir.timestamp.TimestampManagementService	getTimestampManagementService() The timestamp management service is used by libraries providing additional functionality around AtlasDB.
com.palantir.timestamp.TimestampService	getTimestampService() Returns the timestamp service used by this transaction manager.
TransactionService	getTransactionService() The transaction service is used by libraries providing additional functionality around AtlasDB.
long	getUnreadableTimestamp() Returns the timestamp that is before any open start timestamps.
default boolean	isInitialized() Whether this transaction manager has established a connection to the backing store and timestamp/lock services, and is ready to service transactions.
void	registerClosingCallback(Runnable closingCallback) Registers a Runnable that will be run after the transaction manager is closed.
<T,E extends Exception> T	runTaskReadOnly(TransactionTask<T,E> task) This will open and run a read-only transaction.
<T,E extends Exception> T	runTaskThrowOnConflict(TransactionTask<T,E> task) runTaskWithRetry(TransactionTask) should be preferred over runTaskThrowOnConflict(TransactionTask).
<T,C extends PreCommitCondition,E extends Exception> T	runTaskWithConditionReadOnly(C condition, ConditionAwareTransactionTask<T,C,E> task) This method is basically the same as runTaskReadOnly(TransactionTask), but it takes a PreCommitCondition and checks it for validity before executing reads.
<T,C extends PreCommitCondition,E extends Exception> T	runTaskWithConditionThrowOnConflict(C condition, ConditionAwareTransactionTask<T,C,E> task) This method is basically the same as runTaskThrowOnConflict(TransactionTask), but it takes a PreCommitCondition and checks it immediately before the transaction commits.
<T,C extends PreCommitCondition,E extends Exception> T	runTaskWithConditionWithRetry(java.util.function.Supplier<C> conditionSupplier, ConditionAwareTransactionTask<T,C,E> task) This method is basically the same as runTaskWithRetry(TransactionTask), but it will acquire a PreCommitCondition right before the transaction is created and check it immediately before the transaction commits.
default <T,C extends PreCommitCondition,E extends Exception> T	runTaskWithConditionWithRetry(com.google.common.base.Supplier<C> guavaSupplier, ConditionAwareTransactionTask<T,C,E> task) Deprecated. use runTaskWithConditionWithRetry(Supplier, ConditionAwareTransactionTask) instead.
<T,E extends Exception> T	runTaskWithLocksThrowOnConflict(Iterable<com.palantir.lock.HeldLocksToken> lockTokens, LockAwareTransactionTask<T,E> task) This method is the same as runTaskThrowOnConflict(TransactionTask) except the created transaction will not commit successfully if these locks are invalid by the time commit is run.
<T,E extends Exception> T	runTaskWithLocksWithRetry(Iterable<com.palantir.lock.HeldLocksToken> lockTokens, java.util.function.Supplier<com.palantir.lock.LockRequest> lockSupplier, LockAwareTransactionTask<T,E> task) This method is the same as runTaskWithLocksWithRetry(Supplier, LockAwareTransactionTask) but it will also ensure that the existing lock tokens passed are still valid before committing.
default <T,E extends Exception> T	runTaskWithLocksWithRetry(Iterable<com.palantir.lock.HeldLocksToken> lockTokens, com.google.common.base.Supplier<com.palantir.lock.LockRequest> guavaSupplier, LockAwareTransactionTask<T,E> task) Deprecated. use runTaskWithLocksWithRetry(Iterable, Supplier, LockAwareTransactionTask) instead.
<T,E extends Exception> T	runTaskWithLocksWithRetry(java.util.function.Supplier<com.palantir.lock.LockRequest> lockSupplier, LockAwareTransactionTask<T,E> task) This method is basically the same as runTaskWithRetry(TransactionTask) but it will acquire locks right before the transaction is created and release them after the task is complete.
default <T,E extends Exception> T	runTaskWithLocksWithRetry(com.google.common.base.Supplier<com.palantir.lock.LockRequest> guavaSupplier, LockAwareTransactionTask<T,E> task) Deprecated. use runTaskWithLocksWithRetry(Supplier, LockAwareTransactionTask) instead.
<T,E extends Exception> T	runTaskWithRetry(TransactionTask<T,E> task) Runs the given TransactionTask.
List<OpenTransaction>	startTransactions(List<? extends PreCommitCondition> condition) Deprecated. Similar functionality will exist, but this method is likely to change in the future

Method Detail

isInitialized

default boolean isInitialized()

Whether this transaction manager has established a connection to the backing store and timestamp/lock services, and is ready to service transactions. If an attempt is made to execute a transaction when this method returns false, a NotInitializedException will be thrown. This method is used for TransactionManagers that can be initializeppd asynchronously (i.e. those extending com.palantir.async.initializer.AsyncInitializer; other TransactionManagers can keep the default implementation, and return true (they're trivially fully initialized).

Returns:

true if and only if the TransactionManager has been fully initialized

runTaskWithRetry

<T,E extends Exception> T runTaskWithRetry(TransactionTask<T,E> task)
                                    throws E extends Exception

Runs the given TransactionTask. If the task completes successfully and does not call Transaction.commit() or Transaction.abort(), Transaction.commit() is called automatically.

The task is re-run if a conflict is detected (if a TransactionConflictException is thrown)

If runTaskWithRetry completes successfully (no exception is thrown) and the task did not explicitly abort the transaction, then the transaction was successfully committed. If an exception is thrown by the TransactionTask and the task did not call Transaction.commit(), then the transaction will be rolled back.

NOTE: If an exception is thrown by Transaction.commit(), the transaction might have been committed.

It is important that the TransactionTask does not modify any of its input state in any non-idempotent way. If this task gets retried, and if you modified your input, then the second try might not do the right thing. For example: if you are passed a list of objects and at the end of the TransactionTask, you clear the list. If your task gets retried it will have no work to do, because the list was cleared.

Parameters:

task - task to run

Returns:

value returned by task

Throws:

IllegalStateException - if the transaction manager has been closed.

E extends Exception

runTaskThrowOnConflict

<T,E extends Exception> T runTaskThrowOnConflict(TransactionTask<T,E> task)
                                          throws E extends Exception,
                                                 TransactionFailedRetriableException

runTaskWithRetry(TransactionTask) should be preferred over runTaskThrowOnConflict(TransactionTask). This method should be used unless runTaskWithRetry(TransactionTask) cannot be used because the arguments passed are not immutable and will be modified by the transaction so doing automatic retry is unsafe. Runs the given TransactionTask. If the task completes successfully and does not call Transaction.commit() or Transaction.abort(), Transaction.commit() is called automatically.

If runTaskThrowOnConflict() completes successfully (no exception is thrown) and the task did not explicitly abort the transaction, then the transaction was successfully committed. If an exception is thrown by the TransactionTask and the task did not call Transaction.commit(), then the transaction will be rolled back.

NOTE: If an exception is thrown by Transaction.commit(), the transaction might have been committed.

Parameters:

task - task to run

Returns:

value returned by task

Throws:

TransactionConflictException - if a write-write conflict occurs

IllegalStateException - if the transaction manager has been closed.

E extends Exception

TransactionFailedRetriableException

runTaskReadOnly

<T,E extends Exception> T runTaskReadOnly(TransactionTask<T,E> task)
                                   throws E extends Exception

This will open and run a read-only transaction. Read-only transactions are similar to other transactions, but will throw if any write operations are called. Furthermore, they often make fewer network calls than their read/write counterparts so should be used where possible.

Parameters:

task - task to run

Returns:

value returned by task

Throws:

IllegalStateException - if the transaction manager has been closed.

E extends Exception

runTaskWithLocksWithRetry

<T,E extends Exception> T runTaskWithLocksWithRetry(java.util.function.Supplier<com.palantir.lock.LockRequest> lockSupplier,
                                                    LockAwareTransactionTask<T,E> task)
                                             throws E extends Exception,
                                                    InterruptedException,
                                                    LockAcquisitionException

This method is basically the same as runTaskWithRetry(TransactionTask) but it will acquire locks right before the transaction is created and release them after the task is complete.

The created transaction will not commit successfully if these locks are invalid by the time commit is run.

Parameters:

lockSupplier - supplier for the lock request

task - task to run

Returns:

value returned by task

Throws:

LockAcquisitionException - If the supplied lock request is not successfully acquired.

IllegalStateException - if the transaction manager has been closed.

E extends Exception

InterruptedException

runTaskWithLocksWithRetry

@Deprecated
default <T,E extends Exception> T runTaskWithLocksWithRetry(com.google.common.base.Supplier<com.palantir.lock.LockRequest> guavaSupplier,
                                                                        LockAwareTransactionTask<T,E> task)
                                                                 throws E extends Exception,
                                                                        InterruptedException,
                                                                        LockAcquisitionException

Deprecated. use runTaskWithLocksWithRetry(Supplier, LockAwareTransactionTask) instead.

This is the same as runTaskWithLocksWithRetry(Supplier, LockAwareTransactionTask), but instead takes in a Guava supplier. This is deprecated in favour of the aforementioned method.

Throws:

E extends Exception

InterruptedException

LockAcquisitionException

See Also:

runTaskWithLocksWithRetry(Supplier, LockAwareTransactionTask)

runTaskWithLocksWithRetry

<T,E extends Exception> T runTaskWithLocksWithRetry(Iterable<com.palantir.lock.HeldLocksToken> lockTokens,
                                                    java.util.function.Supplier<com.palantir.lock.LockRequest> lockSupplier,
                                                    LockAwareTransactionTask<T,E> task)
                                             throws E extends Exception,
                                                    InterruptedException,
                                                    LockAcquisitionException

This method is the same as runTaskWithLocksWithRetry(Supplier, LockAwareTransactionTask) but it will also ensure that the existing lock tokens passed are still valid before committing.

Parameters:

lockTokens - lock tokens to acquire while transaction executes

task - task to run

Returns:

value returned by task

Throws:

LockAcquisitionException - If the supplied lock request is not successfully acquired.

IllegalStateException - if the transaction manager has been closed.

E extends Exception

InterruptedException

runTaskWithLocksWithRetry

@Deprecated
default <T,E extends Exception> T runTaskWithLocksWithRetry(Iterable<com.palantir.lock.HeldLocksToken> lockTokens,
                                                                        com.google.common.base.Supplier<com.palantir.lock.LockRequest> guavaSupplier,
                                                                        LockAwareTransactionTask<T,E> task)
                                                                 throws E extends Exception,
                                                                        InterruptedException,
                                                                        LockAcquisitionException

Deprecated. use runTaskWithLocksWithRetry(Iterable, Supplier, LockAwareTransactionTask) instead.

This is the same as runTaskWithLocksWithRetry(Iterable, Supplier, LockAwareTransactionTask), but instead takes in a Guava supplier. This is deprecated in favour of the aforementioned method.

Throws:

E extends Exception

InterruptedException

LockAcquisitionException

See Also:

runTaskWithLocksWithRetry(Iterable, Supplier, LockAwareTransactionTask)

runTaskWithLocksThrowOnConflict

<T,E extends Exception> T runTaskWithLocksThrowOnConflict(Iterable<com.palantir.lock.HeldLocksToken> lockTokens,
                                                          LockAwareTransactionTask<T,E> task)
                                                   throws E extends Exception,
                                                          TransactionFailedRetriableException

This method is the same as runTaskThrowOnConflict(TransactionTask) except the created transaction will not commit successfully if these locks are invalid by the time commit is run.

Parameters:

lockTokens - lock tokens to refresh while transaction executes

task - task to run

Returns:

value returned by task

Throws:

IllegalStateException - if the transaction manager has been closed.

E extends Exception

TransactionFailedRetriableException

runTaskWithConditionWithRetry

<T,C extends PreCommitCondition,E extends Exception> T runTaskWithConditionWithRetry(java.util.function.Supplier<C> conditionSupplier,
                                                                                     ConditionAwareTransactionTask<T,C,E> task)
                                                                              throws E extends Exception

This method is basically the same as runTaskWithRetry(TransactionTask), but it will acquire a PreCommitCondition right before the transaction is created and check it immediately before the transaction commits.

The created transaction will not commit successfully if the check fails.

Parameters:

conditionSupplier - supplier for the condition

task - task to run

Returns:

value returned by task

Throws:

IllegalStateException - if the transaction manager has been closed.

E extends Exception

runTaskWithConditionWithRetry

@Deprecated
default <T,C extends PreCommitCondition,E extends Exception> T runTaskWithConditionWithRetry(com.google.common.base.Supplier<C> guavaSupplier,
                                                                                                         ConditionAwareTransactionTask<T,C,E> task)
                                                                                                  throws E extends Exception

Deprecated. use runTaskWithConditionWithRetry(Supplier, ConditionAwareTransactionTask) instead.

This is the same as runTaskWithConditionWithRetry(Supplier, ConditionAwareTransactionTask), but instead takes in a Guava supplier. This is deprecated in favour of the aforementioned method.

Throws:

E extends Exception

See Also:

runTaskWithConditionWithRetry(Supplier, ConditionAwareTransactionTask)

runTaskWithConditionThrowOnConflict

<T,C extends PreCommitCondition,E extends Exception> T runTaskWithConditionThrowOnConflict(C condition,
                                                                                           ConditionAwareTransactionTask<T,C,E> task)
                                                                                    throws E extends Exception,
                                                                                           TransactionFailedRetriableException

This method is basically the same as runTaskThrowOnConflict(TransactionTask), but it takes a PreCommitCondition and checks it immediately before the transaction commits.

The created transaction will not commit successfully if the check fails.

Parameters:

condition - condition associated with the transaction

task - task to run

Returns:

value returned by task

Throws:

IllegalStateException - if the transaction manager has been closed.

E extends Exception

TransactionFailedRetriableException

runTaskWithConditionReadOnly

<T,C extends PreCommitCondition,E extends Exception> T runTaskWithConditionReadOnly(C condition,
                                                                                    ConditionAwareTransactionTask<T,C,E> task)
                                                                             throws E extends Exception

This method is basically the same as runTaskReadOnly(TransactionTask), but it takes a PreCommitCondition and checks it for validity before executing reads.

The created transaction will fail if the check is no longer valid after fetching the read timestamp.

Parameters:

condition - condition associated with the transaction

task - task to run

Returns:

value returned by task

Throws:

IllegalStateException - if the transaction manager has been closed.

E extends Exception

getImmutableTimestamp

long getImmutableTimestamp()

Most AtlasDB TransactionManagers will provide Transaction objects that have less than full serializability. The most common is snapshot isolation (SI). SI has a start timestamp and a commit timestamp and an open transaction can only read values that were committed before its start timestamp.

This method will return a timestamp that is before any uncommited/aborted open start timestamps.

Subsequent calls to this method will always be monotonically increasing for a single client.

You are only allowed to open historic/read-only transactions at a timestamp less than or equal to the immutableTimestamp

Returns:

the latest timestamp for which there are no open transactions

Throws:

IllegalStateException - if the transaction manager has been closed.

getLockService

com.palantir.lock.LockService getLockService()

Returns the lock service used by this transaction manager.

Returns:

the lock service for this transaction manager

getTimelockService

com.palantir.lock.v2.TimelockService getTimelockService()

Returns the timelock service used by this transaction manager.

Returns:

the timelock service for this transaction manager

getLockWatchManager

LockWatchManager getLockWatchManager()

getTimestampService

com.palantir.timestamp.TimestampService getTimestampService()

Returns the timestamp service used by this transaction manager.

Returns:

the timestamp service for this transaction manager

getTimestampManagementService

com.palantir.timestamp.TimestampManagementService getTimestampManagementService()

The timestamp management service is used by libraries providing additional functionality around AtlasDB. End-user clients probably should not require it.

Returns:

the timestamp management service for this transaction manager

getTransactionService

TransactionService getTransactionService()

The transaction service is used by libraries providing additional functionality around AtlasDB. End-user clients probably should not require it. Abuse of the transaction service, especially involving putting new records in, may result in severe and irrecoverable data corruption.

Returns:

the transaction service for this transaction manager

getCleaner

Cleaner getCleaner()

Returns the cleaner used by this transaction manager.

Returns:

the cleaner for this transaction manager

getKeyValueService

KeyValueService getKeyValueService()

Returns the KVS used by this transaction manager. In general, this should not be used by clients, as direct reads and writes to the KVS will bypass the Atlas transaction protocol.

Returns:

the key value service for this transaction manager

getKeyValueServiceStatus

KeyValueServiceStatus getKeyValueServiceStatus()

Provides a KeyValueServiceStatus, indicating the current availability of the key value store. This can be used to infer product health - in the usual, conservative case, products can call KeyValueServiceStatus.isHealthy(), which returns true only if all KVS nodes are up.

Products that use AtlasDB only for reads and writes (no schema mutations or deletes, including having sweep and scrub disabled) can also treat KeyValueServiceStatus.HEALTHY_BUT_NO_SCHEMA_MUTATIONS_OR_DELETES as healthy.

This call must be implemented so that it completes synchronously.

getTimelockServiceStatus

TimelockServiceStatus getTimelockServiceStatus()

Provides a TimelockServiceStatus, indicating the current availability of the timelock service. This can be used to infer product health - in the usual, conservative case, products can call TimelockServiceStatus.isHealthy(), which returns true only a healthy connection to timelock service is established.

Returns:

status of the timelock service

getUnreadableTimestamp

long getUnreadableTimestamp()

Returns the timestamp that is before any open start timestamps. This is different from the immutable timestamp, because it takes into account open read-only transactions. There is likely to be NO running transactions open at a timestamp before the unreadable timestamp, however this cannot be guaranteed.

When using the unreadable timestamp for cleanup it is important to leave a sentinel value behind at a negative timestamp so any transaction that is open will fail out if reading a value that is cleaned up instead of just getting back no data. This is needed to ensure that all transactions either produce correct values or fail. It is not an option to return incorrect data.

Returns:

the timestamp that is before any open start timestamps

Throws:

IllegalStateException - if the transaction manager has been closed.

clearTimestampCache

void clearTimestampCache()

Clear the timestamp cache. This is mostly useful for tests that perform operations that would invalidate the cache, although this can also be used to free up some memory.

registerClosingCallback

void registerClosingCallback(Runnable closingCallback)

Registers a Runnable that will be run after the transaction manager is closed. Concurrency: If this method races with close(), then closingCallback may not be called.

startTransactions

@Deprecated
List<OpenTransaction> startTransactions(List<? extends PreCommitCondition> condition)

Deprecated. Similar functionality will exist, but this method is likely to change in the future

This method can be used for direct control over the lifecycle of a batch of transactions. For example, if the work done in each given transaction is interactive and cannot be expressed as a TransactionTask ahead of time, this method allows for a long lived transaction object. For any data read or written to the transaction to be valid, the transaction must be committed by calling OpenTransaction.finish(TransactionTask) to also perform additional cleanup. Note that this does not clean up the pre commit condition associated with that task. The order of transactions returned corresponds with the pre commit conditions passed in, however there are no guarantees on the ordering of transactions returned with respect to their start timestamp.

Returns:

a batch of transactions with associated immutable timestamp locks

close

void close()

Frees resources used by this TransactionManager, and invokes any callbacks registered to run on close. This includes the cleaner, the key value service (and attendant thread pools), and possibly the lock service. All callbacks will execute in the reverse order of registration, regardless of any exceptions thrown. If any exceptions occur, they will be collected and rethrown as a new exception with any exceptions that occurred set as suppressed exceptions. Concurrency: If this method races with registerClosingCallback(closingCallback), then closingCallback may be called (but is not necessarily called). Callbacks registered before the invocation of close() are guaranteed to be executed.

Specified by:

close in interface AutoCloseable