Package org.dalesbred

Class Database

java.lang.Object
org.dalesbred.Database
public final class Database extends Object

The main abstraction of the library: represents a configured connection to database and provides a way to execute callbacks in transactions.

Usually you'll need only single instance of this in your application, unless you need to connect several different databases or need different default settings for different use cases.

  • Constructor Details

  • Method Details

    • forDataSource

      @NotNull public static @NotNull Database forDataSource(@NotNull @NotNull DataSource dataSource)
      Returns a new Database that uses given DataSource to retrieve connections.

    • forJndiDataSource

      @NotNull public static @NotNull Database forJndiDataSource(@NotNull @NotNull String jndiName)
      Returns a new Database that uses DataSource with given JNDI-name.

    • forUrlAndCredentials

      @NotNull public static @NotNull Database forUrlAndCredentials(@NotNull @NotNull String url, @Nullable @Nullable String username, @Nullable @Nullable String password)
      Returns a new Database that uses given connection options to open connection. The database opens connections directly from DriverManager without performing connection pooling.
      See Also:

    • withTransaction

      public <T> T withTransaction(@NotNull @NotNull TransactionCallback<T> callback)
      Executes a block of code within a context of a transaction, using Propagation.REQUIRED propagation.

    • withTransaction

      public <T> T withTransaction(@NotNull @NotNull Propagation propagation, @NotNull @NotNull TransactionCallback<T> callback)
      Executes a block of code with given propagation and configuration default isolation.

    • withTransaction

      public <T> T withTransaction(@NotNull @NotNull Isolation isolation, @NotNull @NotNull TransactionCallback<T> callback)
      Executes a block of code with given isolation.

    • withTransaction

      public <T> T withTransaction(@NotNull @NotNull Propagation propagation, @NotNull @NotNull Isolation isolation, @NotNull @NotNull TransactionCallback<T> callback)
      Executes a block of code with given propagation and isolation.

    • withTransaction

      public <T> T withTransaction(@NotNull @NotNull TransactionSettings settings, @NotNull @NotNull TransactionCallback<T> callback)
      Executes a block of code with given transaction settings.
      See Also:

    • withVoidTransaction

      public void withVoidTransaction(@NotNull @NotNull VoidTransactionCallback callback)
      Executes a block of code within a context of a transaction, using Propagation.REQUIRED propagation.

    • withVoidTransaction

      public void withVoidTransaction(@NotNull @NotNull Propagation propagation, @NotNull @NotNull VoidTransactionCallback callback)
      Executes a block of code with given propagation and configuration default isolation.

    • withVoidTransaction

      public void withVoidTransaction(@NotNull @NotNull Isolation isolation, @NotNull @NotNull VoidTransactionCallback callback)
      Executes a block of code with given isolation.

    • withVoidTransaction

      public void withVoidTransaction(@NotNull @NotNull Propagation propagation, @NotNull @NotNull Isolation isolation, @NotNull @NotNull VoidTransactionCallback callback)
      Executes a block of code with given propagation and isolation.

    • withVoidTransaction

      public void withVoidTransaction(@NotNull @NotNull TransactionSettings settings, @NotNull @NotNull VoidTransactionCallback callback)
      Executes a block of code with given transaction settings.
      See Also:

    • hasActiveTransaction

      public boolean hasActiveTransaction()
      Returns true if and only if the current thread has an active transaction for this database.

    • executeQuery

      public <T> T executeQuery(@NotNull @NotNull ResultSetProcessor<T> processor, @NotNull @NotNull SqlQuery query)
      Executes a query and processes the results with given ResultSetProcessor. All other findXXX-methods are just convenience methods for this one.

    • executeQuery

      public <T> T executeQuery(@NotNull @NotNull ResultSetProcessor<T> processor, @NotNull @NotNull String sql, Object... args)
      Executes a query and processes the results with given ResultSetProcessor.
      See Also:

    • findAll

      @NotNull public <T> @NotNull List<T> findAll(@NotNull @NotNull RowMapper<T> rowMapper, @NotNull @NotNull SqlQuery query)
      Executes a query and processes each row of the result with given RowMapper to produce a list of results.

    • findAll

      @NotNull public <T> @NotNull List<T> findAll(@NotNull @NotNull RowMapper<T> rowMapper, @NotNull @NotNull String sql, Object... args)
      Executes a query and processes each row of the result with given RowMapper to produce a list of results.

    • findAll

      @NotNull public <T> @NotNull List<T> findAll(@NotNull @NotNull Class<T> cl, @NotNull @NotNull SqlQuery query)
      Executes a query and converts the results to instances of given class using default mechanisms.

    • findAll

      @NotNull public <T> @NotNull List<T> findAll(@NotNull @NotNull Class<T> cl, @NotNull @NotNull String sql, Object... args)
      Executes a query and converts the results to instances of given class using default mechanisms.

    • findUnique

      public <T> T findUnique(@NotNull @NotNull RowMapper<T> mapper, @NotNull @NotNull SqlQuery query)
      Finds a unique result from database, using given RowMapper to convert the row.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUnique

      public <T> T findUnique(@NotNull @NotNull RowMapper<T> mapper, @NotNull @NotNull String sql, Object... args)
      Finds a unique result from database, using given RowMapper to convert the row.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUnique

      public <T> T findUnique(@NotNull @NotNull Class<T> cl, @NotNull @NotNull SqlQuery query)
      Finds a unique result from database, converting the database row to given class using default mechanisms.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUnique

      public <T> T findUnique(@NotNull @NotNull Class<T> cl, @NotNull @NotNull String sql, Object... args)
      Finds a unique result from database, converting the database row to given class using default mechanisms.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findOptional

      @NotNull public <T> @NotNull Optional<T> findOptional(@NotNull @NotNull RowMapper<T> rowMapper, @NotNull @NotNull SqlQuery query)
      Find a unique result from database, using given RowMapper to convert row. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptional

      @NotNull public <T> @NotNull Optional<T> findOptional(@NotNull @NotNull RowMapper<T> rowMapper, @NotNull @NotNull String sql, Object... args)
      Find a unique result from database, using given RowMapper to convert row. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptional

      @NotNull public <T> @NotNull Optional<T> findOptional(@NotNull @NotNull Class<T> cl, @NotNull @NotNull SqlQuery query)
      Finds a unique result from database, converting the database row to given class using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptional

      @NotNull public <T> @NotNull Optional<T> findOptional(@NotNull @NotNull Class<T> cl, @NotNull @NotNull String sql, Object... args)
      Finds a unique result from database, converting the database row to given class using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptionalInt

      @NotNull public @NotNull OptionalInt findOptionalInt(@NotNull @NotNull String sql, Object... args)
      Finds a unique result from database, converting the database row to int using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptionalInt

      @NotNull public @NotNull OptionalInt findOptionalInt(@NotNull @NotNull SqlQuery query)
      Finds a unique result from database, converting the database row to int using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptionalLong

      @NotNull public @NotNull OptionalLong findOptionalLong(@NotNull @NotNull String sql, Object... args)
      Finds a unique result from database, converting the database row to long using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptionalLong

      @NotNull public @NotNull OptionalLong findOptionalLong(@NotNull @NotNull SqlQuery query)
      Finds a unique result from database, converting the database row to long using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptionalDouble

      @NotNull public @NotNull OptionalDouble findOptionalDouble(@NotNull @NotNull String sql, Object... args)
      Finds a unique result from database, converting the database row to double using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findOptionalDouble

      @NotNull public @NotNull OptionalDouble findOptionalDouble(@NotNull @NotNull SqlQuery query)
      Finds a unique result from database, converting the database row to double using default mechanisms. Returns empty if there are no results or if single null result is returned.
      Throws:
      NonUniqueResultException - if there are multiple result rows

    • findUniqueOrNull

      @Nullable public <T> T findUniqueOrNull(@NotNull @NotNull RowMapper<T> rowMapper, @NotNull @NotNull SqlQuery query)
      Alias for findOptional(rowMapper, query).orElse(null).

    • findUniqueOrNull

      @Nullable public <T> T findUniqueOrNull(@NotNull @NotNull RowMapper<T> rowMapper, @NotNull @NotNull String sql, Object... args)
      Alias for {findUniqueOrNull(rowMapper, SqlQuery.query(sql, args))}.

    • findUniqueOrNull

      @Nullable public <T> T findUniqueOrNull(@NotNull @NotNull Class<T> cl, @NotNull @NotNull SqlQuery query)
      Alias for findOptional(cl, query).orElse(null).

    • findUniqueOrNull

      @Nullable public <T> T findUniqueOrNull(@NotNull @NotNull Class<T> cl, @NotNull @NotNull String sql, Object... args)
      Alias for findOptional(cl, sql, args).orElse(null).

    • findUniqueBoolean

      public boolean findUniqueBoolean(@NotNull @NotNull SqlQuery query)
      A convenience method for retrieving a single non-null boolean.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUniqueBoolean

      public boolean findUniqueBoolean(@NotNull @NotNull String sql, Object... args)
      A convenience method for retrieving a single non-null boolean.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUniqueInt

      public int findUniqueInt(@NotNull @NotNull SqlQuery query)
      A convenience method for retrieving a single non-null integer.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUniqueInt

      public int findUniqueInt(@NotNull @NotNull String sql, Object... args)
      A convenience method for retrieving a single non-null integer.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUniqueLong

      public long findUniqueLong(@NotNull @NotNull SqlQuery query)
      A convenience method for retrieving a single non-null long.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findUniqueLong

      public long findUniqueLong(@NotNull @NotNull String sql, Object... args)
      A convenience method for retrieving a single non-null long.
      Throws:
      NonUniqueResultException - if there is more then one row
      EmptyResultException - if there are no rows

    • findMap

      @NotNull public <K, V> @NotNull Map<K,V> findMap(@NotNull @NotNull Class<K> keyType, @NotNull @NotNull Class<V> valueType, @NotNull @NotNull SqlQuery query)
      Executes a query that returns at least two values and creates a map from the results, using the first value as the key and rest of the values for instantiating V.

      If the keys of the result are not distinct, the result contains the last binding of given key.

    • findMap

      @NotNull public <K, V> @NotNull Map<K,V> findMap(@NotNull @NotNull Class<K> keyType, @NotNull @NotNull Class<V> valueType, @NotNull @NotNull String sql, Object... args)
      Executes a query that returns at least two values and creates a map from the results, using the first value as the key and rest of the values for instantiating V.

      If the keys of the result are not distinct, the result contains the last binding of given key.

    • findTable

      @NotNull public @NotNull ResultTable findTable(@NotNull @NotNull SqlQuery query)
      Executes a query and creates a ResultTable from the results.

    • findTable

      @NotNull public @NotNull ResultTable findTable(@NotNull @NotNull String sql, Object... args)
      Executes a query and creates a ResultTable from the results.

    • update

      public int update(@NotNull @NotNull SqlQuery query)
      Executes an update against the database and returns the amount of affected rows.

    • update

      public int update(@NotNull @NotNull String sql, Object... args)
      Executes an update against the database and returns the amount of affected rows.

    • updateUnique

      public void updateUnique(@NotNull @NotNull SqlQuery query)
      Execute an update against the database and assert that a single row will be modified.
      Throws:
      NonUniqueUpdateException - if zero or more then one rows were updated

    • updateUnique

      public void updateUnique(@NotNull @NotNull String sql, Object... args)
      Execute an update against the database and assert that a single row will be modified.
      Throws:
      NonUniqueUpdateException - if zero or more then one rows were updated

    • updateAndProcessGeneratedKeys

      public <T> T updateAndProcessGeneratedKeys(@NotNull @NotNull ResultSetProcessor<T> generatedKeysProcessor, @NotNull @NotNull List<String> columnNames, @NotNull @NotNull SqlQuery query)
      Executes an update against the database and return generated keys as extracted by generatedKeysProcessor.
      Parameters:
      generatedKeysProcessor - processor for handling the generated keys
      columnNames - names of columns that contain the generated keys. Can be empty, in which case the returned columns depend on the database
      query - to execute
      Returns:
      Result of processing the results with generatedKeysProcessor.

    • updateAndProcessGeneratedKeys

      public <T> T updateAndProcessGeneratedKeys(@NotNull @NotNull ResultSetProcessor<T> generatedKeysProcessor, @NotNull @NotNull List<String> columnNames, @NotNull @NotNull String sql, Object... args)
      See Also:

    • updateBatch

      public int[] updateBatch(@NotNull @NotNull String sql, @NotNull @NotNull List<? extends List<?>> argumentLists)
      Executes a batch update against the database, returning an array of modification counts for each argument list.

    • updateBatchAndProcessGeneratedKeys

      public <T> T updateBatchAndProcessGeneratedKeys(@NotNull @NotNull ResultSetProcessor<T> generatedKeysProcessor, @NotNull @NotNull List<String> columnNames, @NotNull @NotNull String sql, @NotNull @NotNull List<? extends List<?>> argumentLists)
      Executes batch of updates against the database and return generated keys as extracted by generatedKeysProcessor.
      Parameters:
      generatedKeysProcessor - processor for handling the generated keys
      columnNames - names of columns that contain the generated keys. Can be empty, in which case the returned columns depend on the database
      sql - to execute
      argumentLists - List of argument lists for items of batch
      Returns:
      Result of processing the results with generatedKeysProcessor.

    • getTypeConversionRegistry

      @NotNull public @NotNull TypeConversionRegistry getTypeConversionRegistry()
      Returns TypeConversionRegistry that can be used to register new type-conversions.

    • isAllowImplicitTransactions

      public boolean isAllowImplicitTransactions()
      If flag is set to true (by default it's false) queries without active transaction will not throw exception but will start a fresh transaction.

    • setAllowImplicitTransactions

      public void setAllowImplicitTransactions(boolean allowImplicitTransactions)
      If flag is set to true (by default it's false) queries without active transaction will not throw exception but will start a fresh transaction.

    • getDefaultTimeout

      @Nullable public @Nullable Duration getDefaultTimeout()
      If default timeout is set to non null (by default it's null) all queries will have this timeout value as default, unless is specified directly on SqlQuery or is set directly on JDBC Connection parameters.

    • setDefaultTimeout

      public void setDefaultTimeout(@NotNull @NotNull Duration timeout)
      If default timeout is set to non null (by default it's null) all queries will have this timeout value as default, unless is specified directly on SqlQuery or is set directly on JDBC Connection parameters.
      Throws:
      IllegalArgumentException - if timeout is negative
      See Also:

    • toString

      @NotNull public @NotNull String toString()
      Returns a string containing useful debug information about the state of this object.
      Overrides:
      toString in class Object