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 ofArrays.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
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Transaction.TransactionType
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description void
abort()
Aborts the transaction.void
commit()
Commits the transaction.void
commit(TransactionService transactionService)
void
delete(TableReference tableRef, Set<Cell> keys)
Deletes values from the key-value store.default void
disableReadWriteConflictChecking(TableReference tableRef)
Disables read-write conflict checking for this table for the duration of this transaction only.Map<Cell,byte[]>
get(TableReference tableRef, Set<Cell> cells)
Gets the values associated for each cell incells
from table specified bytableRef
.com.google.common.util.concurrent.ListenableFuture<Map<Cell,byte[]>>
getAsync(TableReference tableRef, Set<Cell> cells)
Gets the values associated for each cell incells
from table specified bytableRef
.com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>
getRange(TableReference tableRef, RangeRequest rangeRequest)
Creates a visitable that scans the provided range.Iterable<com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>>
getRanges(TableReference tableRef, Iterable<RangeRequest> rangeRequests)
Deprecated.Should use eithergetRanges(TableReference, Iterable, int, BiFunction)
orgetRangesLazy(TableReference, Iterable)
to ensure you are using an appropriate level of concurrency for your specific workflow.<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.<T> java.util.stream.Stream<T>
getRanges(TableReference tableRef, Iterable<RangeRequest> rangeRequests, java.util.function.BiFunction<RangeRequest,com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>,T> visitableProcessor)
Same asgetRanges(TableReference, Iterable, int, BiFunction)
but uses the default concurrency value specified byKeyValueServiceConfig.defaultGetRangesConcurrency()
.<T> java.util.stream.Stream<T>
getRanges(GetRangesQuery<T> getRangesQuery)
java.util.stream.Stream<com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>>
getRangesLazy(TableReference tableRef, Iterable<RangeRequest> rangeRequests)
Returns visitibles that scan the provided ranges.TransactionReadSentinelBehavior
getReadSentinelBehavior()
Determines what the transaction should do if it reads a sentinel timestamp which indicates it may be performing an inconsistent read.NavigableMap<byte[],RowResult<byte[]>>
getRows(TableReference tableRef, Iterable<byte[]> rows, ColumnSelection columnSelection)
Returns a mapping of rows toRowResult
s withintableRef
for the specifiedrows
, loading columns according to the providedColumnSelection
.Map<byte[],com.palantir.common.base.BatchingVisitable<Map.Entry<Cell,byte[]>>>
getRowsColumnRange(TableReference tableRef, Iterable<byte[]> rows, BatchColumnRangeSelection columnRangeSelection)
Returns a mapping of requestedrows
to corresponding columns from the queried table.Iterator<Map.Entry<Cell,byte[]>>
getRowsColumnRange(TableReference tableRef, Iterable<byte[]> rows, ColumnRangeSelection columnRangeSelection, int batchHint)
Returns a single iterator over the cell-value pairs intableRef
for the specifiedrows
, where the columns fall within the providedColumnRangeSelection
.Map<byte[],Iterator<Map.Entry<Cell,byte[]>>>
getRowsColumnRangeIterator(TableReference tableRef, Iterable<byte[]> rows, BatchColumnRangeSelection columnRangeSelection)
Returns a mapping of rows toIterator
s over cell-value pairs withintableRef
for the specifiedrows
, where the columns fall within the providedBatchColumnRangeSelection
.Iterator<Map.Entry<Cell,byte[]>>
getSortedColumns(TableReference tableRef, Iterable<byte[]> rows, BatchColumnRangeSelection batchColumnRangeSelection)
Returns an iterator over cell-value pairs withintableRef
for the specifiedrows
, where the columns fall within the providedBatchColumnRangeSelection
.The single providedBatchColumnRangeSelection
applies to all of the rows.long
getTimestamp()
Gets the timestamp the current transaction is running at.Transaction.TransactionType
getTransactionType()
boolean
isAborted()
Gets whether the transaction has been aborted.boolean
isUncommitted()
Gets whether the transaction has not been committed.default void
markTableInvolved(TableReference tableRef)
Marks this table as involved in this transaction, without actually reading any rows.void
onSuccess(Runnable callback)
Registers a callback that will be called after the AtlasDB client perceives a successful commit of a transaction.void
put(TableReference tableRef, Map<Cell,byte[]> values)
Puts values into the key-value store.void
setTransactionType(Transaction.TransactionType transactionType)
void
useTable(TableReference tableRef, ConstraintCheckable table)
Informs the transaction that a particular table has been written to.
-
-
-
Method Detail
-
getRows
@Idempotent NavigableMap<byte[],RowResult<byte[]>> getRows(TableReference tableRef, Iterable<byte[]> rows, ColumnSelection columnSelection)
Returns a mapping of rows toRowResult
s withintableRef
for the specifiedrows
, loading columns according to the providedColumnSelection
. Duplicate rows are permitted (but there will be just one key-value pair for that row in the returnedNavigableMap
). The returnedNavigableMap
is sorted on the byte order of row keys; the ordering of the input parameterrows
is irrelevant. If there are rows with no cells matching the providedColumnSelection
, they will not be present in theMap.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 fromrows
- rows to be loadedcolumnSelection
- 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 requestedrows
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 returnedBatchingVisitable
s are guaranteed to return cells matching the predicate. These are sorted by column on byte ordering. It is guaranteed that theMap.keySet()
of the returned map has a corresponding element for each of the inputrows
, 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 fromrows
- unique rows to apply the column range selection tocolumnRangeSelection
- 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 intableRef
for the specifiedrows
, where the columns fall within the providedColumnRangeSelection
. The single providedColumnRangeSelection
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 providedrows
Iterable
and then columns on byte ordering. If theIterable
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 fromrows
- unique rows to apply the column range selection tocolumnRangeSelection
- range of columns to load for each of the rows providedbatchHint
- 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
- ifrows
contains duplicates
-
getRowsColumnRangeIterator
@Idempotent Map<byte[],Iterator<Map.Entry<Cell,byte[]>>> getRowsColumnRangeIterator(TableReference tableRef, Iterable<byte[]> rows, BatchColumnRangeSelection columnRangeSelection)
Returns a mapping of rows toIterator
s over cell-value pairs withintableRef
for the specifiedrows
, where the columns fall within the providedBatchColumnRangeSelection
. The single providedBatchColumnRangeSelection
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 theMap.keySet()
of the returned map has a corresponding element for each of the inputrows
, 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 fromrows
- unique rows to apply the column range selection tocolumnRangeSelection
- 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
- ifrows
contains duplicates
-
getSortedColumns
@Idempotent Iterator<Map.Entry<Cell,byte[]>> getSortedColumns(TableReference tableRef, Iterable<byte[]> rows, BatchColumnRangeSelection batchColumnRangeSelection)
Returns an iterator over cell-value pairs withintableRef
for the specifiedrows
, where the columns fall within the providedBatchColumnRangeSelection
.The single providedBatchColumnRangeSelection
applies to all of the rows. The cells for a row appear exactly once even if the same row is included multiple times inrows
. 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 providedrows
Iterable
. If theIterable
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 fromrows
- unique rows to apply column range selection tobatchColumnRangeSelection
- 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 incells
from table specified bytableRef
.
-
getAsync
@Idempotent com.google.common.util.concurrent.ListenableFuture<Map<Cell,byte[]>> getAsync(TableReference tableRef, Set<Cell> cells)
Gets the values associated for each cell incells
from table specified bytableRef
. It is not guaranteed that the actual implementations are in fact asynchronous. The future must be used strictly within the scope of the transaction.
-
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 scanrangeRequest
- 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 eithergetRanges(TableReference, Iterable, int, BiFunction)
orgetRangesLazy(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.
-
getRanges
@Idempotent <T> java.util.stream.Stream<T> getRanges(TableReference tableRef, Iterable<RangeRequest> rangeRequests, java.util.function.BiFunction<RangeRequest,com.palantir.common.base.BatchingVisitable<RowResult<byte[]>>,T> visitableProcessor)
Same asgetRanges(TableReference, Iterable, int, BiFunction)
but uses the default concurrency value specified byKeyValueServiceConfig.defaultGetRangesConcurrency()
.
-
getRanges
@Idempotent <T> java.util.stream.Stream<T> getRanges(GetRangesQuery<T> getRangesQuery)
Same asgetRanges(TableReference, Iterable, int, BiFunction)
. However, additionally allows for the specification of additional parameters specific toGetRangesQuery
.
-
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 valuesvalues
- 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 valueskeys
- the set of cells to delete from the store
-
getTransactionType
@Idempotent Transaction.TransactionType getTransactionType()
-
setTransactionType
@Idempotent void setTransactionType(Transaction.TransactionType transactionType)
-
abort
@Idempotent void abort()
Aborts the transaction. Can be called repeatedly.Cannot be called after a call to
commit()
. CheckisUncommitted()
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 toabort()
. CheckisAborted()
before calling commit if unsure.This method checks for any data conflicts. This can happen if someone else is concurrently writing to the same
Cell
s.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 transactionTransactionCommitFailedException
- if this transaction failed at commit time. If this exception is thrown, then this transaction may have been committed, but most likely not.TransactionFailedException
-
commit
@Idempotent void commit(TransactionService transactionService) throws TransactionFailedException
- Throws:
TransactionFailedException
-
isAborted
@Idempotent boolean isAborted()
Gets whether the transaction has been aborted.- Returns:
true
ifabort()
has been called, otherwisefalse
-
isUncommitted
@Idempotent boolean isUncommitted()
Gets whether the transaction has not been committed.- Returns:
true
if neithercommit()
orabort()
have been called, otherwisefalse
-
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.
-
useTable
void useTable(TableReference tableRef, ConstraintCheckable table)
Informs the transaction that a particular table has been written to.
-
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.
-
-