1. /*
  2. * @(#)ResultSet.java 1.49 04/06/28
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.sql;
  8. import java.math.BigDecimal;
  9. import java.util.Calendar;
  10. /**
  11. * A table of data representing a database result set, which
  12. * is usually generated by executing a statement that queries the database.
  13. *
  14. * <P>A <code>ResultSet</code> object maintains a cursor pointing
  15. * to its current row of data. Initially the cursor is positioned
  16. * before the first row. The <code>next</code> method moves the
  17. * cursor to the next row, and because it returns <code>false</code>
  18. * when there are no more rows in the <code>ResultSet</code> object,
  19. * it can be used in a <code>while</code> loop to iterate through
  20. * the result set.
  21. * <P>
  22. * A default <code>ResultSet</code> object is not updatable and
  23. * has a cursor that moves forward only. Thus, you can
  24. * iterate through it only once and only from the first row to the
  25. * last row. It is possible to
  26. * produce <code>ResultSet</code> objects that are scrollable and/or
  27. * updatable. The following code fragment, in which <code>con</code>
  28. * is a valid <code>Connection</code> object, illustrates how to make
  29. * a result set that is scrollable and insensitive to updates by others, and
  30. * that is updatable. See <code>ResultSet</code> fields for other
  31. * options.
  32. * <PRE>
  33. *
  34. * Statement stmt = con.createStatement(
  35. * ResultSet.TYPE_SCROLL_INSENSITIVE,
  36. * ResultSet.CONCUR_UPDATABLE);
  37. * ResultSet rs = stmt.executeQuery("SELECT a, b FROM TABLE2");
  38. * // rs will be scrollable, will not show changes made by others,
  39. * // and will be updatable
  40. *
  41. * </PRE>
  42. * The <code>ResultSet</code> interface provides
  43. * <i>getter</i> methods (<code>getBoolean</code>, <code>getLong</code>, and so on)
  44. * for retrieving column values from the current row.
  45. * Values can be retrieved using either the index number of the
  46. * column or the name of the column. In general, using the
  47. * column index will be more efficient. Columns are numbered from 1.
  48. * For maximum portability, result set columns within each row should be
  49. * read in left-to-right order, and each column should be read only once.
  50. *
  51. * <P>For the getter methods, a JDBC driver attempts
  52. * to convert the underlying data to the Java type specified in the
  53. * getter method and returns a suitable Java value. The JDBC specification
  54. * has a table showing the allowable mappings from SQL types to Java types
  55. * that can be used by the <code>ResultSet</code> getter methods.
  56. * <P>
  57. * <P>Column names used as input to getter methods are case
  58. * insensitive. When a getter method is called with
  59. * a column name and several columns have the same name,
  60. * the value of the first matching column will be returned.
  61. * The column name option is
  62. * designed to be used when column names are used in the SQL
  63. * query that generated the result set.
  64. * For columns that are NOT explicitly named in the query, it
  65. * is best to use column numbers. If column names are used, there is
  66. * no way for the programmer to guarantee that they actually refer to
  67. * the intended columns.
  68. * <P>
  69. * A set of updater methods were added to this interface
  70. * in the JDBC 2.0 API (JDK 1.2).
  71. * The comments regarding parameters
  72. * to the getter methods also apply to parameters to the
  73. * updater methods.
  74. *<P>
  75. * The updater methods may be used in two ways:
  76. * <ol>
  77. * <LI>to update a column value in the current row. In a scrollable
  78. * <code>ResultSet</code> object, the cursor can be moved backwards
  79. * and forwards, to an absolute position, or to a position
  80. * relative to the current row.
  81. * The following code fragment updates the <code>NAME</code> column
  82. * in the fifth row of the <code>ResultSet</code> object
  83. * <code>rs</code> and then uses the method <code>updateRow</code>
  84. * to update the data source table from which <code>rs</code> was derived.
  85. * <PRE>
  86. *
  87. * rs.absolute(5); // moves the cursor to the fifth row of rs
  88. * rs.updateString("NAME", "AINSWORTH"); // updates the
  89. * // <code>NAME</code> column of row 5 to be <code>AINSWORTH</code>
  90. * rs.updateRow(); // updates the row in the data source
  91. *
  92. * </PRE>
  93. * <LI>to insert column values into the insert row. An updatable
  94. * <code>ResultSet</code> object has a special row associated with
  95. * it that serves as a staging area for building a row to be inserted.
  96. * The following code fragment moves the cursor to the insert row, builds
  97. * a three-column row, and inserts it into <code>rs</code> and into
  98. * the data source table using the method <code>insertRow</code>.
  99. * <PRE>
  100. *
  101. * rs.moveToInsertRow(); // moves cursor to the insert row
  102. * rs.updateString(1, "AINSWORTH"); // updates the
  103. * // first column of the insert row to be <code>AINSWORTH</code>
  104. * rs.updateInt(2,35); // updates the second column to be <code>35</code>
  105. * rs.updateBoolean(3, true); // updates the third column to <code>true</code>
  106. * rs.insertRow();
  107. * rs.moveToCurrentRow();
  108. *
  109. * </PRE>
  110. * </ol>
  111. * <P>A <code>ResultSet</code> object is automatically closed when the
  112. * <code>Statement</code> object that
  113. * generated it is closed, re-executed, or used
  114. * to retrieve the next result from a sequence of multiple results.
  115. *
  116. * <P>The number, types and properties of a <code>ResultSet</code>
  117. * object's columns are provided by the <code>ResulSetMetaData</code>
  118. * object returned by the <code>ResultSet.getMetaData</code> method.
  119. *
  120. * @see Statement#executeQuery
  121. * @see Statement#getResultSet
  122. * @see ResultSetMetaData
  123. */
  124. public interface ResultSet {
  125. /**
  126. * Moves the cursor down one row from its current position.
  127. * A <code>ResultSet</code> cursor is initially positioned
  128. * before the first row; the first call to the method
  129. * <code>next</code> makes the first row the current row; the
  130. * second call makes the second row the current row, and so on.
  131. *
  132. * <P>If an input stream is open for the current row, a call
  133. * to the method <code>next</code> will
  134. * implicitly close it. A <code>ResultSet</code> object's
  135. * warning chain is cleared when a new row is read.
  136. *
  137. * @return <code>true</code> if the new current row is valid;
  138. * <code>false</code> if there are no more rows
  139. * @exception SQLException if a database access error occurs
  140. */
  141. boolean next() throws SQLException;
  142. /**
  143. * Releases this <code>ResultSet</code> object's database and
  144. * JDBC resources immediately instead of waiting for
  145. * this to happen when it is automatically closed.
  146. *
  147. * <P><B>Note:</B> A <code>ResultSet</code> object
  148. * is automatically closed by the
  149. * <code>Statement</code> object that generated it when
  150. * that <code>Statement</code> object is closed,
  151. * re-executed, or is used to retrieve the next result from a
  152. * sequence of multiple results. A <code>ResultSet</code> object
  153. * is also automatically closed when it is garbage collected.
  154. *
  155. * @exception SQLException if a database access error occurs
  156. */
  157. void close() throws SQLException;
  158. /**
  159. * Reports whether
  160. * the last column read had a value of SQL <code>NULL</code>.
  161. * Note that you must first call one of the getter methods
  162. * on a column to try to read its value and then call
  163. * the method <code>wasNull</code> to see if the value read was
  164. * SQL <code>NULL</code>.
  165. *
  166. * @return <code>true</code> if the last column value read was SQL
  167. * <code>NULL</code> and <code>false</code> otherwise
  168. * @exception SQLException if a database access error occurs
  169. */
  170. boolean wasNull() throws SQLException;
  171. //======================================================================
  172. // Methods for accessing results by column index
  173. //======================================================================
  174. /**
  175. * Retrieves the value of the designated column in the current row
  176. * of this <code>ResultSet</code> object as
  177. * a <code>String</code> in the Java programming language.
  178. *
  179. * @param columnIndex the first column is 1, the second is 2, ...
  180. * @return the column value; if the value is SQL <code>NULL</code>, the
  181. * value returned is <code>null</code>
  182. * @exception SQLException if a database access error occurs
  183. */
  184. String getString(int columnIndex) throws SQLException;
  185. /**
  186. * Retrieves the value of the designated column in the current row
  187. * of this <code>ResultSet</code> object as
  188. * a <code>boolean</code> in the Java programming language.
  189. *
  190. * @param columnIndex the first column is 1, the second is 2, ...
  191. * @return the column value; if the value is SQL <code>NULL</code>, the
  192. * value returned is <code>false</code>
  193. * @exception SQLException if a database access error occurs
  194. */
  195. boolean getBoolean(int columnIndex) throws SQLException;
  196. /**
  197. * Retrieves the value of the designated column in the current row
  198. * of this <code>ResultSet</code> object as
  199. * a <code>byte</code> in the Java programming language.
  200. *
  201. * @param columnIndex the first column is 1, the second is 2, ...
  202. * @return the column value; if the value is SQL <code>NULL</code>, the
  203. * value returned is <code>0</code>
  204. * @exception SQLException if a database access error occurs
  205. */
  206. byte getByte(int columnIndex) throws SQLException;
  207. /**
  208. * Retrieves the value of the designated column in the current row
  209. * of this <code>ResultSet</code> object as
  210. * a <code>short</code> in the Java programming language.
  211. *
  212. * @param columnIndex the first column is 1, the second is 2, ...
  213. * @return the column value; if the value is SQL <code>NULL</code>, the
  214. * value returned is <code>0</code>
  215. * @exception SQLException if a database access error occurs
  216. */
  217. short getShort(int columnIndex) throws SQLException;
  218. /**
  219. * Retrieves the value of the designated column in the current row
  220. * of this <code>ResultSet</code> object as
  221. * an <code>int</code> in the Java programming language.
  222. *
  223. * @param columnIndex the first column is 1, the second is 2, ...
  224. * @return the column value; if the value is SQL <code>NULL</code>, the
  225. * value returned is <code>0</code>
  226. * @exception SQLException if a database access error occurs
  227. */
  228. int getInt(int columnIndex) throws SQLException;
  229. /**
  230. * Retrieves the value of the designated column in the current row
  231. * of this <code>ResultSet</code> object as
  232. * a <code>long</code> in the Java programming language.
  233. *
  234. * @param columnIndex the first column is 1, the second is 2, ...
  235. * @return the column value; if the value is SQL <code>NULL</code>, the
  236. * value returned is <code>0</code>
  237. * @exception SQLException if a database access error occurs
  238. */
  239. long getLong(int columnIndex) throws SQLException;
  240. /**
  241. * Retrieves the value of the designated column in the current row
  242. * of this <code>ResultSet</code> object as
  243. * a <code>float</code> in the Java programming language.
  244. *
  245. * @param columnIndex the first column is 1, the second is 2, ...
  246. * @return the column value; if the value is SQL <code>NULL</code>, the
  247. * value returned is <code>0</code>
  248. * @exception SQLException if a database access error occurs
  249. */
  250. float getFloat(int columnIndex) throws SQLException;
  251. /**
  252. * Retrieves the value of the designated column in the current row
  253. * of this <code>ResultSet</code> object as
  254. * a <code>double</code> in the Java programming language.
  255. *
  256. * @param columnIndex the first column is 1, the second is 2, ...
  257. * @return the column value; if the value is SQL <code>NULL</code>, the
  258. * value returned is <code>0</code>
  259. * @exception SQLException if a database access error occurs
  260. */
  261. double getDouble(int columnIndex) throws SQLException;
  262. /**
  263. * Retrieves the value of the designated column in the current row
  264. * of this <code>ResultSet</code> object as
  265. * a <code>java.sql.BigDecimal</code> in the Java programming language.
  266. *
  267. * @param columnIndex the first column is 1, the second is 2, ...
  268. * @param scale the number of digits to the right of the decimal point
  269. * @return the column value; if the value is SQL <code>NULL</code>, the
  270. * value returned is <code>null</code>
  271. * @exception SQLException if a database access error occurs
  272. * @deprecated
  273. */
  274. @Deprecated
  275. BigDecimal getBigDecimal(int columnIndex, int scale) throws SQLException;
  276. /**
  277. * Retrieves the value of the designated column in the current row
  278. * of this <code>ResultSet</code> object as
  279. * a <code>byte</code> array in the Java programming language.
  280. * The bytes represent the raw values returned by the driver.
  281. *
  282. * @param columnIndex the first column is 1, the second is 2, ...
  283. * @return the column value; if the value is SQL <code>NULL</code>, the
  284. * value returned is <code>null</code>
  285. * @exception SQLException if a database access error occurs
  286. */
  287. byte[] getBytes(int columnIndex) throws SQLException;
  288. /**
  289. * Retrieves the value of the designated column in the current row
  290. * of this <code>ResultSet</code> object as
  291. * a <code>java.sql.Date</code> object in the Java programming language.
  292. *
  293. * @param columnIndex the first column is 1, the second is 2, ...
  294. * @return the column value; if the value is SQL <code>NULL</code>, the
  295. * value returned is <code>null</code>
  296. * @exception SQLException if a database access error occurs
  297. */
  298. java.sql.Date getDate(int columnIndex) throws SQLException;
  299. /**
  300. * Retrieves the value of the designated column in the current row
  301. * of this <code>ResultSet</code> object as
  302. * a <code>java.sql.Time</code> object in the Java programming language.
  303. *
  304. * @param columnIndex the first column is 1, the second is 2, ...
  305. * @return the column value; if the value is SQL <code>NULL</code>, the
  306. * value returned is <code>null</code>
  307. * @exception SQLException if a database access error occurs
  308. */
  309. java.sql.Time getTime(int columnIndex) throws SQLException;
  310. /**
  311. * Retrieves the value of the designated column in the current row
  312. * of this <code>ResultSet</code> object as
  313. * a <code>java.sql.Timestamp</code> object in the Java programming language.
  314. *
  315. * @param columnIndex the first column is 1, the second is 2, ...
  316. * @return the column value; if the value is SQL <code>NULL</code>, the
  317. * value returned is <code>null</code>
  318. * @exception SQLException if a database access error occurs
  319. */
  320. java.sql.Timestamp getTimestamp(int columnIndex) throws SQLException;
  321. /**
  322. * Retrieves the value of the designated column in the current row
  323. * of this <code>ResultSet</code> object as
  324. * a stream of ASCII characters. The value can then be read in chunks from the
  325. * stream. This method is particularly
  326. * suitable for retrieving large <char>LONGVARCHAR</char> values.
  327. * The JDBC driver will
  328. * do any necessary conversion from the database format into ASCII.
  329. *
  330. * <P><B>Note:</B> All the data in the returned stream must be
  331. * read prior to getting the value of any other column. The next
  332. * call to a getter method implicitly closes the stream. Also, a
  333. * stream may return <code>0</code> when the method
  334. * <code>InputStream.available</code>
  335. * is called whether there is data available or not.
  336. *
  337. * @param columnIndex the first column is 1, the second is 2, ...
  338. * @return a Java input stream that delivers the database column value
  339. * as a stream of one-byte ASCII characters;
  340. * if the value is SQL <code>NULL</code>, the
  341. * value returned is <code>null</code>
  342. * @exception SQLException if a database access error occurs
  343. */
  344. java.io.InputStream getAsciiStream(int columnIndex) throws SQLException;
  345. /**
  346. * Retrieves the value of the designated column in the current row
  347. * of this <code>ResultSet</code> object as
  348. * as a stream of two-byte Unicode characters. The first byte is
  349. * the high byte; the second byte is the low byte.
  350. *
  351. * The value can then be read in chunks from the
  352. * stream. This method is particularly
  353. * suitable for retrieving large <code>LONGVARCHAR</code>values. The
  354. * JDBC driver will do any necessary conversion from the database
  355. * format into Unicode.
  356. *
  357. * <P><B>Note:</B> All the data in the returned stream must be
  358. * read prior to getting the value of any other column. The next
  359. * call to a getter method implicitly closes the stream.
  360. * Also, a stream may return <code>0</code> when the method
  361. * <code>InputStream.available</code>
  362. * is called, whether there is data available or not.
  363. *
  364. * @param columnIndex the first column is 1, the second is 2, ...
  365. * @return a Java input stream that delivers the database column value
  366. * as a stream of two-byte Unicode characters;
  367. * if the value is SQL <code>NULL</code>, the value returned is
  368. * <code>null</code>
  369. *
  370. * @exception SQLException if a database access error occurs
  371. * @deprecated use <code>getCharacterStream</code> in place of
  372. * <code>getUnicodeStream</code>
  373. */
  374. @Deprecated
  375. java.io.InputStream getUnicodeStream(int columnIndex) throws SQLException;
  376. /**
  377. * Retrieves the value of the designated column in the current row
  378. * of this <code>ResultSet</code> object as a binary stream of
  379. * uninterpreted bytes. The value can then be read in chunks from the
  380. * stream. This method is particularly
  381. * suitable for retrieving large <code>LONGVARBINARY</code> values.
  382. *
  383. * <P><B>Note:</B> All the data in the returned stream must be
  384. * read prior to getting the value of any other column. The next
  385. * call to a getter method implicitly closes the stream. Also, a
  386. * stream may return <code>0</code> when the method
  387. * <code>InputStream.available</code>
  388. * is called whether there is data available or not.
  389. *
  390. * @param columnIndex the first column is 1, the second is 2, ...
  391. * @return a Java input stream that delivers the database column value
  392. * as a stream of uninterpreted bytes;
  393. * if the value is SQL <code>NULL</code>, the value returned is
  394. * <code>null</code>
  395. * @exception SQLException if a database access error occurs
  396. */
  397. java.io.InputStream getBinaryStream(int columnIndex)
  398. throws SQLException;
  399. //======================================================================
  400. // Methods for accessing results by column name
  401. //======================================================================
  402. /**
  403. * Retrieves the value of the designated column in the current row
  404. * of this <code>ResultSet</code> object as
  405. * a <code>String</code> in the Java programming language.
  406. *
  407. * @param columnName the SQL name of the column
  408. * @return the column value; if the value is SQL <code>NULL</code>, the
  409. * value returned is <code>null</code>
  410. * @exception SQLException if a database access error occurs
  411. */
  412. String getString(String columnName) throws SQLException;
  413. /**
  414. * Retrieves the value of the designated column in the current row
  415. * of this <code>ResultSet</code> object as
  416. * a <code>boolean</code> in the Java programming language.
  417. *
  418. * @param columnName the SQL name of the column
  419. * @return the column value; if the value is SQL <code>NULL</code>, the
  420. * value returned is <code>false</code>
  421. * @exception SQLException if a database access error occurs
  422. */
  423. boolean getBoolean(String columnName) throws SQLException;
  424. /**
  425. * Retrieves the value of the designated column in the current row
  426. * of this <code>ResultSet</code> object as
  427. * a <code>byte</code> in the Java programming language.
  428. *
  429. * @param columnName the SQL name of the column
  430. * @return the column value; if the value is SQL <code>NULL</code>, the
  431. * value returned is <code>0</code>
  432. * @exception SQLException if a database access error occurs
  433. */
  434. byte getByte(String columnName) throws SQLException;
  435. /**
  436. * Retrieves the value of the designated column in the current row
  437. * of this <code>ResultSet</code> object as
  438. * a <code>short</code> in the Java programming language.
  439. *
  440. * @param columnName the SQL name of the column
  441. * @return the column value; if the value is SQL <code>NULL</code>, the
  442. * value returned is <code>0</code>
  443. * @exception SQLException if a database access error occurs
  444. */
  445. short getShort(String columnName) throws SQLException;
  446. /**
  447. * Retrieves the value of the designated column in the current row
  448. * of this <code>ResultSet</code> object as
  449. * an <code>int</code> in the Java programming language.
  450. *
  451. * @param columnName the SQL name of the column
  452. * @return the column value; if the value is SQL <code>NULL</code>, the
  453. * value returned is <code>0</code>
  454. * @exception SQLException if a database access error occurs
  455. */
  456. int getInt(String columnName) throws SQLException;
  457. /**
  458. * Retrieves the value of the designated column in the current row
  459. * of this <code>ResultSet</code> object as
  460. * a <code>long</code> in the Java programming language.
  461. *
  462. * @param columnName the SQL name of the column
  463. * @return the column value; if the value is SQL <code>NULL</code>, the
  464. * value returned is <code>0</code>
  465. * @exception SQLException if a database access error occurs
  466. */
  467. long getLong(String columnName) throws SQLException;
  468. /**
  469. * Retrieves the value of the designated column in the current row
  470. * of this <code>ResultSet</code> object as
  471. * a <code>float</code> in the Java programming language.
  472. *
  473. * @param columnName the SQL name of the column
  474. * @return the column value; if the value is SQL <code>NULL</code>, the
  475. * value returned is <code>0</code>
  476. * @exception SQLException if a database access error occurs
  477. */
  478. float getFloat(String columnName) throws SQLException;
  479. /**
  480. * Retrieves the value of the designated column in the current row
  481. * of this <code>ResultSet</code> object as
  482. * a <code>double</code> in the Java programming language.
  483. *
  484. * @param columnName the SQL name of the column
  485. * @return the column value; if the value is SQL <code>NULL</code>, the
  486. * value returned is <code>0</code>
  487. * @exception SQLException if a database access error occurs
  488. */
  489. double getDouble(String columnName) throws SQLException;
  490. /**
  491. * Retrieves the value of the designated column in the current row
  492. * of this <code>ResultSet</code> object as
  493. * a <code>java.math.BigDecimal</code> in the Java programming language.
  494. *
  495. * @param columnName the SQL name of the column
  496. * @param scale the number of digits to the right of the decimal point
  497. * @return the column value; if the value is SQL <code>NULL</code>, the
  498. * value returned is <code>null</code>
  499. * @exception SQLException if a database access error occurs
  500. * @deprecated
  501. */
  502. @Deprecated
  503. BigDecimal getBigDecimal(String columnName, int scale) throws SQLException;
  504. /**
  505. * Retrieves the value of the designated column in the current row
  506. * of this <code>ResultSet</code> object as
  507. * a <code>byte</code> array in the Java programming language.
  508. * The bytes represent the raw values returned by the driver.
  509. *
  510. * @param columnName the SQL name of the column
  511. * @return the column value; if the value is SQL <code>NULL</code>, the
  512. * value returned is <code>null</code>
  513. * @exception SQLException if a database access error occurs
  514. */
  515. byte[] getBytes(String columnName) throws SQLException;
  516. /**
  517. * Retrieves the value of the designated column in the current row
  518. * of this <code>ResultSet</code> object as
  519. * a <code>java.sql.Date</code> object in the Java programming language.
  520. *
  521. * @param columnName the SQL name of the column
  522. * @return the column value; if the value is SQL <code>NULL</code>, the
  523. * value returned is <code>null</code>
  524. * @exception SQLException if a database access error occurs
  525. */
  526. java.sql.Date getDate(String columnName) throws SQLException;
  527. /**
  528. * Retrieves the value of the designated column in the current row
  529. * of this <code>ResultSet</code> object as
  530. * a <code>java.sql.Time</code> object in the Java programming language.
  531. *
  532. * @param columnName the SQL name of the column
  533. * @return the column value;
  534. * if the value is SQL <code>NULL</code>,
  535. * the value returned is <code>null</code>
  536. * @exception SQLException if a database access error occurs
  537. */
  538. java.sql.Time getTime(String columnName) throws SQLException;
  539. /**
  540. * Retrieves the value of the designated column in the current row
  541. * of this <code>ResultSet</code> object as
  542. * a <code>java.sql.Timestamp</code> object.
  543. *
  544. * @param columnName the SQL name of the column
  545. * @return the column value; if the value is SQL <code>NULL</code>, the
  546. * value returned is <code>null</code>
  547. * @exception SQLException if a database access error occurs
  548. */
  549. java.sql.Timestamp getTimestamp(String columnName) throws SQLException;
  550. /**
  551. * Retrieves the value of the designated column in the current row
  552. * of this <code>ResultSet</code> object as a stream of
  553. * ASCII characters. The value can then be read in chunks from the
  554. * stream. This method is particularly
  555. * suitable for retrieving large <code>LONGVARCHAR</code> values.
  556. * The JDBC driver will
  557. * do any necessary conversion from the database format into ASCII.
  558. *
  559. * <P><B>Note:</B> All the data in the returned stream must be
  560. * read prior to getting the value of any other column. The next
  561. * call to a getter method implicitly closes the stream. Also, a
  562. * stream may return <code>0</code> when the method <code>available</code>
  563. * is called whether there is data available or not.
  564. *
  565. * @param columnName the SQL name of the column
  566. * @return a Java input stream that delivers the database column value
  567. * as a stream of one-byte ASCII characters.
  568. * If the value is SQL <code>NULL</code>,
  569. * the value returned is <code>null</code>.
  570. * @exception SQLException if a database access error occurs
  571. */
  572. java.io.InputStream getAsciiStream(String columnName) throws SQLException;
  573. /**
  574. * Retrieves the value of the designated column in the current row
  575. * of this <code>ResultSet</code> object as a stream of two-byte
  576. * Unicode characters. The first byte is the high byte; the second
  577. * byte is the low byte.
  578. *
  579. * The value can then be read in chunks from the
  580. * stream. This method is particularly
  581. * suitable for retrieving large <code>LONGVARCHAR</code> values.
  582. * The JDBC technology-enabled driver will
  583. * do any necessary conversion from the database format into Unicode.
  584. *
  585. * <P><B>Note:</B> All the data in the returned stream must be
  586. * read prior to getting the value of any other column. The next
  587. * call to a getter method implicitly closes the stream.
  588. * Also, a stream may return <code>0</code> when the method
  589. * <code>InputStream.available</code> is called, whether there
  590. * is data available or not.
  591. *
  592. * @param columnName the SQL name of the column
  593. * @return a Java input stream that delivers the database column value
  594. * as a stream of two-byte Unicode characters.
  595. * If the value is SQL <code>NULL</code>, the value returned
  596. * is <code>null</code>.
  597. * @exception SQLException if a database access error occurs
  598. * @deprecated use <code>getCharacterStream</code> instead
  599. */
  600. @Deprecated
  601. java.io.InputStream getUnicodeStream(String columnName) throws SQLException;
  602. /**
  603. * Retrieves the value of the designated column in the current row
  604. * of this <code>ResultSet</code> object as a stream of uninterpreted
  605. * <code>byte</code>s.
  606. * The value can then be read in chunks from the
  607. * stream. This method is particularly
  608. * suitable for retrieving large <code>LONGVARBINARY</code>
  609. * values.
  610. *
  611. * <P><B>Note:</B> All the data in the returned stream must be
  612. * read prior to getting the value of any other column. The next
  613. * call to a getter method implicitly closes the stream. Also, a
  614. * stream may return <code>0</code> when the method <code>available</code>
  615. * is called whether there is data available or not.
  616. *
  617. * @param columnName the SQL name of the column
  618. * @return a Java input stream that delivers the database column value
  619. * as a stream of uninterpreted bytes;
  620. * if the value is SQL <code>NULL</code>, the result is <code>null</code>
  621. * @exception SQLException if a database access error occurs
  622. */
  623. java.io.InputStream getBinaryStream(String columnName)
  624. throws SQLException;
  625. //=====================================================================
  626. // Advanced features:
  627. //=====================================================================
  628. /**
  629. * Retrieves the first warning reported by calls on this
  630. * <code>ResultSet</code> object.
  631. * Subsequent warnings on this <code>ResultSet</code> object
  632. * will be chained to the <code>SQLWarning</code> object that
  633. * this method returns.
  634. *
  635. * <P>The warning chain is automatically cleared each time a new
  636. * row is read. This method may not be called on a <code>ResultSet</code>
  637. * object that has been closed; doing so will cause an
  638. * <code>SQLException</code> to be thrown.
  639. * <P>
  640. * <B>Note:</B> This warning chain only covers warnings caused
  641. * by <code>ResultSet</code> methods. Any warning caused by
  642. * <code>Statement</code> methods
  643. * (such as reading OUT parameters) will be chained on the
  644. * <code>Statement</code> object.
  645. *
  646. * @return the first <code>SQLWarning</code> object reported or
  647. * <code>null</code> if there are none
  648. * @exception SQLException if a database access error occurs or this method is
  649. * called on a closed result set
  650. */
  651. SQLWarning getWarnings() throws SQLException;
  652. /**
  653. * Clears all warnings reported on this <code>ResultSet</code> object.
  654. * After this method is called, the method <code>getWarnings</code>
  655. * returns <code>null</code> until a new warning is
  656. * reported for this <code>ResultSet</code> object.
  657. *
  658. * @exception SQLException if a database access error occurs
  659. */
  660. void clearWarnings() throws SQLException;
  661. /**
  662. * Retrieves the name of the SQL cursor used by this <code>ResultSet</code>
  663. * object.
  664. *
  665. * <P>In SQL, a result table is retrieved through a cursor that is
  666. * named. The current row of a result set can be updated or deleted
  667. * using a positioned update/delete statement that references the
  668. * cursor name. To insure that the cursor has the proper isolation
  669. * level to support update, the cursor's <code>SELECT</code> statement
  670. * should be of the form <code>SELECT FOR UPDATE</code>. If
  671. * <code>FOR UPDATE</code> is omitted, the positioned updates may fail.
  672. *
  673. * <P>The JDBC API supports this SQL feature by providing the name of the
  674. * SQL cursor used by a <code>ResultSet</code> object.
  675. * The current row of a <code>ResultSet</code> object
  676. * is also the current row of this SQL cursor.
  677. *
  678. * <P><B>Note:</B> If positioned update is not supported, a
  679. * <code>SQLException</code> is thrown.
  680. *
  681. * @return the SQL name for this <code>ResultSet</code> object's cursor
  682. * @exception SQLException if a database access error occurs
  683. */
  684. String getCursorName() throws SQLException;
  685. /**
  686. * Retrieves the number, types and properties of
  687. * this <code>ResultSet</code> object's columns.
  688. *
  689. * @return the description of this <code>ResultSet</code> object's columns
  690. * @exception SQLException if a database access error occurs
  691. */
  692. ResultSetMetaData getMetaData() throws SQLException;
  693. /**
  694. * <p>Gets the value of the designated column in the current row
  695. * of this <code>ResultSet</code> object as
  696. * an <code>Object</code> in the Java programming language.
  697. *
  698. * <p>This method will return the value of the given column as a
  699. * Java object. The type of the Java object will be the default
  700. * Java object type corresponding to the column's SQL type,
  701. * following the mapping for built-in types specified in the JDBC
  702. * specification. If the value is an SQL <code>NULL</code>,
  703. * the driver returns a Java <code>null</code>.
  704. *
  705. * <p>This method may also be used to read database-specific
  706. * abstract data types.
  707. *
  708. * In the JDBC 2.0 API, the behavior of method
  709. * <code>getObject</code> is extended to materialize
  710. * data of SQL user-defined types. When a column contains
  711. * a structured or distinct value, the behavior of this method is as
  712. * if it were a call to: <code>getObject(columnIndex,
  713. * this.getStatement().getConnection().getTypeMap())</code>.
  714. *
  715. * @param columnIndex the first column is 1, the second is 2, ...
  716. * @return a <code>java.lang.Object</code> holding the column value
  717. * @exception SQLException if a database access error occurs
  718. */
  719. Object getObject(int columnIndex) throws SQLException;
  720. /**
  721. * <p>Gets the value of the designated column in the current row
  722. * of this <code>ResultSet</code> object as
  723. * an <code>Object</code> in the Java programming language.
  724. *
  725. * <p>This method will return the value of the given column as a
  726. * Java object. The type of the Java object will be the default
  727. * Java object type corresponding to the column's SQL type,
  728. * following the mapping for built-in types specified in the JDBC
  729. * specification. If the value is an SQL <code>NULL</code>,
  730. * the driver returns a Java <code>null</code>.
  731. * <P>
  732. * This method may also be used to read database-specific
  733. * abstract data types.
  734. * <P>
  735. * In the JDBC 2.0 API, the behavior of the method
  736. * <code>getObject</code> is extended to materialize
  737. * data of SQL user-defined types. When a column contains
  738. * a structured or distinct value, the behavior of this method is as
  739. * if it were a call to: <code>getObject(columnIndex,
  740. * this.getStatement().getConnection().getTypeMap())</code>.
  741. *
  742. * @param columnName the SQL name of the column
  743. * @return a <code>java.lang.Object</code> holding the column value
  744. * @exception SQLException if a database access error occurs
  745. */
  746. Object getObject(String columnName) throws SQLException;
  747. //----------------------------------------------------------------
  748. /**
  749. * Maps the given <code>ResultSet</code> column name to its
  750. * <code>ResultSet</code> column index.
  751. *
  752. * @param columnName the name of the column
  753. * @return the column index of the given column name
  754. * @exception SQLException if the <code>ResultSet</code> object
  755. * does not contain <code>columnName</code> or a database access error occurs
  756. */
  757. int findColumn(String columnName) throws SQLException;
  758. //--------------------------JDBC 2.0-----------------------------------
  759. //---------------------------------------------------------------------
  760. // Getters and Setters
  761. //---------------------------------------------------------------------
  762. /**
  763. * Retrieves the value of the designated column in the current row
  764. * of this <code>ResultSet</code> object as a
  765. * <code>java.io.Reader</code> object.
  766. * @return a <code>java.io.Reader</code> object that contains the column
  767. * value; if the value is SQL <code>NULL</code>, the value returned is
  768. * <code>null</code> in the Java programming language.
  769. * @param columnIndex the first column is 1, the second is 2, ...
  770. * @exception SQLException if a database access error occurs
  771. * @since 1.2
  772. */
  773. java.io.Reader getCharacterStream(int columnIndex) throws SQLException;
  774. /**
  775. * Retrieves the value of the designated column in the current row
  776. * of this <code>ResultSet</code> object as a
  777. * <code>java.io.Reader</code> object.
  778. *
  779. * @param columnName the name of the column
  780. * @return a <code>java.io.Reader</code> object that contains the column
  781. * value; if the value is SQL <code>NULL</code>, the value returned is
  782. * <code>null</code> in the Java programming language
  783. * @exception SQLException if a database access error occurs
  784. * @since 1.2
  785. */
  786. java.io.Reader getCharacterStream(String columnName) throws SQLException;
  787. /**
  788. * Retrieves the value of the designated column in the current row
  789. * of this <code>ResultSet</code> object as a
  790. * <code>java.math.BigDecimal</code> with full precision.
  791. *
  792. * @param columnIndex the first column is 1, the second is 2, ...
  793. * @return the column value (full precision);
  794. * if the value is SQL <code>NULL</code>, the value returned is
  795. * <code>null</code> in the Java programming language.
  796. * @exception SQLException if a database access error occurs
  797. * @since 1.2
  798. */
  799. BigDecimal getBigDecimal(int columnIndex) throws SQLException;
  800. /**
  801. * Retrieves the value of the designated column in the current row
  802. * of this <code>ResultSet</code> object as a
  803. * <code>java.math.BigDecimal</code> with full precision.
  804. *
  805. * @param columnName the column name
  806. * @return the column value (full precision);
  807. * if the value is SQL <code>NULL</code>, the value returned is
  808. * <code>null</code> in the Java programming language.
  809. * @exception SQLException if a database access error occurs
  810. * @since 1.2
  811. *
  812. */
  813. BigDecimal getBigDecimal(String columnName) throws SQLException;
  814. //---------------------------------------------------------------------
  815. // Traversal/Positioning
  816. //---------------------------------------------------------------------
  817. /**
  818. * Retrieves whether the cursor is before the first row in
  819. * this <code>ResultSet</code> object.
  820. *
  821. * @return <code>true</code> if the cursor is before the first row;
  822. * <code>false</code> if the cursor is at any other position or the
  823. * result set contains no rows
  824. * @exception SQLException if a database access error occurs
  825. * @since 1.2
  826. */
  827. boolean isBeforeFirst() throws SQLException;
  828. /**
  829. * Retrieves whether the cursor is after the last row in
  830. * this <code>ResultSet</code> object.
  831. *
  832. * @return <code>true</code> if the cursor is after the last row;
  833. * <code>false</code> if the cursor is at any other position or the
  834. * result set contains no rows
  835. * @exception SQLException if a database access error occurs
  836. * @since 1.2
  837. */
  838. boolean isAfterLast() throws SQLException;
  839. /**
  840. * Retrieves whether the cursor is on the first row of
  841. * this <code>ResultSet</code> object.
  842. *
  843. * @return <code>true</code> if the cursor is on the first row;
  844. * <code>false</code> otherwise
  845. * @exception SQLException if a database access error occurs
  846. * @since 1.2
  847. */
  848. boolean isFirst() throws SQLException;
  849. /**
  850. * Retrieves whether the cursor is on the last row of
  851. * this <code>ResultSet</code> object.
  852. * Note: Calling the method <code>isLast</code> may be expensive
  853. * because the JDBC driver
  854. * might need to fetch ahead one row in order to determine
  855. * whether the current row is the last row in the result set.
  856. *
  857. * @return <code>true</code> if the cursor is on the last row;
  858. * <code>false</code> otherwise
  859. * @exception SQLException if a database access error occurs
  860. * @since 1.2
  861. */
  862. boolean isLast() throws SQLException;
  863. /**
  864. * Moves the cursor to the front of
  865. * this <code>ResultSet</code> object, just before the
  866. * first row. This method has no effect if the result set contains no rows.
  867. *
  868. * @exception SQLException if a database access error
  869. * occurs or the result set type is <code>TYPE_FORWARD_ONLY</code>
  870. * @since 1.2
  871. */
  872. void beforeFirst() throws SQLException;
  873. /**
  874. * Moves the cursor to the end of
  875. * this <code>ResultSet</code> object, just after the
  876. * last row. This method has no effect if the result set contains no rows.
  877. * @exception SQLException if a database access error
  878. * occurs or the result set type is <code>TYPE_FORWARD_ONLY</code>
  879. * @since 1.2
  880. */
  881. void afterLast() throws SQLException;
  882. /**
  883. * Moves the cursor to the first row in
  884. * this <code>ResultSet</code> object.
  885. *
  886. * @return <code>true</code> if the cursor is on a valid row;
  887. * <code>false</code> if there are no rows in the result set
  888. * @exception SQLException if a database access error
  889. * occurs or the result set type is <code>TYPE_FORWARD_ONLY</code>
  890. * @since 1.2
  891. */
  892. boolean first() throws SQLException;
  893. /**
  894. * Moves the cursor to the last row in
  895. * this <code>ResultSet</code> object.
  896. *
  897. * @return <code>true</code> if the cursor is on a valid row;
  898. * <code>false</code> if there are no rows in the result set
  899. * @exception SQLException if a database access error
  900. * occurs or the result set type is <code>TYPE_FORWARD_ONLY</code>
  901. * @since 1.2
  902. */
  903. boolean last() throws SQLException;
  904. /**
  905. * Retrieves the current row number. The first row is number 1, the
  906. * second number 2, and so on.
  907. *
  908. * @return the current row number; <code>0</code> if there is no current row
  909. * @exception SQLException if a database access error occurs
  910. * @since 1.2
  911. */
  912. int getRow() throws SQLException;
  913. /**
  914. * Moves the cursor to the given row number in
  915. * this <code>ResultSet</code> object.
  916. *
  917. * <p>If the row number is positive, the cursor moves to
  918. * the given row number with respect to the
  919. * beginning of the result set. The first row is row 1, the second
  920. * is row 2, and so on.
  921. *
  922. * <p>If the given row number is negative, the cursor moves to
  923. * an absolute row position with respect to
  924. * the end of the result set. For example, calling the method
  925. * <code>absolute(-1)</code> positions the
  926. * cursor on the last row; calling the method <code>absolute(-2)</code>
  927. * moves the cursor to the next-to-last row, and so on.
  928. *
  929. * <p>An attempt to position the cursor beyond the first/last row in
  930. * the result set leaves the cursor before the first row or after
  931. * the last row.
  932. *
  933. * <p><B>Note:</B> Calling <code>absolute(1)</code> is the same
  934. * as calling <code>first()</code>. Calling <code>absolute(-1)</code>
  935. * is the same as calling <code>last()</code>.
  936. *
  937. * @param row the number of the row to which the cursor should move.
  938. * A positive number indicates the row number counting from the
  939. * beginning of the result set; a negative number indicates the
  940. * row number counting from the end of the result set
  941. * @return <code>true</code> if the cursor is on the result set;
  942. * <code>false</code> otherwise
  943. * @exception SQLException if a database access error
  944. * occurs, or the result set type is <code>TYPE_FORWARD_ONLY</code>
  945. * @since 1.2
  946. */
  947. boolean absolute( int row ) throws SQLException;
  948. /**
  949. * Moves the cursor a relative number of rows, either positive or negative.
  950. * Attempting to move beyond the first/last row in the
  951. * result set positions the cursor before/after the
  952. * the first/last row. Calling <code>relative(0)</code> is valid, but does
  953. * not change the cursor position.
  954. *
  955. * <p>Note: Calling the method <code>relative(1)</code>
  956. * is identical to calling the method <code>next()</code> and
  957. * calling the method <code>relative(-1)</code> is identical
  958. * to calling the method <code>previous()</code>.
  959. *
  960. * @param rows an <code>int</code> specifying the number of rows to
  961. * move from the current row; a positive number moves the cursor
  962. * forward; a negative number moves the cursor backward
  963. * @return <code>true</code> if the cursor is on a row;
  964. * <code>false</code> otherwise
  965. * @exception SQLException if a database access error occurs,
  966. * there is no current row, or the result set type is
  967. * <code>TYPE_FORWARD_ONLY</code>
  968. * @since 1.2
  969. */
  970. boolean relative( int rows ) throws SQLException;
  971. /**
  972. * Moves the cursor to the previous row in this
  973. * <code>ResultSet</code> object.
  974. *
  975. * @return <code>true</code> if the cursor is on a valid row;
  976. * <code>false</code> if it is off the result set
  977. * @exception SQLException if a database access error
  978. * occurs or the result set type is <code>TYPE_FORWARD_ONLY</code>
  979. * @since 1.2
  980. */
  981. boolean previous() throws SQLException;
  982. //---------------------------------------------------------------------
  983. // Properties
  984. //---------------------------------------------------------------------
  985. /**
  986. * The constant indicating that the rows in a result set will be
  987. * processed in a forward direction; first-to-last.
  988. * This constant is used by the method <code>setFetchDirection</code>
  989. * as a hint to the driver, which the driver may ignore.
  990. * @since 1.2
  991. */
  992. int FETCH_FORWARD = 1000;
  993. /**
  994. * The constant indicating that the rows in a result set will be
  995. * processed in a reverse direction; last-to-first.
  996. * This constant is used by the method <code>setFetchDirection</code>
  997. * as a hint to the driver, which the driver may ignore.
  998. * @since 1.2
  999. */
  1000. int FETCH_REVERSE = 1001;
  1001. /**
  1002. * The constant indicating that the order in which rows in a
  1003. * result set will be processed is unknown.
  1004. * This constant is used by the method <code>setFetchDirection</code>
  1005. * as a hint to the driver, which the driver may ignore.
  1006. */
  1007. int FETCH_UNKNOWN = 1002;
  1008. /**
  1009. * Gives a hint as to the direction in which the rows in this
  1010. * <code>ResultSet</code> object will be processed.
  1011. * The initial value is determined by the
  1012. * <code>Statement</code> object
  1013. * that produced this <code>ResultSet</code> object.
  1014. * The fetch direction may be changed at any time.
  1015. *
  1016. * @param direction an <code>int</code> specifying the suggested
  1017. * fetch direction; one of <code>ResultSet.FETCH_FORWARD</code>,
  1018. * <code>ResultSet.FETCH_REVERSE</code>, or
  1019. * <code>ResultSet.FETCH_UNKNOWN</code>
  1020. * @exception SQLException if a database access error occurs or
  1021. * the result set type is <code>TYPE_FORWARD_ONLY</code> and the fetch
  1022. * direction is not <code>FETCH_FORWARD</code>
  1023. * @since 1.2
  1024. * @see Statement#setFetchDirection
  1025. * @see #getFetchDirection
  1026. */
  1027. void setFetchDirection(int direction) throws SQLException;
  1028. /**
  1029. * Retrieves the fetch direction for this
  1030. * <code>ResultSet</code> object.
  1031. *
  1032. * @return the current fetch direction for this <code>ResultSet</code> object
  1033. * @exception SQLException if a database access error occurs
  1034. * @since 1.2
  1035. * @see #setFetchDirection
  1036. */
  1037. int getFetchDirection() throws SQLException;
  1038. /**
  1039. * Gives the JDBC driver a hint as to the number of rows that should
  1040. * be fetched from the database when more rows are needed for this
  1041. * <code>ResultSet</code> object.
  1042. * If the fetch size specified is zero, the JDBC driver
  1043. * ignores the value and is free to make its own best guess as to what
  1044. * the fetch size should be. The default value is set by the
  1045. * <code>Statement</code> object
  1046. * that created the result set. The fetch size may be changed at any time.
  1047. *
  1048. * @param rows the number of rows to fetch
  1049. * @exception SQLException if a database access error occurs or the
  1050. * condition <code>0 <= rows <= Statement.getMaxRows()</code> is not satisfied
  1051. * @since 1.2
  1052. * @see #getFetchSize
  1053. */
  1054. void setFetchSize(int rows) throws SQLException;
  1055. /**
  1056. * Retrieves the fetch size for this
  1057. * <code>ResultSet</code> object.
  1058. *
  1059. * @return the current fetch size for this <code>ResultSet</code> object
  1060. * @exception SQLException if a database access error occurs
  1061. * @since 1.2
  1062. * @see #setFetchSize
  1063. */
  1064. int getFetchSize() throws SQLException;
  1065. /**
  1066. * The constant indicating the type for a <code>ResultSet</code> object
  1067. * whose cursor may move only forward.
  1068. * @since 1.2
  1069. */
  1070. int TYPE_FORWARD_ONLY = 1003;
  1071. /**
  1072. * The constant indicating the type for a <code>ResultSet</code> object
  1073. * that is scrollable but generally not sensitive to changes made by others.
  1074. * @since 1.2
  1075. */
  1076. int TYPE_SCROLL_INSENSITIVE = 1004;
  1077. /**
  1078. * The constant indicating the type for a <code>ResultSet</code> object
  1079. * that is scrollable and generally sensitive to changes made by others.
  1080. * @since 1.2
  1081. */
  1082. int TYPE_SCROLL_SENSITIVE = 1005;
  1083. /**
  1084. * Retrieves the type of this <code>ResultSet</code> object.
  1085. * The type is determined by the <code>Statement</code> object
  1086. * that created the result set.
  1087. *
  1088. * @return <code>ResultSet.TYPE_FORWARD_ONLY</code>,
  1089. * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>,
  1090. * or <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
  1091. * @exception SQLException if a database access error occurs
  1092. * @since 1.2
  1093. */
  1094. int getType() throws SQLException;
  1095. /**
  1096. * The constant indicating the concurrency mode for a
  1097. * <code>ResultSet</code> object that may NOT be updated.
  1098. * @since 1.2
  1099. */
  1100. int CONCUR_READ_ONLY = 1007;
  1101. /**
  1102. * The constant indicating the concurrency mode for a
  1103. * <code>ResultSet</code> object that may be updated.
  1104. * @since 1.2
  1105. */
  1106. int CONCUR_UPDATABLE = 1008;
  1107. /**
  1108. * Retrieves the concurrency mode of this <code>ResultSet</code> object.
  1109. * The concurrency used is determined by the
  1110. * <code>Statement</code> object that created the result set.
  1111. *
  1112. * @return the concurrency type, either
  1113. * <code>ResultSet.CONCUR_READ_ONLY</code>
  1114. * or <code>ResultSet.CONCUR_UPDATABLE</code>
  1115. * @exception SQLException if a database access error occurs
  1116. * @since 1.2
  1117. */
  1118. int getConcurrency() throws SQLException;
  1119. //---------------------------------------------------------------------
  1120. // Updates
  1121. //---------------------------------------------------------------------
  1122. /**
  1123. * Retrieves whether the current row has been updated. The value returned
  1124. * depends on whether or not the result set can detect updates.
  1125. *
  1126. * @return <code>true</code> if both (1) the row has been visibly updated
  1127. * by the owner or another and (2) updates are detected
  1128. * @exception SQLException if a database access error occurs
  1129. * @see DatabaseMetaData#updatesAreDetected
  1130. * @since 1.2
  1131. */
  1132. boolean rowUpdated() throws SQLException;
  1133. /**
  1134. * Retrieves whether the current row has had an insertion.
  1135. * The value returned depends on whether or not this
  1136. * <code>ResultSet</code> object can detect visible inserts.
  1137. *
  1138. * @return <code>true</code> if a row has had an insertion
  1139. * and insertions are detected; <code>false</code> otherwise
  1140. * @exception SQLException if a database access error occurs
  1141. *
  1142. * @see DatabaseMetaData#insertsAreDetected
  1143. * @since 1.2
  1144. */
  1145. boolean rowInserted() throws SQLException;
  1146. /**
  1147. * Retrieves whether a row has been deleted. A deleted row may leave
  1148. * a visible "hole" in a result set. This method can be used to
  1149. * detect holes in a result set. The value returned depends on whether
  1150. * or not this <code>ResultSet</code> object can detect deletions.
  1151. *
  1152. * @return <code>true</code> if a row was deleted and deletions are detected;
  1153. * <code>false</code> otherwise
  1154. * @exception SQLException if a database access error occurs
  1155. *
  1156. * @see DatabaseMetaData#deletesAreDetected
  1157. * @since 1.2
  1158. */
  1159. boolean rowDeleted() throws SQLException;
  1160. /**
  1161. * Gives a nullable column a null value.
  1162. *
  1163. * The updater methods are used to update column values in the
  1164. * current row or the insert row. The updater methods do not
  1165. * update the underlying database; instead the <code>updateRow</code>
  1166. * or <code>insertRow</code> methods are called to update the database.
  1167. *
  1168. * @param columnIndex the first column is 1, the second is 2, ...
  1169. * @exception SQLException if a database access error occurs
  1170. * @since 1.2
  1171. */
  1172. void updateNull(int columnIndex) throws SQLException;
  1173. /**
  1174. * Updates the designated column with a <code>boolean</code> value.
  1175. * The updater methods are used to update column values in the
  1176. * current row or the insert row. The updater methods do not
  1177. * update the underlying database; instead the <code>updateRow</code> or
  1178. * <code>insertRow</code> methods are called to update the database.
  1179. *
  1180. * @param columnIndex the first column is 1, the second is 2, ...
  1181. * @param x the new column value
  1182. * @exception SQLException if a database access error occurs
  1183. * @since 1.2
  1184. */
  1185. void updateBoolean(int columnIndex, boolean x) throws SQLException;
  1186. /**
  1187. * Updates the designated column with a <code>byte</code> value.
  1188. * The updater methods are used to update column values in the
  1189. * current row or the insert row. The updater methods do not
  1190. * update the underlying database; instead the <code>updateRow</code> or
  1191. * <code>insertRow</code> methods are called to update the database.
  1192. *
  1193. *
  1194. * @param columnIndex the first column is 1, the second is 2, ...
  1195. * @param x the new column value
  1196. * @exception SQLException if a database access error occurs
  1197. * @since 1.2
  1198. */
  1199. void updateByte(int columnIndex, byte x) throws SQLException;
  1200. /**
  1201. * Updates the designated column with a <code>short</code> value.
  1202. * The updater methods are used to update column values in the
  1203. * current row or the insert row. The updater methods do not
  1204. * update the underlying database; instead the <code>updateRow</code> or
  1205. * <code>insertRow</code> methods are called to update the database.
  1206. *
  1207. * @param columnIndex the first column is 1, the second is 2, ...
  1208. * @param x the new column value
  1209. * @exception SQLException if a database access error occurs
  1210. * @since 1.2
  1211. */
  1212. void updateShort(int columnIndex, short x) throws SQLException;
  1213. /**
  1214. * Updates the designated column with an <code>int</code> value.
  1215. * The updater methods are used to update column values in the
  1216. * current row or the insert row. The updater methods do not
  1217. * update the underlying database; instead the <code>updateRow</code> or
  1218. * <code>insertRow</code> methods are called to update the database.
  1219. *
  1220. * @param columnIndex the first column is 1, the second is 2, ...
  1221. * @param x the new column value
  1222. * @exception SQLException if a database access error occurs
  1223. * @since 1.2
  1224. */
  1225. void updateInt(int columnIndex, int x) throws SQLException;
  1226. /**
  1227. * Updates the designated column with a <code>long</code> value.
  1228. * The updater methods are used to update column values in the
  1229. * current row or the insert row. The updater methods do not
  1230. * update the underlying database; instead the <code>updateRow</code> or
  1231. * <code>insertRow</code> methods are called to update the database.
  1232. *
  1233. * @param columnIndex the first column is 1, the second is 2, ...
  1234. * @param x the new column value
  1235. * @exception SQLException if a database access error occurs
  1236. * @since 1.2
  1237. */
  1238. void updateLong(int columnIndex, long x) throws SQLException;
  1239. /**
  1240. * Updates the designated column with a <code>float</code> value.
  1241. * The updater methods are used to update column values in the
  1242. * current row or the insert row. The updater methods do not
  1243. * update the underlying database; instead the <code>updateRow</code> or
  1244. * <code>insertRow</code> methods are called to update the database.
  1245. *
  1246. * @param columnIndex the first column is 1, the second is 2, ...
  1247. * @param x the new column value
  1248. * @exception SQLException if a database access error occurs
  1249. * @since 1.2
  1250. */
  1251. void updateFloat(int columnIndex, float x) throws SQLException;
  1252. /**
  1253. * Updates the designated column with a <code>double</code> value.
  1254. * The updater methods are used to update column values in the
  1255. * current row or the insert row. The updater methods do not
  1256. * update the underlying database; instead the <code>updateRow</code> or
  1257. * <code>insertRow</code> methods are called to update the database.
  1258. *
  1259. * @param columnIndex the first column is 1, the second is 2, ...
  1260. * @param x the new column value
  1261. * @exception SQLException if a database access error occurs
  1262. * @since 1.2
  1263. */
  1264. void updateDouble(int columnIndex, double x) throws SQLException;
  1265. /**
  1266. * Updates the designated column with a <code>java.math.BigDecimal</code>
  1267. * value.
  1268. * The updater methods are used to update column values in the
  1269. * current row or the insert row. The updater methods do not
  1270. * update the underlying database; instead the <code>updateRow</code> or
  1271. * <code>insertRow</code> methods are called to update the database.
  1272. *
  1273. * @param columnIndex the first column is 1, the second is 2, ...
  1274. * @param x the new column value
  1275. * @exception SQLException if a database access error occurs
  1276. * @since 1.2
  1277. */
  1278. void updateBigDecimal(int columnIndex, BigDecimal x) throws SQLException;
  1279. /**
  1280. * Updates the designated column with a <code>String</code> value.
  1281. * The updater methods are used to update column values in the
  1282. * current row or the insert row. The updater methods do not
  1283. * update the underlying database; instead the <code>updateRow</code> or
  1284. * <code>insertRow</code> methods are called to update the database.
  1285. *
  1286. * @param columnIndex the first column is 1, the second is 2, ...
  1287. * @param x the new column value
  1288. * @exception SQLException if a database access error occurs
  1289. * @since 1.2
  1290. */
  1291. void updateString(int columnIndex, String x) throws SQLException;
  1292. /**
  1293. * Updates the designated column with a <code>byte</code> array value.
  1294. * The updater methods are used to update column values in the
  1295. * current row or the insert row. The updater methods do not
  1296. * update the underlying database; instead the <code>updateRow</code> or
  1297. * <code>insertRow</code> methods are called to update the database.
  1298. *
  1299. * @param columnIndex the first column is 1, the second is 2, ...
  1300. * @param x the new column value
  1301. * @exception SQLException if a database access error occurs
  1302. * @since 1.2
  1303. */
  1304. void updateBytes(int columnIndex, byte x[]) throws SQLException;
  1305. /**
  1306. * Updates the designated column with a <code>java.sql.Date</code> value.
  1307. * The updater methods are used to update column values in the
  1308. * current row or the insert row. The updater methods do not
  1309. * update the underlying database; instead the <code>updateRow</code> or
  1310. * <code>insertRow</code> methods are called to update the database.
  1311. *
  1312. * @param columnIndex the first column is 1, the second is 2, ...
  1313. * @param x the new column value
  1314. * @exception SQLException if a database access error occurs
  1315. * @since 1.2
  1316. */
  1317. void updateDate(int columnIndex, java.sql.Date x) throws SQLException;
  1318. /**
  1319. * Updates the designated column with a <code>java.sql.Time</code> value.
  1320. * The updater methods are used to update column values in the
  1321. * current row or the insert row. The updater methods do not
  1322. * update the underlying database; instead the <code>updateRow</code> or
  1323. * <code>insertRow</code> methods are called to update the database.
  1324. *
  1325. * @param columnIndex the first column is 1, the second is 2, ...
  1326. * @param x the new column value
  1327. * @exception SQLException if a database access error occurs
  1328. * @since 1.2
  1329. */
  1330. void updateTime(int columnIndex, java.sql.Time x) throws SQLException;
  1331. /**
  1332. * Updates the designated column with a <code>java.sql.Timestamp</code>
  1333. * value.
  1334. * The updater methods are used to update column values in the
  1335. * current row or the insert row. The updater methods do not
  1336. * update the underlying database; instead the <code>updateRow</code> or
  1337. * <code>insertRow</code> methods are called to update the database.
  1338. *
  1339. * @param columnIndex the first column is 1, the second is 2, ...
  1340. * @param x the new column value
  1341. * @exception SQLException if a database access error occurs
  1342. * @since 1.2
  1343. */
  1344. void updateTimestamp(int columnIndex, java.sql.Timestamp x)
  1345. throws SQLException;
  1346. /**
  1347. * Updates the designated column with an ascii stream value.
  1348. * The updater methods are used to update column values in the
  1349. * current row or the insert row. The updater methods do not
  1350. * update the underlying database; instead the <code>updateRow</code> or
  1351. * <code>insertRow</code> methods are called to update the database.
  1352. *
  1353. * @param columnIndex the first column is 1, the second is 2, ...
  1354. * @param x the new column value
  1355. * @param length the length of the stream
  1356. * @exception SQLException if a database access error occurs
  1357. * @since 1.2
  1358. */
  1359. void updateAsciiStream(int columnIndex,
  1360. java.io.InputStream x,
  1361. int length) throws SQLException;
  1362. /**
  1363. * Updates the designated column with a binary stream value.
  1364. * The updater methods are used to update column values in the
  1365. * current row or the insert row. The updater methods do not
  1366. * update the underlying database; instead the <code>updateRow</code> or
  1367. * <code>insertRow</code> methods are called to update the database.
  1368. *
  1369. * @param columnIndex the first column is 1, the second is 2, ...
  1370. * @param x the new column value
  1371. * @param length the length of the stream
  1372. * @exception SQLException if a database access error occurs
  1373. * @since 1.2
  1374. */
  1375. void updateBinaryStream(int columnIndex,
  1376. java.io.InputStream x,
  1377. int length) throws SQLException;
  1378. /**
  1379. * Updates the designated column with a character stream value.
  1380. * The updater methods are used to update column values in the
  1381. * current row or the insert row. The updater methods do not
  1382. * update the underlying database; instead the <code>updateRow</code> or
  1383. * <code>insertRow</code> methods are called to update the database.
  1384. *
  1385. * @param columnIndex the first column is 1, the second is 2, ...
  1386. * @param x the new column value
  1387. * @param length the length of the stream
  1388. * @exception SQLException if a database access error occurs
  1389. * @since 1.2
  1390. */
  1391. void updateCharacterStream(int columnIndex,
  1392. java.io.Reader x,
  1393. int length) throws SQLException;
  1394. /**
  1395. * Updates the designated column with an <code>Object</code> value.
  1396. * The updater methods are used to update column values in the
  1397. * current row or the insert row. The updater methods do not
  1398. * update the underlying database; instead the <code>updateRow</code> or
  1399. * <code>insertRow</code> methods are called to update the database.
  1400. *
  1401. * @param columnIndex the first column is 1, the second is 2, ...
  1402. * @param x the new column value
  1403. * @param scale for <code>java.sql.Types.DECIMA</code>
  1404. * or <code>java.sql.Types.NUMERIC</code> types,
  1405. * this is the number of digits after the decimal point. For all other
  1406. * types this value will be ignored.
  1407. * @exception SQLException if a database access error occurs
  1408. * @since 1.2
  1409. */
  1410. void updateObject(int columnIndex, Object x, int scale)
  1411. throws SQLException;
  1412. /**
  1413. * Updates the designated column with an <code>Object</code> value.
  1414. * The updater methods are used to update column values in the
  1415. * current row or the insert row. The updater methods do not
  1416. * update the underlying database; instead the <code>updateRow</code> or
  1417. * <code>insertRow</code> methods are called to update the database.
  1418. *
  1419. * @param columnIndex the first column is 1, the second is 2, ...
  1420. * @param x the new column value
  1421. * @exception SQLException if a database access error occurs
  1422. * @since 1.2
  1423. */
  1424. void updateObject(int columnIndex, Object x) throws SQLException;
  1425. /**
  1426. * Updates the designated column with a <code>null</code> value.
  1427. * The updater methods are used to update column values in the
  1428. * current row or the insert row. The updater methods do not
  1429. * update the underlying database; instead the <code>updateRow</code> or
  1430. * <code>insertRow</code> methods are called to update the database.
  1431. *
  1432. * @param columnName the name of the column
  1433. * @exception SQLException if a database access error occurs
  1434. * @since 1.2
  1435. */
  1436. void updateNull(String columnName) throws SQLException;
  1437. /**
  1438. * Updates the designated column with a <code>boolean</code> value.
  1439. * The updater methods are used to update column values in the
  1440. * current row or the insert row. The updater methods do not
  1441. * update the underlying database; instead the <code>updateRow</code> or
  1442. * <code>insertRow</code> methods are called to update the database.
  1443. *
  1444. * @param columnName the name of the column
  1445. * @param x the new column value
  1446. * @exception SQLException if a database access error occurs
  1447. * @since 1.2
  1448. */
  1449. void updateBoolean(String columnName, boolean x) throws SQLException;
  1450. /**
  1451. * Updates the designated column with a <code>byte</code> value.
  1452. * The updater methods are used to update column values in the
  1453. * current row or the insert row. The updater methods do not
  1454. * update the underlying database; instead the <code>updateRow</code> or
  1455. * <code>insertRow</code> methods are called to update the database.
  1456. *
  1457. * @param columnName the name of the column
  1458. * @param x the new column value
  1459. * @exception SQLException if a database access error occurs
  1460. * @since 1.2
  1461. */
  1462. void updateByte(String columnName, byte x) throws SQLException;
  1463. /**
  1464. * Updates the designated column with a <code>short</code> value.
  1465. * The updater methods are used to update column values in the
  1466. * current row or the insert row. The updater methods do not
  1467. * update the underlying database; instead the <code>updateRow</code> or
  1468. * <code>insertRow</code> methods are called to update the database.
  1469. *
  1470. * @param columnName the name of the column
  1471. * @param x the new column value
  1472. * @exception SQLException if a database access error occurs
  1473. * @since 1.2
  1474. */
  1475. void updateShort(String columnName, short x) throws SQLException;
  1476. /**
  1477. * Updates the designated column with an <code>int</code> value.
  1478. * The updater methods are used to update column values in the
  1479. * current row or the insert row. The updater methods do not
  1480. * update the underlying database; instead the <code>updateRow</code> or
  1481. * <code>insertRow</code> methods are called to update the database.
  1482. *
  1483. * @param columnName the name of the column
  1484. * @param x the new column value
  1485. * @exception SQLException if a database access error occurs
  1486. * @since 1.2
  1487. */
  1488. void updateInt(String columnName, int x) throws SQLException;
  1489. /**
  1490. * Updates the designated column with a <code>long</code> value.
  1491. * The updater methods are used to update column values in the
  1492. * current row or the insert row. The updater methods do not
  1493. * update the underlying database; instead the <code>updateRow</code> or
  1494. * <code>insertRow</code> methods are called to update the database.
  1495. *
  1496. * @param columnName the name of the column
  1497. * @param x the new column value
  1498. * @exception SQLException if a database access error occurs
  1499. * @since 1.2
  1500. */
  1501. void updateLong(String columnName, long x) throws SQLException;
  1502. /**
  1503. * Updates the designated column with a <code>float </code> value.
  1504. * The updater methods are used to update column values in the
  1505. * current row or the insert row. The updater methods do not
  1506. * update the underlying database; instead the <code>updateRow</code> or
  1507. * <code>insertRow</code> methods are called to update the database.
  1508. *
  1509. * @param columnName the name of the column
  1510. * @param x the new column value
  1511. * @exception SQLException if a database access error occurs
  1512. * @since 1.2
  1513. */
  1514. void updateFloat(String columnName, float x) throws SQLException;
  1515. /**
  1516. * Updates the designated column with a <code>double</code> value.
  1517. * The updater methods are used to update column values in the
  1518. * current row or the insert row. The updater methods do not
  1519. * update the underlying database; instead the <code>updateRow</code> or
  1520. * <code>insertRow</code> methods are called to update the database.
  1521. *
  1522. * @param columnName the name of the column
  1523. * @param x the new column value
  1524. * @exception SQLException if a database access error occurs
  1525. * @since 1.2
  1526. */
  1527. void updateDouble(String columnName, double x) throws SQLException;
  1528. /**
  1529. * Updates the designated column with a <code>java.sql.BigDecimal</code>
  1530. * value.
  1531. * The updater methods are used to update column values in the
  1532. * current row or the insert row. The updater methods do not
  1533. * update the underlying database; instead the <code>updateRow</code> or
  1534. * <code>insertRow</code> methods are called to update the database.
  1535. *
  1536. * @param columnName the name of the column
  1537. * @param x the new column value
  1538. * @exception SQLException if a database access error occurs
  1539. * @since 1.2
  1540. */
  1541. void updateBigDecimal(String columnName, BigDecimal x) throws SQLException;
  1542. /**
  1543. * Updates the designated column with a <code>String</code> value.
  1544. * The updater methods are used to update column values in the
  1545. * current row or the insert row. The updater methods do not
  1546. * update the underlying database; instead the <code>updateRow</code> or
  1547. * <code>insertRow</code> methods are called to update the database.
  1548. *
  1549. * @param columnName the name of the column
  1550. * @param x the new column value
  1551. * @exception SQLException if a database access error occurs
  1552. * @since 1.2
  1553. */
  1554. void updateString(String columnName, String x) throws SQLException;
  1555. /**
  1556. * Updates the designated column with a byte array value.
  1557. *
  1558. * The updater methods are used to update column values in the
  1559. * current row or the insert row. The updater methods do not
  1560. * update the underlying database; instead the <code>updateRow</code>
  1561. * or <code>insertRow</code> methods are called to update the database.
  1562. *
  1563. * @param columnName the name of the column
  1564. * @param x the new column value
  1565. * @exception SQLException if a database access error occurs
  1566. * @since 1.2
  1567. */
  1568. void updateBytes(String columnName, byte x[]) throws SQLException;
  1569. /**
  1570. * Updates the designated column with a <code>java.sql.Date</code> value.
  1571. * The updater methods are used to update column values in the
  1572. * current row or the insert row. The updater methods do not
  1573. * update the underlying database; instead the <code>updateRow</code> or
  1574. * <code>insertRow</code> methods are called to update the database.
  1575. *
  1576. * @param columnName the name of the column
  1577. * @param x the new column value
  1578. * @exception SQLException if a database access error occurs
  1579. * @since 1.2
  1580. */
  1581. void updateDate(String columnName, java.sql.Date x) throws SQLException;
  1582. /**
  1583. * Updates the designated column with a <code>java.sql.Time</code> value.
  1584. * The updater methods are used to update column values in the
  1585. * current row or the insert row. The updater methods do not
  1586. * update the underlying database; instead the <code>updateRow</code> or
  1587. * <code>insertRow</code> methods are called to update the database.
  1588. *
  1589. * @param columnName the name of the column
  1590. * @param x the new column value
  1591. * @exception SQLException if a database access error occurs
  1592. * @since 1.2
  1593. */
  1594. void updateTime(String columnName, java.sql.Time x) throws SQLException;
  1595. /**
  1596. * Updates the designated column with a <code>java.sql.Timestamp</code>
  1597. * value.
  1598. * The updater methods are used to update column values in the
  1599. * current row or the insert row. The updater methods do not
  1600. * update the underlying database; instead the <code>updateRow</code> or
  1601. * <code>insertRow</code> methods are called to update the database.
  1602. *
  1603. * @param columnName the name of the column
  1604. * @param x the new column value
  1605. * @exception SQLException if a database access error occurs
  1606. * @since 1.2
  1607. */
  1608. void updateTimestamp(String columnName, java.sql.Timestamp x)
  1609. throws SQLException;
  1610. /**
  1611. * Updates the designated column with an ascii stream value.
  1612. * The updater methods are used to update column values in the
  1613. * current row or the insert row. The updater methods do not
  1614. * update the underlying database; instead the <code>updateRow</code> or
  1615. * <code>insertRow</code> methods are called to update the database.
  1616. *
  1617. * @param columnName the name of the column
  1618. * @param x the new column value
  1619. * @param length the length of the stream
  1620. * @exception SQLException if a database access error occurs
  1621. * @since 1.2
  1622. */
  1623. void updateAsciiStream(String columnName,
  1624. java.io.InputStream x,
  1625. int length) throws SQLException;
  1626. /**
  1627. * Updates the designated column with a binary stream value.
  1628. * The updater methods are used to update column values in the
  1629. * current row or the insert row. The updater methods do not
  1630. * update the underlying database; instead the <code>updateRow</code> or
  1631. * <code>insertRow</code> methods are called to update the database.
  1632. *
  1633. * @param columnName the name of the column
  1634. * @param x the new column value
  1635. * @param length the length of the stream
  1636. * @exception SQLException if a database access error occurs
  1637. * @since 1.2
  1638. */
  1639. void updateBinaryStream(String columnName,
  1640. java.io.InputStream x,
  1641. int length) throws SQLException;
  1642. /**
  1643. * Updates the designated column with a character stream value.
  1644. * The updater methods are used to update column values in the
  1645. * current row or the insert row. The updater methods do not
  1646. * update the underlying database; instead the <code>updateRow</code> or
  1647. * <code>insertRow</code> methods are called to update the database.
  1648. *
  1649. * @param columnName the name of the column
  1650. * @param reader the <code>java.io.Reader</code> object containing
  1651. * the new column value
  1652. * @param length the length of the stream
  1653. * @exception SQLException if a database access error occurs
  1654. * @since 1.2
  1655. */
  1656. void updateCharacterStream(String columnName,
  1657. java.io.Reader reader,
  1658. int length) throws SQLException;
  1659. /**
  1660. * Updates the designated column with an <code>Object</code> value.
  1661. * The updater methods are used to update column values in the
  1662. * current row or the insert row. The updater methods do not
  1663. * update the underlying database; instead the <code>updateRow</code> or
  1664. * <code>insertRow</code> methods are called to update the database.
  1665. *
  1666. * @param columnName the name of the column
  1667. * @param x the new column value
  1668. * @param scale for <code>java.sql.Types.DECIMAL</code>
  1669. * or <code>java.sql.Types.NUMERIC</code> types,
  1670. * this is the number of digits after the decimal point. For all other
  1671. * types this value will be ignored.
  1672. * @exception SQLException if a database access error occurs
  1673. * @since 1.2
  1674. */
  1675. void updateObject(String columnName, Object x, int scale)
  1676. throws SQLException;
  1677. /**
  1678. * Updates the designated column with an <code>Object</code> value.
  1679. * The updater methods are used to update column values in the
  1680. * current row or the insert row. The updater methods do not
  1681. * update the underlying database; instead the <code>updateRow</code> or
  1682. * <code>insertRow</code> methods are called to update the database.
  1683. *
  1684. * @param columnName the name of the column
  1685. * @param x the new column value
  1686. * @exception SQLException if a database access error occurs
  1687. * @since 1.2
  1688. */
  1689. void updateObject(String columnName, Object x) throws SQLException;
  1690. /**
  1691. * Inserts the contents of the insert row into this
  1692. * <code>ResultSet</code> object and into the database.
  1693. * The cursor must be on the insert row when this method is called.
  1694. *
  1695. * @exception SQLException if a database access error occurs,
  1696. * if this method is called when the cursor is not on the insert row,
  1697. * or if not all of non-nullable columns in
  1698. * the insert row have been given a value
  1699. * @since 1.2
  1700. */
  1701. void insertRow() throws SQLException;
  1702. /**
  1703. * Updates the underlying database with the new contents of the
  1704. * current row of this <code>ResultSet</code> object.
  1705. * This method cannot be called when the cursor is on the insert row.
  1706. *
  1707. * @exception SQLException if a database access error occurs or
  1708. * if this method is called when the cursor is on the insert row
  1709. * @since 1.2
  1710. */
  1711. void updateRow() throws SQLException;
  1712. /**
  1713. * Deletes the current row from this <code>ResultSet</code> object
  1714. * and from the underlying database. This method cannot be called when
  1715. * the cursor is on the insert row.
  1716. *
  1717. * @exception SQLException if a database access error occurs
  1718. * or if this method is called when the cursor is on the insert row
  1719. * @since 1.2
  1720. */
  1721. void deleteRow() throws SQLException;
  1722. /**
  1723. * Refreshes the current row with its most recent value in
  1724. * the database. This method cannot be called when
  1725. * the cursor is on the insert row.
  1726. *
  1727. * <P>The <code>refreshRow</code> method provides a way for an
  1728. * application to
  1729. * explicitly tell the JDBC driver to refetch a row(s) from the
  1730. * database. An application may want to call <code>refreshRow</code> when
  1731. * caching or prefetching is being done by the JDBC driver to
  1732. * fetch the latest value of a row from the database. The JDBC driver
  1733. * may actually refresh multiple rows at once if the fetch size is
  1734. * greater than one.
  1735. *
  1736. * <P> All values are refetched subject to the transaction isolation
  1737. * level and cursor sensitivity. If <code>refreshRow</code> is called after
  1738. * calling an updater method, but before calling
  1739. * the method <code>updateRow</code>, then the
  1740. * updates made to the row are lost. Calling the method
  1741. * <code>refreshRow</code> frequently will likely slow performance.
  1742. *
  1743. * @exception SQLException if a database access error
  1744. * occurs or if this method is called when the cursor is on the insert row
  1745. * @since 1.2
  1746. */
  1747. void refreshRow() throws SQLException;
  1748. /**
  1749. * Cancels the updates made to the current row in this
  1750. * <code>ResultSet</code> object.
  1751. * This method may be called after calling an
  1752. * updater method(s) and before calling
  1753. * the method <code>updateRow</code> to roll back
  1754. * the updates made to a row. If no updates have been made or
  1755. * <code>updateRow</code> has already been called, this method has no
  1756. * effect.
  1757. *
  1758. * @exception SQLException if a database access error
  1759. * occurs or if this method is called when the cursor is
  1760. * on the insert row
  1761. * @since 1.2
  1762. */
  1763. void cancelRowUpdates() throws SQLException;
  1764. /**
  1765. * Moves the cursor to the insert row. The current cursor position is
  1766. * remembered while the cursor is positioned on the insert row.
  1767. *
  1768. * The insert row is a special row associated with an updatable
  1769. * result set. It is essentially a buffer where a new row may
  1770. * be constructed by calling the updater methods prior to
  1771. * inserting the row into the result set.
  1772. *
  1773. * Only the updater, getter,
  1774. * and <code>insertRow</code> methods may be
  1775. * called when the cursor is on the insert row. All of the columns in
  1776. * a result set must be given a value each time this method is
  1777. * called before calling <code>insertRow</code>.
  1778. * An updater method must be called before a
  1779. * getter method can be called on a column value.
  1780. *
  1781. * @exception SQLException if a database access error occurs
  1782. * or the result set is not updatable
  1783. * @since 1.2
  1784. */
  1785. void moveToInsertRow() throws SQLException;
  1786. /**
  1787. * Moves the cursor to the remembered cursor position, usually the
  1788. * current row. This method has no effect if the cursor is not on
  1789. * the insert row.
  1790. *
  1791. * @exception SQLException if a database access error occurs
  1792. * or the result set is not updatable
  1793. * @since 1.2
  1794. */
  1795. void moveToCurrentRow() throws SQLException;
  1796. /**
  1797. * Retrieves the <code>Statement</code> object that produced this
  1798. * <code>ResultSet</code> object.
  1799. * If the result set was generated some other way, such as by a
  1800. * <code>DatabaseMetaData</code> method, this method returns
  1801. * <code>null</code>.
  1802. *
  1803. * @return the <code>Statment</code> object that produced
  1804. * this <code>ResultSet</code> object or <code>null</code>
  1805. * if the result set was produced some other way
  1806. * @exception SQLException if a database access error occurs
  1807. * @since 1.2
  1808. */
  1809. Statement getStatement() throws SQLException;
  1810. /**
  1811. * Retrieves the value of the designated column in the current row
  1812. * of this <code>ResultSet</code> object as an <code>Object</code>
  1813. * in the Java programming language.
  1814. * If the value is an SQL <code>NULL</code>,
  1815. * the driver returns a Java <code>null</code>.
  1816. * This method uses the given <code>Map</code> object
  1817. * for the custom mapping of the
  1818. * SQL structured or distinct type that is being retrieved.
  1819. *
  1820. * @param i the first column is 1, the second is 2, ...
  1821. * @param map a <code>java.util.Map</code> object that contains the mapping
  1822. * from SQL type names to classes in the Java programming language
  1823. * @return an <code>Object</code> in the Java programming language
  1824. * representing the SQL value
  1825. * @exception SQLException if a database access error occurs
  1826. * @since 1.2
  1827. */
  1828. Object getObject(int i, java.util.Map<String,Class<?>> map)
  1829. throws SQLException;
  1830. /**
  1831. * Retrieves the value of the designated column in the current row
  1832. * of this <code>ResultSet</code> object as a <code>Ref</code> object
  1833. * in the Java programming language.
  1834. *
  1835. * @param i the first column is 1, the second is 2, ...
  1836. * @return a <code>Ref</code> object representing an SQL <code>REF</code>
  1837. * value
  1838. * @exception SQLException if a database access error occurs
  1839. * @since 1.2
  1840. */
  1841. Ref getRef(int i) throws SQLException;
  1842. /**
  1843. * Retrieves the value of the designated column in the current row
  1844. * of this <code>ResultSet</code> object as a <code>Blob</code> object
  1845. * in the Java programming language.
  1846. *
  1847. * @param i the first column is 1, the second is 2, ...
  1848. * @return a <code>Blob</code> object representing the SQL
  1849. * <code>BLOB</code> value in the specified column
  1850. * @exception SQLException if a database access error occurs
  1851. * @since 1.2
  1852. */
  1853. Blob getBlob(int i) throws SQLException;
  1854. /**
  1855. * Retrieves the value of the designated column in the current row
  1856. * of this <code>ResultSet</code> object as a <code>Clob</code> object
  1857. * in the Java programming language.
  1858. *
  1859. * @param i the first column is 1, the second is 2, ...
  1860. * @return a <code>Clob</code> object representing the SQL
  1861. * <code>CLOB</code> value in the specified column
  1862. * @exception SQLException if a database access error occurs
  1863. * @since 1.2
  1864. */
  1865. Clob getClob(int i) throws SQLException;
  1866. /**
  1867. * Retrieves the value of the designated column in the current row
  1868. * of this <code>ResultSet</code> object as an <code>Array</code> object
  1869. * in the Java programming language.
  1870. *
  1871. * @param i the first column is 1, the second is 2, ...
  1872. * @return an <code>Array</code> object representing the SQL
  1873. * <code>ARRAY</code> value in the specified column
  1874. * @exception SQLException if a database access error occurs
  1875. * @since 1.2
  1876. */
  1877. Array getArray(int i) throws SQLException;
  1878. /**
  1879. * Retrieves the value of the designated column in the current row
  1880. * of this <code>ResultSet</code> object as an <code>Object</code>
  1881. * in the Java programming language.
  1882. * If the value is an SQL <code>NULL</code>,
  1883. * the driver returns a Java <code>null</code>.
  1884. * This method uses the specified <code>Map</code> object for
  1885. * custom mapping if appropriate.
  1886. *
  1887. * @param colName the name of the column from which to retrieve the value
  1888. * @param map a <code>java.util.Map</code> object that contains the mapping
  1889. * from SQL type names to classes in the Java programming language
  1890. * @return an <code>Object</code> representing the SQL value in the
  1891. * specified column
  1892. * @exception SQLException if a database access error occurs
  1893. * @since 1.2
  1894. */
  1895. Object getObject(String colName, java.util.Map<String,Class<?>> map)
  1896. throws SQLException;
  1897. /**
  1898. * Retrieves the value of the designated column in the current row
  1899. * of this <code>ResultSet</code> object as a <code>Ref</code> object
  1900. * in the Java programming language.
  1901. *
  1902. * @param colName the column name
  1903. * @return a <code>Ref</code> object representing the SQL <code>REF</code>
  1904. * value in the specified column
  1905. * @exception SQLException if a database access error occurs
  1906. * @since 1.2
  1907. */
  1908. Ref getRef(String colName) throws SQLException;
  1909. /**
  1910. * Retrieves the value of the designated column in the current row
  1911. * of this <code>ResultSet</code> object as a <code>Blob</code> object
  1912. * in the Java programming language.
  1913. *
  1914. * @param colName the name of the column from which to retrieve the value
  1915. * @return a <code>Blob</code> object representing the SQL <code>BLOB</code>
  1916. * value in the specified column
  1917. * @exception SQLException if a database access error occurs
  1918. * @since 1.2
  1919. */
  1920. Blob getBlob(String colName) throws SQLException;
  1921. /**
  1922. * Retrieves the value of the designated column in the current row
  1923. * of this <code>ResultSet</code> object as a <code>Clob</code> object
  1924. * in the Java programming language.
  1925. *
  1926. * @param colName the name of the column from which to retrieve the value
  1927. * @return a <code>Clob</code> object representing the SQL <code>CLOB</code>
  1928. * value in the specified column
  1929. * @exception SQLException if a database access error occurs
  1930. * @since 1.2
  1931. */
  1932. Clob getClob(String colName) throws SQLException;
  1933. /**
  1934. * Retrieves the value of the designated column in the current row
  1935. * of this <code>ResultSet</code> object as an <code>Array</code> object
  1936. * in the Java programming language.
  1937. *
  1938. * @param colName the name of the column from which to retrieve the value
  1939. * @return an <code>Array</code> object representing the SQL <code>ARRAY</code> value in
  1940. * the specified column
  1941. * @exception SQLException if a database access error occurs
  1942. * @since 1.2
  1943. */
  1944. Array getArray(String colName) throws SQLException;
  1945. /**
  1946. * Retrieves the value of the designated column in the current row
  1947. * of this <code>ResultSet</code> object as a <code>java.sql.Date</code> object
  1948. * in the Java programming language.
  1949. * This method uses the given calendar to construct an appropriate millisecond
  1950. * value for the date if the underlying database does not store
  1951. * timezone information.
  1952. *
  1953. * @param columnIndex the first column is 1, the second is 2, ...
  1954. * @param cal the <code>java.util.Calendar</code> object
  1955. * to use in constructing the date
  1956. * @return the column value as a <code>java.sql.Date</code> object;
  1957. * if the value is SQL <code>NULL</code>,
  1958. * the value returned is <code>null</code> in the Java programming language
  1959. * @exception SQLException if a database access error occurs
  1960. * @since 1.2
  1961. */
  1962. java.sql.Date getDate(int columnIndex, Calendar cal) throws SQLException;
  1963. /**
  1964. * Retrieves the value of the designated column in the current row
  1965. * of this <code>ResultSet</code> object as a <code>java.sql.Date</code> object
  1966. * in the Java programming language.
  1967. * This method uses the given calendar to construct an appropriate millisecond
  1968. * value for the date if the underlying database does not store
  1969. * timezone information.
  1970. *
  1971. * @param columnName the SQL name of the column from which to retrieve the value
  1972. * @param cal the <code>java.util.Calendar</code> object
  1973. * to use in constructing the date
  1974. * @return the column value as a <code>java.sql.Date</code> object;
  1975. * if the value is SQL <code>NULL</code>,
  1976. * the value returned is <code>null</code> in the Java programming language
  1977. * @exception SQLException if a database access error occurs
  1978. * @since 1.2
  1979. */
  1980. java.sql.Date getDate(String columnName, Calendar cal) throws SQLException;
  1981. /**
  1982. * Retrieves the value of the designated column in the current row
  1983. * of this <code>ResultSet</code> object as a <code>java.sql.Time</code> object
  1984. * in the Java programming language.
  1985. * This method uses the given calendar to construct an appropriate millisecond
  1986. * value for the time if the underlying database does not store
  1987. * timezone information.
  1988. *
  1989. * @param columnIndex the first column is 1, the second is 2, ...
  1990. * @param cal the <code>java.util.Calendar</code> object
  1991. * to use in constructing the time
  1992. * @return the column value as a <code>java.sql.Time</code> object;
  1993. * if the value is SQL <code>NULL</code>,
  1994. * the value returned is <code>null</code> in the Java programming language
  1995. * @exception SQLException if a database access error occurs
  1996. * @since 1.2
  1997. */
  1998. java.sql.Time getTime(int columnIndex, Calendar cal) throws SQLException;
  1999. /**
  2000. * Retrieves the value of the designated column in the current row
  2001. * of this <code>ResultSet</code> object as a <code>java.sql.Time</code> object
  2002. * in the Java programming language.
  2003. * This method uses the given calendar to construct an appropriate millisecond
  2004. * value for the time if the underlying database does not store
  2005. * timezone information.
  2006. *
  2007. * @param columnName the SQL name of the column
  2008. * @param cal the <code>java.util.Calendar</code> object
  2009. * to use in constructing the time
  2010. * @return the column value as a <code>java.sql.Time</code> object;
  2011. * if the value is SQL <code>NULL</code>,
  2012. * the value returned is <code>null</code> in the Java programming language
  2013. * @exception SQLException if a database access error occurs
  2014. * @since 1.2
  2015. */
  2016. java.sql.Time getTime(String columnName, Calendar cal) throws SQLException;
  2017. /**
  2018. * Retrieves the value of the designated column in the current row
  2019. * of this <code>ResultSet</code> object as a <code>java.sql.Timestamp</code> object
  2020. * in the Java programming language.
  2021. * This method uses the given calendar to construct an appropriate millisecond
  2022. * value for the timestamp if the underlying database does not store
  2023. * timezone information.
  2024. *
  2025. * @param columnIndex the first column is 1, the second is 2, ...
  2026. * @param cal the <code>java.util.Calendar</code> object
  2027. * to use in constructing the timestamp
  2028. * @return the column value as a <code>java.sql.Timestamp</code> object;
  2029. * if the value is SQL <code>NULL</code>,
  2030. * the value returned is <code>null</code> in the Java programming language
  2031. * @exception SQLException if a database access error occurs
  2032. * @since 1.2
  2033. */
  2034. java.sql.Timestamp getTimestamp(int columnIndex, Calendar cal)
  2035. throws SQLException;
  2036. /**
  2037. * Retrieves the value of the designated column in the current row
  2038. * of this <code>ResultSet</code> object as a <code>java.sql.Timestamp</code> object
  2039. * in the Java programming language.
  2040. * This method uses the given calendar to construct an appropriate millisecond
  2041. * value for the timestamp if the underlying database does not store
  2042. * timezone information.
  2043. *
  2044. * @param columnName the SQL name of the column
  2045. * @param cal the <code>java.util.Calendar</code> object
  2046. * to use in constructing the date
  2047. * @return the column value as a <code>java.sql.Timestamp</code> object;
  2048. * if the value is SQL <code>NULL</code>,
  2049. * the value returned is <code>null</code> in the Java programming language
  2050. * @exception SQLException if a database access error occurs
  2051. * @since 1.2
  2052. */
  2053. java.sql.Timestamp getTimestamp(String columnName, Calendar cal)
  2054. throws SQLException;
  2055. //-------------------------- JDBC 3.0 ----------------------------------------
  2056. /**
  2057. * The constant indicating that <code>ResultSet</code> objects should not
  2058. * be closed when the method <code>Connection.commit</code> is called.
  2059. *
  2060. * @since 1.4
  2061. */
  2062. int HOLD_CURSORS_OVER_COMMIT = 1;
  2063. /**
  2064. * The constant indicating that <code>ResultSet</code> objects should be
  2065. * closed when the method <code>Connection.commit</code> is called.
  2066. *
  2067. * @since 1.4
  2068. */
  2069. int CLOSE_CURSORS_AT_COMMIT = 2;
  2070. /**
  2071. * Retrieves the value of the designated column in the current row
  2072. * of this <code>ResultSet</code> object as a <code>java.net.URL</code>
  2073. * object in the Java programming language.
  2074. *
  2075. * @param columnIndex the index of the column 1 is the first, 2 is the second,...
  2076. * @return the column value as a <code>java.net.URL</code> object;
  2077. * if the value is SQL <code>NULL</code>,
  2078. * the value returned is <code>null</code> in the Java programming language
  2079. * @exception SQLException if a database access error occurs,
  2080. * or if a URL is malformed
  2081. * @since 1.4
  2082. */
  2083. java.net.URL getURL(int columnIndex) throws SQLException;
  2084. /**
  2085. * Retrieves the value of the designated column in the current row
  2086. * of this <code>ResultSet</code> object as a <code>java.net.URL</code>
  2087. * object in the Java programming language.
  2088. *
  2089. * @param columnName the SQL name of the column
  2090. * @return the column value as a <code>java.net.URL</code> object;
  2091. * if the value is SQL <code>NULL</code>,
  2092. * the value returned is <code>null</code> in the Java programming language
  2093. * @exception SQLException if a database access error occurs
  2094. * or if a URL is malformed
  2095. * @since 1.4
  2096. */
  2097. java.net.URL getURL(String columnName) throws SQLException;
  2098. /**
  2099. * Updates the designated column with a <code>java.sql.Ref</code> value.
  2100. * The updater methods are used to update column values in the
  2101. * current row or the insert row. The updater methods do not
  2102. * update the underlying database; instead the <code>updateRow</code> or
  2103. * <code>insertRow</code> methods are called to update the database.
  2104. *
  2105. * @param columnIndex the first column is 1, the second is 2, ...
  2106. * @param x the new column value
  2107. * @exception SQLException if a database access error occurs
  2108. * @since 1.4
  2109. */
  2110. void updateRef(int columnIndex, java.sql.Ref x) throws SQLException;
  2111. /**
  2112. * Updates the designated column with a <code>java.sql.Ref</code> value.
  2113. * The updater methods are used to update column values in the
  2114. * current row or the insert row. The updater methods do not
  2115. * update the underlying database; instead the <code>updateRow</code> or
  2116. * <code>insertRow</code> methods are called to update the database.
  2117. *
  2118. * @param columnName the name of the column
  2119. * @param x the new column value
  2120. * @exception SQLException if a database access error occurs
  2121. * @since 1.4
  2122. */
  2123. void updateRef(String columnName, java.sql.Ref x) throws SQLException;
  2124. /**
  2125. * Updates the designated column with a <code>java.sql.Blob</code> value.
  2126. * The updater methods are used to update column values in the
  2127. * current row or the insert row. The updater methods do not
  2128. * update the underlying database; instead the <code>updateRow</code> or
  2129. * <code>insertRow</code> methods are called to update the database.
  2130. *
  2131. * @param columnIndex the first column is 1, the second is 2, ...
  2132. * @param x the new column value
  2133. * @exception SQLException if a database access error occurs
  2134. * @since 1.4
  2135. */
  2136. void updateBlob(int columnIndex, java.sql.Blob x) throws SQLException;
  2137. /**
  2138. * Updates the designated column with a <code>java.sql.Blob</code> value.
  2139. * The updater methods are used to update column values in the
  2140. * current row or the insert row. The updater methods do not
  2141. * update the underlying database; instead the <code>updateRow</code> or
  2142. * <code>insertRow</code> methods are called to update the database.
  2143. *
  2144. * @param columnName the name of the column
  2145. * @param x the new column value
  2146. * @exception SQLException if a database access error occurs
  2147. * @since 1.4
  2148. */
  2149. void updateBlob(String columnName, java.sql.Blob x) throws SQLException;
  2150. /**
  2151. * Updates the designated column with a <code>java.sql.Clob</code> value.
  2152. * The updater methods are used to update column values in the
  2153. * current row or the insert row. The updater methods do not
  2154. * update the underlying database; instead the <code>updateRow</code> or
  2155. * <code>insertRow</code> methods are called to update the database.
  2156. *
  2157. * @param columnIndex the first column is 1, the second is 2, ...
  2158. * @param x the new column value
  2159. * @exception SQLException if a database access error occurs
  2160. * @since 1.4
  2161. */
  2162. void updateClob(int columnIndex, java.sql.Clob x) throws SQLException;
  2163. /**
  2164. * Updates the designated column with a <code>java.sql.Clob</code> value.
  2165. * The updater methods are used to update column values in the
  2166. * current row or the insert row. The updater methods do not
  2167. * update the underlying database; instead the <code>updateRow</code> or
  2168. * <code>insertRow</code> methods are called to update the database.
  2169. *
  2170. * @param columnName the name of the column
  2171. * @param x the new column value
  2172. * @exception SQLException if a database access error occurs
  2173. * @since 1.4
  2174. */
  2175. void updateClob(String columnName, java.sql.Clob x) throws SQLException;
  2176. /**
  2177. * Updates the designated column with a <code>java.sql.Array</code> value.
  2178. * The updater methods are used to update column values in the
  2179. * current row or the insert row. The updater methods do not
  2180. * update the underlying database; instead the <code>updateRow</code> or
  2181. * <code>insertRow</code> methods are called to update the database.
  2182. *
  2183. * @param columnIndex the first column is 1, the second is 2, ...
  2184. * @param x the new column value
  2185. * @exception SQLException if a database access error occurs
  2186. * @since 1.4
  2187. */
  2188. void updateArray(int columnIndex, java.sql.Array x) throws SQLException;
  2189. /**
  2190. * Updates the designated column with a <code>java.sql.Array</code> value.
  2191. * The updater methods are used to update column values in the
  2192. * current row or the insert row. The updater methods do not
  2193. * update the underlying database; instead the <code>updateRow</code> or
  2194. * <code>insertRow</code> methods are called to update the database.
  2195. *
  2196. * @param columnName the name of the column
  2197. * @param x the new column value
  2198. * @exception SQLException if a database access error occurs
  2199. * @since 1.4
  2200. */
  2201. void updateArray(String columnName, java.sql.Array x) throws SQLException;
  2202. }