1 /*
2 * Copyright 2002-2014 the original author or authors.
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 package org.springframework.jdbc.support.rowset;
18
19 import java.io.Serializable;
20 import java.math.BigDecimal;
21 import java.sql.Date;
22 import java.sql.Time;
23 import java.sql.Timestamp;
24 import java.util.Calendar;
25 import java.util.Map;
26
27 import org.springframework.jdbc.InvalidResultSetAccessException;
28
29 /**
30 * Mirror interface for {@link javax.sql.RowSet}, representing
31 * disconnected {@link java.sql.ResultSet} data.
32 *
33 * <p>The main difference to the standard JDBC RowSet is that a
34 * {@link java.sql.SQLException} is never thrown here. This allows a
35 * SqlRowSet to be used without having to deal with checked exceptions.
36 * A SqlRowSet will throw Spring's {@link InvalidResultSetAccessException}
37 * instead (when appropriate).
38 *
39 * <p>Note: This interface extends the {@code java.io.Serializable} marker
40 * interface. Implementations, which typically hold disconnected data,
41 * are encouraged to be actually serializable (as far as possible).
42 *
43 * @author Thomas Risberg
44 * @author Juergen Hoeller
45 * @since 1.2
46 * @see javax.sql.RowSet
47 * @see java.sql.ResultSet
48 * @see org.springframework.jdbc.InvalidResultSetAccessException
49 * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet
50 */
51 public interface SqlRowSet extends Serializable {
52
53 /**
54 * Retrieve the meta data, i.e. number, types and properties
55 * for the columns of this row set.
56 * @return a corresponding SqlRowSetMetaData instance
57 * @see java.sql.ResultSet#getMetaData()
58 */
59 SqlRowSetMetaData getMetaData();
60
61 /**
62 * Map the given column label to its column index.
63 * @param columnLabel the name of the column
64 * @return the column index for the given column label
65 * @see java.sql.ResultSet#findColumn(String)
66 */
67 int findColumn(String columnLabel) throws InvalidResultSetAccessException;
68
69
70 // RowSet methods for extracting data values
71
72 /**
73 * Retrieve the value of the indicated column in the current row
74 * as a BigDecimal object.
75 * @param columnIndex the column index
76 * @return an BigDecimal object representing the column value
77 * @see java.sql.ResultSet#getBigDecimal(int)
78 */
79 BigDecimal getBigDecimal(int columnIndex) throws InvalidResultSetAccessException;
80
81 /**
82 * Retrieve the value of the indicated column in the current row
83 * as a BigDecimal object.
84 * @param columnLabel the column label
85 * @return an BigDecimal object representing the column value
86 * @see java.sql.ResultSet#getBigDecimal(String)
87 */
88 BigDecimal getBigDecimal(String columnLabel) throws InvalidResultSetAccessException;
89
90 /**
91 * Retrieve the value of the indicated column in the current row
92 * as a boolean.
93 * @param columnIndex the column index
94 * @return a boolean representing the column value
95 * @see java.sql.ResultSet#getBoolean(int)
96 */
97 boolean getBoolean(int columnIndex) throws InvalidResultSetAccessException;
98
99 /**
100 * Retrieve the value of the indicated column in the current row
101 * as a boolean.
102 * @param columnLabel the column label
103 * @return a boolean representing the column value
104 * @see java.sql.ResultSet#getBoolean(String)
105 */
106 boolean getBoolean(String columnLabel) throws InvalidResultSetAccessException;
107
108 /**
109 * Retrieve the value of the indicated column in the current row
110 * as a byte.
111 * @param columnIndex the column index
112 * @return a byte representing the column value
113 * @see java.sql.ResultSet#getByte(int)
114 */
115 byte getByte(int columnIndex) throws InvalidResultSetAccessException;
116
117 /**
118 * Retrieve the value of the indicated column in the current row
119 * as a byte.
120 * @param columnLabel the column label
121 * @return a byte representing the column value
122 * @see java.sql.ResultSet#getByte(String)
123 */
124 byte getByte(String columnLabel) throws InvalidResultSetAccessException;
125
126 /**
127 * Retrieve the value of the indicated column in the current row
128 * as a Date object.
129 * @param columnIndex the column index
130 * @return a Date object representing the column value
131 * @see java.sql.ResultSet#getDate(int)
132 */
133 Date getDate(int columnIndex) throws InvalidResultSetAccessException;
134
135 /**
136 * Retrieve the value of the indicated column in the current row
137 * as a Date object.
138 * @param columnLabel the column label
139 * @return a Date object representing the column value
140 * @see java.sql.ResultSet#getDate(String)
141 */
142 Date getDate(String columnLabel) throws InvalidResultSetAccessException;
143
144 /**
145 * Retrieve the value of the indicated column in the current row
146 * as a Date object.
147 * @param columnIndex the column index
148 * @param cal the Calendar to use in constructing the Date
149 * @return a Date object representing the column value
150 * @see java.sql.ResultSet#getDate(int, Calendar)
151 */
152 Date getDate(int columnIndex, Calendar cal) throws InvalidResultSetAccessException;
153
154 /**
155 * Retrieve the value of the indicated column in the current row
156 * as a Date object.
157 * @param columnLabel the column label
158 * @param cal the Calendar to use in constructing the Date
159 * @return a Date object representing the column value
160 * @see java.sql.ResultSet#getDate(String, Calendar)
161 */
162 Date getDate(String columnLabel, Calendar cal) throws InvalidResultSetAccessException;
163
164 /**
165 * Retrieve the value of the indicated column in the current row
166 * as a Double object.
167 * @param columnIndex the column index
168 * @return a Double object representing the column value
169 * @see java.sql.ResultSet#getDouble(int)
170 */
171 double getDouble(int columnIndex) throws InvalidResultSetAccessException;
172
173 /**
174 * Retrieve the value of the indicated column in the current row
175 * as a Double object.
176 * @param columnLabel the column label
177 * @return a Double object representing the column value
178 * @see java.sql.ResultSet#getDouble(String)
179 */
180 double getDouble(String columnLabel) throws InvalidResultSetAccessException;
181
182 /**
183 * Retrieve the value of the indicated column in the current row
184 * as a float.
185 * @param columnIndex the column index
186 * @return a float representing the column value
187 * @see java.sql.ResultSet#getFloat(int)
188 */
189 float getFloat(int columnIndex) throws InvalidResultSetAccessException;
190
191 /**
192 * Retrieve the value of the indicated column in the current row
193 * as a float.
194 * @param columnLabel the column label
195 * @return a float representing the column value
196 * @see java.sql.ResultSet#getFloat(String)
197 */
198 float getFloat(String columnLabel) throws InvalidResultSetAccessException;
199
200 /**
201 * Retrieve the value of the indicated column in the current row
202 * as an int.
203 * @param columnIndex the column index
204 * @return an int representing the column value
205 * @see java.sql.ResultSet#getInt(int)
206 */
207 int getInt(int columnIndex) throws InvalidResultSetAccessException;
208
209 /**
210 * Retrieve the value of the indicated column in the current row
211 * as an int.
212 * @param columnLabel the column label
213 * @return an int representing the column value
214 * @see java.sql.ResultSet#getInt(String)
215 */
216 int getInt(String columnLabel) throws InvalidResultSetAccessException;
217
218 /**
219 * Retrieve the value of the indicated column in the current row
220 * as a long.
221 * @param columnIndex the column index
222 * @return a long representing the column value
223 * @see java.sql.ResultSet#getLong(int)
224 */
225 long getLong(int columnIndex) throws InvalidResultSetAccessException;
226
227 /**
228 * Retrieve the value of the indicated column in the current row
229 * as a long.
230 * @param columnLabel the column label
231 * @return a long representing the column value
232 * @see java.sql.ResultSet#getLong(String)
233 */
234 long getLong(String columnLabel) throws InvalidResultSetAccessException;
235
236 /**
237 * Retrieve the value of the indicated column in the current row
238 * as a String (for NCHAR, NVARCHAR, LONGNVARCHAR columns).
239 * @param columnIndex the column index
240 * @return a String representing the column value
241 * @see java.sql.ResultSet#getNString(int)
242 * @since 4.1.3
243 */
244 String getNString(int columnIndex) throws InvalidResultSetAccessException;
245
246 /**
247 * Retrieve the value of the indicated column in the current row
248 * as a String (for NCHAR, NVARCHAR, LONGNVARCHAR columns).
249 * @param columnLabel the column label
250 * @return a String representing the column value
251 * @see java.sql.ResultSet#getNString(String)
252 * @since 4.1.3
253 */
254 String getNString(String columnLabel) throws InvalidResultSetAccessException;
255
256 /**
257 * Retrieve the value of the indicated column in the current row
258 * as an Object.
259 * @param columnIndex the column index
260 * @return a Object representing the column value
261 * @see java.sql.ResultSet#getObject(int)
262 */
263 Object getObject(int columnIndex) throws InvalidResultSetAccessException;
264
265 /**
266 * Retrieve the value of the indicated column in the current row
267 * as an Object.
268 * @param columnLabel the column label
269 * @return a Object representing the column value
270 * @see java.sql.ResultSet#getObject(String)
271 */
272 Object getObject(String columnLabel) throws InvalidResultSetAccessException;
273
274 /**
275 * Retrieve the value of the indicated column in the current row
276 * as an Object.
277 * @param columnIndex the column index
278 * @param map a Map object containing the mapping from SQL types to Java types
279 * @return a Object representing the column value
280 * @see java.sql.ResultSet#getObject(int, Map)
281 */
282 Object getObject(int columnIndex, Map<String, Class<?>> map) throws InvalidResultSetAccessException;
283
284 /**
285 * Retrieve the value of the indicated column in the current row
286 * as an Object.
287 * @param columnLabel the column label
288 * @param map a Map object containing the mapping from SQL types to Java types
289 * @return a Object representing the column value
290 * @see java.sql.ResultSet#getObject(String, Map)
291 */
292 Object getObject(String columnLabel, Map<String, Class<?>> map) throws InvalidResultSetAccessException;
293
294 /**
295 * Retrieve the value of the indicated column in the current row
296 * as an Object.
297 * @param columnIndex the column index
298 * @param type the Java type to convert the designated column to
299 * @return a Object representing the column value
300 * @see java.sql.ResultSet#getObject(int)
301 * @since 4.1.3
302 */
303 <T> T getObject(int columnIndex, Class<T> type) throws InvalidResultSetAccessException;
304
305 /**
306 * Retrieve the value of the indicated column in the current row
307 * as an Object.
308 * @param columnLabel the column label
309 * @param type the Java type to convert the designated column to
310 * @return a Object representing the column value
311 * @see java.sql.ResultSet#getObject(int)
312 * @since 4.1.3
313 */
314 <T> T getObject(String columnLabel, Class<T> type) throws InvalidResultSetAccessException;
315
316 /**
317 * Retrieve the value of the indicated column in the current row
318 * as a short.
319 * @param columnIndex the column index
320 * @return a short representing the column value
321 * @see java.sql.ResultSet#getShort(int)
322 */
323 short getShort(int columnIndex) throws InvalidResultSetAccessException;
324
325 /**
326 * Retrieve the value of the indicated column in the current row
327 * as a short.
328 * @param columnLabel the column label
329 * @return a short representing the column value
330 * @see java.sql.ResultSet#getShort(String)
331 */
332 short getShort(String columnLabel) throws InvalidResultSetAccessException;
333
334 /**
335 * Retrieve the value of the indicated column in the current row
336 * as a String.
337 * @param columnIndex the column index
338 * @return a String representing the column value
339 * @see java.sql.ResultSet#getString(int)
340 */
341 String getString(int columnIndex) throws InvalidResultSetAccessException;
342
343 /**
344 * Retrieve the value of the indicated column in the current row
345 * as a String.
346 * @param columnLabel the column label
347 * @return a String representing the column value
348 * @see java.sql.ResultSet#getString(String)
349 */
350 String getString(String columnLabel) throws InvalidResultSetAccessException;
351
352 /**
353 * Retrieve the value of the indicated column in the current row
354 * as a Time object.
355 * @param columnIndex the column index
356 * @return a Time object representing the column value
357 * @see java.sql.ResultSet#getTime(int)
358 */
359 Time getTime(int columnIndex) throws InvalidResultSetAccessException;
360
361 /**
362 * Retrieve the value of the indicated column in the current row
363 * as a Time object.
364 * @param columnLabel the column label
365 * @return a Time object representing the column value
366 * @see java.sql.ResultSet#getTime(String)
367 */
368 Time getTime(String columnLabel) throws InvalidResultSetAccessException;
369
370 /**
371 * Retrieve the value of the indicated column in the current row
372 * as a Time object.
373 * @param columnIndex the column index
374 * @param cal the Calendar to use in constructing the Date
375 * @return a Time object representing the column value
376 * @see java.sql.ResultSet#getTime(int, Calendar)
377 */
378 Time getTime(int columnIndex, Calendar cal) throws InvalidResultSetAccessException;
379
380 /**
381 * Retrieve the value of the indicated column in the current row
382 * as a Time object.
383 * @param columnLabel the column label
384 * @param cal the Calendar to use in constructing the Date
385 * @return a Time object representing the column value
386 * @see java.sql.ResultSet#getTime(String, Calendar)
387 */
388 Time getTime(String columnLabel, Calendar cal) throws InvalidResultSetAccessException;
389
390 /**
391 * Retrieve the value of the indicated column in the current row
392 * as a Timestamp object.
393 * @param columnIndex the column index
394 * @return a Timestamp object representing the column value
395 * @see java.sql.ResultSet#getTimestamp(int)
396 */
397 Timestamp getTimestamp(int columnIndex) throws InvalidResultSetAccessException;
398
399 /**
400 * Retrieve the value of the indicated column in the current row
401 * as a Timestamp object.
402 * @param columnLabel the column label
403 * @return a Timestamp object representing the column value
404 * @see java.sql.ResultSet#getTimestamp(String)
405 */
406 Timestamp getTimestamp(String columnLabel) throws InvalidResultSetAccessException;
407
408 /**
409 * Retrieve the value of the indicated column in the current row
410 * as a Timestamp object.
411 * @param columnIndex the column index
412 * @param cal the Calendar to use in constructing the Date
413 * @return a Timestamp object representing the column value
414 * @see java.sql.ResultSet#getTimestamp(int, Calendar)
415 */
416 Timestamp getTimestamp(int columnIndex, Calendar cal) throws InvalidResultSetAccessException;
417
418 /**
419 * Retrieve the value of the indicated column in the current row
420 * as a Timestamp object.
421 * @param columnLabel the column label
422 * @param cal the Calendar to use in constructing the Date
423 * @return a Timestamp object representing the column value
424 * @see java.sql.ResultSet#getTimestamp(String, Calendar)
425 */
426 Timestamp getTimestamp(String columnLabel, Calendar cal) throws InvalidResultSetAccessException;
427
428
429 // RowSet navigation methods
430
431 /**
432 * Move the cursor to the given row number in the row set,
433 * just after the last row.
434 * @param row the number of the row where the cursor should move
435 * @return {@code true} if the cursor is on the row set,
436 * {@code false} otherwise
437 * @see java.sql.ResultSet#absolute(int)
438 */
439 boolean absolute(int row) throws InvalidResultSetAccessException;
440
441 /**
442 * Move the cursor to the end of this row set.
443 * @see java.sql.ResultSet#afterLast()
444 */
445 void afterLast() throws InvalidResultSetAccessException;
446
447 /**
448 * Move the cursor to the front of this row set,
449 * just before the first row.
450 * @see java.sql.ResultSet#beforeFirst()
451 */
452 void beforeFirst() throws InvalidResultSetAccessException;
453
454 /**
455 * Move the cursor to the first row of this row set.
456 * @return {@code true} if the cursor is on a valid row,
457 * {@code false} otherwise
458 * @see java.sql.ResultSet#first()
459 */
460 boolean first() throws InvalidResultSetAccessException;
461
462 /**
463 * Retrieve the current row number.
464 * @return the current row number
465 * @see java.sql.ResultSet#getRow()
466 */
467 int getRow() throws InvalidResultSetAccessException;
468
469 /**
470 * Retrieve whether the cursor is after the last row of this row set.
471 * @return {@code true} if the cursor is after the last row,
472 * {@code false} otherwise
473 * @see java.sql.ResultSet#isAfterLast()
474 */
475 boolean isAfterLast() throws InvalidResultSetAccessException;
476
477 /**
478 * Retrieve whether the cursor is before the first row of this row set.
479 * @return {@code true} if the cursor is before the first row,
480 * {@code false} otherwise
481 * @see java.sql.ResultSet#isBeforeFirst()
482 */
483 boolean isBeforeFirst() throws InvalidResultSetAccessException;
484
485 /**
486 * Retrieve whether the cursor is on the first row of this row set.
487 * @return {@code true} if the cursor is after the first row,
488 * {@code false} otherwise
489 * @see java.sql.ResultSet#isFirst()
490 */
491 boolean isFirst() throws InvalidResultSetAccessException;
492
493 /**
494 * Retrieve whether the cursor is on the last row of this row set.
495 * @return {@code true} if the cursor is after the last row,
496 * {@code false} otherwise
497 * @see java.sql.ResultSet#isLast()
498 */
499 boolean isLast() throws InvalidResultSetAccessException;
500
501 /**
502 * Move the cursor to the last row of this row set.
503 * @return {@code true} if the cursor is on a valid row,
504 * {@code false} otherwise
505 * @see java.sql.ResultSet#last()
506 */
507 boolean last() throws InvalidResultSetAccessException;
508
509 /**
510 * Move the cursor to the next row.
511 * @return {@code true} if the new row is valid,
512 * {@code false} if there are no more rows
513 * @see java.sql.ResultSet#next()
514 */
515 boolean next() throws InvalidResultSetAccessException;
516
517 /**
518 * Move the cursor to the previous row.
519 * @return {@code true} if the new row is valid,
520 * {@code false} if it is off the row set
521 * @see java.sql.ResultSet#previous()
522 */
523 boolean previous() throws InvalidResultSetAccessException;
524
525 /**
526 * Move the cursor a relative number of rows,
527 * either positive or negative.
528 * @return {@code true} if the cursor is on a row,
529 * {@code false} otherwise
530 * @see java.sql.ResultSet#relative(int)
531 */
532 boolean relative(int rows) throws InvalidResultSetAccessException;
533
534 /**
535 * Report whether the last column read had a value of SQL {@code NULL}.
536 * <p>Note that you must first call one of the getter methods
537 * and then call the {@code wasNull()} method.
538 * @return {@code true} if the most recent coumn retrieved was
539 * SQL {@code NULL}, {@code false} otherwise
540 * @see java.sql.ResultSet#wasNull()
541 */
542 boolean wasNull() throws InvalidResultSetAccessException;
543
544 }