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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	SQLKVTransaction.StmtType Used internally to build SQL statements.

Field Summary

Fields

Modifier and Type	Field and Description
protected Connection	connection
protected SQLKVDatabase	database
protected Logger	log

Constructor Summary

Constructors

Constructor and Description
SQLKVTransaction(SQLKVDatabase database, Connection connection) Constructor.

Method Summary

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.

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

adjustCounter, decodeCounter, encodeCounter, get, getAtLeast, getAtMost, getRange

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.permazen.kv.KVStore

adjustCounter, decodeCounter, encodeCounter, get, getAtLeast, getAtMost, getRange, getRange, getRange, removeRange

Field Detail

log

protected final Logger log

database

protected final SQLKVDatabase database

connection

protected final Connection connection

Constructor Detail

SQLKVTransaction

public SQLKVTransaction(SQLKVDatabase database,
                        Connection connection)
                 throws SQLException

Constructor.

Parameters:

database - the associated database

connection - the Connection for the transaction

Throws:

SQLException - if an SQL error occurs

Method Detail

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:

StaleTransactionException - if this transaction is no longer usable

RetryTransactionException - 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:

JTransaction.getKey()

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

mutableSnapshot

public CloseableKVStore mutableSnapshot()

Description copied from interface: KVTransaction

Create a mutable copy of the database content represented by this transaction.

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.

Specified by:

mutableSnapshot in interface KVTransaction

Returns:

independent, mutable 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.

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

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

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:

encodeKey()