Package io.permazen.kv.sql

Class SQLKVTransaction

java.lang.Object
io.permazen.kv.util.ForwardingKVStore
io.permazen.kv.sql.SQLKVTransaction
All Implemented Interfaces:
KVStore, KVTransaction
public class SQLKVTransaction extends ForwardingKVStore implements KVTransaction
SQLKVDatabase transaction.

  • Field Details

  • Constructor Details

  • Method Details

    • getKVDatabase

      public SQLKVDatabase getKVDatabase()
      Description copied from interface: KVTransaction
      Get the KVDatabase with which this instance is associated.
      Specified by:
      getKVDatabase in interface KVTransaction
      Returns:
      associated database

    • setTimeout

      public void setTimeout(long timeout)
      Description copied from interface: KVTransaction
      Change the timeout for this transaction from its default value (optional operation).
      Specified by:
      setTimeout in interface KVTransaction
      Parameters:
      timeout - transaction timeout in milliseconds, or zero for unlimited

    • watchKey

      public Future<Void> watchKey(byte[] key)
      Watch a key to monitor for changes in its value.

      The implementation in SQLKVTransaction always throws UnsupportedOperationException. Subclasses may add support using a database-specific notification mechanism.

      Specified by:
      watchKey in interface KVTransaction
      Parameters:
      key - the key to watch
      Returns:
      a Future that returns key when the value associated with key is modified
      Throws:
      StaleKVTransactionException - if this transaction is no longer usable
      RetryKVTransactionException - if this transaction must be retried and is no longer usable
      KVDatabaseException - if an unexpected error occurs
      UnsupportedOperationException - if this instance does not support key watches
      IllegalArgumentException - if key is null
      See Also:

    • isReadOnly

      public boolean isReadOnly()
      Description copied from interface: KVTransaction
      Determine whether this transaction is read-only.

      Default is false.

      Specified by:
      isReadOnly in interface KVTransaction
      Returns:
      true if this instance is read-only

    • commit

      public void commit()
      Description copied from interface: KVTransaction
      Commit this transaction.

      Note that if this method throws a RetryKVTransactionException, 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.

      Specified by:
      commit in interface KVTransaction

    • rollback

      public void rollback()
      Description copied from interface: KVTransaction
      Cancel this transaction, if not already canceled.

      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 must not throw StaleKVTransactionException.

      Specified by:
      rollback in interface KVTransaction

    • readOnlySnapshot

      public CloseableKVStore readOnlySnapshot()
      Description copied from interface: KVTransaction
      Create a read-only snapshot of the database content represented by this transaction.

      The returned CloseableKVStore should be treated as read-only. It may not actually be read-only, but if it's not, then any changes should have no effect on this instance. The returned CloseableKVStore must be completely independent from this transaction (subsequent changes to either one do not affect the other).

      Note: 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.

      Specified by:
      readOnlySnapshot in interface KVTransaction
      Returns:
      independent, read-only copy of this transaction's entire database content

    • handleException

      protected KVTransactionException handleException(SQLException e)
      Handle an unexpected SQL exception.

      The implementation in SQLKVTransaction rolls back the SQL transaction, closes the associated Connection, and wraps the exception via SQLKVDatabase.wrapException().

      Parameters:
      e - original exception
      Returns:
      key/value transaction exception

    • closeConnection

      protected void closeConnection()
      Close the Connection associated with this instance, if it's not already closed. This method is idempotent.

    • finalize

      protected void finalize() throws Throwable
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • put

      public void put(byte[] key, byte[] value)
      Description copied from interface: KVStore
      Set the value associated with the given key.
      Specified by:
      put in interface KVStore
      Overrides:
      put in class ForwardingKVStore
      Parameters:
      key - key
      value - value

    • remove

      public void remove(byte[] key)
      Description copied from interface: KVStore
      Remove the key/value pair with the given key, if it exists.
      Specified by:
      remove in interface KVStore
      Overrides:
      remove in class ForwardingKVStore
      Parameters:
      key - key

    • removeRange

      public void removeRange(byte[] minKey, byte[] maxKey)
      Description copied from interface: KVStore
      Remove all key/value pairs whose keys are in a given range.

      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:

      • If minKey starts with 0xff, then no change occurs
      • If maxKey starts with 0xff, then this method behaves as if maxKey were null
      Specified by:
      removeRange in interface KVStore
      Overrides:
      removeRange in class ForwardingKVStore
      Parameters:
      minKey - minimum key (inclusive), or null for no minimum
      maxKey - maximum key (exclusive), or null for no maximum

    • apply

      public void apply(Mutations mutations)
      Description copied from interface: KVStore
      Apply all the given 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.

      Unlike AtomicKVStore.apply(), this method is not required to apply the mutations atomically.

      Specified by:
      apply in interface KVStore
      Overrides:
      apply in class ForwardingKVStore
      Parameters:
      mutations - mutations to apply

    • delegate

      protected KVStore delegate()
      Description copied from class: ForwardingKVStore
      Get the underlying KVStore.
      Specified by:
      delegate in class ForwardingKVStore
      Returns:
      underlying KVStore

    • setReadOnly

      public void setReadOnly(boolean readOnly)
      Description copied from interface: KVTransaction
      Enable or disable read-only mode.

      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
      • Once set to read-only, a transaction may not be set back to read-write
      If one of the above constraints is violated, an IllegalStateException is thrown.

      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.

      Specified by:
      setReadOnly in interface KVTransaction
      Parameters:
      readOnly - read-only setting

    • queryBytes

      protected byte[] queryBytes(SQLKVTransaction.StmtType stmtType, byte[]... params)

    • queryKVPair

      protected KVPair queryKVPair(SQLKVTransaction.StmtType stmtType, byte[]... params)

    • queryIterator

      protected CloseableIterator<KVPair> queryIterator(SQLKVTransaction.StmtType stmtType, byte[]... params)

    • query

      protected <T> T query(SQLKVTransaction.StmtType stmtType, io.permazen.kv.sql.SQLKVTransaction.ResultSetFunction<T> resultSetFunction, boolean close, byte[]... params)

    • update

      protected void update(SQLKVTransaction.StmtType stmtType, byte[]... params)

    • updateBatch

      protected void updateBatch(SQLKVTransaction.StmtType stmtType, List<byte[]> paramList)

    • encodeKey

      protected byte[] encodeKey(byte[] key)
      Encode the given key for the underlying database key column.

      The implementation in SQLKVTransaction just returns key.

      Parameters:
      key - key
      Returns:
      database value for key column
      See Also:

    • decodeKey

      protected byte[] decodeKey(byte[] dbkey)
      Decode the given database key value encoded by encodeKey().

      The implementation in SQLKVTransaction just returns dbkey.

      Parameters:
      dbkey - database value for key column
      Returns:
      key
      See Also: