public class ConnectionHelper extends Object
startBatch()
and endBatch(boolean)
methods for this).
This class contains logic to retry execution of SQL statements. If this helper is not in batch mode
and if a statement fails due to an SQLException
, then it is retried. If the block
argument
of the constructor call was false
then it is retried only once. Otherwise the statement is retried
until either it succeeds or the thread is interrupted. This clearly assumes that the only cause of SQLExceptions
is faulty Connections
which are restored eventually.
Note:
This retry logic only applies to the following methods:
This class is not thread-safe and if it is to be used by multiple threads then the clients must make sure that access to this class is properly synchronized.
Implementation note: The Connection
that is retrieved from the DataSource
in getConnection(boolean)
may be broken. This is so because if an internal DataSource
is used,
then this is a commons-dbcp DataSource
with a testWhileIdle
validation strategy (see
the ConnectionFactory
class). Furthermore, if it is a DataSource
obtained through JNDI then we
can make no assumptions about the validation strategy. This means that our retry logic must either assume that
the SQL it tries to execute can do so without errors (i.e., the statement is valid), or it must implement its
own validation strategy to apply. Currently, the former is in place.
Modifier and Type | Class and Description |
---|---|
class |
ConnectionHelper.RetryManager<T>
This class encapsulates the logic to retry a method invocation if it threw an SQLException.
|
Modifier and Type | Field and Description |
---|---|
protected DataSource |
dataSource |
Modifier | Constructor and Description |
---|---|
|
ConnectionHelper(DataSource dataSrc,
boolean block) |
protected |
ConnectionHelper(DataSource dataSrc,
boolean checkWithUserName,
boolean block) |
protected |
ConnectionHelper(DataSource dataSrc,
boolean checkWithUserName,
boolean block,
int fetchSize) |
Modifier and Type | Method and Description |
---|---|
protected void |
closeResources(Connection con,
Statement stmt,
ResultSet rs,
boolean inBatchMode)
Closes the given resources given the
batchMode state. |
void |
endBatch(boolean commit)
This method always ends the batch mode.
|
void |
exec(String sql,
Object... params)
Executes a general SQL statement and immediately closes all resources.
|
ResultSet |
exec(String sql,
Object[] params,
boolean returnGeneratedKeys,
int maxRows)
Executes a general SQL statement and returns the
ResultSet of the executed statement. |
protected PreparedStatement |
execute(PreparedStatement stmt,
Object[] params)
This method is used by all methods of this class that execute SQL statements.
|
protected Connection |
getConnection(boolean inBatchMode)
Gets a connection based on the
batchMode state of this helper. |
protected boolean |
inBatchMode()
Returns true if we are currently in a batch mode, false otherwise.
|
String |
prepareDbIdentifier(String identifier)
A utility method that makes sure that
identifier does only consist of characters that are
allowed in names on the target database. |
ResultSet |
query(String sql,
Object... params)
Executes a SQL query and returns the
ResultSet . |
protected void |
replaceCharacter(StringBuilder escaped,
char c)
Called from
prepareDbIdentifier(String) . |
void |
startBatch()
Starts the batch mode.
|
boolean |
tableExists(String tableName)
Checks whether the given table exists in the database.
|
int |
update(String sql,
Object... params)
Executes an update or delete statement and returns the update count.
|
protected final DataSource dataSource
public ConnectionHelper(DataSource dataSrc, boolean block)
dataSrc
- the DataSource
on which this instance actsblock
- whether the helper should transparently block on DB connection loss (otherwise it retries
once and if that fails throws exception)protected ConnectionHelper(DataSource dataSrc, boolean checkWithUserName, boolean block)
dataSrc
- the DataSource
on which this instance actscheckWithUserName
- whether the username is to be used for the tableExists(String)
methodblock
- whether the helper should transparently block on DB connection loss (otherwise it throws exceptions)protected ConnectionHelper(DataSource dataSrc, boolean checkWithUserName, boolean block, int fetchSize)
dataSrc
- the DataSource
on which this instance actscheckWithUserName
- whether the username is to be used for the tableExists(String)
methodblock
- whether the helper should transparently block on DB connection loss (otherwise it throws exceptions)fetchSize
- the fetchSize that will be used per defaultpublic final String prepareDbIdentifier(String identifier) throws SQLException
identifier
does only consist of characters that are
allowed in names on the target database. Illegal characters will be escaped as necessary.
This method is not affected by theidentifier
- the identifier to convert to a db specific identifierSQLException
- if an error occursprotected void replaceCharacter(StringBuilder escaped, char c)
prepareDbIdentifier(String)
. Default implementation replaces the illegal
characters with their hexadecimal encoding.escaped
- the escaped db identifierc
- the character to replaceprotected boolean inBatchMode()
public final boolean tableExists(String tableName) throws SQLException
tableName
- the name of the tableSQLException
- on errorpublic final void startBatch() throws SQLException
SQLException
is thrown, then the batch mode is not started.
Important: clients that call this method must make sure that
endBatch(boolean)
is called eventually.
SQLException
- on errorpublic final void endBatch(boolean commit) throws SQLException
commit
- whether the changes in the batch should be committed or rolled backSQLException
- if the commit or rollback of the underlying JDBC Connection threw an SQLException
public final void exec(String sql, Object... params) throws SQLException
sql
- an SQL statement stringparams
- the parameters for the SQL statementSQLException
- on errorpublic final int update(String sql, Object... params) throws SQLException
sql
- an SQL statement stringparams
- the parameters for the SQL statementSQLException
- on errorpublic final ResultSet query(String sql, Object... params) throws SQLException
sql
- an SQL statement stringparams
- the parameters for the SQL statementResultSet
SQLException
public final ResultSet exec(String sql, Object[] params, boolean returnGeneratedKeys, int maxRows) throws SQLException
ResultSet
of the executed statement. The
returned ResultSet
should be closed by clients.sql
- an SQL statement stringparams
- the parameters for the SQL statementreturnGeneratedKeys
- whether generated keys should be returnedmaxRows
- the maximum number of rows in a potential ResultSet
(0 means no limit)ResultSet
SQLException
- on errorprotected final Connection getConnection(boolean inBatchMode) throws SQLException
batchMode
state of this helper. The connection should be closed
by a call to closeResources(Connection, Statement, ResultSet, boolean)
which also takes the batchMode
state into account.inBatchMode
- indicates if we are in a batchModeConnection
to use, based on the batch mode stateSQLException
- on errorprotected final void closeResources(Connection con, Statement stmt, ResultSet rs, boolean inBatchMode)
batchMode
state.con
- the Connection
obtained through the getConnection(boolean)
methodstmt
- a Statement
rs
- a ResultSet
inBatchMode
- indicates if we are in a batchModeprotected PreparedStatement execute(PreparedStatement stmt, Object[] params) throws SQLException
StreamWrapper
instances. Subclasses may override
this method to do something special with the parameters. E.g., the Oracle10R1ConnectionHelper
overrides it in order to add special blob handling.stmt
- the PreparedStatement
to executeparams
- the parametersSQLException
- on errorCopyright © 2004–2021 The Apache Software Foundation. All rights reserved.