public class SQLKVTransaction extends ForwardingKVStore implements KVTransaction
SQLKVDatabase
transaction.Modifier and Type | Class and Description |
---|---|
protected static class |
SQLKVTransaction.StmtType
Used internally to build SQL statements.
|
Modifier and Type | Field and Description |
---|---|
protected Connection |
connection |
protected SQLKVDatabase |
database |
protected Logger |
log |
Constructor and Description |
---|
SQLKVTransaction(SQLKVDatabase database,
Connection connection)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
apply(Mutations mutations)
Apply all the given
Mutations to this instance. |
protected void |
closeConnection()
Close the
Connection associated with this instance, if it's not already closed. |
void |
commit()
Commit this transaction.
|
protected byte[] |
decodeKey(byte[] dbkey)
Decode the given database key value encoded by
encodeKey() . |
protected KVStore |
delegate()
Get the underlying
KVStore . |
protected byte[] |
encodeKey(byte[] key)
Encode the given key for the underlying database key column.
|
protected void |
finalize() |
SQLKVDatabase |
getKVDatabase()
Get the
KVDatabase with which this instance is associated. |
protected KVTransactionException |
handleException(SQLException e)
Handle an unexpected SQL exception.
|
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.
|
protected <T> T |
query(SQLKVTransaction.StmtType stmtType,
io.permazen.kv.sql.SQLKVTransaction.ResultSetFunction<T> resultSetFunction,
boolean close,
byte[]... params) |
protected byte[] |
queryBytes(SQLKVTransaction.StmtType stmtType,
byte[]... params) |
protected CloseableIterator<KVPair> |
queryIterator(SQLKVTransaction.StmtType stmtType,
byte[]... params) |
protected KVPair |
queryKVPair(SQLKVTransaction.StmtType stmtType,
byte[]... params) |
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).
|
protected void |
update(SQLKVTransaction.StmtType stmtType,
byte[]... params) |
protected void |
updateBatch(SQLKVTransaction.StmtType stmtType,
List<byte[]> paramList) |
Future<Void> |
watchKey(byte[] key)
Watch a key to monitor for changes in its value.
|
adjustCounter, decodeCounter, encodeCounter, get, getAtLeast, getAtMost, getRange
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
adjustCounter, decodeCounter, encodeCounter, get, getAtLeast, getAtMost, getRange, getRange, getRange, removeRange
protected final Logger log
protected final SQLKVDatabase database
protected final Connection connection
public SQLKVTransaction(SQLKVDatabase database, Connection connection) throws SQLException
database
- the associated databaseconnection
- the Connection
for the transactionSQLException
- if an SQL error occurspublic SQLKVDatabase getKVDatabase()
KVTransaction
KVDatabase
with which this instance is associated.getKVDatabase
in interface KVTransaction
public void setTimeout(long timeout)
KVTransaction
setTimeout
in interface KVTransaction
timeout
- transaction timeout in milliseconds, or zero for unlimitedpublic Future<Void> watchKey(byte[] key)
The implementation in SQLKVTransaction
always throws UnsupportedOperationException
.
Subclasses may add support using a database-specific notification mechanism.
watchKey
in interface KVTransaction
key
- the key to watchFuture
that returns key
when the value associated with key
is modifiedStaleTransactionException
- if this transaction is no longer usableRetryTransactionException
- if this transaction must be retried and is no longer usableKVDatabaseException
- if an unexpected error occursUnsupportedOperationException
- if this instance does not support key watchesIllegalArgumentException
- if key
is nullJTransaction.getKey()
public boolean isReadOnly()
KVTransaction
Default is false.
isReadOnly
in interface KVTransaction
public 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 KVTransaction
public void rollback()
KVTransaction
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 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 KVTransaction
public 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 KVTransaction
protected KVTransactionException handleException(SQLException e)
The implementation in SQLKVTransaction
rolls back the SQL transaction, closes the associated Connection
,
and wraps the exception via SQLKVDatabase.wrapException()
.
e
- original exceptionprotected void closeConnection()
Connection
associated with this instance, if it's not already closed.
This method is idempotent.protected void finalize() throws Throwable
public void put(byte[] key, byte[] value)
KVStore
put
in interface KVStore
put
in class ForwardingKVStore
key
- keyvalue
- valuepublic void remove(byte[] key)
KVStore
remove
in interface KVStore
remove
in class ForwardingKVStore
key
- keypublic 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 KVStore
removeRange
in class ForwardingKVStore
minKey
- minimum key (inclusive), or null for no minimummaxKey
- maximum key (exclusive), or null for no maximumpublic void apply(Mutations mutations)
KVStore
Mutations
to this instance.
Mutations are always to be applied in this order: removes, puts, counter adjustments.
The implementation in KVStore
simply iterates over the individual changes and applies them
via remove()
(for removals of a single key), removeRange()
,
put()
, and/or adjustCounter()
. Implementations that can process
batch updates more efficiently are encouraged to override this method.
apply
in interface KVStore
apply
in class ForwardingKVStore
mutations
- mutations to applyprotected KVStore delegate()
ForwardingKVStore
KVStore
.delegate
in class ForwardingKVStore
KVStore
public 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 KVTransaction
readOnly
- read-only settingprotected byte[] queryBytes(SQLKVTransaction.StmtType stmtType, byte[]... params)
protected KVPair queryKVPair(SQLKVTransaction.StmtType stmtType, byte[]... params)
protected CloseableIterator<KVPair> queryIterator(SQLKVTransaction.StmtType stmtType, byte[]... params)
protected <T> T query(SQLKVTransaction.StmtType stmtType, io.permazen.kv.sql.SQLKVTransaction.ResultSetFunction<T> resultSetFunction, boolean close, byte[]... params)
protected void update(SQLKVTransaction.StmtType stmtType, byte[]... params)
protected void updateBatch(SQLKVTransaction.StmtType stmtType, List<byte[]> paramList)
protected byte[] encodeKey(byte[] key)
The implementation in SQLKVTransaction
just returns key
.
key
- keydecodeKey()
protected byte[] decodeKey(byte[] dbkey)
encodeKey()
.
The implementation in SQLKVTransaction
just returns dbkey
.
dbkey
- database value for key columnencodeKey()
Copyright © 2022. All rights reserved.