cvs commit: jakarta-commons/beanutils/src/java/org/apache/commons/beanutils RowSetDynaClass.java package.html

[cr...@apache.org]

craigmcc    2003/01/04 21:45:41

  Modified:    beanutils/src/java/org/apache/commons/beanutils
                        RowSetDynaClass.java package.html
  Log:
  Update the beanutils docs to talk about the new RowSetDynaClass
  implementation, and fix a typo in the class JavaDocs.
  
  Revision  Changes    Path
  1.2       +5 -5      jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/RowSetDynaClass.java
  
  Index: RowSetDynaClass.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/RowSetDynaClass.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- RowSetDynaClass.java	5 Jan 2003 05:33:05 -0000	1.1
  +++ RowSetDynaClass.java	5 Jan 2003 05:45:41 -0000	1.2
  @@ -287,7 +287,7 @@
        * <p>Return a <code>List</code> containing the {@link DynaBean}s that
        * represent the contents of each <code>Row</code> from the
        * <code>ResultSet</code> that was the basis of this
  -     * {@link RowSetDynaClass} instance.  These {@link DynaBeans} are
  +     * {@link RowSetDynaClass} instance.  These {@link DynaBean}s are
        * disconnected from the database itself, so there is no problem with
        * modifying the contents of the list, or the values of the properties
        * of these {@link DynaBean}s.  However, it is the application's
  
  
  
  1.13      +51 -0     jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/beanutils/src/java/org/apache/commons/beanutils/package.html,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- package.html	6 Nov 2002 22:02:48 -0000	1.12
  +++ package.html	5 Jan 2003 05:45:41 -0000	1.13
  @@ -28,6 +28,7 @@
       <li><a href="#dynamic.background">Background</a></li>
       <li><a href="#dynamic.basic">BasicDynaBean and BasicDynaClass</a></li>
       <li><a href="#dynamic.resultSet">ResultSetDynaClass (Wraps ResultSet in DynaBeans)</a></li>
  +    <li><a href="#dynamic.rowSet">RowSetDynaClass (Disconnected ResultSet as DynaBeans)</a></li>
       <li><a href="#dynamic.wrap">WrapDynaBean and WrapDynaClass</a></li>
       </ul></li>
   <li><a href="#conversion">Data Type Conversions</a>
  @@ -499,6 +500,56 @@
     rs.close();
     stmt.close();
   </pre>
  +
  +
  +<a name="dynamic.rowSet"></a>
  +<h3><code>RowSetDynaClass</code> (Disconnected ResultSet as DynaBeans)</h3>
  +
  +<p>Although <a href="#dynamic.resultSet">ResultSetDynaClass</code> is a very
  +useful technique for representing the results of an SQL query as a series of
  +DynaBeans, an important problem is that the underlying <code>ResultSet</code>
  +must remain open throughout the period of time that the rows are being
  +processed by your application.  This hinders the ability to use
  +<code>ResultSetDynaClass</code> as a means of communicating information from
  +the model layer to the view layer in a model-view-controller architecture
  +such as that provided by the <a href="http://jakarta.apache.org/struts/">Struts
  +Framework</a>, because there is no easy mechanism to assure that the result set
  +is finally closed (and the underlying <code>Connection</code> returned to its
  +connection pool, if you are using one).</p>
  +
  +<p>The <code>RowSetDynaClass</code> class represents a different approach to
  +this problem.  When you construct such an instance, the underlying data is
  +<em>copied</em> into a set of in-memory DynaBeans that represent the result.
  +The advantage of this technique, of course, is that you can immediately close
  +the ResultSet (and the corresponding Statement), normally before you even
  +process the actual data that was returned.  The disadvantage, of course, is
  +that you must pay the performance and memory costs of copying the result data,
  +and the result data must fit entirely into available heap memory.  For many
  +environments (particularly in web applications), this tradeoff is usually
  +quite beneficial.</p>
  +
  +<p>As an additional benefit, the <code>RowSetDynaClass</code> class is defined
  +to implement <code>java.io.Serializable</code>, so that it (and the
  +DynaBeans that correspond to each row of the result) can be conveniently
  +serialized and deserialized (as long as the underlying column values are
  +also Serializable).  Thus, <code>RowSetDynaClass</code> represents a very
  +convenient way to transmit the results 0f an SQL query to a remote Java-based
  +client application (such as an applet).</p>
  +
  +<p>The normal usage pattern for a <code>RowSetDynaClass</code> will look
  +something like this:</p>
  +<pre>
  +    Connection conn = ...;  // Acquire connection from pool
  +    Statement stmt = conn.createStatement();
  +    ResultSet rs = stmt.executeQuery("SELECT ...");
  +    RowSetDynaClass rsdc = new RowSetDynaClass(rs);
  +    rs.close();
  +    stmt.close();
  +    ...;                    // Return connection to pool
  +    List rows = rsdc.getRows();
  +    ...;                   // Process the rows as desired
  +/pre>
  +
   
   <a name="dynamic.wrap"></a>
   <h3><code>WrapDynaBean</code> and <code>WrapDynaClass</code></h3>
  
  
  

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>