Package uk.ac.manchester.spinnaker.alloc.db

Interface DatabaseAPI

All Known Implementing Classes:

DatabaseEngineJDBCImpl

public interface DatabaseAPI

The primary interface to the database. It conceptually represents an SQLite database that can have connections opened on it.

Author:

Donal Fellows

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	DatabaseAPI.Connected	Some code that may be run within a transaction and which will be given a new connection for the duration.
static interface	DatabaseAPI.ConnectedWithResult<T>	Some code that may be run within a transaction that returns a result and which will be given a new connection for the duration.
static interface	DatabaseAPI.Connection	Connections made by the database engine bean.
static interface	DatabaseAPI.Query	Wrapping a prepared query to be more suitable for Java 8 onwards.
static interface	DatabaseAPI.RowMapper<T>	Maps database Row to an object.
static interface	DatabaseAPI.StatementCommon	Common shared API between DatabaseAPI.Query and DatabaseAPI.Update.
static interface	DatabaseAPI.Transacted	Some code that may be run within a transaction.
static interface	DatabaseAPI.TransactedWithResult<T>	Some code that may be run within a transaction that returns a result.
static interface	DatabaseAPI.Update	Wrapping a prepared update to be more suitable for Java 8 onwards.

Method Summary

Modifier and Type	Method	Description
<T> T	execute(boolean lockForWriting, DatabaseAPI.ConnectedWithResult<T> operation)	A connection manager and transaction runner.
default <T> T	execute(DatabaseAPI.ConnectedWithResult<T> operation)	A connection manager and transaction runner.
void	executeVoid(boolean lockForWriting, DatabaseAPI.Connected operation)	A connection manager and transaction runner.
default void	executeVoid(DatabaseAPI.Connected operation)	A connection manager and transaction runner.
DatabaseAPI.Connection	getConnection()	Get a connection.
DatabaseAPI.Connection	getHistoricalConnection()	Get a connection to the historical database, similar to the above.
boolean	isHistoricalDBAvailable()	Whether the historical data DB is available.

Method Details

getConnection

@MustBeClosed DatabaseAPI.Connection getConnection()

Get a connection. This connection is thread-bound and pooled; it must not be passed to other threads. They should get their own connections instead. The connection has auto-commit disabled; use the transaction() method instead.

Returns:

A configured initialised connection to the database.

isHistoricalDBAvailable

boolean isHistoricalDBAvailable()

Whether the historical data DB is available. If it isn't, you can't move any data to longer-term storage, but ordinary operations should be fine.

Returns:

Whether the historical data DB is available.

getHistoricalConnection

@MustBeClosed DatabaseAPI.Connection getHistoricalConnection()

Get a connection to the historical database, similar to the above.

Returns:

A configured initialised connection to the historical database.

executeVoid

void executeVoid(boolean lockForWriting, DatabaseAPI.Connected operation)

A connection manager and transaction runner. If the operation completes normally (and this isn't a nested use), the transaction commits. If an exception is thrown, the transaction is rolled back. The connection is closed up in any case.

Parameters:

lockForWriting - Whether to lock for writing. Multiple read locks can be held at once, but only one write lock. Locks cannot be upgraded (because that causes deadlocks).

operation - The operation to run

Throws:

RuntimeException - If something goes wrong with the database access or the contained code.

executeVoid

default void executeVoid(DatabaseAPI.Connected operation)

A connection manager and transaction runner. If the operation completes normally (and this isn't a nested use), the transaction commits. If an exception is thrown, the transaction is rolled back. The connection is closed up in any case. This uses a write lock.

Parameters:

operation - The operation to run

Throws:

RuntimeException - If something goes wrong with the database access or the contained code.

execute

<T> T execute(boolean lockForWriting, DatabaseAPI.ConnectedWithResult<T> operation)

A connection manager and transaction runner. If the operation completes normally (and this isn't a nested use), the transaction commits. If an exception is thrown, the transaction is rolled back. The connection is closed up in any case.

Type Parameters:

T - The type of the result of operation

Parameters:

lockForWriting - Whether to lock for writing. Multiple read locks can be held at once, but only one write lock. Locks cannot be upgraded (because that causes deadlocks).

operation - The operation to run

Returns:

the value returned by operation

Throws:

RuntimeException - If something other than database access goes wrong with the contained code.

execute

default <T> T execute(DatabaseAPI.ConnectedWithResult<T> operation)

A connection manager and transaction runner. If the operation completes normally (and this isn't a nested use), the transaction commits. If an exception is thrown, the transaction is rolled back. The connection is closed up in any case. This uses a write lock.

Type Parameters:

T - The type of the result of operation

Parameters:

operation - The operation to run

Returns:

the value returned by operation

Throws:

RuntimeException - If something other than database access goes wrong with the contained code.