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 Summary

Fields

Modifier and Type	Field and Description
protected DatabaseClient	client
protected TimestampBound	consistency
protected SpannerKVDatabase	kvdb
protected Logger	log
protected String	tableName

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SpannerKVTransaction(SpannerKVDatabase kvdb, DatabaseClient client, String tableName, TimestampBound consistency) Constructor.

Method Summary

Modifier and Type	Method and Description
void	commit() Commit this transaction.
protected KVStore	delegate() Get the underlying KVStore.
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.
TimestampBound	getConsistency() Get the consistency level configured for this transaction.
SpannerKVDatabase	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.
com.google.cloud.Timestamp	getTimestamp() Get the timestamp associated with this transaction.
boolean	isReadOnly() Determine whether this transaction is read-only.
boolean	isStrongConsistency() Convenience method to determine whether this transaction is using strong consistency.
CloseableKVStore	mutableSnapshot() Create a mutable snapshot of this transaction.
void	rollback() Cancel this transaction, if not already canceled.
void	setReadOnly(boolean readOnly) Enable or disable read-only mode.
void	setTimeout(long timeout) Set transaction timeout.
Future<Void>	watchKey(byte[] key) Set key watch.
protected RuntimeException	wrapException(SpannerException e)

Methods inherited from class io.permazen.kv.util.ForwardingKVStore

adjustCounter, apply, decodeCounter, encodeCounter, put, remove, removeRange

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.permazen.kv.KVStore

adjustCounter, apply, decodeCounter, encodeCounter, getRange, getRange, put, remove, removeRange, removeRange

Field Detail

log

protected final Logger log

kvdb

protected final SpannerKVDatabase kvdb

client

protected final DatabaseClient client

tableName

protected final String tableName

consistency

protected final TimestampBound consistency

Constructor Detail

SpannerKVTransaction

protected SpannerKVTransaction(SpannerKVDatabase kvdb,
                               DatabaseClient client,
                               String tableName,
                               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 Detail

getConsistency

public 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

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

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 should not throw StaleTransactionException.

Specified by:

rollback in interface KVTransaction

watchKey

public Future<Void> watchKey(byte[] 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:

JTransaction.getKey()

mutableSnapshot

public CloseableKVStore mutableSnapshot()

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:

mutableSnapshot in interface KVTransaction

Returns:

independent, mutable copy of this transaction's entire database content

Throws:

UnsupportedOperationException - always

get

public byte[] get(byte[] key)

Description copied from interface: KVStore

Get the value associated with the given key, if any.

Modifications to the returned byte[] array do not affect this instance.

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(byte[] minKey,
                         byte[] 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.

Modifications to the returned byte[] arrays do not affect this instance.

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(byte[] maxKey,
                        byte[] 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.

Modifications to the returned byte[] arrays do not affect this instance.

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(byte[] minKey,
                                          byte[] maxKey,
                                          boolean reverse)

Description copied from interface: KVStore

Iterate the key/value pairs in the specified range. The returned Iterator'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.

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(SpannerException e)