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

Class ConnectionHelper

  • Direct Known Subclasses:
    DerbyConnectionHelper, OracleConnectionHelper, PostgreSQLConnectionHelper
    public class ConnectionHelper
extends java.lang.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​(javax.sql.DataSource dataSrc, boolean block)  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void endBatch​(boolean commit)
      This method always ends the batch mode.
      void exec​(java.lang.String sql, java.lang.Object... params)
      Executes a general SQL statement and immediately closes all resources.
      java.sql.ResultSet exec​(java.lang.String sql, java.lang.Object[] params, boolean returnGeneratedKeys, int maxRows)
      Executes a general SQL statement and returns the ResultSet of the executed statement.
      java.lang.String prepareDbIdentifier​(java.lang.String identifier)
      A utility method that makes sure that identifier does only consist of characters that are allowed in names on the target database.
      java.sql.ResultSet query​(java.lang.String sql, java.lang.Object... params)
      Executes a SQL query and returns the ResultSet.
      void startBatch()
      Starts the batch mode.
      boolean tableExists​(java.lang.String tableName)
      Checks whether the given table exists in the database.
      int update​(java.lang.String sql, java.lang.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​(javax.sql.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 java.lang.String prepareDbIdentifier​(java.lang.String identifier)
                                           throws java.sql.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:
        java.sql.SQLException - if an error occurs

      • tableExists

        public final boolean tableExists​(java.lang.String tableName)
                          throws java.sql.SQLException
        Checks whether the given table exists in the database.
        Parameters:
        tableName - the name of the table
        Returns:
        whether the given table exists
        Throws:
        java.sql.SQLException - on error

      • startBatch

        public final void startBatch()
                      throws java.sql.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:
        java.sql.SQLException - on error

      • endBatch

        public final void endBatch​(boolean commit)
                    throws java.sql.SQLException
        This method always ends the batch mode.
        Parameters:
        commit - whether the changes in the batch should be committed or rolled back
        Throws:
        java.sql.SQLException - if the commit or rollback of the underlying JDBC Connection threw an SQLException

      • exec

        public final void exec​(java.lang.String sql,
                       java.lang.Object... params)
                throws java.sql.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:
        java.sql.SQLException - on error

      • update

        public final int update​(java.lang.String sql,
                        java.lang.Object... params)
                 throws java.sql.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:
        java.sql.SQLException - on error

      • query

        public final java.sql.ResultSet query​(java.lang.String sql,
                                      java.lang.Object... params)
                               throws java.sql.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:
        java.sql.SQLException

      • exec

        public final java.sql.ResultSet exec​(java.lang.String sql,
                                     java.lang.Object[] params,
                                     boolean returnGeneratedKeys,
                                     int maxRows)
                              throws java.sql.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:
        java.sql.SQLException - on error