com.helger.db.jdbc.executor

Class DBExecutor

java.lang.Object

com.helger.db.jdbc.executor.DBExecutor

All Implemented Interfaces:

Serializable

@NotThreadSafe
public class DBExecutor
extends Object
implements Serializable

Simple wrapper around common JDBC functionality.

Author:

Philip Helger

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DBExecutor.CountAndKey

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	DEFAULT_DEBUG_CONNECTIONS
static boolean	DEFAULT_DEBUG_SQL_STATEMENTS
static boolean	DEFAULT_DEBUG_TRANSACTIONS
static long	DEFAULT_EXECUTION_DURATION_WARN_MS

Constructor Summary

Constructors

Constructor and Description
DBExecutor(IHasConnection aConnectionProvider)
DBExecutor(IHasDataSource aDataSourceProvider)

Method Summary

Modifier and Type	Method and Description
protected static void	debugLog(String sMessage) Debug logging method.
com.helger.commons.callback.CallbackList<com.helger.commons.callback.exception.IExceptionCallback<? super Exception>>	exceptionCallbacks()
com.helger.commons.state.ESuccess	executePreparedStatement(String sSQL, IPreparedStatementDataProvider aPSDP)
com.helger.commons.state.ESuccess	executePreparedStatement(String sSQL, IPreparedStatementDataProvider aPSDP, IUpdatedRowCountCallback aURWCC, IGeneratedKeysCallback aGeneratedKeysCB, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
Object	executePreparedStatementAndGetGeneratedKey(String sSQL, IPreparedStatementDataProvider aPSDP, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB) Execute a prepared statement and return the generated key.
com.helger.commons.state.ESuccess	executeStatement(String sSQL)
com.helger.commons.state.ESuccess	executeStatement(String sSQL, IGeneratedKeysCallback aGeneratedKeysCB, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
static com.helger.commons.callback.CallbackList<com.helger.db.api.callback.IExecutionTimeExceededCallback>	executionTimeExceededHandlers() Get the custom exception handler list.
static com.helger.commons.state.ETriState	getConnectionEstablished()
static IConnectionStatusChangeCallback	getConnectionStatusChangeCallback()
long	getExecutionDurationWarnMS()
protected static void	handleGeneratedKeys(ResultSet aGeneratedKeysRS, IGeneratedKeysCallback aGeneratedKeysCB)
DBExecutor.CountAndKey	insertOrUpdateAndGetGeneratedKey(String sSQL, IPreparedStatementDataProvider aPSDP, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
long	insertOrUpdateOrDelete(String sSQL, IPreparedStatementDataProvider aPSDP) Perform an INSERT or UPDATE statement.
long	insertOrUpdateOrDelete(String sSQL, IPreparedStatementDataProvider aPSDP, IGeneratedKeysCallback aGeneratedKeysCB, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB) Perform an INSERT or UPDATE statement.
boolean	isDebugConnections()
boolean	isDebugSQLStatements()
boolean	isDebugTransactions()
boolean	isExecutionDurationWarnEnabled()
protected static long	iterateResultSet(ResultSet aRS, IResultSetRowCallback aCallback) Iterate the passed result set, collect all values of a single result row, and call the callback for each row of result objects.
void	onExecutionTimeExceeded(String sMsg, long nExecutionMillis)
com.helger.commons.state.ESuccess	performInTransaction(com.helger.commons.callback.IThrowingRunnable<Exception> aRunnable)
com.helger.commons.state.ESuccess	performInTransaction(com.helger.commons.callback.IThrowingRunnable<Exception> aRunnable, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
com.helger.commons.collection.impl.ICommonsList<DBResultRow>	queryAll(String sSQL) Query a list of 0-n rows with an SQL script without parameters.
com.helger.commons.collection.impl.ICommonsList<DBResultRow>	queryAll(String sSQL, IPreparedStatementDataProvider aPSDP) Query a list of 0-n rows with an SQL script with parameters.
com.helger.commons.state.ESuccess	queryAll(String sSQL, IPreparedStatementDataProvider aPSDP, IResultSetRowCallback aResultItemCallback) Perform an SQL query that does contains parameters to be filled with the provided IPreparedStatementDataProvider.
com.helger.commons.state.ESuccess	queryAll(String sSQL, IResultSetRowCallback aResultItemCallback) Perform an SQL query that does not contain any parameters.
long	queryCount(String sSQL)
long	queryCount(String sSQL, IPreparedStatementDataProvider aPSDP)
com.helger.commons.state.ESuccess	querySingle(String sSQL, Consumer<? super DBResultRow> aConsumer) Query a a single result row with an SQL script without parameters.
com.helger.commons.state.ESuccess	querySingle(String sSQL, IPreparedStatementDataProvider aPSDP, Consumer<? super DBResultRow> aConsumer) Query a a single result row with an SQL script with parameters.
static void	resetConnectionEstablished() Reset the "Connection established" flag.
static void	setConnectionEstablished(com.helger.commons.state.ETriState eNewState) Set the "Connection established" state.
static void	setConnectionStatusChangeCallback(IConnectionStatusChangeCallback aCB) Set the callback to be invoked, if the connection status changes.
DBExecutor	setDebugConnections(boolean bDebugConnections)
DBExecutor	setDebugSQLStatements(boolean bDebugSQLStatements)
DBExecutor	setDebugTransactions(boolean bDebugTransactions)
DBExecutor	setExecutionDurationWarnMS(long nExecutionDurationWarnMS)
String	toString()
protected com.helger.commons.state.ESuccess	withExistingConnectionDo(Connection aConnection, com.helger.db.jdbc.executor.DBExecutor.IWithConnectionCallback aCB, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
protected com.helger.commons.state.ESuccess	withNewConnectionDo(com.helger.db.jdbc.executor.DBExecutor.IWithConnectionCallback aCB, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
protected com.helger.commons.state.ESuccess	withPreparedStatementDo(String sSQL, IPreparedStatementDataProvider aPSDP, com.helger.db.jdbc.executor.DBExecutor.IWithPreparedStatementCallback aPSCallback, IUpdatedRowCountCallback aUpdatedRowCountCB, IGeneratedKeysCallback aGeneratedKeysCB, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
protected com.helger.commons.state.ESuccess	withStatementDo(com.helger.db.jdbc.executor.DBExecutor.IWithStatementCallback aCB, IGeneratedKeysCallback aGeneratedKeysCB, com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)
protected void	withTimingDo(String sDescription, com.helger.commons.callback.IThrowingRunnable<SQLException> aRunnable)

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_EXECUTION_DURATION_WARN_MS

public static final long DEFAULT_EXECUTION_DURATION_WARN_MS

See Also:

Constant Field Values

DEFAULT_DEBUG_CONNECTIONS

public static final boolean DEFAULT_DEBUG_CONNECTIONS

See Also:

Constant Field Values

DEFAULT_DEBUG_TRANSACTIONS

public static final boolean DEFAULT_DEBUG_TRANSACTIONS

See Also:

Constant Field Values

DEFAULT_DEBUG_SQL_STATEMENTS

public static final boolean DEFAULT_DEBUG_SQL_STATEMENTS

See Also:

Constant Field Values

Constructor Detail

DBExecutor

public DBExecutor(@Nonnull
                  IHasDataSource aDataSourceProvider)

DBExecutor

public DBExecutor(@Nonnull
                  IHasConnection aConnectionProvider)

Method Detail

debugLog

protected static final void debugLog(@Nonnull
                                     String sMessage)

Debug logging method. Only invoked if the respective "debug log" member is set to true

Parameters:

sMessage - The message to log. May not be null.

getConnectionEstablished

@Nonnull
public static final com.helger.commons.state.ETriState getConnectionEstablished()

Returns:

The current "connection established" state. Never null.

setConnectionEstablished

public static final void setConnectionEstablished(@Nonnull
                                                  com.helger.commons.state.ETriState eNewState)

Set the "Connection established" state.

Parameters:

eNewState - The new state. May not be null.

resetConnectionEstablished

public static final void resetConnectionEstablished()

Reset the "Connection established" flag. This is a shortcut for setConnectionEstablished (ETriState.UNDEFINED).

getConnectionStatusChangeCallback

@Nullable
public static final IConnectionStatusChangeCallback getConnectionStatusChangeCallback()

Returns:

The callback to be invoked, if the connection status changes. May be null.

setConnectionStatusChangeCallback

public static final void setConnectionStatusChangeCallback(@Nullable
                                                           IConnectionStatusChangeCallback aCB)

Set the callback to be invoked, if the connection status changes. Only one callback can be invoked.

Parameters:

aCB - The callback to be invoked. May be null.

exceptionCallbacks

@Nonnull
 @ReturnsMutableObject
public final com.helger.commons.callback.CallbackList<com.helger.commons.callback.exception.IExceptionCallback<? super Exception>> exceptionCallbacks()

Returns:

The mutable list of exception callbacks to be invoked in case of an Exception.

getExecutionDurationWarnMS

@CheckForSigned
public final long getExecutionDurationWarnMS()

isExecutionDurationWarnEnabled

public final boolean isExecutionDurationWarnEnabled()

setExecutionDurationWarnMS

@Nonnull
public final DBExecutor setExecutionDurationWarnMS(long nExecutionDurationWarnMS)

executionTimeExceededHandlers

@Nonnull
 @ReturnsMutableObject
public static final com.helger.commons.callback.CallbackList<com.helger.db.api.callback.IExecutionTimeExceededCallback> executionTimeExceededHandlers()

Get the custom exception handler list.

Returns:

Never null.

onExecutionTimeExceeded

public final void onExecutionTimeExceeded(@Nonnull
                                          String sMsg,
                                          @Nonnegative
                                          long nExecutionMillis)

isDebugConnections

public final boolean isDebugConnections()

setDebugConnections

@Nonnull
public final DBExecutor setDebugConnections(boolean bDebugConnections)

isDebugTransactions

public final boolean isDebugTransactions()

setDebugTransactions

@Nonnull
public final DBExecutor setDebugTransactions(boolean bDebugTransactions)

isDebugSQLStatements

public final boolean isDebugSQLStatements()

setDebugSQLStatements

@Nonnull
public final DBExecutor setDebugSQLStatements(boolean bDebugSQLStatements)

withNewConnectionDo

@CodingStyleguideUnaware(value="Needs to be synchronized!")
 @Nonnull
protected final com.helger.commons.state.ESuccess withNewConnectionDo(@Nonnull
                                                                                                                                              com.helger.db.jdbc.executor.DBExecutor.IWithConnectionCallback aCB,
                                                                                                                                              @Nullable
                                                                                                                                              com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

withExistingConnectionDo

@Nonnull
protected final com.helger.commons.state.ESuccess withExistingConnectionDo(@Nonnull
                                                                                     Connection aConnection,
                                                                                     @Nonnull
                                                                                     com.helger.db.jdbc.executor.DBExecutor.IWithConnectionCallback aCB,
                                                                                     @Nullable
                                                                                     com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

handleGeneratedKeys

protected static void handleGeneratedKeys(@Nonnull
                                          ResultSet aGeneratedKeysRS,
                                          @Nonnull
                                          IGeneratedKeysCallback aGeneratedKeysCB)
                                   throws SQLException

Throws:

SQLException

performInTransaction

@Nonnull
public final com.helger.commons.state.ESuccess performInTransaction(@Nonnull
                                                                              com.helger.commons.callback.IThrowingRunnable<Exception> aRunnable)

performInTransaction

@Nonnull
public final com.helger.commons.state.ESuccess performInTransaction(@Nonnull
                                                                              com.helger.commons.callback.IThrowingRunnable<Exception> aRunnable,
                                                                              @Nullable
                                                                              com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

withStatementDo

@Nonnull
protected final com.helger.commons.state.ESuccess withStatementDo(@Nonnull
                                                                            com.helger.db.jdbc.executor.DBExecutor.IWithStatementCallback aCB,
                                                                            @Nullable
                                                                            IGeneratedKeysCallback aGeneratedKeysCB,
                                                                            @Nullable
                                                                            com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

withTimingDo

protected final void withTimingDo(@Nonnull
                                  String sDescription,
                                  @Nonnull
                                  com.helger.commons.callback.IThrowingRunnable<SQLException> aRunnable)
                           throws SQLException

Throws:

SQLException

withPreparedStatementDo

@Nonnull
protected final com.helger.commons.state.ESuccess withPreparedStatementDo(@Nonnull
                                                                                    String sSQL,
                                                                                    @Nonnull
                                                                                    IPreparedStatementDataProvider aPSDP,
                                                                                    @Nonnull
                                                                                    com.helger.db.jdbc.executor.DBExecutor.IWithPreparedStatementCallback aPSCallback,
                                                                                    @Nullable
                                                                                    IUpdatedRowCountCallback aUpdatedRowCountCB,
                                                                                    @Nullable
                                                                                    IGeneratedKeysCallback aGeneratedKeysCB,
                                                                                    @Nullable
                                                                                    com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

executeStatement

@Nonnull
public com.helger.commons.state.ESuccess executeStatement(@Nonnull
                                                                    String sSQL)

executeStatement

@Nonnull
public com.helger.commons.state.ESuccess executeStatement(@Nonnull
                                                                    String sSQL,
                                                                    @Nullable
                                                                    IGeneratedKeysCallback aGeneratedKeysCB,
                                                                    @Nullable
                                                                    com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

executePreparedStatement

@Nonnull
public com.helger.commons.state.ESuccess executePreparedStatement(@Nonnull
                                                                            String sSQL,
                                                                            @Nonnull
                                                                            IPreparedStatementDataProvider aPSDP)

executePreparedStatement

@Nonnull
public com.helger.commons.state.ESuccess executePreparedStatement(@Nonnull
                                                                            String sSQL,
                                                                            @Nonnull
                                                                            IPreparedStatementDataProvider aPSDP,
                                                                            @Nullable
                                                                            IUpdatedRowCountCallback aURWCC,
                                                                            @Nullable
                                                                            IGeneratedKeysCallback aGeneratedKeysCB,
                                                                            @Nullable
                                                                            com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

executePreparedStatementAndGetGeneratedKey

@Nonnull
public Object executePreparedStatementAndGetGeneratedKey(@Nonnull
                                                                   String sSQL,
                                                                   @Nonnull
                                                                   IPreparedStatementDataProvider aPSDP,
                                                                   @Nullable
                                                                   com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

Execute a prepared statement and return the generated key.

Parameters:

sSQL - The SQL to execute. May not be null.

aPSDP - The data provider for the prepared statement. May not be null.

aExtraExCB - An additional exception callback for this execution only.

Returns:

null if the execution failed (see exception handler) and no key was created, or a non-null key.

insertOrUpdateOrDelete

public long insertOrUpdateOrDelete(@Nonnull
                                   String sSQL,
                                   @Nonnull
                                   IPreparedStatementDataProvider aPSDP)

Perform an INSERT or UPDATE statement.

Parameters:

sSQL - SQL to execute.

aPSDP - The prepared statement provider.

Returns:

The number of modified/inserted rows.

insertOrUpdateOrDelete

public long insertOrUpdateOrDelete(@Nonnull
                                   String sSQL,
                                   @Nonnull
                                   IPreparedStatementDataProvider aPSDP,
                                   @Nullable
                                   IGeneratedKeysCallback aGeneratedKeysCB,
                                   @Nullable
                                   com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

Perform an INSERT or UPDATE statement.

Parameters:

sSQL - SQL to execute.

aPSDP - The prepared statement provider.

aGeneratedKeysCB - An optional callback to retrieve eventually generated values. May be null.

aExtraExCB - Per-call Exception callback. May be null.

Returns:

The number of modified/inserted rows.

insertOrUpdateAndGetGeneratedKey

@Nonnull
public DBExecutor.CountAndKey insertOrUpdateAndGetGeneratedKey(@Nonnull
                                                                         String sSQL,
                                                                         @Nonnull
                                                                         IPreparedStatementDataProvider aPSDP,
                                                                         @Nullable
                                                                         com.helger.commons.callback.exception.IExceptionCallback<? super Exception> aExtraExCB)

iterateResultSet

@Nonnegative
protected static final long iterateResultSet(@WillClose
                                                           ResultSet aRS,
                                                           @Nonnull
                                                           IResultSetRowCallback aCallback)
                                                    throws SQLException

Iterate the passed result set, collect all values of a single result row, and call the callback for each row of result objects.

Parameters:

aRS - The result set to iterate.

aCallback - The callback to be invoked for each row.

Returns:

The number of result rows. Always ≥ 0

Throws:

SQLException - on error

queryAll

@Nonnull
public com.helger.commons.state.ESuccess queryAll(@Nonnull @Nonempty
                                                            String sSQL,
                                                            @Nonnull
                                                            IResultSetRowCallback aResultItemCallback)

Perform an SQL query that does not contain any parameters.

Parameters:

sSQL - The SQL to query. May neither be null nor empty.

aResultItemCallback - The result item callback to be invoked. May not be null.

Returns:

ESuccess and never null.

queryAll

@Nonnull
public com.helger.commons.state.ESuccess queryAll(@Nonnull
                                                            String sSQL,
                                                            @Nonnull
                                                            IPreparedStatementDataProvider aPSDP,
                                                            @Nonnull
                                                            IResultSetRowCallback aResultItemCallback)

Perform an SQL query that does contains parameters to be filled with the provided IPreparedStatementDataProvider.

Parameters:

sSQL - The SQL to query. May neither be null nor empty.

aPSDP - The data provider for the SQL statement. May not be null.

aResultItemCallback - The result item callback to be invoked. May not be null.

Returns:

ESuccess and never null.

queryAll

@Nullable
public com.helger.commons.collection.impl.ICommonsList<DBResultRow> queryAll(@Nonnull @Nonempty
                                                                                        String sSQL)

Query a list of 0-n rows with an SQL script without parameters.

Parameters:

sSQL - The SQL to query. May neither be null nor empty.

Returns:

null in case of error (see the provided exception handler) or a non-null but maybe empty list if querying was successful.

queryAll

@Nullable
public com.helger.commons.collection.impl.ICommonsList<DBResultRow> queryAll(@Nonnull @Nonempty
                                                                                        String sSQL,
                                                                                        @Nonnull
                                                                                        IPreparedStatementDataProvider aPSDP)

Query a list of 0-n rows with an SQL script with parameters.

Parameters:

sSQL - The SQL to query. May neither be null nor empty.

aPSDP - The data provider for the SQL statement. May not be null.

Returns:

null in case of error (see the provided exception handler) or a non-null but maybe empty list if querying was successful.

querySingle

@Nonnull
public com.helger.commons.state.ESuccess querySingle(@Nonnull @Nonempty
                                                               String sSQL,
                                                               @Nonnull
                                                               Consumer<? super DBResultRow> aConsumer)

Query a a single result row with an SQL script without parameters.

Parameters:

sSQL - The SQL to query. May neither be null nor empty.

aConsumer - The consumer to be invoked with the result row. May not be null. This is necessary to differentiate a null-result was a "not found" or "a DB error". The consumer is only invoked if no exception occurred.

Returns:

ESuccess and never null.

querySingle

@Nonnull
public com.helger.commons.state.ESuccess querySingle(@Nonnull @Nonempty
                                                               String sSQL,
                                                               @Nonnull
                                                               IPreparedStatementDataProvider aPSDP,
                                                               @Nonnull
                                                               Consumer<? super DBResultRow> aConsumer)

Query a a single result row with an SQL script with parameters.

Parameters:

sSQL - The SQL to query. May neither be null nor empty.

aPSDP - The data provider for the SQL statement. May not be null.

aConsumer - The consumer to be invoked with the result row. May not be null. This is necessary to differentiate a null-result was a "not found" or "a DB error". The consumer is only invoked if no exception occurred.

Returns:

ESuccess and never null.

queryCount

@CheckForSigned
public long queryCount(@Nonnull
                                        String sSQL)

queryCount

@CheckForSigned
public long queryCount(@Nonnull
                                        String sSQL,
                                        @Nonnull
                                        IPreparedStatementDataProvider aPSDP)

toString

public String toString()

Overrides:

toString in class Object