Package com.palantir.atlasdb.transaction.api

Interface Transaction

  • All Known Subinterfaces:
    ConstraintCheckingTransaction, OpenTransaction
    public interface Transaction
    Provides the methods for a transaction with the key-value store. In general: users may assume that if maps (including sorted maps) keyed on byte[] are returned to the user, they may be accessed via any byte array that is equivalent in terms of Arrays.equals(byte[], byte[]). Throughout this class, methods that return structures that may not perform all of their loading upfront (batching visitables, iterables, streams and futures, for instance) _must_ be used strictly within the scope of the transaction. Concretely, this means that results must be retrieved before exiting the transaction - in the case of streams and iterators, this means that you must collect the results before exiting; in the case of futures, you must await all asynchronous calls before returning from the transaction.
    See Also:
    TransactionManager

    • Method Detail

      • getRows

        @Idempotent
NavigableMap<byte[],​RowResult<byte[]>> getRows​(TableReference tableRef,
                                                     Iterable<byte[]> rows,
                                                     ColumnSelection columnSelection)
        Returns a mapping of rows to RowResults within tableRef for the specified rows, loading columns according to the provided ColumnSelection. Duplicate rows are permitted (but there will be just one key-value pair for that row in the returned NavigableMap). The returned NavigableMap is sorted on the byte order of row keys; the ordering of the input parameter rows is irrelevant. If there are rows with no cells matching the provided ColumnSelection, they will not be present in the Map.keySet() of the output map at all. This accounts for writes and deletes done in this transaction: a row written to in this transaction will be present, and a row which is deleted in this transaction will be absent.
        Parameters:
        tableRef - table to load rows from
        rows - rows to be loaded
        columnSelection - columns to load from the given rows
        Returns:
        a mapping of rows to the columns matching the provided column selection

      • getRowsColumnRange

        @Idempotent
Map<byte[],​com.palantir.common.base.BatchingVisitable<Map.Entry<Cell,​byte[]>>> getRowsColumnRange​(TableReference tableRef,
                                                                                                              Iterable<byte[]> rows,
                                                                                                              BatchColumnRangeSelection columnRangeSelection)
        Returns a mapping of requested rows to corresponding columns from the queried table. Only columns matching the provided predicate will be returned, and the single predicate provided applies across all of the rows. Users should provide unique rows: behaviour is undefined if this is not the case. The returned BatchingVisitables are guaranteed to return cells matching the predicate. These are sorted by column on byte ordering. It is guaranteed that the Map.keySet() of the returned map has a corresponding element for each of the input rows, even if there are rows where no columns match the predicate. Batching visitables must be used strictly within the scope of the transaction.
        Parameters:
        tableRef - table to load values from
        rows - unique rows to apply the column range selection to
        columnRangeSelection - range of columns and batch size to load for each of the rows provided
        Returns:
        a mapping of rows to cells matching the predicate in the row, following the ordering outlined above

      • getRowsColumnRange

        @Idempotent
Iterator<Map.Entry<Cell,​byte[]>> getRowsColumnRange​(TableReference tableRef,
                                                          Iterable<byte[]> rows,
                                                          ColumnRangeSelection columnRangeSelection,
                                                          int batchHint)
        Returns a single iterator over the cell-value pairs in tableRef for the specified rows, where the columns fall within the provided ColumnRangeSelection. The single provided ColumnRangeSelection applies to all of the rows. The returned iterator is guaranteed to return cell-value pairs in a lexicographic ordering over rows and columns where rows are sorted according to the provided rows Iterable and then columns on byte ordering. If the Iterable does not have a stable ordering (i.e. iteration order can change across iterators returned) then the returned iterator is sorted lexicographically with columns sorted on byte ordering, but the ordering of rows is undefined. Iterators must be used strictly within the scope of the transaction.
        Parameters:
        tableRef - table to load values from
        rows - unique rows to apply the column range selection to
        columnRangeSelection - range of columns to load for each of the rows provided
        batchHint - number of columns that should be loaded from the underlying database at once
        Returns:
        an iterator over cell-value pairs, guaranteed to follow the ordering outlined above
        Throws:
        IllegalArgumentException - if rows contains duplicates

      • getRowsColumnRangeIterator

        @Idempotent
Map<byte[],​Iterator<Map.Entry<Cell,​byte[]>>> getRowsColumnRangeIterator​(TableReference tableRef,
                                                                                    Iterable<byte[]> rows,
                                                                                    BatchColumnRangeSelection columnRangeSelection)
        Returns a mapping of rows to Iterators over cell-value pairs within tableRef for the specified rows, where the columns fall within the provided BatchColumnRangeSelection. The single provided BatchColumnRangeSelection applies to all of the rows. The returned iterators are guaranteed to return cells matching the predicate. These are sorted by column on byte ordering. It is guaranteed that the Map.keySet() of the returned map has a corresponding element for each of the input rows, even if there are rows where no columns match the predicate. Iterators must be used strictly within the scope of the transaction.
        Parameters:
        tableRef - table to load values from
        rows - unique rows to apply the column range selection to
        columnRangeSelection - range of columns and batch size to load for each of the rows provided
        Returns:
        a mapping of rows to cells matching the predicate in the row, following the ordering outlined above
        Throws:
        IllegalArgumentException - if rows contains duplicates

      • getSortedColumns

        @Idempotent
Iterator<Map.Entry<Cell,​byte[]>> getSortedColumns​(TableReference tableRef,
                                                        Iterable<byte[]> rows,
                                                        BatchColumnRangeSelection batchColumnRangeSelection)
        Returns an iterator over cell-value pairs within tableRef for the specified rows, where the columns fall within the provided BatchColumnRangeSelection.The single provided BatchColumnRangeSelection applies to all of the rows. The cells for a row appear exactly once even if the same row is included multiple times in rows. The returned iterator is guaranteed to contain cells sorted first in lexicographical order of column on byte ordering, then in order of row, where rows are sorted according to the provided rows Iterable. If the Iterable does not have a stable ordering (i.e. iteration order can change across iterators returned) then the returned iterator is sorted lexicographically with columns sorted on byte ordering, but the ordering of rows is undefined. In case of duplicate rows, the ordering is based on the first occurrence of the row. Iterators must be used strictly within the scope of the transaction.
        Parameters:
        tableRef - table to load values from
        rows - unique rows to apply column range selection to
        batchColumnRangeSelection - range of columns and batch size to load for all rows provided
        Returns:
        an iterator over cell-value pairs, guaranteed to follow the ordering outlined above

      • get

        @Idempotent
Map<Cell,​byte[]> get​(TableReference tableRef,
                           Set<Cell> cells)
        Gets the values associated for each cell in cells from table specified by tableRef.
        Parameters:
        tableRef - the table from which to get the values
        cells - the cells for which we want to get the values
        Returns:
        a Map from Cell to byte[] representing cell/value pairs

      • getAsync

        @Idempotent
com.google.common.util.concurrent.ListenableFuture<Map<Cell,​byte[]>> getAsync​(TableReference tableRef,
                                                                                    Set<Cell> cells)
        Gets the values associated for each cell in cells from table specified by tableRef. It is not guaranteed that the actual implementations are in fact asynchronous. The future must be used strictly within the scope of the transaction.
        Parameters:
        tableRef - the table from which to get the values
        cells - the cells for which we want to get the values
        Returns:
        a Map from Cell to byte[] representing cell/value pairs

      • getRange

        @Idempotent
com.palantir.common.base.BatchingVisitable<RowResult<byte[]>> getRange​(TableReference tableRef,
                                                                       RangeRequest rangeRequest)
        Creates a visitable that scans the provided range. Batching visitables must be used strictly within the scope of the transaction.
        Parameters:
        tableRef - the table to scan
        rangeRequest - the range of rows and columns to scan
        Returns:
        an array of RowResult objects representing the range

      • getRanges

        @Idempotent
@Deprecated
Iterable<com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>> getRanges​(TableReference tableRef,
                                                                                  Iterable<RangeRequest> rangeRequests)
        Deprecated.
        Should use either getRanges(TableReference, Iterable, int, BiFunction) or getRangesLazy(TableReference, Iterable) to ensure you are using an appropriate level of concurrency for your specific workflow.
        Creates a visitable that scans the provided range.

        To get good performance out of this method, it is important to specify the batch hint in each RangeRequest. If this isn't done then this method may do more work than you need and will be slower than it needs to be. If the batchHint isn't specified it will default to 1 for the first page in each range. Batching visitables must be used strictly within the scope of the transaction.

      • getRanges

        @Idempotent
<T> java.util.stream.Stream<T> getRanges​(TableReference tableRef,
                                         Iterable<RangeRequest> rangeRequests,
                                         int concurrencyLevel,
                                         java.util.function.BiFunction<RangeRequest,​com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>,​T> visitableProcessor)
        Creates unvisited visitables that scan the provided ranges and then applies the provided visitableProcessor function with concurrency specified by the concurrencyLevel parameter. It is guaranteed that the range requests seen by the provided visitable processor are equal to the provided iterable of range requests, though no guarantees are made on the order they are encountered in. Streams must be read within the scope of the transaction.

      • getRangesLazy

        @Idempotent
java.util.stream.Stream<com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>> getRangesLazy​(TableReference tableRef,
                                                                                                     Iterable<RangeRequest> rangeRequests)
        Returns visitibles that scan the provided ranges. This does no pre-fetching so visiting the resulting visitibles will incur database reads on first access. Streams and visitables must be read within the scope of this transaction.

      • put

        @Idempotent
void put​(TableReference tableRef,
         Map<Cell,​byte[]> values)
        Puts values into the key-value store. If you put a null or the empty byte array, then this is treated like a delete to the store.
        Parameters:
        tableRef - the table into which to put the values
        values - the values to append to the table

      • delete

        @Idempotent
void delete​(TableReference tableRef,
            Set<Cell> keys)
        Deletes values from the key-value store.
        Parameters:
        tableRef - the table from which to delete the values
        keys - the set of cells to delete from the store

      • abort

        @Idempotent
void abort()
        Aborts the transaction. Can be called repeatedly.

        Cannot be called after a call to commit(). Check isUncommitted() to be sure.

      • commit

        @Idempotent
void commit()
     throws TransactionFailedException
        Commits the transaction. Can be called repeatedly, but will only commit the first time. Cannot be called after a call to abort(). Check isAborted() before calling commit if unsure.

        This method checks for any data conflicts. This can happen if someone else is concurrently writing to the same Cells.

        NOTE: only cell-level conflicts are detected. If another transaction writes to the same row but a different cell, then no conflict occurs.

        Throws:
        TransactionConflictException - if this transaction had a conflict with another running transaction
        TransactionCommitFailedException - if this transaction failed at commit time. If this exception is thrown, then this transaction may have been committed, but most likely not.
        TransactionFailedException

      • isAborted

        @Idempotent
boolean isAborted()
        Gets whether the transaction has been aborted.
        Returns:
        true if abort() has been called, otherwise false

      • isUncommitted

        @Idempotent
boolean isUncommitted()
        Gets whether the transaction has not been committed.
        Returns:
        true if neither commit() or abort() have been called, otherwise false

      • getTimestamp

        @Idempotent
long getTimestamp()
        Gets the timestamp the current transaction is running at.

      • getReadSentinelBehavior

        TransactionReadSentinelBehavior getReadSentinelBehavior()
        Determines what the transaction should do if it reads a sentinel timestamp which indicates it may be performing an inconsistent read.

      • onSuccess

        void onSuccess​(Runnable callback)
        Registers a callback that will be called after the AtlasDB client perceives a successful commit of a transaction. We guarantee that if the provided callback runs, the transaction has definitely committed successfully. The converse is NOT true: it is possible that the callback is NOT called even if the transaction was successful. The semantics of callbacks are as follows:
        • Callbacks must be registered before a transaction commits or aborts; registration of a callback once either of the above is true will throw an exception.
        • Callbacks will run serially in the order they were registered.
        • Exceptions thrown from any callback will be propagated immediately, and cause callbacks registered later to not run.
        • Exceptions thrown from any callback will not change the result of the transaction.

      • disableReadWriteConflictChecking

        @Idempotent
default void disableReadWriteConflictChecking​(TableReference tableRef)
        Disables read-write conflict checking for this table for the duration of this transaction only. This method should be called before any reads are done on this table.

      • markTableInvolved

        @Idempotent
default void markTableInvolved​(TableReference tableRef)
        Marks this table as involved in this transaction, without actually reading any rows.