View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */ 
16  
17  
18  package org.apache.commons.beanutils;
19  
20  
21  import java.sql.ResultSet;
22  import java.sql.SQLException;
23  import java.util.Iterator;
24  import java.util.NoSuchElementException;
25  
26  
27  /**
28   * <p>Implementation of <code>java.util.Iterator</code> returned by the
29   * <code>iterator()</code> method of {@link ResultSetDynaClass}.  Each
30   * object returned by this iterator will be a {@link DynaBean} that
31   * represents a single row from the result set being wrapped.</p>
32   *
33   * @author Craig R. McClanahan
34   * @version $Revision: 1.5 $ $Date: 2004/02/28 13:18:34 $
35   */
36  
37  public class ResultSetIterator implements DynaBean, Iterator {
38  
39  
40      // ------------------------------------------------------------ Constructor
41  
42  
43      /**
44       * <p>Construct an <code>Iterator</code> for the result set being wrapped
45       * by the specified {@link ResultSetDynaClass}.</p>
46       *
47       * @param dynaClass The {@link ResultSetDynaClass} wrapping the
48       *  result set we will iterate over
49       */
50      ResultSetIterator(ResultSetDynaClass dynaClass) {
51  
52          this.dynaClass = dynaClass;
53  
54      }
55  
56  
57      // ----------------------------------------------------- Instance Variables
58  
59  
60  
61      /**
62       * <p>Flag indicating whether the result set is currently positioned at a
63       * row for which we have not yet returned an element in the iteration.</p>
64       */
65      protected boolean current = false;
66  
67  
68      /**
69       * <p>The {@link ResultSetDynaClass} we are associated with.</p>
70       */
71      protected ResultSetDynaClass dynaClass = null;
72  
73  
74      /**
75       * <p>Flag indicating whether the result set has indicated that there are
76       * no further rows.</p>
77       */
78      protected boolean eof = false;
79  
80  
81      // ------------------------------------------------------- DynaBean Methods
82  
83  
84      /**
85       * Does the specified mapped property contain a value for the specified
86       * key value?
87       *
88       * @param name Name of the property to check
89       * @param key Name of the key to check
90       *
91       * @exception IllegalArgumentException if there is no property
92       *  of the specified name
93       */
94      public boolean contains(String name, String key) {
95  
96          throw new UnsupportedOperationException
97              ("FIXME - mapped properties not currently supported");
98  
99      }
100 
101 
102     /**
103      * Return the value of a simple property with the specified name.
104      *
105      * @param name Name of the property whose value is to be retrieved
106      *
107      * @exception IllegalArgumentException if there is no property
108      *  of the specified name
109      */
110     public Object get(String name) {
111 
112         if (dynaClass.getDynaProperty(name) == null) {
113             throw new IllegalArgumentException(name);
114         }
115         try {
116             return (dynaClass.getResultSet().getObject(name));
117         } catch (SQLException e) {
118             throw new RuntimeException
119                 ("get(" + name + "): SQLException: " + e);
120         }
121 
122     }
123 
124 
125     /**
126      * Return the value of an indexed property with the specified name.
127      *
128      * @param name Name of the property whose value is to be retrieved
129      * @param index Index of the value to be retrieved
130      *
131      * @exception IllegalArgumentException if there is no property
132      *  of the specified name
133      * @exception IllegalArgumentException if the specified property
134      *  exists, but is not indexed
135      * @exception IndexOutOfBoundsException if the specified index
136      *  is outside the range of the underlying property
137      * @exception NullPointerException if no array or List has been
138      *  initialized for this property
139      */
140     public Object get(String name, int index) {
141 
142         throw new UnsupportedOperationException
143             ("FIXME - indexed properties not currently supported");
144 
145     }
146 
147 
148     /**
149      * Return the value of a mapped property with the specified name,
150      * or <code>null</code> if there is no value for the specified key.
151      *
152      * @param name Name of the property whose value is to be retrieved
153      * @param key Key of the value to be retrieved
154      *
155      * @exception IllegalArgumentException if there is no property
156      *  of the specified name
157      * @exception IllegalArgumentException if the specified property
158      *  exists, but is not mapped
159      */
160     public Object get(String name, String key) {
161 
162         throw new UnsupportedOperationException
163             ("FIXME - mapped properties not currently supported");
164 
165     }
166 
167 
168     /**
169      * Return the <code>DynaClass</code> instance that describes the set of
170      * properties available for this DynaBean.
171      */
172     public DynaClass getDynaClass() {
173 
174         return (this.dynaClass);
175 
176     }
177 
178 
179     /**
180      * Remove any existing value for the specified key on the
181      * specified mapped property.
182      *
183      * @param name Name of the property for which a value is to
184      *  be removed
185      * @param key Key of the value to be removed
186      *
187      * @exception IllegalArgumentException if there is no property
188      *  of the specified name
189      */
190     public void remove(String name, String key) {
191 
192         throw new UnsupportedOperationException
193             ("FIXME - mapped operations not currently supported");
194 
195     }
196 
197 
198     /**
199      * Set the value of a simple property with the specified name.
200      *
201      * @param name Name of the property whose value is to be set
202      * @param value Value to which this property is to be set
203      *
204      * @exception ConversionException if the specified value cannot be
205      *  converted to the type required for this property
206      * @exception IllegalArgumentException if there is no property
207      *  of the specified name
208      * @exception NullPointerException if an attempt is made to set a
209      *  primitive property to null
210      */
211     public void set(String name, Object value) {
212 
213         if (dynaClass.getDynaProperty(name) == null) {
214             throw new IllegalArgumentException(name);
215         }
216         try {
217             dynaClass.getResultSet().updateObject(name, value);
218         } catch (SQLException e) {
219             throw new RuntimeException
220                 ("set(" + name + "): SQLException: " + e);
221         }
222 
223     }
224 
225 
226     /**
227      * Set the value of an indexed property with the specified name.
228      *
229      * @param name Name of the property whose value is to be set
230      * @param index Index of the property to be set
231      * @param value Value to which this property is to be set
232      *
233      * @exception ConversionException if the specified value cannot be
234      *  converted to the type required for this property
235      * @exception IllegalArgumentException if there is no property
236      *  of the specified name
237      * @exception IllegalArgumentException if the specified property
238      *  exists, but is not indexed
239      * @exception IndexOutOfBoundsException if the specified index
240      *  is outside the range of the underlying property
241      */
242     public void set(String name, int index, Object value) {
243 
244         throw new UnsupportedOperationException
245             ("FIXME - indexed properties not currently supported");
246 
247     }
248 
249 
250     /**
251      * Set the value of a mapped property with the specified name.
252      *
253      * @param name Name of the property whose value is to be set
254      * @param key Key of the property to be set
255      * @param value Value to which this property is to be set
256      *
257      * @exception ConversionException if the specified value cannot be
258      *  converted to the type required for this property
259      * @exception IllegalArgumentException if there is no property
260      *  of the specified name
261      * @exception IllegalArgumentException if the specified property
262      *  exists, but is not mapped
263      */
264     public void set(String name, String key, Object value) {
265 
266         throw new UnsupportedOperationException
267             ("FIXME - mapped properties not currently supported");
268 
269     }
270 
271 
272     // ------------------------------------------------------- Iterator Methods
273 
274 
275     /**
276      * <p>Return <code>true</code> if the iteration has more elements.</p>
277      */
278     public boolean hasNext() {
279 
280         try {
281             advance();
282             return (!eof);
283         } catch (SQLException e) {
284             throw new RuntimeException("hasNext():  SQLException:  " + e);
285         }
286 
287     }
288 
289 
290     /**
291      * <p>Return the next element in the iteration.</p>
292      */
293     public Object next() {
294 
295         try {
296             advance();
297             if (eof) {
298                 throw new NoSuchElementException();
299             }
300             current = false;
301             return (this);
302         } catch (SQLException e) {
303             throw new RuntimeException("next():  SQLException:  " + e);
304         }
305 
306     }
307 
308 
309     /**
310      * <p>Remove the current element from the iteration.  This method is
311      * not supported.</p>
312      */
313     public void remove() {
314 
315         throw new UnsupportedOperationException("remove()");
316 
317     }
318 
319 
320     // ------------------------------------------------------ Protected Methods
321 
322 
323     /**
324      * <p>Advance the result set to the next row, if there is not a current
325      * row (and if we are not already at eof).</p>
326      *
327      * @exception SQLException if the result set throws an exception
328      */
329     protected void advance() throws SQLException {
330 
331         if (!current && !eof) {
332             if (dynaClass.getResultSet().next()) {
333                 current = true;
334                 eof = false;
335             } else {
336                 current = false;
337                 eof = true;
338             }
339         }
340 
341     }
342 
343 
344 }