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:

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
    final void
    endBatch(boolean commit)
    This method always ends the batch mode.
    final void
    exec(String sql, Object... params)
    Executes a general SQL statement and immediately closes all resources.
    final ResultSet
    exec(String sql, Object[] params, boolean returnGeneratedKeys, int maxRows)
    Executes a general SQL statement and returns the ResultSet of the executed statement.
    final 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.
    final ResultSet
    query(String sql, Object... params)
    Executes a SQL query and returns the ResultSet.
    final void
    startBatch()
    Starts the batch mode.
    final boolean
    tableExists(String tableName)
    Checks whether the given table exists in the database.
    final 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 Details

    • 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 Details

    • 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