dgraham 2003/10/20 17:12:58
Modified: dbutils/src/java/org/apache/commons/dbutils QueryRunner.java
Log:
Added javadoc and more versions of query() and update(). There are
now methods that take 0, 1, or an array of replacement parameters.
Revision Changes Path
1.6 +203 -42
jakarta-commons-sandbox/dbutils/src/java/org/apache/commons/dbutils/QueryRunner.java
Index: QueryRunner.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/dbutils/src/java/org/apache/commons/dbutils/QueryRunner.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- QueryRunner.java 20 Oct 2003 02:10:21 -0000 1.5
+++ QueryRunner.java 21 Oct 2003 00:12:58 -0000 1.6
@@ -66,7 +66,9 @@
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Types;
+import java.util.ArrayList;
import java.util.Arrays;
+import java.util.List;
import javax.sql.DataSource;
@@ -97,18 +99,36 @@
}
/**
- * Constructor for QueryRunner.
- * @param ds The <code>DataSource</code> to retrieve connections
- * from.
+ * Constructor for QueryRunner. Methods that do not take a
+ * <code>Connection</code> parameter will retrieve connections from this
+ * <code>DataSource</code>.
+ *
+ * @param ds The <code>DataSource</code> to retrieve connections from.
*/
public QueryRunner(DataSource ds) {
super();
this.ds = ds;
}
- public boolean execute(
+ /**
+ * Execute any SQL statement and return all the results in an
+ * <code>Object[]</code>. Callers are responsible for connection cleanup.
+ *
+ * @param conn The connection to execute the query with.
+ * @param sql The SQL statement.
+ * @param params SQL replacement parameters; <code>null</code> if no
+ * parameters are required.
+ * @param rsh The handler to generate result objects with
+ * @param rsmdh Handles the meta data.
+ * @param userObject Object to pass to the handler.
+ * @return An array filled with result objects from the handler for each
+ * <code>ResultSet</code> returned by the query; <code>null</code> if the
+ * statment was an UPDATE.
+ * @throws SQLException
+ */
+ public Object[] execute(
Connection conn,
- String query,
+ String sql,
Object[] params,
ResultSetHandler rsh,
ResultSetMetaDataHandler rsmdh,
@@ -118,37 +138,40 @@
PreparedStatement stmt = null;
ResultSet rs = null;
+ List results = new ArrayList();
+
try {
- stmt = conn.prepareStatement(query);
- fillStatement(stmt, params);
+ stmt = conn.prepareStatement(sql);
+ this.fillStatement(stmt, params);
if (!stmt.execute()) {
- return false;
+ return null;
}
do {
rs = stmt.getResultSet();
if (rs != null) {
rs = this.wrap(rs);
-
+
if (rsmdh != null) {
rsmdh.handle(rs.getMetaData());
}
- rsh.handle(rs, params, userObject);
+ results.add(rsh.handle(rs, params, userObject));
}
} while (stmt.getMoreResults());
} catch (SQLException e) {
- rethrow(e, query, params);
+ rethrow(e, sql, params);
} finally {
DbUtils.closeQuietly(rs);
DbUtils.closeQuietly(stmt);
}
- return true;
+ Object[] res = new Object[results.size()];
+ return results.toArray(res);
}
/**
@@ -183,35 +206,86 @@
}
/**
- * Creates a PreparedStatement using the String and Object array,
- * executes this using the Connection, and returns the results
- * inside an Iterator.
- * Null values in the Object array will be passed to the driver.
+ * Execute an SQL SELECT query with a single replacement parameter. The
+ * caller is responsible for connection cleanup.
+ *
+ * @param conn The connection to execute the query in.
+ * @param sql The query to execute.
+ * @param param The replacement parameter.
+ * @param rsh The handler that converts the results into an object.
+ * @return The object returned by the handler.
+ * @throws SQLException
*/
public Object query(
Connection conn,
- String query,
+ String sql,
+ Object param,
+ ResultSetHandler rsh)
+ throws SQLException {
+
+ return this.query(conn, sql, new Object[] { param }, rsh, null, null);
+ }
+
+ /**
+ * Execute an SQL SELECT query without any replacement parameters. The
+ * caller is responsible for connection cleanup.
+ *
+ * @param conn The connection to execute the query in.
+ * @param sql The query to execute.
+ * @param params The replacement parameters.
+ * @param rsh The handler that converts the results into an object.
+ * @return The object returned by the handler.
+ * @throws SQLException
+ */
+ public Object query(
+ Connection conn,
+ String sql,
Object[] params,
ResultSetHandler rsh)
throws SQLException {
- return this.query(conn, query, params, rsh, null, null);
+ return this.query(conn, sql, params, rsh, null, null);
}
+ /**
+ * Execute an SQL SELECT query with replacement parameters. The
+ * caller is responsible for connection cleanup.
+ *
+ * @param conn The connection to execute the query in.
+ * @param sql The query to execute.
+ * @param params The replacement parameters.
+ * @param rsh The handler that converts the results into an object.
+ * @param rsmdh Handles the meta data.
+ * @return The object returned by the handler.
+ * @throws SQLException
+ */
public Object query(
Connection conn,
- String query,
+ String sql,
Object[] params,
ResultSetHandler rsh,
ResultSetMetaDataHandler rsmdh)
throws SQLException {
- return this.query(conn, query, params, rsh, rsmdh, null);
+ return this.query(conn, sql, params, rsh, rsmdh, null);
}
+ /**
+ * Execute an SQL SELECT query with replacement parameters. The
+ * caller is responsible for connection cleanup.
+ *
+ * @param conn The connection to execute the query in.
+ * @param sql The query to execute.
+ * @param params The replacement parameters.
+ * @param rsh The handler that converts the results into an object.
+ * @param rsmdh Handles the meta data.
+ * @param userObject Pass this object to the handler.
+ * @return The object returned by the handler.
+ * @throws SQLException
+ */
public Object query(
Connection conn,
- String query,
+ String sql,
Object[] params,
ResultSetHandler rsh,
ResultSetMetaDataHandler rsmdh,
@@ -223,7 +297,7 @@
Object result = null;
try {
- stmt = conn.prepareStatement(query);
+ stmt = conn.prepareStatement(sql);
this.fillStatement(stmt, params);
rs = this.wrap(stmt.executeQuery());
@@ -235,7 +309,7 @@
result = rsh.handle(rs, params, userObject);
} catch (SQLException e) {
- this.rethrow(e, query, params);
+ this.rethrow(e, sql, params);
} finally {
DbUtils.closeQuietly(rs);
@@ -245,18 +319,66 @@
return result;
}
+ /**
+ * Execute an SQL SELECT query with replacement parameters. The
+ * caller is responsible for connection cleanup.
+ *
+ * @param conn The connection to execute the query in.
+ * @param sql The query to execute.
+ * @param params The replacement parameters.
+ * @param rsdmh Handles the meta data.
+ * @return The object returned by the handler.
+ * @throws SQLException
+ */
public Object query(
Connection conn,
- String query,
+ String sql,
Object[] params,
ResultSetMetaDataHandler rsmdh)
throws SQLException {
- return this.query(conn, query, params, null, rsmdh, null);
+ return this.query(conn, sql, params, null, rsmdh, null);
+ }
+
+ /**
+ * Execute an SQL SELECT query without any replacement parameters. The
+ * caller is responsible for connection cleanup.
+ *
+ * @param conn The connection to execute the query in.
+ * @param sql The query to execute.
+ * @param rsh The handler that converts the results into an object.
+ * @return The object returned by the handler.
+ * @throws SQLException
+ */
+ public Object query(Connection conn, String sql, ResultSetHandler rsh)
+ throws SQLException {
+
+ return this.query(conn, sql, null, rsh, null, null);
+ }
+
+ /**
+ * Executes the given SELECT SQL with a single replacement parameter.
+ * The <code>Connection</code> is retrieved from the
+ * <code>DataSource</code> set in the constructor.
+ *
+ * @param sql The SQL statement to execute.
+ * @param rsh The handler used to create the result object from
+ * the <code>ResultSet</code>.
+ * @param param The replacement parameter.
+ * @return An object generated by the handler.
+ * @throws SQLException
+ */
+ public Object query(String sql, Object param, ResultSetHandler rsh)
+ throws SQLException {
+
+ return this.query(sql, new Object[] { param }, rsh);
}
/**
* Executes the given SELECT SQL query and returns a result object.
+ * The <code>Connection</code> is retrieved from the
+ * <code>DataSource</code> set in the constructor.
+ *
* @param sql The SQL statement to execute.
* @param params Initialize the PreparedStatement's IN parameters with this
* array.
@@ -284,15 +406,16 @@
/**
* Executes the given SELECT SQL without any replacement parameters.
+ * The <code>Connection</code> is retrieved from the
+ * <code>DataSource</code> set in the constructor.
+ *
* @param sql The SQL statement to execute.
* @param rsh The handler used to create the result object from
* the <code>ResultSet</code>.
* @return An object generated by the handler.
* @throws SQLException
*/
- public Object query(String sql, ResultSetHandler rsh)
- throws SQLException {
-
+ public Object query(String sql, ResultSetHandler rsh) throws SQLException {
return this.query(sql, null, rsh);
}
@@ -333,27 +456,44 @@
/**
* Execute an SQL INSERT, UPDATE, or DELETE query without replacement
* parameters.
+ *
+ * @param conn The connection to use to run the query.
+ * @param sql The SQL to execute.
+ * @return The number of rows updated.
+ * @throws SQLException
+ */
+ public int update(Connection conn, String sql) throws SQLException {
+ return this.update(conn, sql, null);
+ }
+
+ /**
+ * Execute an SQL INSERT, UPDATE, or DELETE query with a single replacement
+ * parameter.
+ *
* @param conn The connection to use to run the query.
- * @param query The SQL to execute.
+ * @param sql The SQL to execute.
+ * @param param The replacement parameter.
* @return The number of rows updated.
* @throws SQLException
*/
- public int update(Connection conn, String query) throws SQLException {
- return this.update(conn, query, null);
+ public int update(Connection conn, String sql, Object param)
+ throws SQLException {
+
+ return this.update(conn, sql, new Object[] { param });
}
/**
* Execute an SQL INSERT, UPDATE, or DELETE query.
* @param conn The connection to use to run the query.
- * @param query The SQL to execute.
+ * @param sql The SQL to execute.
* @param params The query replacement parameters.
* @return The number of rows updated.
* @throws SQLException
*/
- public int update(Connection conn, String query, Object[] params)
+ public int update(Connection conn, String sql, Object[] params)
throws SQLException {
- PreparedStatement stmt = conn.prepareStatement(query);
+ PreparedStatement stmt = conn.prepareStatement(sql);
this.fillStatement(stmt, params);
int rows = 0;
@@ -362,7 +502,7 @@
rows = stmt.executeUpdate();
} catch (SQLException e) {
- this.rethrow(e, query, params);
+ this.rethrow(e, sql, params);
} finally {
DbUtils.closeQuietly(stmt);
@@ -375,7 +515,9 @@
* Executes the given INSERT, UPDATE, or DELETE SQL statement without
* any replacement parameters. The statement is executed in it's own
* transaction that will be committed or rolled back depending on any
- * SQLExceptions thrown.
+ * SQLExceptions thrown. The <code>Connection</code> is retrieved from the
+ * <code>DataSource</code> set in the constructor.
+ *
* @param sql The SQL statement to execute.
* @throws SQLException
* @return The number of rows updated.
@@ -385,9 +527,28 @@
}
/**
+ * Executes the given INSERT, UPDATE, or DELETE SQL statement with
+ * a single replacement parameter. The statement is executed in it's own
+ * transaction that will be committed or rolled back depending on any
+ * SQLExceptions thrown. The <code>Connection</code> is retrieved from the
+ * <code>DataSource</code> set in the constructor.
+ *
+ * @param sql The SQL statement to execute.
+ * @param param The replacement parameter.
+ * @throws SQLException
+ * @return The number of rows updated.
+ */
+ public int update(String sql, Object param) throws SQLException {
+ return this.update(sql, new Object[] { param });
+ }
+
+ /**
* Executes the given INSERT, UPDATE, or DELETE SQL statement. The
* statement is executed in it's own transaction that will be committed or
- * rolled back depending on any SQLExceptions thrown.
+ * rolled back depending on any SQLExceptions thrown. The
+ * <code>Connection</code> is retrieved from the <code>DataSource</code>
+ * set in the constructor.
+ *
* @param sql The SQL statement to execute.
* @param params Initializes the PreparedStatement's IN (ie. '?')
* parameters.
@@ -415,7 +576,7 @@
return rows;
}
-
+
/**
* Wrap the <code>ResultSet</code> in a decorator before processing it.
* This implementation returns the <code>ResultSet</code> it is given
@@ -424,7 +585,7 @@
* <code>null</code>.
* @return The <code>ResultSet</code> wrapped in some decorator.
*/
- protected ResultSet wrap(ResultSet rs){
+ protected ResultSet wrap(ResultSet rs) {
return rs;
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
