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

Interface DatabaseAPI.Connection

All Superinterfaces:

AutoCloseable

Enclosing interface:

DatabaseAPI

public static interface DatabaseAPI.Connection
extends AutoCloseable

Connections made by the database engine bean. Its methods do not throw checked exceptions. The connection is thread-bound, and will be cleaned up correctly when the thread exits (ideal for thread pools).

Method Summary

Modifier and Type	Method	Description
void	close()	Closes this connection and releases any resources.
boolean	isReadOnly()	Retrieves whether this connection is in read-only mode.
DatabaseAPI.Query	query(String sql)	Create a new query.
DatabaseAPI.Query	query(String sql, boolean lockType)	Create a new query.
DatabaseAPI.Query	query(Resource sqlResource)	Create a new query.
DatabaseAPI.Query	query(Resource sqlResource, boolean lockType)	Create a new query.
DatabaseAPI.Query	query(SQL sql)	Create a new query.
DatabaseAPI.Query	query(SQL sql, boolean lockType)	Create a new query.
void	rollback()	Undoes all changes made in the current transaction and releases any database locks currently held by this connection.
void	transaction(boolean lockForWriting, DatabaseAPI.Transacted operation)	A nestable transaction runner.
<T> T	transaction(boolean lockForWriting, DatabaseAPI.TransactedWithResult<T> operation)	A nestable transaction runner.
void	transaction(DatabaseAPI.Transacted operation)	A nestable transaction runner.
<T> T	transaction(DatabaseAPI.TransactedWithResult<T> operation)	A nestable transaction runner.
DatabaseAPI.Update	update(String sql)	Create a new update.
DatabaseAPI.Update	update(Resource sqlResource)	Create a new update.
DatabaseAPI.Update	update(SQL sql)	Create a new update.

Method Details

close

void close()

Closes this connection and releases any resources. The actual underlying connection may remain open if the connection pool wishes to maintain it, but this handle should not be retained by the caller after this point.

Specified by:

close in interface AutoCloseable

See Also:

• Connection.close()

rollback

void rollback()

Undoes all changes made in the current transaction and releases any database locks currently held by this connection.

This method should be used only when in a transaction; it is only required when the transaction is to be rolled back without throwing an exception, as the normal behaviour of the internal transaction manager is to roll the transaction back when an exception leaves the code inside the transaction boundary.

See Also:

• Connection.rollback()

isReadOnly

boolean isReadOnly()

Retrieves whether this connection is in read-only mode.

Returns:

true if this connection is read-only; false otherwise.

See Also:

• Connection.isReadOnly()

transaction

void transaction(boolean lockForWriting,
 DatabaseAPI.Transacted operation)

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

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

See Also:

• transaction(DatabaseEngine.TransactedWithResult)

transaction

void transaction(DatabaseAPI.Transacted operation)

A nestable 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. This uses a write lock.

Parameters:

operation - The operation to run

See Also:

• transaction(DatabaseEngine.TransactedWithResult)

transaction

<T> T transaction(DatabaseAPI.TransactedWithResult<T> operation)

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

See Also:

• transaction(DatabaseEngine.Transacted)

transaction

<T> T transaction(boolean lockForWriting,
 DatabaseAPI.TransactedWithResult<T> operation)

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

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

See Also:

• transaction(DatabaseEngine.Transacted)

query

DatabaseAPI.Query query(@CompileTimeConstant
 String sql)

Create a new query. Usage pattern:

 try (var q = conn.query(SQL_SELECT)) {
     for (var value : q.call(mapper, argument1, argument2)) {
         // Do something with the mapped row
     }
 }
 

or:

 try (var q = conn.query(SQL_SELECT)) {
     q.call(mapper, argument1, argument2).forEach(value -> {
         // Do something with the mapped row
     });
 }
 

or:

 try (var q = conn.query(SQL_SELECT)) {
     q.call1(mapper, argument1, argument2).ifPresent(value -> {
         // Do something with the mapped row
     });
 }
 

Parameters:

sql - The SQL of the query.

Returns:

The query object.

See Also:

• query(Resource)
• query(SQL)
• update(String)
• SQLQueries

query

DatabaseAPI.Query query(@CompileTimeConstant
 String sql,
 boolean lockType)

Create a new query. Usage pattern:

 try (var q = conn.query(SQL_SELECT, false)) {
     for (var value : q.call(mapper, argument1, argument2)) {
         // Do something with the mapped row
     }
 }
 

or:

 try (var q = conn.query(SQL_SELECT, false)) {
     q.call(mapper, argument1, argument2).forEach(value -> {
         // Do something with the mapped row
     });
 }
 

or:

 try (var q = conn.query(SQL_SELECT, false)) {
     q.call1(mapper, argument1, argument2).ifPresent(value -> {
         // Do something with the mapped row
     });
 }
 

Parameters:

sql - The SQL of the query.

lockType - Whether we expect to have a write lock. This is vital

Returns:

The query object.

See Also:

• query(Resource)
• query(SQL)
• update(String)
• SQLQueries

query

DatabaseAPI.Query query(Resource sqlResource)

Create a new query.

 try (var q = conn.query(sqlSelectResource)) {
     for (var value : q.call(mapper, argument1, argument2)) {
         // Do something with the mapped row
     }
 }
 

or:

 try (var q = conn.query(sqlSelectResource)) {
     q.call(mapper, argument1, argument2).forEach(value -> {
         // Do something with the mapped row
     });
 }
 

or:

 try (var q = conn.query(sqlSelectResource)) {
     q.call1(mapper, argument1, argument2).ifPresent(value -> {
         // Do something with the mapped row
     });
 }
 

Parameters:

sqlResource - Reference to the SQL of the query.

Returns:

The query object.

See Also:

• query(String)
• query(SQL)
• update(Resource)
• SQLQueries

query

DatabaseAPI.Query query(Resource sqlResource,
 boolean lockType)

Create a new query.

 try (var q = conn.query(sqlSelectResource, false)) {
     for (var value : q.call(mapper, argument1, argument2)) {
         // Do something with the mapped row
     }
 }
 

or:

 try (var q = conn.query(sqlSelectResource, false)) {
     q.call(mapper, argument1, argument2).forEach(value -> {
         // Do something with the mapped row
     });
 }
 

or:

 try (var q = conn.query(sqlSelectResource, false)) {
     q.call1(mapper, argument1, argument2).ifPresent(value -> {
         // Do something with the mapped row
     });
 }
 

Parameters:

sqlResource - Reference to the SQL of the query.

lockType - Whether we expect to have a write lock. This is vital only when the query is an UPDATE RETURNING.

Returns:

The query object.

See Also:

• query(String)
• query(SQL)
• update(Resource)
• SQLQueries

query

DatabaseAPI.Query query(SQL sql)

Create a new query. Usage pattern:

 try (var q = conn.query(new SQL(SQL_SELECT))) {
     for (var value : q.call(mapper, argument1, argument2)) {
         // Do something with the mapped row
     }
 }
 

or:

 try (var q = conn.query(new SQL(SQL_SELECT))) {
     q.call(mapper, argument1, argument2).forEach(value -> {
         // Do something with the mapped row
     });
 }
 

or:

 try (var q = conn.query(new SQL(SQL_SELECT))) {
     q.call1(mapper, argument1, argument2).ifPresent(value -> {
         // Do something with the mapped row
     });
 }
 

Parameters:

sql - The SQL of the query.

Returns:

The query object.

See Also:

• query(String)
• query(Resource)
• update(String)
• SQLQueries

query

DatabaseAPI.Query query(SQL sql,
 boolean lockType)

Create a new query. Usage pattern:

 try (var q = conn.query(SQL_SELECT, false)) {
     for (var value : q.call(mapper, argument1, argument2)) {
         // Do something with the mapped row
     }
 }
 

or:

 try (var q = conn.query(SQL_SELECT, false)) {
     q.call(mapper, argument1, argument2).forEach(value -> {
         // Do something with the mapped row
     });
 }
 

or:

 try (var q = conn.query(SQL_SELECT, false)) {
     q.call1(mapper, argument1, argument2).ifPresent(value -> {
         // Do something with the mapped row
     });
 }
 

Parameters:

sql - The SQL of the query.

lockType - Whether we expect to have a write lock. This is vital

Returns:

The query object.

See Also:

• query(String)
• query(Resource)
• update(String)
• SQLQueries

update

DatabaseAPI.Update update(@CompileTimeConstant
 String sql)

Create a new update. Usage pattern:

 try (var u = conn.update(SQL_UPDATE)) {
     int numRows = u.call(argument1, argument2);
 }
 

or:

 try (var u = conn.update(SQL_INSERT)) {
     for (var key : u.keys(argument1, argument2)) {
         // Do something with the key
     }
 }
 

or even:

 try (var u = conn.update(SQL_INSERT)) {
     u.key(argument1, argument2).ifPresent(key -> {
         // Do something with the key
     });
 }
 

Note: If you use a RETURNING clause then you should use a DatabaseAPI.Query with the lockType set to true. RETURNING clauses are not supported by MySQL.

Parameters:

sql - The SQL of the update.

Returns:

The update object.

See Also:

• update(Resource)
• update(SQL)
• query(String)
• SQLQueries

update

DatabaseAPI.Update update(Resource sqlResource)

Create a new update.

 try (var u = conn.update(sqlUpdateResource)) {
     int numRows = u.call(argument1, argument2);
 }
 

or:

 try (var u = conn.update(sqlInsertResource)) {
     for (var key : u.keys(argument1, argument2)) {
         // Do something with the key
     }
 }
 

or even:

 try (var u = conn.update(sqlInsertResource)) {
     u.key(argument1, argument2).ifPresent(key -> {
         // Do something with the key
     });
 }
 

Note: If you use a RETURNING clause then you should use a DatabaseAPI.Query with the lockType set to true. RETURNING clauses are not supported by MySQL.

Parameters:

sqlResource - Reference to the SQL of the update.

Returns:

The update object.

See Also:

• update(String)
• update(SQL)
• query(Resource)
• SQLQueries

update

DatabaseAPI.Update update(SQL sql)

Create a new update. Usage pattern:

 try (var u = conn.update(new SQL(SQL_UPDATE))) {
     int numRows = u.call(argument1, argument2);
 }
 

or:

 try (var u = conn.update(new SQL(SQL_INSERT))) {
     for (var key : u.keys(argument1, argument2)) {
         // Do something with the key
     }
 }
 

or even:

 try (var u = conn.update(new SQL(SQL_INSERT))) {
     u.key(argument1, argument2).ifPresent(key -> {
         // Do something with the key
     });
 }
 

Note: If you use a RETURNING clause then you should use a DatabaseAPI.Query with the lockType set to true. RETURNING clauses are not supported by MySQL.

Parameters:

sql - The SQL of the update.

Returns:

The update object.

See Also:

• update(String)
• update(Resource)
• query(String)
• SQLQueries