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

      public static @NonNull 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

      public @NonNull 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.

      Nested calls to transaction(...) are independent transactions with independent JDBC connections; they do not automatically join an outer transaction. Use participate(Transaction, TransactionalOperation) to join an existing transaction explicitly.

      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.

      Nested calls to transaction(...) are independent transactions with independent JDBC connections; they do not automatically join an outer transaction. Use participate(Transaction, TransactionalOperation) to join an existing transaction explicitly.

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

    • transaction

      public <T> @NonNull 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.

      Nested calls to transaction(...) are independent transactions with independent JDBC connections; they do not automatically join an outer transaction. Use participate(Transaction, ReturningTransactionalOperation) to join an existing transaction explicitly.

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

    • transaction

      public <T> @NonNull 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.

      Nested calls to transaction(...) are independent transactions with independent JDBC connections; they do not automatically join an outer transaction. Use participate(Transaction, ReturningTransactionalOperation) to join an existing transaction explicitly.

      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

      public <T> @NonNull 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

    • query

      public @NonNull Query query(@NonNull String sql)
      Creates a fluent builder for executing SQL.

      Named parameters use the :paramName syntax and are bound via Query.bind(String, Object). Positional parameters via ? are not supported.

      Example: 

      Optional<Employee> employee = database.query("SELECT * FROM employee WHERE id = :id")
  .bind("id", 42)
  .fetchObject(Employee.class);
      Parameters:
      sql - SQL containing :paramName placeholders
      Returns:
      a fluent builder for binding parameters and executing
      Since:
      4.0.0

    • 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

      public @NonNull DatabaseType getDatabaseType()
      Gets the database type for this database.

      If Database.Builder.databaseType(DatabaseType) was not configured and the database type has not already been detected, this method may acquire a connection and inspect DatabaseMetaData. Configure an explicit database type to avoid runtime detection.

      Returns:
      the database type
      Throws:
      DatabaseException - if automatic database type detection fails
      Since:
      3.0.0

    • getTimeZone

      public @NonNull ZoneId getTimeZone()
      Since:
      3.0.0