You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by dg...@apache.org on 2003/12/13 21:53:11 UTC
cvs commit: jakarta-commons/dbutils/xdocs examples.xml
dgraham 2003/12/13 12:53:11
Modified: dbutils/xdocs examples.xml
Log:
Added more examples.
Revision Changes Path
1.2 +109 -28 jakarta-commons/dbutils/xdocs/examples.xml
Index: examples.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/dbutils/xdocs/examples.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- examples.xml 10 Nov 2003 16:45:45 -0000 1.1
+++ examples.xml 13 Dec 2003 20:53:11 -0000 1.2
@@ -5,60 +5,141 @@
<properties>
<title>JDBC Utility Component -- Examples</title>
<author email="yoavs@apache.org">Yoav Shapira</author>
+ <author email="dgraham@apache.org">David Graham</author>
</properties>
<body>
<section name="DbUtils: JDBC Utility Component Examples">
<p>
-This page provides examples that show how the DbUtils component
-may be used.
+This page provides examples that show how DbUtils may be used.
</p>
</section>
<section name="Basic Usage">
<p>
+DbUtils is a very small library of classes so it won't take long
+to go through the <a href="apidocs/">javadocs</a> for each class.
The core classes/interfaces in DbUtils are
<code><a href="apidocs/org/apache/commons/dbutils/QueryRunner.html">QueryRunner</a></code>
and
<code><a href="apidocs/org/apache/commons/dbutils/ResultSetHandler.html">ResultSetHandler</a></code>.
-The following example demonstrates how these classes are used together.
+You don't need to know about any other DbUtils classes to benefit from using the
+library. The following example demonstrates how these classes are used together.
</p>
<pre>
-DataSource ds = // somehow get DataSource;
+<![CDATA[
+// Create a ResultSetHandler implementation to convert the
+// first row into an Object[].
+ResultSetHandler h = new ResultSetHandler() {
+ public Object handle(ResultSet rs) throws SQLException {
+ ResultSetMetaData meta = rs.getMetaData();
+ int cols = meta.getColumnCount();
+ Object[] result = new Object[cols];
+
+ for (int i = 0; i < cols; i++) {
+ result[i] = rs.getObject(i + 1);
+ }
+
+ return result;
+ }
+};
+
+// Create a QueryRunner that will use connections from
+// the given DataSource
+QueryRunner run = new QueryRunner(dataSource);
+
+// Execute the query and get the results back from the handler
+Object[] result = (Object[]) run.query("SELECT * FROM Person WHERE name=?", "John Doe", h);
+]]>
+</pre>
+
-// Step 1.
-QueryRunner run = new QueryRunner(ds);
+<p>
+You could also perform the previous query using a <code>java.sql.Connection</code> object
+instead of a <code>DataSource</code>. Notice that you are responsible for closing the
+<code>Connection</code> in this example.
+</p>
+<pre>
+<![CDATA[
+ResultSetHandler h = new ResultSetHandler() {
+ public Object handle(ResultSet rs) throws SQLException {
+ ResultSetMetaData meta = rs.getMetaData();
+ int cols = meta.getColumnCount();
+ Object[] result = new Object[cols];
+
+ for (int i = 0; i < cols; i++) {
+ result[i] = rs.getObject(i + 1);
+ }
+
+ return result;
+ }
+};
+
+QueryRunner run = new QueryRunner();
+
+Connection conn = ... // open a connection
+try{
+ Object[] result = (Object[]) run.query(conn, "SELECT * FROM Person WHERE name=?", "John Doe", h);
+ // do something with the result
+
+} finally {
+ // use this helper method so we don't have to check for null
+ DbUtils.close(conn);
+}
+]]>
+</pre>
+</section>
+
+
+<section name="ResultSetHandler Implementations">
+<p>
+In the examples above we implemented the <code>ResultSetHandler</code> interface
+to turn the first row of the <code>ResultSet</code> into an Object[]. This is a
+fairly generic implementation that can be reused across many projects.
+In recognition of this DbUtils provides a set of <code>ResultSetHandler</code>
+implementations in the
+<a href="apidocs/org/apache/commons/dbutils/handlers/package-summary.html">org.apache.commons.dbutils.handlers</a>
+package that perform common transformations into arrays, Maps, and JavaBeans.
+There is a version of each implementation that converts just the first row and
+another that converts all rows in the <code>ResultSet</code>.
+</p>
-// Step 2.
+<pre>
+QueryRunner run = new QueryRunner(dataSource);
+
+// Use the BeanHandler implementation to convert the first
+// ResultSet row into a Person JavaBean.
ResultSetHandler h = new BeanHandler(Person.class);
-// Step 3.
+// Execute the SQL statement with one replacement parameter and
+// return the results in a new Person object generated by the BeanHandler.
Person p = (Person) run.query("SELECT * FROM Person WHERE name=?", "John Doe", h);
-
</pre>
-<p>Explanation</p>
-<ol>
- <li>
- Configure QueryRunner with the DataSource.
- Note that QueryRunner has methods that take a
- java.sql.Connection so you are not required to
- use DataSources.
- </li>
- <li>
- Implement the ResultSetHandler interface or use
- one of the provided implementations. This one converts a
- ResultSet row into a bean.
- </li>
- <li>
- Execute the SQL statement with one replacement parameter and
- return the results in a new Person object (generated by the handler
- in step 2).
- </li>
-</ol>
+</section>
+
+<section name="Custom RowProcessor">
+<p>
+Each of the provided <code>ResultSetHandler</code> implementations accept a
+<a href="apidocs/org/apache/commons/dbutils/RowProcessor.html">RowProcessor</a>
+to do the actual conversion of rows into objects. By default the handlers
+use the <a href="apidocs/org/apache/commons/dbutils/BasicRowProcessor.html">BasicRowProcessor</a>
+implementation but you can implement a custom version to plug in.
+Probably the most common customization is to implement the <code>toBean()</code>
+method to handle custom database datatype issues.
+</p>
+</section>
+<section name="Custom ColumnProcessor">
+<p>
+<code>BasicRowProcessor</code> uses a <a href="apidocs/org/apache/commons/dbutils/ColumnProcessor.html">ColumnProcessor</a>
+to convert <code>ResultSet</code> columns into JavaBean properties. You can implement this interface
+to handle datatype mapping specific to your application. By default <code>BasicRowProcessor</code> uses a
+<a href="apidocs/org/apache/commons/dbutils/BasicColumnProcessor.html">BasicColumnProcessor</a>
+instance which may be sufficient for your application.
+</p>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org