View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  
19  package org.apache.commons.beanutils;
20  
21  
22  import java.io.Serializable;
23  import java.sql.ResultSet;
24  import java.sql.SQLException;
25  import java.util.ArrayList;
26  import java.util.List;
27  
28  
29  /**
30   * <p>Implementation of {@link DynaClass} that creates an in-memory collection
31   * of {@link DynaBean}s representing the results of an SQL query.  Once the
32   * {@link DynaClass} instance has been created, the JDBC <code>ResultSet</code>
33   * and <code>Statement</code> on which it is based can be closed, and the
34   * underlying <code>Connection</code> can be returned to its connection pool
35   * (if you are using one).</p>
36   *
37   * <p>The normal usage pattern is something like:</p>
38   * <pre>
39   *   Connection conn = ...;  // Acquire connection from pool
40   *   Statement stmt = conn.createStatement();
41   *   ResultSet rs = stmt.executeQuery("SELECT ...");
42   *   RowSetDynaClass rsdc = new RowSetDynaClass(rs);
43   *   rs.close();
44   *   stmt.close();
45   *   ...;                    // Return connection to pool
46   *   List rows = rsdc.getRows();
47   *   ...;                   // Process the rows as desired
48   * </pre>
49   *
50   * <p>Each column in the result set will be represented as a {@link DynaBean}
51   * property of the corresponding name (optionally forced to lower case
52   * for portability).  There will be one {@link DynaBean} in the
53   * <code>List</code> returned by <code>getRows()</code> for each
54   * row in the original <code>ResultSet</code>.</p>
55   *
56   * <p>In general, instances of {@link RowSetDynaClass} can be serialized
57   * and deserialized, which will automatically include the list of
58   * {@link DynaBean}s representing the data content.  The only exception
59   * to this rule would be when the underlying property values that were
60   * copied from the <code>ResultSet</code> originally cannot themselves
61   * be serialized.  Therefore, a {@link RowSetDynaClass} makes a very
62   * convenient mechanism for transporting data sets to remote Java-based
63   * application components.</p>
64   *
65   * @version $Id: RowSetDynaClass.java 1540186 2013-11-08 21:08:30Z oheger $
66   */
67  
68  public class RowSetDynaClass extends JDBCDynaClass implements DynaClass, Serializable {
69  
70  
71      // ----------------------------------------------------- Instance variables
72  
73      /**
74       * <p>Limits the size of the returned list.  The call to
75       * <code>getRows()</code> will return at most limit number of rows.
76       * If less than or equal to 0, does not limit the size of the result.
77       */
78      protected int limit = -1;
79  
80      /**
81       * <p>The list of {@link DynaBean}s representing the contents of
82       * the original <code>ResultSet</code> on which this
83       * {@link RowSetDynaClass} was based.</p>
84       */
85      protected List<DynaBean> rows = new ArrayList<DynaBean>();
86  
87      // ----------------------------------------------------------- Constructors
88  
89  
90      /**
91       * <p>Construct a new {@link RowSetDynaClass} for the specified
92       * <code>ResultSet</code>.  The property names corresponding
93       * to column names in the result set will be lower cased.</p>
94       *
95       * @param resultSet The result set to be wrapped
96       *
97       * @exception NullPointerException if <code>resultSet</code>
98       *  is <code>null</code>
99       * @exception SQLException if the metadata for this result set
100      *  cannot be introspected
101      */
102     public RowSetDynaClass(ResultSet resultSet) throws SQLException {
103 
104         this(resultSet, true, -1);
105 
106     }
107 
108     /**
109      * <p>Construct a new {@link RowSetDynaClass} for the specified
110      * <code>ResultSet</code>.  The property names corresponding
111      * to column names in the result set will be lower cased.</p>
112      *
113      * If <code>limit</code> is not less than 0, max <code>limit</code>
114      * number of rows will be copied into the list.
115      *
116      * @param resultSet The result set to be wrapped
117      * @param limit The maximum for the size of the result.
118      *
119      * @exception NullPointerException if <code>resultSet</code>
120      *  is <code>null</code>
121      * @exception SQLException if the metadata for this result set
122      *  cannot be introspected
123      */
124     public RowSetDynaClass(ResultSet resultSet, int limit) throws SQLException {
125 
126         this(resultSet, true, limit);
127 
128     }
129 
130 
131     /**
132      * <p>Construct a new {@link RowSetDynaClass} for the specified
133      * <code>ResultSet</code>.  The property names corresponding
134      * to the column names in the result set will be lower cased or not,
135      * depending on the specified <code>lowerCase</code> value.</p>
136      *
137      * If <code>limit</code> is not less than 0, max <code>limit</code>
138      * number of rows will be copied into the resultset.
139      *
140      *
141      * @param resultSet The result set to be wrapped
142      * @param lowerCase Should property names be lower cased?
143      *
144      * @exception NullPointerException if <code>resultSet</code>
145      *  is <code>null</code>
146      * @exception SQLException if the metadata for this result set
147      *  cannot be introspected
148      */
149     public RowSetDynaClass(ResultSet resultSet, boolean lowerCase)
150                                                     throws SQLException {
151         this(resultSet, lowerCase, -1);
152 
153     }
154 
155     /**
156      * <p>Construct a new {@link RowSetDynaClass} for the specified
157      * <code>ResultSet</code>.  The property names corresponding
158      * to the column names in the result set will be lower cased or not,
159      * depending on the specified <code>lowerCase</code> value.</p>
160      *
161      * <p><strong>WARNING</strong> - If you specify <code>false</code>
162      * for <code>lowerCase</code>, the returned property names will
163      * exactly match the column names returned by your JDBC driver.
164      * Because different drivers might return column names in different
165      * cases, the property names seen by your application will vary
166      * depending on which JDBC driver you are using.</p>
167      *
168      * @param resultSet The result set to be wrapped
169      * @param lowerCase Should property names be lower cased?
170      * @param limit Maximum limit for the <code>List</code> of {@link DynaBean}
171      *
172      * @exception NullPointerException if <code>resultSet</code>
173      *  is <code>null</code>
174      * @exception SQLException if the metadata for this result set
175      *  cannot be introspected
176      */
177     public RowSetDynaClass(ResultSet resultSet, boolean lowerCase, int limit)
178                                                             throws SQLException {
179 
180         this(resultSet, lowerCase, limit, false);
181 
182     }
183 
184     /**
185      * <p>Construct a new {@link RowSetDynaClass} for the specified
186      * <code>ResultSet</code>.  The property names corresponding
187      * to the column names in the result set will be lower cased or not,
188      * depending on the specified <code>lowerCase</code> value.</p>
189      *
190      * <p><strong>WARNING</strong> - If you specify <code>false</code>
191      * for <code>lowerCase</code>, the returned property names will
192      * exactly match the column names returned by your JDBC driver.
193      * Because different drivers might return column names in different
194      * cases, the property names seen by your application will vary
195      * depending on which JDBC driver you are using.</p>
196      *
197      * @param resultSet The result set to be wrapped
198      * @param lowerCase Should property names be lower cased?
199      * @param useColumnLabel true if the column label should be used, otherwise false
200      *
201      * @exception NullPointerException if <code>resultSet</code>
202      *  is <code>null</code>
203      * @exception SQLException if the metadata for this result set
204      *  cannot be introspected
205      * @since 1.8.3
206      */
207     public RowSetDynaClass(ResultSet resultSet, boolean lowerCase, boolean useColumnLabel)
208         throws SQLException {
209         this(resultSet, lowerCase, -1, useColumnLabel);
210 
211     }
212 
213     /**
214      * <p>Construct a new {@link RowSetDynaClass} for the specified
215      * <code>ResultSet</code>.  The property names corresponding
216      * to the column names in the result set will be lower cased or not,
217      * depending on the specified <code>lowerCase</code> value.</p>
218      *
219      * <p><strong>WARNING</strong> - If you specify <code>false</code>
220      * for <code>lowerCase</code>, the returned property names will
221      * exactly match the column names returned by your JDBC driver.
222      * Because different drivers might return column names in different
223      * cases, the property names seen by your application will vary
224      * depending on which JDBC driver you are using.</p>
225      *
226      * @param resultSet The result set to be wrapped
227      * @param lowerCase Should property names be lower cased?
228      * @param limit Maximum limit for the <code>List</code> of {@link DynaBean}
229      * @param useColumnLabel true if the column label should be used, otherwise false
230      *
231      * @exception NullPointerException if <code>resultSet</code>
232      *  is <code>null</code>
233      * @exception SQLException if the metadata for this result set
234      *  cannot be introspected
235      * @since 1.8.3
236      */
237     public RowSetDynaClass(ResultSet resultSet, boolean lowerCase, int limit, boolean useColumnLabel)
238                                                             throws SQLException {
239 
240         if (resultSet == null) {
241             throw new NullPointerException();
242         }
243         this.lowerCase = lowerCase;
244         this.limit = limit;
245         setUseColumnLabel(useColumnLabel);
246         introspect(resultSet);
247         copy(resultSet);
248 
249     }
250 
251     /**
252      * <p>Return a <code>List</code> containing the {@link DynaBean}s that
253      * represent the contents of each <code>Row</code> from the
254      * <code>ResultSet</code> that was the basis of this
255      * {@link RowSetDynaClass} instance.  These {@link DynaBean}s are
256      * disconnected from the database itself, so there is no problem with
257      * modifying the contents of the list, or the values of the properties
258      * of these {@link DynaBean}s.  However, it is the application's
259      * responsibility to persist any such changes back to the database,
260      * if it so desires.</p>
261      *
262      * @return A <code>List</code> of {@link DynaBean} instances
263      */
264     public List<DynaBean> getRows() {
265 
266         return (this.rows);
267 
268     }
269 
270 
271     // ------------------------------------------------------ Protected Methods
272 
273 
274     /**
275      * <p>Copy the column values for each row in the specified
276      * <code>ResultSet</code> into a newly created {@link DynaBean}, and add
277      * this bean to the list of {@link DynaBean}s that will later by
278      * returned by a call to <code>getRows()</code>.</p>
279      *
280      * @param resultSet The <code>ResultSet</code> whose data is to be
281      *  copied
282      *
283      * @exception SQLException if an error is encountered copying the data
284      */
285     protected void copy(ResultSet resultSet) throws SQLException {
286 
287         int cnt = 0;
288         while (resultSet.next() && (limit < 0  || cnt++ < limit) ) {
289             DynaBean bean = createDynaBean();
290             for (int i = 0; i < properties.length; i++) {
291                 String name = properties[i].getName();
292                 Object value = getObject(resultSet, name);
293                 bean.set(name, value);
294             }
295             rows.add(bean);
296         }
297 
298     }
299 
300 
301     /**
302      * <p>Create and return a new {@link DynaBean} instance to be used for
303      * representing a row in the underlying result set.</p>
304      *
305      * @return A new <code>DynaBean</code> instance
306      */
307     protected DynaBean createDynaBean() {
308 
309         return (new BasicDynaBean(this));
310 
311     }
312 
313 
314 }