001: /*
002: * Copyright 2002-2005 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.jdbc.support.rowset;
018:
019: import java.io.Serializable;
020: import java.math.BigDecimal;
021: import java.sql.Date;
022: import java.sql.Time;
023: import java.sql.Timestamp;
024: import java.util.Calendar;
025: import java.util.Map;
026:
027: import org.springframework.jdbc.InvalidResultSetAccessException;
028:
029: /**
030: * Mirror interface for <code>javax.sql.RowSet</code>, representing
031: * disconnected <code>java.sql.ResultSet</code> data.
032: *
033: * <p>The main difference to the standard JDBC RowSet is that an SQLException
034: * is never thrown here. This allows a SqlRowSet to be used without having
035: * to deal with checked exceptions. A SqlRowSet will throw Spring's
036: * <code>org.springframework.jdbc.InvalidResultSetAccessException</code>
037: * instead (when appropriate).
038: *
039: * <p>Note: This interface extends the <code>java.io.Serializable</code>
040: * marker interface. Implementations, which typically hold disconnected data,
041: * are encouraged to be actually serializable (as far as possible).
042: *
043: * @author Thomas Risberg
044: * @author Juergen Hoeller
045: * @since 1.2
046: * @see javax.sql.RowSet
047: * @see java.sql.ResultSet
048: * @see org.springframework.jdbc.InvalidResultSetAccessException
049: * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet
050: */
051: public interface SqlRowSet extends Serializable {
052:
053: /**
054: * Retrieves the meta data (number, types and properties for the columns)
055: * of this row set.
056: * @return a corresponding SqlRowSetMetaData instance
057: * @see java.sql.ResultSet#getMetaData()
058: */
059: SqlRowSetMetaData getMetaData();
060:
061: /**
062: * Maps the given column name to its column index.
063: * @param columnName the name of the column
064: * @return the column index for the given column name
065: * @see java.sql.ResultSet#findColumn(String)
066: */
067: int findColumn(String columnName)
068: throws InvalidResultSetAccessException;
069:
070: // RowSet methods for extracting data values
071:
072: /**
073: * Retrieves the value of the indicated column in the current row as
074: * an BigDecimal object.
075: * @param columnIndex the column index
076: * @return an BigDecimal object representing the column value
077: * @see java.sql.ResultSet#getBigDecimal(int)
078: */
079: BigDecimal getBigDecimal(int columnIndex)
080: throws InvalidResultSetAccessException;
081:
082: /**
083: * Retrieves the value of the indicated column in the current row as
084: * an BigDecimal object.
085: * @param columnName the column name
086: * @return an BigDecimal object representing the column value
087: * @see java.sql.ResultSet#getBigDecimal(java.lang.String)
088: */
089: BigDecimal getBigDecimal(String columnName)
090: throws InvalidResultSetAccessException;
091:
092: /**
093: * Retrieves the value of the indicated column in the current row as
094: * a boolean.
095: * @param columnIndex the column index
096: * @return a boolean representing the column value
097: * @see java.sql.ResultSet#getBoolean(int)
098: */
099: boolean getBoolean(int columnIndex)
100: throws InvalidResultSetAccessException;
101:
102: /**
103: * Retrieves the value of the indicated column in the current row as
104: * a boolean.
105: * @param columnName the column name
106: * @return a boolean representing the column value
107: * @see java.sql.ResultSet#getBoolean(java.lang.String)
108: */
109: boolean getBoolean(String columnName)
110: throws InvalidResultSetAccessException;
111:
112: /**
113: * Retrieves the value of the indicated column in the current row as
114: * a byte.
115: * @param columnIndex the column index
116: * @return a byte representing the column value
117: * @see java.sql.ResultSet#getByte(int)
118: */
119: byte getByte(int columnIndex)
120: throws InvalidResultSetAccessException;
121:
122: /**
123: * Retrieves the value of the indicated column in the current row as
124: * a byte.
125: * @param columnName the column name
126: * @return a byte representing the column value
127: * @see java.sql.ResultSet#getByte(java.lang.String)
128: */
129: byte getByte(String columnName)
130: throws InvalidResultSetAccessException;
131:
132: /**
133: * Retrieves the value of the indicated column in the current row as
134: * a Date object.
135: * @param columnIndex the column index
136: * @param cal the Calendar to use in constructing the Date
137: * @return a Date object representing the column value
138: * @see java.sql.ResultSet#getDate(int, java.util.Calendar)
139: */
140: Date getDate(int columnIndex, Calendar cal)
141: throws InvalidResultSetAccessException;
142:
143: /**
144: * Retrieves the value of the indicated column in the current row as
145: * a Date object.
146: * @param columnIndex the column index
147: * @return a Date object representing the column value
148: * @see java.sql.ResultSet#getDate(int)
149: */
150: Date getDate(int columnIndex)
151: throws InvalidResultSetAccessException;
152:
153: /**
154: * Retrieves the value of the indicated column in the current row as
155: * a Date object.
156: * @param columnName the column name
157: * @param cal the Calendar to use in constructing the Date
158: * @return a Date object representing the column value
159: * @see java.sql.ResultSet#getDate(java.lang.String, java.util.Calendar)
160: */
161: Date getDate(String columnName, Calendar cal)
162: throws InvalidResultSetAccessException;
163:
164: /**
165: * Retrieves the value of the indicated column in the current row as
166: * a Date object.
167: * @param columnName the column name
168: * @return a Date object representing the column value
169: * @see java.sql.ResultSet#getDate(java.lang.String)
170: */
171: Date getDate(String columnName)
172: throws InvalidResultSetAccessException;
173:
174: /**
175: * Retrieves the value of the indicated column in the current row as
176: * a Double object.
177: * @param columnIndex the column index
178: * @return a Double object representing the column value
179: * @see java.sql.ResultSet#getDouble(int)
180: */
181: double getDouble(int columnIndex)
182: throws InvalidResultSetAccessException;
183:
184: /**
185: * Retrieves the value of the indicated column in the current row as
186: * a Double object.
187: * @param columnName the column name
188: * @return a Double object representing the column value
189: * @see java.sql.ResultSet#getDouble(java.lang.String)
190: */
191: double getDouble(String columnName)
192: throws InvalidResultSetAccessException;
193:
194: /**
195: * Retrieves the value of the indicated column in the current row as
196: * a float.
197: * @param columnIndex the column index
198: * @return a float representing the column value
199: * @see java.sql.ResultSet#getFloat(int)
200: */
201: float getFloat(int columnIndex)
202: throws InvalidResultSetAccessException;
203:
204: /**
205: * Retrieves the value of the indicated column in the current row as
206: * a float.
207: * @param columnName the column name
208: * @return a float representing the column value
209: * @see java.sql.ResultSet#getFloat(java.lang.String)
210: */
211: float getFloat(String columnName)
212: throws InvalidResultSetAccessException;
213:
214: /**
215: * Retrieves the value of the indicated column in the current row as
216: * an int.
217: * @param columnIndex the column index
218: * @return an int representing the column value
219: * @see java.sql.ResultSet#getInt(int)
220: */
221: int getInt(int columnIndex) throws InvalidResultSetAccessException;
222:
223: /**
224: * Retrieves the value of the indicated column in the current row as
225: * an int.
226: * @param columnName the column name
227: * @return an int representing the column value
228: * @see java.sql.ResultSet#getInt(java.lang.String)
229: */
230: int getInt(String columnName)
231: throws InvalidResultSetAccessException;
232:
233: /**
234: * Retrieves the value of the indicated column in the current row as
235: * a long.
236: * @param columnIndex the column index
237: * @return a long representing the column value
238: * @see java.sql.ResultSet#getLong(int)
239: */
240: long getLong(int columnIndex)
241: throws InvalidResultSetAccessException;
242:
243: /**
244: * Retrieves the value of the indicated column in the current row as
245: * a long.
246: * @param columnName the column name
247: * @return a long representing the column value
248: * @see java.sql.ResultSet#getLong(java.lang.String)
249: */
250: long getLong(String columnName)
251: throws InvalidResultSetAccessException;
252:
253: /**
254: * Retrieves the value of the indicated column in the current row as
255: * an Object.
256: * @param columnIndex the column index
257: * @param map a Map object containing the mapping from SQL types to Java types
258: * @return a Object representing the column value
259: * @see java.sql.ResultSet#getObject(int, java.util.Map)
260: */
261: Object getObject(int columnIndex, Map map)
262: throws InvalidResultSetAccessException;
263:
264: /**
265: * Retrieves the value of the indicated column in the current row as
266: * an Object.
267: * @param columnIndex the column index
268: * @return a Object representing the column value
269: * @see java.sql.ResultSet#getObject(int)
270: */
271: Object getObject(int columnIndex)
272: throws InvalidResultSetAccessException;
273:
274: /**
275: * Retrieves the value of the indicated column in the current row as
276: * an Object.
277: * @param columnName the column name
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(java.lang.String, java.util.Map)
281: */
282: Object getObject(String columnName, Map map)
283: throws InvalidResultSetAccessException;
284:
285: /**
286: * Retrieves the value of the indicated column in the current row as
287: * an Object.
288: * @param columnName the column name
289: * @return a Object representing the column value
290: * @see java.sql.ResultSet#getObject(java.lang.String)
291: */
292: Object getObject(String columnName)
293: throws InvalidResultSetAccessException;
294:
295: /**
296: * Retrieves the value of the indicated column in the current row as
297: * a short.
298: * @param columnIndex the column index
299: * @return a short representing the column value
300: * @see java.sql.ResultSet#getShort(int)
301: */
302: short getShort(int columnIndex)
303: throws InvalidResultSetAccessException;
304:
305: /**
306: * Retrieves the value of the indicated column in the current row as
307: * a short.
308: * @param columnName the column name
309: * @return a short representing the column value
310: * @see java.sql.ResultSet#getShort(java.lang.String)
311: */
312: short getShort(String columnName)
313: throws InvalidResultSetAccessException;
314:
315: /**
316: * Retrieves the value of the indicated column in the current row as
317: * a String.
318: * @param columnIndex the column index
319: * @return a String representing the column value
320: * @see java.sql.ResultSet#getString(int)
321: */
322: String getString(int columnIndex)
323: throws InvalidResultSetAccessException;
324:
325: /**
326: * Retrieves the value of the indicated column in the current row as
327: * a String.
328: * @param columnName the column name
329: * @return a String representing the column value
330: * @see java.sql.ResultSet#getString(java.lang.String)
331: */
332: String getString(String columnName)
333: throws InvalidResultSetAccessException;
334:
335: /**
336: * Retrieves the value of the indicated column in the current row as
337: * a Time object.
338: * @param columnIndex the column index
339: * @param cal the Calendar to use in constructing the Date
340: * @return a Time object representing the column value
341: * @see java.sql.ResultSet#getTime(int, java.util.Calendar)
342: */
343: Time getTime(int columnIndex, Calendar cal)
344: throws InvalidResultSetAccessException;
345:
346: /**
347: * Retrieves the value of the indicated column in the current row as
348: * a Time object.
349: * @param columnIndex the column index
350: * @return a Time object representing the column value
351: * @see java.sql.ResultSet#getTime(int)
352: */
353: Time getTime(int columnIndex)
354: throws InvalidResultSetAccessException;
355:
356: /**
357: * Retrieves the value of the indicated column in the current row as
358: * a Time object.
359: * @param columnName the column name
360: * @param cal the Calendar to use in constructing the Date
361: * @return a Time object representing the column value
362: * @see java.sql.ResultSet#getTime(java.lang.String, java.util.Calendar)
363: */
364: Time getTime(String columnName, Calendar cal)
365: throws InvalidResultSetAccessException;
366:
367: /**
368: * Retrieves the value of the indicated column in the current row as
369: * a Time object.
370: * @param columnName the column name
371: * @return a Time object representing the column value
372: * @see java.sql.ResultSet#getTime(java.lang.String)
373: */
374: Time getTime(String columnName)
375: throws InvalidResultSetAccessException;
376:
377: /**
378: * Retrieves the value of the indicated column in the current row as
379: * a Timestamp object.
380: * @param columnIndex the column index
381: * @param cal the Calendar to use in constructing the Date
382: * @return a Timestamp object representing the column value
383: * @see java.sql.ResultSet#getTimestamp(int, java.util.Calendar)
384: */
385: Timestamp getTimestamp(int columnIndex, Calendar cal)
386: throws InvalidResultSetAccessException;
387:
388: /**
389: * Retrieves the value of the indicated column in the current row as
390: * a Timestamp object.
391: * @param columnIndex the column index
392: * @return a Timestamp object representing the column value
393: * @see java.sql.ResultSet#getTimestamp(int)
394: */
395: Timestamp getTimestamp(int columnIndex)
396: throws InvalidResultSetAccessException;
397:
398: /**
399: * Retrieves the value of the indicated column in the current row as
400: * a Timestamp object.
401: * @param columnName the column name
402: * @param cal the Calendar to use in constructing the Date
403: * @return a Timestamp object representing the column value
404: * @see java.sql.ResultSet#getTimestamp(java.lang.String, java.util.Calendar)
405: */
406: Timestamp getTimestamp(String columnName, Calendar cal)
407: throws InvalidResultSetAccessException;
408:
409: /**
410: * Retrieves the value of the indicated column in the current row as
411: * a Timestamp object.
412: * @param columnName the column name
413: * @return a Timestamp object representing the column value
414: * @see java.sql.ResultSet#getTimestamp(java.lang.String)
415: */
416: Timestamp getTimestamp(String columnName)
417: throws InvalidResultSetAccessException;
418:
419: // RowSet navigation methods
420:
421: /**
422: * Moves the cursor to the given row number in the RowSet, just after the last row.
423: * @param row the number of the row where the cursor should move
424: * @return true if the cursor is on the RowSet, false otherwise
425: * @see java.sql.ResultSet#absolute(int)
426: */
427: boolean absolute(int row) throws InvalidResultSetAccessException;
428:
429: /**
430: * Moves the cursor to the end of this RowSet.
431: * @see java.sql.ResultSet#afterLast()
432: */
433: void afterLast() throws InvalidResultSetAccessException;
434:
435: /**
436: * Moves the cursor to the front of this RowSet, just before the first row.
437: * @see java.sql.ResultSet#beforeFirst()
438: */
439: void beforeFirst() throws InvalidResultSetAccessException;
440:
441: /**
442: * Moves the cursor to the first row of this RowSet.
443: * @return true if the cursor is on a valid row, false otherwise
444: * @see java.sql.ResultSet#first()
445: */
446: boolean first() throws InvalidResultSetAccessException;
447:
448: /**
449: * Retrieves the current row number.
450: * @return the current row number
451: * @see java.sql.ResultSet#getRow()
452: */
453: int getRow() throws InvalidResultSetAccessException;
454:
455: /**
456: * Retrieves whether the cursor is after the last row of this RowSet.
457: * @return true if the cursor is after the last row, false otherwise
458: * @see java.sql.ResultSet#isAfterLast()
459: */
460: boolean isAfterLast() throws InvalidResultSetAccessException;
461:
462: /**
463: * Retrieves whether the cursor is after the first row of this RowSet.
464: * @return true if the cursor is after the first row, false otherwise
465: * @see java.sql.ResultSet#isBeforeFirst()
466: */
467: boolean isBeforeFirst() throws InvalidResultSetAccessException;
468:
469: /**
470: * Retrieves whether the cursor is on the first row of this RowSet.
471: * @return true if the cursor is after the first row, false otherwise
472: * @see java.sql.ResultSet#isFirst()
473: */
474: boolean isFirst() throws InvalidResultSetAccessException;
475:
476: /**
477: * Retrieves whether the cursor is on the last row of this RowSet.
478: * @return true if the cursor is after the last row, false otherwise
479: * @see java.sql.ResultSet#isLast()
480: */
481: boolean isLast() throws InvalidResultSetAccessException;
482:
483: /**
484: * Moves the cursor to the last row of this RowSet.
485: * @return true if the cursor is on a valid row, false otherwise
486: * @see java.sql.ResultSet#last()
487: */
488: boolean last() throws InvalidResultSetAccessException;
489:
490: /**
491: * Moves the cursor to the next row.
492: * @return true if the new row is valid, false if there are no more rows
493: * @see java.sql.ResultSet#next()
494: */
495: boolean next() throws InvalidResultSetAccessException;
496:
497: /**
498: * Moves the cursor to the previous row.
499: * @return true if the new row is valid, false if it is off the RowSet
500: * @see java.sql.ResultSet#previous()
501: */
502: boolean previous() throws InvalidResultSetAccessException;
503:
504: /**
505: * Moves the cursor a relative number f rows, either positive or negative.
506: * @return true if the cursor is on a row, false otherwise
507: * @see java.sql.ResultSet#relative(int)
508: */
509: boolean relative(int rows) throws InvalidResultSetAccessException;
510:
511: /**
512: * Reports whether the last column read had a value of SQL <code>NULL</code>.
513: * Note that you must first call one of the getter methods and then call
514: * the <code>wasNull</code> method.
515: * @return true if the most recent coumn retrieved was SQL <code>NULL</code>,
516: * false otherwise
517: * @see java.sql.ResultSet#wasNull()
518: */
519: boolean wasNull() throws InvalidResultSetAccessException;
520:
521: }
|