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