Package com.palantir.atlasdb.transaction.api

Interface TransactionManager

    • 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 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

      • 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​(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. If the lock request provided has a blocking mode of type BlockingMode.DO_NOT_BLOCK, the lock request will NOT be retried if it fails. Otherwise, the lock request will be retried on failure for a finite number of times (though users must of course be prepared for the case where all retries fail).

        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

      • 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

      • 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

      • 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