public class PrefixKVTransaction extends PrefixKVStore implements KVTransaction
KVTransactionview of all keys having a common
byteprefix in a containing
Instances are normally created indirectly from
PrefixKVDatabase instances via
Instances may also be created directly from an existing
KVTransaction; in that case,
rollback() forward to the containing transaction,
|Constructor and Description|
Constructor that wraps an existing
|Modifier and Type||Method and Description|
Commit this transaction.
Get the underlying
Determine whether this transaction is read-only.
Create a mutable copy of the database content represented by this transaction.
Cancel this transaction, if not already canceled.
Enable or disable read-only mode.
Change the timeout for this transaction from its default value (optional operation).
Watch a key to monitor for changes in its value.
adjustCounter, create, get, getAtLeast, getAtMost, getKeyPrefix, getRange, put, remove, removeRange
apply, decodeCounter, encodeCounter
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
protected KVTransaction delegate()
public PrefixKVDatabase getKVDatabase()
PrefixKVDatabaseassociated with this instance.
public void setTimeout(long timeout)
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.stop()'ed, all outstanding
key watches are implicitly
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
field, whose key is then watched (to determine the key corresponding to a Java model object field, use
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,
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
Some implementations may only support watching a key that already exists.
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 support is indepdendent of whether the transaction is read-only.
public boolean isReadOnly()
Default is false.
public void setReadOnly(boolean readOnly)
Read-only transactions allow mutations, but all changes are discarded on
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
not guaranteed to be up to date, even if that transaction is read-only.
Default is false.
public void commit()
Note that if this method throws a
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.
public void rollback()
After 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
This method may be invoked at any time, even after a previous invocation of
KVTransaction.rollback(), in which case the invocation will be ignored.
In particular, this method should not throw
public CloseableKVStore mutableSnapshot()
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.
CloseableKVStore should be promply
close()'d when no longer
needed to release any underlying resources. In particular, the caller must ensure that the
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.
Copyright © 2022. All rights reserved.