Package org.apache.jackrabbit.core.util.db

Class ConnectionHelper

java.lang.Object

org.apache.jackrabbit.core.util.db.ConnectionHelper

Direct Known Subclasses:

DerbyConnectionHelper, OracleConnectionHelper, PostgreSQLConnectionHelper

public class ConnectionHelper
extends Object

This class provides convenience methods to execute SQL statements. They can be either executed in isolation or within the context of a JDBC transaction; the so-called batch mode (use the 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:

• exec(String, Object...)
• update(String, Object[])
• exec(String, Object[], boolean, int)

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	ConnectionHelper.RetryManager<T>	This class encapsulates the logic to retry a method invocation if it threw an SQLException.

Constructor Summary

Constructors

Constructor	Description
ConnectionHelper(DataSource dataSrc, boolean block)

Method Summary

Modifier and Type	Method	Description
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.
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.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionHelper

public ConnectionHelper(DataSource dataSrc,
                        boolean block)

Parameters:

dataSrc - the DataSource on which this instance acts

block - whether the helper should transparently block on DB connection loss (otherwise it retries once and if that fails throws exception)

Method Detail

prepareDbIdentifier

public final String prepareDbIdentifier(String identifier)
                                 throws SQLException

A utility method that makes sure that 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 the

Parameters:

identifier - the identifier to convert to a db specific identifier

Returns:

the db-normalized form of the given identifier

Throws:

SQLException - if an error occurs

tableExists

public final boolean tableExists(String tableName)
                          throws SQLException

Checks whether the given table exists in the database.

Parameters:

tableName - the name of the table

Returns:

whether the given table exists

Throws:

SQLException - on error

startBatch

public final void startBatch()
                      throws SQLException

Starts the batch mode. If an 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.

Throws:

SQLException - on error

endBatch

public final void endBatch(boolean commit)
                    throws SQLException

This method always ends the batch mode.

Parameters:

commit - whether the changes in the batch should be committed or rolled back

Throws:

SQLException - if the commit or rollback of the underlying JDBC Connection threw an SQLException

exec

public final void exec(String sql,
                       Object... params)
                throws SQLException

Executes a general SQL statement and immediately closes all resources. Note: We use a Statement if there are no parameters to avoid a problem on the Oracle 10g JDBC driver w.r.t. :NEW and :OLD keywords that triggers ORA-17041.

Parameters:

sql - an SQL statement string

params - the parameters for the SQL statement

Throws:

SQLException - on error

update

public final int update(String sql,
                        Object... params)
                 throws SQLException

Executes an update or delete statement and returns the update count.

Parameters:

sql - an SQL statement string

params - the parameters for the SQL statement

Returns:

the update count

Throws:

SQLException - on error

query

public final ResultSet query(String sql,
                             Object... params)
                      throws SQLException

Executes a SQL query and returns the ResultSet. The returned ResultSet should be closed by clients.

Parameters:

sql - an SQL statement string

params - the parameters for the SQL statement

Returns:

a ResultSet

Throws:

SQLException

exec

public final ResultSet exec(String sql,
                            Object[] params,
                            boolean returnGeneratedKeys,
                            int maxRows)
                     throws SQLException

Executes a general SQL statement and returns the ResultSet of the executed statement. The returned ResultSet should be closed by clients.

Parameters:

sql - an SQL statement string

params - the parameters for the SQL statement

returnGeneratedKeys - whether generated keys should be returned

maxRows - the maximum number of rows in a potential ResultSet (0 means no limit)

Returns:

a ResultSet

Throws:

SQLException - on error