@ThreadSafe public class FoundationKVTransaction extends Object implements KVTransaction
| Modifier and Type | Method and Description |
|---|---|
void |
adjustCounter(byte[] key,
long amount)
Adjust the counter at the given key by the given amount.
|
void |
commit()
Commit this transaction.
|
long |
decodeCounter(byte[] bytes)
Decode a counter value previously encoded by
encodeCounter(). |
byte[] |
encodeCounter(long value)
Encode a counter value into a
byte[] value suitable for use with decodeCounter()
and/or adjustCounter(). |
byte[] |
get(byte[] key)
Get the value associated with the given key, if any.
|
KVPair |
getAtLeast(byte[] minKey,
byte[] maxKey)
Get the key/value pair having the smallest key greater than or equal to the given minimum, if any.
|
KVPair |
getAtMost(byte[] maxKey,
byte[] minKey)
Get the key/value pair having the largest key strictly less than the given maximum, if any.
|
FoundationKVDatabase |
getKVDatabase()
Get the
KVDatabase with which this instance is associated. |
CloseableIterator<KVPair> |
getRange(byte[] minKey,
byte[] maxKey,
boolean reverse)
Iterate the key/value pairs in the specified range.
|
Transaction |
getTransaction()
Get the underlying
Transaction associated with this instance. |
boolean |
isReadOnly()
Determine whether this transaction is read-only.
|
CloseableKVStore |
mutableSnapshot()
Create a mutable copy of the database content represented by this transaction.
|
void |
put(byte[] key,
byte[] value)
Set the value associated with the given key.
|
void |
remove(byte[] key)
Remove the key/value pair with the given key, if it exists.
|
void |
removeRange(byte[] minKey,
byte[] maxKey)
Remove all key/value pairs whose keys are in a given range.
|
void |
rollback()
Cancel this transaction, if not already canceled.
|
void |
setReadOnly(boolean readOnly)
Enable or disable read-only mode.
|
void |
setTimeout(long timeout)
Change the timeout for this transaction from its default value (optional operation).
|
CompletableFuture<Void> |
watchKey(byte[] key)
Watch a key to monitor for changes in its value.
|
KVTransactionException |
wrapException(FDBException e)
Wrap the given
FDBException in the appropriate KVTransactionException. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitapply, getRange, getRange, removeRangepublic Transaction getTransaction()
Transaction associated with this instance.
Note: even if this transaction is read-only, the returned Transaction will permit mutations
that persist on commit(); use accordingly.
public FoundationKVDatabase getKVDatabase()
KVTransactionKVDatabase with which this instance is associated.getKVDatabase in interface KVTransactionpublic void setTimeout(long timeout)
KVTransactionsetTimeout in interface KVTransactiontimeout - transaction timeout in milliseconds, or zero for unlimitedpublic CompletableFuture<Void> watchKey(byte[] key)
KVTransaction
When this method is invoked, key's current value (if any) as read by this transaction is remembered. The returned
Future completes if and when a different value for key is subsequently committed by some transaction,
including possibly this one. This includes creation or deletion of the key.
Key watches outlive the transaction in which they are created, persisting until they complete or are
cancel()'ed. When a KVDatabase is KVDatabase.stop()'ed, all outstanding
key watches are implicitly cancel()'ed.
Caveats
Key watches are not without overhead; applications should avoid overuse. For example, consider creating a
single key that is used to consolidate modifications to some set of keys; at the Permazen layer, modification
to multiple objects and/or fields can detected and consolidated using an
@OnChange method that increments a single Counter
field, whose key is then watched (to determine the key corresponding to a Java model object field, use
JTransaction.getKey()).
Conceptually, detection of changes behaves as if by a background thread that periodically creates a new transaction and reads the key's value (the actual implementation will likely be more efficient). This means a change that is quickly reverted could be missed, and that multiple changes could occur before notification. In addition, spurious notifications may occur, where the key's value has not changed.
A key watch is only guaranteed to be valid if the transaction in which it was created successfully commits.
In particular, nothing is specified about how or whether Futures associated with failed transactions complete,
so the Futures returned by this method should not be relied on until after a successful commit (perhaps with
the help of a transaction callback).
Key watch support is optional; instances that don't support key watches throw UnsupportedOperationException.
Some implementations may only support watching a key that already exists.
Note: many KVDatabase implementations actually return a
ListenableFuture. However, listeners must not perform any
long running or blocking operations. Also, because the semantics of RetryTransactionException allow for
the possibility that the transaction actually did commit, "duplicate" listener notifications could occur.
Key watch Futures that have not completed yet, but are no longer needed, must be cancel()'ed
to avoid memory leaks.
Key watch support is indepdendent of whether the transaction is read-only.
watchKey in interface KVTransactionkey - the key to watchFuture that returns key when the value associated with key is modifiedJTransaction.getKey()public boolean isReadOnly()
KVTransactionDefault is false.
isReadOnly in interface KVTransactionpublic void setReadOnly(boolean readOnly)
KVTransaction
Read-only transactions allow mutations, but all changes are discarded on KVTransaction.commit().
Some implementations may impose one or more of the following restrictions on this method:
setReadOnly() may only be invoked prior to accessing data;setReadOnly() may only be invoked prior to mutating data; and/or
Note: for some implementations, the data read from a transaction that is never KVTransaction.commit()'ed is
not guaranteed to be up to date, even if that transaction is read-only.
Default is false.
setReadOnly in interface KVTransactionreadOnly - read-only settingpublic void commit()
KVTransaction
Note that if this method throws a RetryTransactionException,
the transaction was either successfully committed or rolled back. In either case,
this instance is no longer usable.
Note also for some implementations, even read-only transactions must be KVTransaction.commit()'ed in order for the
data accessed during the transaction to be guaranteed to be up to date.
commit in interface KVTransactionpublic void rollback()
KVTransactionAfter this method returns, this instance is no longer usable.
Note: for some implementations, rolling back a transaction invalidates guarantees about the the data read
during the transaction being up to date, even if the transaction was setReadOnly().
This method may be invoked at any time, even after a previous invocation of
KVTransaction.commit() or KVTransaction.rollback(), in which case the invocation will be ignored.
In particular, this method should not throw StaleTransactionException.
rollback in interface KVTransactionpublic CloseableKVStore mutableSnapshot()
KVTransaction
The returned CloseableKVStore should be mutable, but all changes should remain private until
close() is invoked, at which time they should be discarded.
That is, the CloseableKVStore it is completely independent from this transaction
(subsequent changes to either one do not affect the other).
Note that as with any other information extracted from a KVTransaction, the returned content
should not be considered valid until this transaction has been successfully committed.
The returned CloseableKVStore should be promply close()'d when no longer
needed to release any underlying resources. In particular, the caller must ensure that the CloseableKVStore
is close()'d even if this transaction's commit fails. This may require
adding a transaction synchronization callback, etc.
This is an optional method; only some underlying key/value store technologies can efficiently support it.
Implementations should throw UnsupportedOperationException if not supported.
mutableSnapshot in interface KVTransactionpublic byte[] get(byte[] key)
KVStore
Modifications to the returned byte[] array do not affect this instance.
public KVPair getAtLeast(byte[] minKey, byte[] maxKey)
KVStore
An optional (exclusive) maximum key may also be specified; if maxKey is null, there is no upper bound;
if maxKey <= minKey, null is always returned.
If keys starting with 0xff are not supported by this instance, and minKey starts with 0xff,
then this method returns null.
Modifications to the returned byte[] arrays do not affect this instance.
getAtLeast in interface KVStoreminKey - minimum key (inclusive), or null for no minimum (get the smallest key)maxKey - maximum key (exclusive), or null for no maximum (no upper bound)key >= minKey and key < maxKey, or null if none existspublic KVPair getAtMost(byte[] maxKey, byte[] minKey)
KVStore
An optional (inclusive) minimum key may also be specified; if minKey is null, there is no lower bound
(equivalent to a lower bound of the empty byte array); if minKey >= maxKey, null is always returned.
If keys starting with 0xff are not supported by this instance, and maxKey starts with 0xff,
then this method behaves as if maxKey were null.
Modifications to the returned byte[] arrays do not affect this instance.
getAtMost in interface KVStoremaxKey - maximum key (exclusive), or null for no maximum (get the largest key)minKey - minimum key (inclusive), or null for no minimum (no lower bound)key < maxKey and key >= minKey, or null if none existspublic CloseableIterator<KVPair> getRange(byte[] minKey, byte[] maxKey, boolean reverse)
KVStoreIterator's
remove() method must be supported and should have the same effect as
invoking remove() on the corresponding key.
If keys starting with 0xff are not supported by this instance, and minKey starts with 0xff,
then this method returns an empty iteration.
If keys starting with 0xff are not supported by this instance, and maxKey starts with 0xff,
then this method behaves as if maxKey were null.
The returned Iterator must not throw ConcurrentModificationException;
however, whether or not a "live" Iterator reflects any modifications made after its creation is
implementation dependent. Implementations that do make post-creation updates visible in the Iterator,
even if the update occurs after some delay, must preserve the order in which the modifications actually occurred.
The returned Iterator itself is not guaranteed to be thread safe.
Invokers of this method are encouraged to close() the returned iterators,
though this is not required for correct behavior.
Modifications to the returned KVPair key and value byte[] arrays do not affect this instance.
getRange in interface KVStoreminKey - minimum key (inclusive), or null for no minimum (start at the smallest key)maxKey - maximum key (exclusive), or null for no maximum (end at the largest key)reverse - true to return key/value pairs in reverse order (i.e., keys descending)minKey (inclusive) to maxKey (exclusive)public void put(byte[] key,
byte[] value)
KVStorepublic void remove(byte[] key)
KVStorepublic void removeRange(byte[] minKey,
byte[] maxKey)
KVStore
The minKey must be less than or equal to maxKey; if they equal (and not null)
then nothing happens; if they are both null then all entries are deleted.
If keys starting with 0xff are not supported by this instance, then:
minKey starts with 0xff, then no change occursmaxKey starts with 0xff, then this method behaves as if maxKey were nullremoveRange in interface KVStoreminKey - minimum key (inclusive), or null for no minimummaxKey - maximum key (exclusive), or null for no maximumpublic byte[] encodeCounter(long value)
KVStorebyte[] value suitable for use with decodeCounter()
and/or adjustCounter().encodeCounter in interface KVStorevalue - desired counter valuepublic long decodeCounter(byte[] bytes)
KVStoreencodeCounter().decodeCounter in interface KVStorebytes - encoded counter valuepublic void adjustCounter(byte[] key,
long amount)
KVStoreIdeally this operation should behave in a lock-free manner, so that concurrent transactions can invoke it without conflict. However, when lock-free behavior occurs (if at all) depends on the implementation.
If there is no value associated with key, or key's value is not a valid counter encoding as
would be acceptable to decodeCounter(), then how this operation affects key's
value is undefined.
adjustCounter in interface KVStorekey - keyamount - amount to adjust counter value bypublic KVTransactionException wrapException(FDBException e)
FDBException in the appropriate KVTransactionException.e - FoundationDB exceptionKVTransactionException with chained exception eNullPointerException - if e is nullCopyright © 2020. All rights reserved.