com.jolbox.bonecp.hooks

Interface ConnectionHook

All Known Implementing Classes:

AbstractConnectionHook

public interface ConnectionHook

Interface to the hooking mechanism of a connection lifecycle. Applications will generally want to extend AbstractConnectionHook instead to provide a default implementation. Applications might also want to make use of connection.setDebugHandle(...) to keep track of additional information on each connection. Since the class is eventually loaded via reflection, the implementation must provide a public, no argument constructor. Warning: Be careful to make sure that the hook methods are re-entrant and thread-safe; do not rely on external state without appropriate locking, use appropriate synchronization!

Author:

wallacew

Method Summary

Methods

Modifier and Type	Method and Description
void	onAcquire(ConnectionHandle connection) Called upon getting a new connection from the JDBC driver (and prior to inserting into the pool).
boolean	onAcquireFail(Throwable t, AcquireFailConfig acquireConfig) Called on attempting (and failing) to acquire a connection.
void	onAfterStatementExecute(ConnectionHandle conn, StatementHandle statement, String sql, Map<Object,Object> params) Called right after a statement has executed.
void	onBeforeStatementExecute(ConnectionHandle conn, StatementHandle statement, String sql, Map<Object,Object> params) Called before a statement is about to execute.
void	onCheckIn(ConnectionHandle connection) Called when the connection is about to be returned to the pool.
void	onCheckOut(ConnectionHandle connection) Called when the connection is extracted from the pool and about to be given to the application.
boolean	onConnectionException(ConnectionHandle connection, String state, Throwable t) Called whenever an exception on a connection occurs.
void	onDestroy(ConnectionHandle connection) Called when the connection is about to be completely removed from the pool.
ConnectionState	onMarkPossiblyBroken(ConnectionHandle connection, String state, SQLException e) Called to give you a chance to override the logic on whether a connection can be considered broken or not.
void	onQueryExecuteTimeLimitExceeded(ConnectionHandle conn, Statement statement, String sql, Map<Object,Object> logParams) Deprecated.
void	onQueryExecuteTimeLimitExceeded(ConnectionHandle conn, Statement statement, String sql, Map<Object,Object> logParams, long timeElapsedInNs) Called when a query execute time limit has been set and an executing query took longer to than the limit to return control to the application.
void	onQueryExecuteTimeLimitExceeded(String sql, Map<Object,Object> logParams) Deprecated.

Method Detail

onAcquire

void onAcquire(ConnectionHandle connection)

Called upon getting a new connection from the JDBC driver (and prior to inserting into the pool). You may call connection.getInternalConnection() to obtain a handle to the actual (unwrapped) connection obtained from the driver.

Parameters:

connection - Handle to the new connection

onCheckIn

void onCheckIn(ConnectionHandle connection)

Called when the connection is about to be returned to the pool.

Parameters:

connection - being returned to pool.

onCheckOut

void onCheckOut(ConnectionHandle connection)

Called when the connection is extracted from the pool and about to be given to the application.

Parameters:

connection - about to given to the app.

onDestroy

void onDestroy(ConnectionHandle connection)

Called when the connection is about to be completely removed from the pool. Careful with this hook; the connection might be marked as being broken. Use connection.isPossiblyBroken() to determine if the connection has triggered an exception at some point. Connection has already been closed by the time you receive this callback.

Parameters:

connection -

onAcquireFail

boolean onAcquireFail(Throwable t,
                    AcquireFailConfig acquireConfig)

Called on attempting (and failing) to acquire a connection. Note that implementing this means that acquireRetry/delay logic will be overridden by this code.

Parameters:

t - Exception that occurred.

acquireConfig - handle containing retry delay, retry attempts etc.

Returns:

Return true to attempt the connection again.

onQueryExecuteTimeLimitExceeded

void onQueryExecuteTimeLimitExceeded(ConnectionHandle conn,
                                   Statement statement,
                                   String sql,
                                   Map<Object,Object> logParams,
                                   long timeElapsedInNs)

Called when a query execute time limit has been set and an executing query took longer to than the limit to return control to the application.

Parameters:

conn - handle to the connection

statement - statement handle.

sql - SQL statement that was used.

logParams - Parameters used in this statement.

timeElapsedInNs - actual time the query took (in nanoseconds)

onQueryExecuteTimeLimitExceeded

@Deprecated
void onQueryExecuteTimeLimitExceeded(ConnectionHandle conn,
                                              Statement statement,
                                              String sql,
                                              Map<Object,Object> logParams)

Deprecated.

Deprecated. Use the similarly named hook having more parameters instead.

Parameters:

conn - handle to the connection

statement - statement handle.

sql - SQL statement that was used.

logParams - Parameters used in this statement.

onQueryExecuteTimeLimitExceeded

@Deprecated
void onQueryExecuteTimeLimitExceeded(String sql,
                                              Map<Object,Object> logParams)

Deprecated.

Deprecated. Use the similarly named hook having more parameters instead. Called when a query execute time limit has been set and an executing query took longer to than the limit to return control to the application.

Parameters:

sql - SQL statement that was used.

logParams - Parameters used in this statement.

onBeforeStatementExecute

void onBeforeStatementExecute(ConnectionHandle conn,
                            StatementHandle statement,
                            String sql,
                            Map<Object,Object> params)

Called before a statement is about to execute. Tip: You may use PoolUtil.fillLogParams(...) to get the sql statement with the '?' replaced with the actual values.

Parameters:

conn - Connection handle

statement - Handle to the statement

sql - SQL statement about to be executed.

params - parameters currently bound to the statement

onAfterStatementExecute

void onAfterStatementExecute(ConnectionHandle conn,
                           StatementHandle statement,
                           String sql,
                           Map<Object,Object> params)

Called right after a statement has executed. Tip: You may use PoolUtil.fillLogParams(...) to get the sql statement with the '?' replaced with the actual values.

Parameters:

conn - Connection handle

statement - Handle to the statement

sql - SQL statement about to be executed.

params - parameters currently bound to the statement

onConnectionException

boolean onConnectionException(ConnectionHandle connection,
                            String state,
                            Throwable t)

Called whenever an exception on a connection occurs. This exception may be a connection failure, a DB failure or a non-fatal logical failure (eg Duplicate key exception).

SQLSTATE Value

Value Meaning

08001 The application requester is unable to establish the connection.

08002 The connection already exists.

08003 The connection does not exist.

08004 The application server rejected establishment of the connection.

08007 Transaction resolution unknown.

08502 The CONNECT statement issued by an application process running with a SYNCPOINT of TWOPHASE has failed, because no transaction manager is available.

08504 An error was encountered while processing the specified path rename configuration file.

SQL Failure codes 08001, 08007 & 57P01 indicate that the database is broken/died (and thus all remaining connections are killed off).

Anything else will be taken as the connection (not the db) being broken.

Note: You may use pool.isConnectionHandleAlive(connection) to verify if the connection is in a usable state again. Note 2: As in all interceptor hooks, this method may be called concurrently so any implementation must be thread-safe.

Parameters:

connection - The handle that triggered this error

state - the SQLState error code.

t - Exception that caused this failure.

Returns:

Returning true means: when you eventually close off this connection, test to see if the connection is still alive and discard it if not (this is the normal behaviour). Returning false pretends that the connection is still ok when the connection is closed (your application will still receive the original exception that was thrown).

onMarkPossiblyBroken

ConnectionState onMarkPossiblyBroken(ConnectionHandle connection,
                                   String state,
                                   SQLException e)

Called to give you a chance to override the logic on whether a connection can be considered broken or not. Note: You may use pool.isConnectionHandleAlive(connection) to verify if the connection is in a usable state again. Note 2: As in all interceptor hooks, this method may be called concurrently so any implementation must be thread-safe.

Parameters:

connection - The handle that triggered this error

state - the SQLState error code.

e - Exception that caused us to call this hook.

Returns:

ConnectionState enum to signal back to the pool what action you intend to take.