Class Database

java.lang.Object
com.pyranid.Database
@ThreadSafe public final class Database extends Object
Main class for performing database access operations.
Since:
1.0.0
Author:
Mark Allen

  • Method Details

    • withDataSource

      @Nonnull public static Database.Builder withDataSource(@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

      @Nonnull public Optional<Transaction> 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

    • readDatabaseMetaData

      public void readDatabaseMetaData(@Nonnull DatabaseMetaDataReader databaseMetaDataReader)
      Exposes a temporary handle to JDBC DatabaseMetaData, which provides comprehensive vendor-specific information about this database as a whole.

      This method acquires DatabaseMetaData on its own newly-borrowed connection, which it manages internally.

      It does not participate in the active transaction, if one exists.

      The connection is closed as soon as DatabaseMetaDataReader.read(DatabaseMetaData) completes.

      See DatabaseMetaData Javadoc for details.

    • getDatabaseType

      @Nonnull public DatabaseType getDatabaseType()
      Since:
      3.0.0

    • getTimeZone

      @Nonnull public ZoneId getTimeZone()
      Since:
      3.0.0