Package io.permazen.kv.spanner

Class SpannerKVTransaction

java.lang.Object
io.permazen.kv.util.ForwardingKVStore
io.permazen.kv.spanner.SpannerKVTransaction
All Implemented Interfaces:
KVStore, KVTransaction
@ThreadSafe public class SpannerKVTransaction extends ForwardingKVStore implements KVTransaction
SpannerKVDatabase transaction.

  • Field Details

    • log

      protected final Logger log

    • kvdb

      protected final SpannerKVDatabase kvdb

    • client

      protected final com.google.cloud.spanner.DatabaseClient client

    • tableName

      protected final String tableName

    • consistency

      protected final com.google.cloud.spanner.TimestampBound consistency

  • Constructor Details

    • SpannerKVTransaction

      protected SpannerKVTransaction(SpannerKVDatabase kvdb, com.google.cloud.spanner.DatabaseClient client, String tableName, com.google.cloud.spanner.TimestampBound consistency)
      Constructor.
      Parameters:
      kvdb - associated database
      client - client for access
      tableName - Spanner key/value database table name
      consistency - transaction consistency level
      Throws:
      IllegalArgumentException - if any paramter is null

  • Method Details

    • getConsistency

      public com.google.cloud.spanner.TimestampBound getConsistency()
      Get the consistency level configured for this transaction.

      Note that read-write transactions always use strong consistency.

      Returns:
      consistency of this transaction

    • isStrongConsistency

      public boolean isStrongConsistency()
      Convenience method to determine whether this transaction is using strong consistency.
      Returns:
      true if this transaction has strong consistency

    • getTimestamp

      public com.google.cloud.Timestamp getTimestamp()
      Get the timestamp associated with this transaction.

      For read-only transactions, this returns the Spanner timestamp at which the data was accessed. It should not be invoked until at least one data query has occurred.

      For read-write transactions, this returns the Spanner timestamp at which the changes were successfully applied.

      Returns:
      this transaction's Spanner timestamp
      Throws:
      IllegalStateException - if timestamp is not available yet
      IllegalStateException - if invoked on a read/write transaction that was not successfully committed

    • getKVDatabase

      public SpannerKVDatabase 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)
      Set transaction timeout.

      Currently not supported; this method does nothing.

      Specified by:
      setTimeout in interface KVTransaction
      Parameters:
      timeout - transaction timeout in milliseconds, or zero for unlimited

    • 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

    • 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

    • 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

    • watchKey

      public Future<Void> watchKey(ByteData key)
      Set key watch.

      Key watches are not supported.

      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:
      UnsupportedOperationException - always
      See Also:

    • readOnlySnapshot

      public CloseableKVStore readOnlySnapshot()
      Create a mutable snapshot of this transaction.

      This method is not supported.

      With Spanner, a transaction is not needed to create mutable snapshots; instead, see SpannerKVDatabase.snapshot() and MutableView.

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

    • get

      public ByteData get(ByteData key)
      Description copied from interface: KVStore
      Get the value associated with the given key, if any.
      Specified by:
      get in interface KVStore
      Overrides:
      get in class ForwardingKVStore
      Parameters:
      key - key
      Returns:
      value associated with key, or null if not found

    • getAtLeast

      public KVPair getAtLeast(ByteData minKey, ByteData maxKey)
      Description copied from interface: KVStore
      Get the key/value pair having the smallest key greater than or equal to the given minimum, if any.

      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.

      Specified by:
      getAtLeast in interface KVStore
      Overrides:
      getAtLeast in class ForwardingKVStore
      Parameters:
      minKey - minimum key (inclusive), or null for no minimum (get the smallest key)
      maxKey - maximum key (exclusive), or null for no maximum (no upper bound)
      Returns:
      smallest key/value pair with key >= minKey and key < maxKey, or null if none exists

    • getAtMost

      public KVPair getAtMost(ByteData maxKey, ByteData minKey)
      Description copied from interface: KVStore
      Get the key/value pair having the largest key strictly less than the given maximum, if any.

      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.

      Specified by:
      getAtMost in interface KVStore
      Overrides:
      getAtMost in class ForwardingKVStore
      Parameters:
      maxKey - maximum key (exclusive), or null for no maximum (get the largest key)
      minKey - minimum key (inclusive), or null for no minimum (no lower bound)
      Returns:
      largest key/value pair with key < maxKey and key >= minKey, or null if none exists

    • getRange

      public CloseableIterator<KVPair> getRange(ByteData minKey, ByteData maxKey, boolean reverse)
      Description copied from interface: KVStore
      Iterate the key/value pairs in the specified range. The returned CloseableIterator'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 CloseableIterator is weakly consistent (see java.util.concurrent). In short, the returned CloseableIterator must not throw ConcurrentModificationException; however, whether or not a "live" CloseableIterator reflects any modifications made after its creation is implementation dependent. Implementations that do make post-creation updates visible in the CloseableIterator, even if the update occurs after some delay, must preserve the order in which the modifications actually occurred.

      The returned CloseableIterator itself is not guaranteed to be thread safe; is should only be used in the thread that created it.

      Invokers of this method are encouraged to close() the returned iterators, though this is not required for correct behavior.

      Specified by:
      getRange in interface KVStore
      Overrides:
      getRange in class ForwardingKVStore
      Parameters:
      minKey - 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)
      Returns:
      iteration of key/value pairs in the range minKey (inclusive) to maxKey (exclusive)

    • delegate

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

    • wrapException

      protected RuntimeException wrapException(com.google.cloud.spanner.SpannerException e)