Package com.pyranid

Class Database

java.lang.Object
com.pyranid.Database

@ThreadSafe public class Database extends Object
Main class for performing database access operations.
Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • forDataSource

      @Nonnull public static Database.Builder forDataSource(@Nonnull DataSource dataSource)
      Provides a Database builder for the given DataSource.
      Parameters:
      dataSource - data source used to create the Database builder
      Returns:
      a Database builder
    • currentTransaction

      Gets a reference to the current transaction, if any.
      Returns:
      the current transaction
    • transaction

      public void transaction(@Nonnull TransactionalOperation transactionalOperation)
      Performs an operation transactionally.

      The transaction will be automatically rolled back if an exception bubbles out of transactionalOperation.

      Parameters:
      transactionalOperation - the operation to perform transactionally
    • transaction

      public void transaction(@Nonnull TransactionIsolation transactionIsolation, @Nonnull TransactionalOperation transactionalOperation)
      Performs an operation transactionally with the given isolation level.

      The transaction will be automatically rolled back if an exception bubbles out of transactionalOperation.

      Parameters:
      transactionIsolation - the desired database transaction isolation level
      transactionalOperation - the operation to perform transactionally
    • transaction

      @Nonnull public <T> Optional<T> transaction(@Nonnull ReturningTransactionalOperation<T> transactionalOperation)
      Performs an operation transactionally and optionally returns a value.

      The transaction will be automatically rolled back if an exception bubbles out of transactionalOperation.

      Type Parameters:
      T - the type to be returned
      Parameters:
      transactionalOperation - the operation to perform transactionally
      Returns:
      the result of the transactional operation
    • transaction

      @Nonnull public <T> Optional<T> transaction(@Nonnull TransactionIsolation transactionIsolation, @Nonnull ReturningTransactionalOperation<T> transactionalOperation)
      Performs an operation transactionally with the given isolation level, optionally returning a value.

      The transaction will be automatically rolled back if an exception bubbles out of transactionalOperation.

      Type Parameters:
      T - the type to be returned
      Parameters:
      transactionIsolation - the desired database transaction isolation level
      transactionalOperation - the operation to perform transactionally
      Returns:
      the result of the transactional operation
    • participate

      public void participate(@Nonnull Transaction transaction, @Nonnull TransactionalOperation transactionalOperation)
      Performs an operation in the context of a pre-existing transaction.

      No commit or rollback on the transaction will occur when transactionalOperation completes.

      However, if an exception bubbles out of transactionalOperation, the transaction will be marked as rollback-only.

      Parameters:
      transaction - the transaction in which to participate
      transactionalOperation - the operation that should participate in the transaction
    • participate

      @Nonnull public <T> Optional<T> participate(@Nonnull Transaction transaction, @Nonnull ReturningTransactionalOperation<T> transactionalOperation)
      Performs an operation in the context of a pre-existing transaction, optionall returning a value.

      No commit or rollback on the transaction will occur when transactionalOperation completes.

      However, if an exception bubbles out of transactionalOperation, the transaction will be marked as rollback-only.

      Type Parameters:
      T - the type to be returned
      Parameters:
      transaction - the transaction in which to participate
      transactionalOperation - the operation that should participate in the transaction
      Returns:
      the result of the transactional operation
    • queryForObject

      @Nonnull public <T> Optional<T> queryForObject(@Nonnull String sql, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Performs a SQL query that is expected to return 0 or 1 result rows.
      Type Parameters:
      T - the type to be returned
      Parameters:
      sql - the SQL query to execute
      resultSetRowType - the type to which ResultSet rows should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a single result (or no result)
      Throws:
      DatabaseException - if > 1 row is returned
    • queryForObject

      public <T> Optional<T> queryForObject(@Nonnull Statement statement, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Performs a SQL query that is expected to return 0 or 1 result rows.
      Type Parameters:
      T - the type to be returned
      Parameters:
      statement - the SQL statement to execute
      resultSetRowType - the type to which ResultSet rows should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a single result (or no result)
      Throws:
      DatabaseException - if > 1 row is returned
    • queryForList

      @Nonnull public <T> List<T> queryForList(@Nonnull String sql, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Performs a SQL query that is expected to return any number of result rows.
      Type Parameters:
      T - the type to be returned
      Parameters:
      sql - the SQL query to execute
      resultSetRowType - the type to which ResultSet rows should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a list of results
    • queryForList

      @Nonnull public <T> List<T> queryForList(@Nonnull Statement statement, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Performs a SQL query that is expected to return any number of result rows.
      Type Parameters:
      T - the type to be returned
      Parameters:
      statement - the SQL statement to execute
      resultSetRowType - the type to which ResultSet rows should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a list of results
    • execute

      @Nonnull public Long execute(@Nonnull String sql, @Nullable Object... parameters)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE; or a SQL statement that returns nothing, such as a DDL statement.
      Parameters:
      sql - the SQL to execute
      parameters - PreparedStatement parameters, if any
      Returns:
      the number of rows affected by the SQL statement
    • execute

      @Nonnull public Long execute(@Nonnull Statement statement, @Nullable Object... parameters)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE; or a SQL statement that returns nothing, such as a DDL statement.
      Parameters:
      statement - the SQL statement to execute
      parameters - PreparedStatement parameters, if any
      Returns:
      the number of rows affected by the SQL statement
    • executeForObject

      @Nonnull public <T> Optional<T> executeForObject(@Nonnull String sql, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE, which returns 0 or 1 rows, e.g. with Postgres/Oracle's RETURNING clause.
      Type Parameters:
      T - the type to be returned
      Parameters:
      sql - the SQL query to execute
      resultSetRowType - the type to which the ResultSet row should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a single result (or no result)
      Throws:
      DatabaseException - if > 1 row is returned
    • executeForObject

      public <T> Optional<T> executeForObject(@Nonnull Statement statement, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE, which returns 0 or 1 rows, e.g. with Postgres/Oracle's RETURNING clause.
      Type Parameters:
      T - the type to be returned
      Parameters:
      statement - the SQL statement to execute
      resultSetRowType - the type to which ResultSet rows should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a single result (or no result)
      Throws:
      DatabaseException - if > 1 row is returned
    • executeForList

      @Nonnull public <T> List<T> executeForList(@Nonnull String sql, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE, which returns any number of rows, e.g. with Postgres/Oracle's RETURNING clause.
      Type Parameters:
      T - the type to be returned
      Parameters:
      sql - the SQL to execute
      resultSetRowType - the type to which ResultSet rows should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a list of results
    • executeForList

      @Nonnull public <T> List<T> executeForList(@Nonnull Statement statement, @Nonnull Class<T> resultSetRowType, @Nullable Object... parameters)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE, which returns any number of rows, e.g. with Postgres/Oracle's RETURNING clause.
      Type Parameters:
      T - the type to be returned
      Parameters:
      statement - the SQL statement to execute
      resultSetRowType - the type to which ResultSet rows should be marshaled
      parameters - PreparedStatement parameters, if any
      Returns:
      a list of results
    • executeBatch

      @Nonnull public List<Long> executeBatch(@Nonnull String sql, @Nonnull List<List<Object>> parameterGroups)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE in "batch" over a set of parameter groups.

      Useful for bulk-inserting or updating large amounts of data.

      Parameters:
      sql - the SQL to execute
      parameterGroups - Groups of PreparedStatement parameters
      Returns:
      the number of rows affected by the SQL statement per-group
    • executeBatch

      @Nonnull public List<Long> executeBatch(@Nonnull Statement statement, @Nonnull List<List<Object>> parameterGroups)
      Executes a SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE, or DELETE in "batch" over a set of parameter groups.

      Useful for bulk-inserting or updating large amounts of data.

      Parameters:
      statement - the SQL statement to execute
      parameterGroups - Groups of PreparedStatement parameters
      Returns:
      the number of rows affected by the SQL statement per-group