Interface DatabaseConnection

All Superinterfaces:
AutoCloseable

public interface DatabaseConnection extends AutoCloseable
Manages a Connection instance, providing basic transaction control. A factory for DatabaseConnection instances.
  • Field Details

    • SQL_STATE_NO_DATA

      static final String SQL_STATE_NO_DATA
      SQLException state indicating that a query did not return a result
      See Also:
  • Method Details

    • connected

      boolean connected()
      Note that this method does not check if the connection is valid, only that it is connected.
      Returns:
      true if a connection has been established
      See Also:
    • valid

      boolean valid()
      Returns:
      true if a connection has been established and is valid
      See Also:
    • getConnection

      Connection getConnection()
      Returns the underlying connection object. Use valid() to verify that the connection is available and valid.
      Returns:
      the underlying connection object
      Throws:
      IllegalStateException - in case this connection has been closed
      See Also:
    • setConnection

      void setConnection(Connection connection)
      Sets the internal connection to use, note that no validation or transaction checking is performed on the connection and auto-commit is assumed to be disabled. The connection is simply used 'as is'. Note that setting the connection to null causes all methods requiring it to throw a IllegalStateException until a non-null connection is set.
      Parameters:
      connection - the JDBC connection
    • startTransaction

      void startTransaction()
      Starts a transaction on this connection, to end the transaction use commitTransaction() or rollbackTransaction().
      Throws:
      IllegalStateException - in case a transaction is already open
    • transactionOpen

      boolean transactionOpen()
      Returns:
      true if a transaction is open
    • commitTransaction

      void commitTransaction() throws SQLException
      Performs a commit and ends the current transaction
      Throws:
      SQLException - in case the commit failed
      IllegalStateException - in case a transaction is not open
    • rollbackTransaction

      void rollbackTransaction() throws SQLException
      Performs a rollback and ends the current transaction
      Throws:
      SQLException - in case the rollback failed
      IllegalStateException - in case a transaction is not open
    • commit

      void commit() throws SQLException
      Performs a commit
      Throws:
      SQLException - thrown if anything goes wrong during the commit
      IllegalStateException - in case a transaction is already open
    • rollback

      void rollback() throws SQLException
      Performs a rollback
      Throws:
      SQLException - thrown if anything goes wrong during the rollback
      IllegalStateException - in case a transaction is open
    • close

      void close()
      Performs a rollback and disconnects this connection. The only way to resurrect a closed connection is by using setConnection(Connection). Calling this method renders this connection unusable, subsequent calls to methods using the underlying connection result in a IllegalStateException being thrown, that is, until a new Connection is set via setConnection(Connection).
      Specified by:
      close in interface AutoCloseable
    • user

      User user()
      Returns:
      the connection user
    • database

      Database database()
      Returns:
      the database implementation this connection is based on
    • setMethodLogger

      void setMethodLogger(MethodLogger methodLogger)
      Parameters:
      methodLogger - the MethodLogger to use, null to disable method logging
    • getMethodLogger

      MethodLogger getMethodLogger()
      Returns:
      the MethodLogger being used, possibly null
    • databaseConnection

      static DatabaseConnection databaseConnection(Database database, User user) throws DatabaseException
      Constructs a new DatabaseConnection instance, based on the given Database and User
      Parameters:
      database - the database
      user - the user to use when establishing a connection
      Returns:
      a new DatabaseConnection instance
      Throws:
      DatabaseException - in case there is a problem connecting to the database
    • databaseConnection

      static DatabaseConnection databaseConnection(Database database, Connection connection) throws DatabaseException
      Constructs a new DatabaseConnection instance, based on the given Connection object. NB. auto commit is disabled on the Connection that is provided.
      Parameters:
      database - the database
      connection - the Connection object to base this DatabaseConnection on
      Returns:
      a new DatabaseConnection instance
      Throws:
      DatabaseException - in case there is a problem with the connection