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 {@link #startBatch()}and {@link #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 {@code SQLException}, then it is retried. If the {@code block} argumentof the constructor call was {@code false} then it is retried only once. Otherwise the statement is retrieduntil either it succeeds or the thread is interrupted. This clearly assumes that the only cause of {@code SQLExceptions} is faulty {@code Connections} which are restored eventually.
Note:This retry logic only applies to the following methods:
- {@link #exec(String,Object)}
- {@link #update(String,Object[])}
- {@link #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 {@code Connection} that is retrieved from the {@code DataSource}in {@link #getConnection()} may be broken. This is so because if an internal {@code DataSource} is used,then this is a commons-dbcp {@code DataSource} with a
testWhileIdle validation strategy (seethe {@code ConnectionFactory} class). Furthermore, if it is a {@code DataSource} obtained through JNDI then wecan 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.