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