com.github.susom.database

Class DatabaseImpl

java.lang.Object

com.github.susom.database.DatabaseImpl

All Implemented Interfaces:

Database, Supplier<Database>

public class DatabaseImpl
extends Object
implements Database

Primary class for accessing a relational (SQL) database.

Author:

garricko

Constructor Summary

Constructors

Constructor and Description
DatabaseImpl(Connection connection, Options options)
DatabaseImpl(DatabaseMock mock, Flavor flavor)
DatabaseImpl(DatabaseMock mock, Options options)

Method Summary

Modifier and Type	Method and Description
void	assertTimeSynchronized() Convenience method, same as Database.assertTimeSynchronized(long, long) with millisToWarn=10000 and millisToError=30000.
void	assertTimeSynchronized(long millisToWarn, long millisToError) Check the JVM time (and timezone) against the database and log a warning or throw an error if they are too far apart.
void	commitNow() Cause the underlying connection to commit its transaction immediately.
Ddl	ddl(String sql) Create a DDL (schema modifying) statement for further manipulation and execution.
void	dropSequenceQuietly(String sequenceName) Convenience method to deal with mutually incompatible syntax for this.
void	dropTableQuietly(String tableName) Convenience method to deal with dropping tables that may or may not exist.
Flavor	flavor() Access information about what kind of database we are dealing with.
DatabaseImpl	get()
Long	nextSequenceValue(String sequenceName) Read the next value from a sequence.
String	normalizeTableName(String tableName) Return the DB table name in the normalized form in which it is stored.
Date	nowPerApp() Get the value that would be used if you specify an argNowPerApp() parameter.
Options	options()
void	rollbackNow() Cause the underlying connection to roll back its transaction immediately.
boolean	tableExists(String tableName) Convenience method to check if a table or view exists so that caller can decide whether to create or update a table.
boolean	tableExists(String tableName, String schemaName) Convenience method to check whether a table or view exists or not.
SqlUpdate	toDelete(Sql sql)
SqlUpdate	toDelete(String sql) Create a SQL "delete" statement for further manipulation and execution.
SqlInsert	toInsert(Sql sql)
SqlInsert	toInsert(String sql) Create a SQL "insert" statement for further manipulation and execution.
SqlSelect	toSelect(Sql sql)
SqlSelect	toSelect(String sql) Create a SQL "select" statement for further manipulation and execution.
SqlUpdate	toUpdate(Sql sql)
SqlUpdate	toUpdate(String sql) Create a SQL "update" statement for further manipulation and execution.
Connection	underlyingConnection() Obtain direct access to the connection being used by this instance.
When	when() A little syntax sugar to make it easier to customize your SQL based on the specific database.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DatabaseImpl

public DatabaseImpl(@Nonnull
                    Connection connection,
                    @Nonnull
                    Options options)

DatabaseImpl

public DatabaseImpl(@Nonnull
                    DatabaseMock mock,
                    Flavor flavor)

DatabaseImpl

public DatabaseImpl(@Nonnull
                    DatabaseMock mock,
                    @Nonnull
                    Options options)

Method Detail

get

@Nonnull
public DatabaseImpl get()

Specified by:

get in interface Supplier<Database>

toInsert

@Nonnull
public SqlInsert toInsert(@Nonnull
                                   String sql)

Description copied from interface: Database

Create a SQL "insert" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Specified by:

toInsert in interface Database

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toInsert

@Nonnull
public SqlInsert toInsert(@Nonnull
                                   Sql sql)

Specified by:

toInsert in interface Database

toSelect

@Nonnull
public SqlSelect toSelect(@Nonnull
                                   String sql)

Description copied from interface: Database

Create a SQL "select" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Specified by:

toSelect in interface Database

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toSelect

@Nonnull
public SqlSelect toSelect(@Nonnull
                                   Sql sql)

Specified by:

toSelect in interface Database

toUpdate

@Nonnull
public SqlUpdate toUpdate(@Nonnull
                                   String sql)

Description copied from interface: Database

Create a SQL "update" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Specified by:

toUpdate in interface Database

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toUpdate

@Nonnull
public SqlUpdate toUpdate(@Nonnull
                                   Sql sql)

Specified by:

toUpdate in interface Database

toDelete

@Nonnull
public SqlUpdate toDelete(@Nonnull
                                   String sql)

Description copied from interface: Database

Create a SQL "delete" statement for further manipulation and execution. Note this call does not actually execute the SQL.

Specified by:

toDelete in interface Database

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

toDelete

@Nonnull
public SqlUpdate toDelete(@Nonnull
                                   Sql sql)

Specified by:

toDelete in interface Database

ddl

@Nonnull
public Ddl ddl(@Nonnull
                        String sql)

Description copied from interface: Database

Create a DDL (schema modifying) statement for further manipulation and execution. Note this call does not actually execute the SQL.

Specified by:

ddl in interface Database

Parameters:

sql - the SQL to execute, optionally containing indexed ("?") or named (":foo") parameters. To include the characters '?' or ':' in the SQL you must escape them with two ("??" or "::"). You MUST be careful not to pass untrusted strings in as SQL, since this will be executed in the database.

Returns:

an interface for further manipulating the statement; never null

nextSequenceValue

public Long nextSequenceValue(@Nonnull
                              String sequenceName)

Description copied from interface: Database

Read the next value from a sequence. This method helps smooth over the syntax differences across databases.

Specified by:

nextSequenceValue in interface Database

nowPerApp

public Date nowPerApp()

Description copied from interface: Database

Get the value that would be used if you specify an argNowPerApp() parameter.

Specified by:

nowPerApp in interface Database

commitNow

public void commitNow()

Description copied from interface: Database

Cause the underlying connection to commit its transaction immediately. This must be explicitly enabled (see Options, or it will throw a DatabaseException.

Specified by:

commitNow in interface Database

rollbackNow

public void rollbackNow()

Description copied from interface: Database

Cause the underlying connection to roll back its transaction immediately. This must be explicitly enabled (see Options, or it will throw a DatabaseException.

Specified by:

rollbackNow in interface Database

underlyingConnection

@Nonnull
public Connection underlyingConnection()

Description copied from interface: Database

Obtain direct access to the connection being used by this instance. Be very careful as this is highly likely to be unsafe and cause you great pain and suffering. This method is included to help ease into the library in large codebases where some parts still rely on direct JDBC access.

By default this method will throw a DatabaseException. If you want to use this method you must explicitly enable it via Options.allowConnectionAccess()

Specified by:

underlyingConnection in interface Database

options

@Nonnull
public Options options()

Specified by:

options in interface Database

flavor

@Nonnull
public Flavor flavor()

Description copied from interface: Database

Access information about what kind of database we are dealing with.

Specified by:

flavor in interface Database

when

@Nonnull
public When when()

Description copied from interface: Database

A little syntax sugar to make it easier to customize your SQL based on the specific database. For example:

"select 1" + db.when().oracle(" from dual")

"select " + db.when().postgres("date_trunc('day',").other("trunc(") + ") ..."

Specified by:

when in interface Database

Returns:

an interface for chaining or terminating the conditionals

dropSequenceQuietly

public void dropSequenceQuietly(@Nonnull
                                String sequenceName)

Description copied from interface: Database

Convenience method to deal with mutually incompatible syntax for this. For example:

Oracle: 'drop sequence x'

Derby: 'drop sequence x restrict'

"

Specified by:

dropSequenceQuietly in interface Database

dropTableQuietly

public void dropTableQuietly(@Nonnull
                             String tableName)

Description copied from interface: Database

Convenience method to deal with dropping tables that may or may not exist. Some databases make it hard to check and conditionally drop things, so we will just try to drop it and ignore the errors.

Specified by:

dropTableQuietly in interface Database

Parameters:

tableName - the table to be dropped

tableExists

public boolean tableExists(@Nonnull
                           String tableName)
                    throws DatabaseException

Description copied from interface: Database

Convenience method to check if a table or view exists so that caller can decide whether to create or update a table. The table name's case is normalized using the database's convention unless tableName is enclosed in double quotes. The default catalog and schema from the DB connection will be used.

Specified by:

tableExists in interface Database

Parameters:

tableName - the table to be checked

Returns:

true if the table or view exists

Throws:

DatabaseException

tableExists

public boolean tableExists(@Nonnull
                           String tableName,
                           String schemaName)
                    throws DatabaseException

Description copied from interface: Database

Convenience method to check whether a table or view exists or not. The table name's case is normalized using the database's convention unless tableName is enclosed in double quotes. The default catalog from the DB connection will be used.

Specified by:

tableExists in interface Database

Parameters:

tableName - the table to be checked

schemaName - the schema expected to contain the table

Returns:

true if the table or view exists

Throws:

DatabaseException

normalizeTableName

public String normalizeTableName(String tableName)

Description copied from interface: Database

Return the DB table name in the normalized form in which it is stored. Databases like Oracle, Derby, HSQL store their tables in upper case. Databases like postgres and sqlserver use lower case unless configured otherwise. If the caller passes in a quoted string, we will leave the name as is, removing the quotes.

Specified by:

normalizeTableName in interface Database

Parameters:

tableName - this should be a name, not a pattern

Returns:

table name in appropriate format for DB lookup - original case, uppercase, or lowercase

assertTimeSynchronized

public void assertTimeSynchronized(long millisToWarn,
                                   long millisToError)

Description copied from interface: Database

Check the JVM time (and timezone) against the database and log a warning or throw an error if they are too far apart. It is a good idea to do this before you store and dates, and maybe make it part of your health checks. If the clocks differ by more than an hour, a DatabaseException is thrown suggesting you check the timezones (under the assumptions the JVM and database are running in different timezones).

Specified by:

assertTimeSynchronized in interface Database

Parameters:

millisToWarn - if the clocks disagree by more than this and less than millisToError, a warning will be dropped in the log

millisToError - if the clocks disagree by more than this a DatabaseEception will be thrown

assertTimeSynchronized

public void assertTimeSynchronized()

Description copied from interface: Database

Convenience method, same as Database.assertTimeSynchronized(long, long) with millisToWarn=10000 and millisToError=30000.

Specified by:

assertTimeSynchronized in interface Database