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