1. /*
  2. * @(#)Statement.java 1.40 03/12/19
  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. /**
  9. * <P>The object used for executing a static SQL statement
  10. * and returning the results it produces.
  11. * <P>
  12. * By default, only one <code>ResultSet</code> object per <code>Statement</code>
  13. * object can be open at the same time. Therefore, if the reading of one
  14. * <code>ResultSet</code> object is interleaved
  15. * with the reading of another, each must have been generated by
  16. * different <code>Statement</code> objects. All execution methods in the
  17. * <code>Statement</code> interface implicitly close a statment's current
  18. * <code>ResultSet</code> object if an open one exists.
  19. *
  20. * @see Connection#createStatement
  21. * @see ResultSet
  22. */
  23. public interface Statement {
  24. /**
  25. * Executes the given SQL statement, which returns a single
  26. * <code>ResultSet</code> object.
  27. *
  28. * @param sql an SQL statement to be sent to the database, typically a
  29. * static SQL <code>SELECT</code> statement
  30. * @return a <code>ResultSet</code> object that contains the data produced
  31. * by the given query; never <code>null</code>
  32. * @exception SQLException if a database access error occurs or the given
  33. * SQL statement produces anything other than a single
  34. * <code>ResultSet</code> object
  35. */
  36. ResultSet executeQuery(String sql) throws SQLException;
  37. /**
  38. * Executes the given SQL statement, which may be an <code>INSERT</code>,
  39. * <code>UPDATE</code>, or <code>DELETE</code> statement or an
  40. * SQL statement that returns nothing, such as an SQL DDL statement.
  41. *
  42. * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
  43. * <code>DELETE</code> statement or an SQL statement that returns nothing
  44. * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
  45. * or <code>DELETE</code> statements, or <code>0</code> for SQL statements
  46. * that return nothing
  47. * @exception SQLException if a database access error occurs or the given
  48. * SQL statement produces a <code>ResultSet</code> object
  49. */
  50. int executeUpdate(String sql) throws SQLException;
  51. /**
  52. * Releases this <code>Statement</code> object's database
  53. * and JDBC resources immediately instead of waiting for
  54. * this to happen when it is automatically closed.
  55. * It is generally good practice to release resources as soon as
  56. * you are finished with them to avoid tying up database
  57. * resources.
  58. * <P>
  59. * Calling the method <code>close</code> on a <code>Statement</code>
  60. * object that is already closed has no effect.
  61. * <P>
  62. * <B>Note:</B> A <code>Statement</code> object is automatically closed
  63. * when it is garbage collected. When a <code>Statement</code> object is
  64. * closed, its current <code>ResultSet</code> object, if one exists, is
  65. * also closed.
  66. *
  67. * @exception SQLException if a database access error occurs
  68. */
  69. void close() throws SQLException;
  70. //----------------------------------------------------------------------
  71. /**
  72. * Retrieves the maximum number of bytes that can be
  73. * returned for character and binary column values in a <code>ResultSet</code>
  74. * object produced by this <code>Statement</code> object.
  75. * This limit applies only to <code>BINARY</code>,
  76. * <code>VARBINARY</code>, <code>LONGVARBINARY</code>, <code>CHAR</code>,
  77. * <code>VARCHAR</code>, and <code>LONGVARCHAR</code>
  78. * columns. If the limit is exceeded, the excess data is silently
  79. * discarded.
  80. *
  81. * @return the current column size limit for columns storing character and
  82. * binary values; zero means there is no limit
  83. * @exception SQLException if a database access error occurs
  84. * @see #setMaxFieldSize
  85. */
  86. int getMaxFieldSize() throws SQLException;
  87. /**
  88. * Sets the limit for the maximum number of bytes in a <code>ResultSet</code>
  89. * column storing character or binary values to
  90. * the given number of bytes. This limit applies
  91. * only to <code>BINARY</code>, <code>VARBINARY</code>,
  92. * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>, and
  93. * <code>LONGVARCHAR</code> fields. If the limit is exceeded, the excess data
  94. * is silently discarded. For maximum portability, use values
  95. * greater than 256.
  96. *
  97. * @param max the new column size limit in bytes; zero means there is no limit
  98. * @exception SQLException if a database access error occurs
  99. * or the condition max >= 0 is not satisfied
  100. * @see #getMaxFieldSize
  101. */
  102. void setMaxFieldSize(int max) throws SQLException;
  103. /**
  104. * Retrieves the maximum number of rows that a
  105. * <code>ResultSet</code> object produced by this
  106. * <code>Statement</code> object can contain. If this limit is exceeded,
  107. * the excess rows are silently dropped.
  108. *
  109. * @return the current maximum number of rows for a <code>ResultSet</code>
  110. * object produced by this <code>Statement</code> object;
  111. * zero means there is no limit
  112. * @exception SQLException if a database access error occurs
  113. * @see #setMaxRows
  114. */
  115. int getMaxRows() throws SQLException;
  116. /**
  117. * Sets the limit for the maximum number of rows that any
  118. * <code>ResultSet</code> object can contain to the given number.
  119. * If the limit is exceeded, the excess
  120. * rows are silently dropped.
  121. *
  122. * @param max the new max rows limit; zero means there is no limit
  123. * @exception SQLException if a database access error occurs
  124. * or the condition max >= 0 is not satisfied
  125. * @see #getMaxRows
  126. */
  127. void setMaxRows(int max) throws SQLException;
  128. /**
  129. * Sets escape processing on or off.
  130. * If escape scanning is on (the default), the driver will do
  131. * escape substitution before sending the SQL statement to the database.
  132. *
  133. * Note: Since prepared statements have usually been parsed prior
  134. * to making this call, disabling escape processing for
  135. * <code>PreparedStatements</code> objects will have no effect.
  136. *
  137. * @param enable <code>true</code> to enable escape processing;
  138. * <code>false</code> to disable it
  139. * @exception SQLException if a database access error occurs
  140. */
  141. void setEscapeProcessing(boolean enable) throws SQLException;
  142. /**
  143. * Retrieves the number of seconds the driver will
  144. * wait for a <code>Statement</code> object to execute. If the limit is exceeded, a
  145. * <code>SQLException</code> is thrown.
  146. *
  147. * @return the current query timeout limit in seconds; zero means there is
  148. * no limit
  149. * @exception SQLException if a database access error occurs
  150. * @see #setQueryTimeout
  151. */
  152. int getQueryTimeout() throws SQLException;
  153. /**
  154. * Sets the number of seconds the driver will wait for a
  155. * <code>Statement</code> object to execute to the given number of seconds.
  156. * If the limit is exceeded, an <code>SQLException</code> is thrown.
  157. *
  158. * @param seconds the new query timeout limit in seconds; zero means
  159. * there is no limit
  160. * @exception SQLException if a database access error occurs
  161. * or the condition seconds >= 0 is not satisfied
  162. * @see #getQueryTimeout
  163. */
  164. void setQueryTimeout(int seconds) throws SQLException;
  165. /**
  166. * Cancels this <code>Statement</code> object if both the DBMS and
  167. * driver support aborting an SQL statement.
  168. * This method can be used by one thread to cancel a statement that
  169. * is being executed by another thread.
  170. *
  171. * @exception SQLException if a database access error occurs
  172. */
  173. void cancel() throws SQLException;
  174. /**
  175. * Retrieves the first warning reported by calls on this <code>Statement</code> object.
  176. * Subsequent <code>Statement</code> object warnings will be chained to this
  177. * <code>SQLWarning</code> object.
  178. *
  179. * <p>The warning chain is automatically cleared each time
  180. * a statement is (re)executed. This method may not be called on a closed
  181. * <code>Statement</code> object; doing so will cause an <code>SQLException</code>
  182. * to be thrown.
  183. *
  184. * <P><B>Note:</B> If you are processing a <code>ResultSet</code> object, any
  185. * warnings associated with reads on that <code>ResultSet</code> object
  186. * will be chained on it rather than on the <code>Statement</code>
  187. * object that produced it.
  188. *
  189. * @return the first <code>SQLWarning</code> object or <code>null</code>
  190. * if there are no warnings
  191. * @exception SQLException if a database access error occurs or this
  192. * method is called on a closed statement
  193. */
  194. SQLWarning getWarnings() throws SQLException;
  195. /**
  196. * Clears all the warnings reported on this <code>Statement</code>
  197. * object. After a call to this method,
  198. * the method <code>getWarnings</code> will return
  199. * <code>null</code> until a new warning is reported for this
  200. * <code>Statement</code> object.
  201. *
  202. * @exception SQLException if a database access error occurs
  203. */
  204. void clearWarnings() throws SQLException;
  205. /**
  206. * Sets the SQL cursor name to the given <code>String</code>, which
  207. * will be used by subsequent <code>Statement</code> object
  208. * <code>execute</code> methods. This name can then be
  209. * used in SQL positioned update or delete statements to identify the
  210. * current row in the <code>ResultSet</code> object generated by this
  211. * statement. If the database does not support positioned update/delete,
  212. * this method is a noop. To insure that a cursor has the proper isolation
  213. * level to support updates, the cursor's <code>SELECT</code> statement
  214. * should have the form <code>SELECT FOR UPDATE</code>. If
  215. * <code>FOR UPDATE</code> is not present, positioned updates may fail.
  216. *
  217. * <P><B>Note:</B> By definition, the execution of positioned updates and
  218. * deletes must be done by a different <code>Statement</code> object than
  219. * the one that generated the <code>ResultSet</code> object being used for
  220. * positioning. Also, cursor names must be unique within a connection.
  221. *
  222. * @param name the new cursor name, which must be unique within
  223. * a connection
  224. * @exception SQLException if a database access error occurs
  225. */
  226. void setCursorName(String name) throws SQLException;
  227. //----------------------- Multiple Results --------------------------
  228. /**
  229. * Executes the given SQL statement, which may return multiple results.
  230. * In some (uncommon) situations, a single SQL statement may return
  231. * multiple result sets and/or update counts. Normally you can ignore
  232. * this unless you are (1) executing a stored procedure that you know may
  233. * return multiple results or (2) you are dynamically executing an
  234. * unknown SQL string.
  235. * <P>
  236. * The <code>execute</code> method executes an SQL statement and indicates the
  237. * form of the first result. You must then use the methods
  238. * <code>getResultSet</code> or <code>getUpdateCount</code>
  239. * to retrieve the result, and <code>getMoreResults</code> to
  240. * move to any subsequent result(s).
  241. *
  242. * @param sql any SQL statement
  243. * @return <code>true</code> if the first result is a <code>ResultSet</code>
  244. * object; <code>false</code> if it is an update count or there are
  245. * no results
  246. * @exception SQLException if a database access error occurs
  247. * @see #getResultSet
  248. * @see #getUpdateCount
  249. * @see #getMoreResults
  250. */
  251. boolean execute(String sql) throws SQLException;
  252. /**
  253. * Retrieves the current result as a <code>ResultSet</code> object.
  254. * This method should be called only once per result.
  255. *
  256. * @return the current result as a <code>ResultSet</code> object or
  257. * <code>null</code> if the result is an update count or there are no more results
  258. * @exception SQLException if a database access error occurs
  259. * @see #execute
  260. */
  261. ResultSet getResultSet() throws SQLException;
  262. /**
  263. * Retrieves the current result as an update count;
  264. * if the result is a <code>ResultSet</code> object or there are no more results, -1
  265. * is returned. This method should be called only once per result.
  266. *
  267. * @return the current result as an update count; -1 if the current result is a
  268. * <code>ResultSet</code> object or there are no more results
  269. * @exception SQLException if a database access error occurs
  270. * @see #execute
  271. */
  272. int getUpdateCount() throws SQLException;
  273. /**
  274. * Moves to this <code>Statement</code> object's next result, returns
  275. * <code>true</code> if it is a <code>ResultSet</code> object, and
  276. * implicitly closes any current <code>ResultSet</code>
  277. * object(s) obtained with the method <code>getResultSet</code>.
  278. *
  279. * <P>There are no more results when the following is true:
  280. * <PRE>
  281. * // stmt is a Statement object
  282. * ((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))
  283. * </PRE>
  284. *
  285. * @return <code>true</code> if the next result is a <code>ResultSet</code>
  286. * object; <code>false</code> if it is an update count or there are
  287. * no more results
  288. * @exception SQLException if a database access error occurs
  289. * @see #execute
  290. */
  291. boolean getMoreResults() throws SQLException;
  292. //--------------------------JDBC 2.0-----------------------------
  293. /**
  294. * Gives the driver a hint as to the direction in which
  295. * rows will be processed in <code>ResultSet</code>
  296. * objects created using this <code>Statement</code> object. The
  297. * default value is <code>ResultSet.FETCH_FORWARD</code>.
  298. * <P>
  299. * Note that this method sets the default fetch direction for
  300. * result sets generated by this <code>Statement</code> object.
  301. * Each result set has its own methods for getting and setting
  302. * its own fetch direction.
  303. *
  304. * @param direction the initial direction for processing rows
  305. * @exception SQLException if a database access error occurs
  306. * or the given direction
  307. * is not one of <code>ResultSet.FETCH_FORWARD</code>,
  308. * <code>ResultSet.FETCH_REVERSE</code>, or <code>ResultSet.FETCH_UNKNOWN</code>
  309. * @since 1.2
  310. * @see #getFetchDirection
  311. */
  312. void setFetchDirection(int direction) throws SQLException;
  313. /**
  314. * Retrieves the direction for fetching rows from
  315. * database tables that is the default for result sets
  316. * generated from this <code>Statement</code> object.
  317. * If this <code>Statement</code> object has not set
  318. * a fetch direction by calling the method <code>setFetchDirection</code>,
  319. * the return value is implementation-specific.
  320. *
  321. * @return the default fetch direction for result sets generated
  322. * from this <code>Statement</code> object
  323. * @exception SQLException if a database access error occurs
  324. * @since 1.2
  325. * @see #setFetchDirection
  326. */
  327. int getFetchDirection() throws SQLException;
  328. /**
  329. * Gives the JDBC driver a hint as to the number of rows that should
  330. * be fetched from the database when more rows are needed. The number
  331. * of rows specified affects only result sets created using this
  332. * statement. If the value specified is zero, then the hint is ignored.
  333. * The default value is zero.
  334. *
  335. * @param rows the number of rows to fetch
  336. * @exception SQLException if a database access error occurs, or the
  337. * condition 0 <= <code>rows</code> <= <code>this.getMaxRows()</code>
  338. * is not satisfied.
  339. * @since 1.2
  340. * @see #getFetchSize
  341. */
  342. void setFetchSize(int rows) throws SQLException;
  343. /**
  344. * Retrieves the number of result set rows that is the default
  345. * fetch size for <code>ResultSet</code> objects
  346. * generated from this <code>Statement</code> object.
  347. * If this <code>Statement</code> object has not set
  348. * a fetch size by calling the method <code>setFetchSize</code>,
  349. * the return value is implementation-specific.
  350. *
  351. * @return the default fetch size for result sets generated
  352. * from this <code>Statement</code> object
  353. * @exception SQLException if a database access error occurs
  354. * @since 1.2
  355. * @see #setFetchSize
  356. */
  357. int getFetchSize() throws SQLException;
  358. /**
  359. * Retrieves the result set concurrency for <code>ResultSet</code> objects
  360. * generated by this <code>Statement</code> object.
  361. *
  362. * @return either <code>ResultSet.CONCUR_READ_ONLY</code> or
  363. * <code>ResultSet.CONCUR_UPDATABLE</code>
  364. * @exception SQLException if a database access error occurs
  365. * @since 1.2
  366. */
  367. int getResultSetConcurrency() throws SQLException;
  368. /**
  369. * Retrieves the result set type for <code>ResultSet</code> objects
  370. * generated by this <code>Statement</code> object.
  371. *
  372. * @return one of <code>ResultSet.TYPE_FORWARD_ONLY</code>,
  373. * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
  374. * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
  375. * @exception SQLException if a database access error occurs
  376. * @since 1.2
  377. */
  378. int getResultSetType() throws SQLException;
  379. /**
  380. * Adds the given SQL command to the current list of commmands for this
  381. * <code>Statement</code> object. The commands in this list can be
  382. * executed as a batch by calling the method <code>executeBatch</code>.
  383. * <P>
  384. * <B>NOTE:</B> This method is optional.
  385. *
  386. * @param sql typically this is a static SQL <code>INSERT</code> or
  387. * <code>UPDATE</code> statement
  388. * @exception SQLException if a database access error occurs, or the
  389. * driver does not support batch updates
  390. * @see #executeBatch
  391. * @since 1.2
  392. */
  393. void addBatch( String sql ) throws SQLException;
  394. /**
  395. * Empties this <code>Statement</code> object's current list of
  396. * SQL commands.
  397. * <P>
  398. * <B>NOTE:</B> This method is optional.
  399. *
  400. * @exception SQLException if a database access error occurs or the
  401. * driver does not support batch updates
  402. * @see #addBatch
  403. * @since 1.2
  404. */
  405. void clearBatch() throws SQLException;
  406. /**
  407. * Submits a batch of commands to the database for execution and
  408. * if all commands execute successfully, returns an array of update counts.
  409. * The <code>int</code> elements of the array that is returned are ordered
  410. * to correspond to the commands in the batch, which are ordered
  411. * according to the order in which they were added to the batch.
  412. * The elements in the array returned by the method <code>executeBatch</code>
  413. * may be one of the following:
  414. * <OL>
  415. * <LI>A number greater than or equal to zero -- indicates that the
  416. * command was processed successfully and is an update count giving the
  417. * number of rows in the database that were affected by the command's
  418. * execution
  419. * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
  420. * processed successfully but that the number of rows affected is
  421. * unknown
  422. * <P>
  423. * If one of the commands in a batch update fails to execute properly,
  424. * this method throws a <code>BatchUpdateException</code>, and a JDBC
  425. * driver may or may not continue to process the remaining commands in
  426. * the batch. However, the driver's behavior must be consistent with a
  427. * particular DBMS, either always continuing to process commands or never
  428. * continuing to process commands. If the driver continues processing
  429. * after a failure, the array returned by the method
  430. * <code>BatchUpdateException.getUpdateCounts</code>
  431. * will contain as many elements as there are commands in the batch, and
  432. * at least one of the elements will be the following:
  433. * <P>
  434. * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
  435. * to execute successfully and occurs only if a driver continues to
  436. * process commands after a command fails
  437. * </OL>
  438. * <P>
  439. * A driver is not required to implement this method.
  440. * The possible implementations and return values have been modified in
  441. * the Java 2 SDK, Standard Edition, version 1.3 to
  442. * accommodate the option of continuing to proccess commands in a batch
  443. * update after a <code>BatchUpdateException</code> obejct has been thrown.
  444. *
  445. * @return an array of update counts containing one element for each
  446. * command in the batch. The elements of the array are ordered according
  447. * to the order in which commands were added to the batch.
  448. * @exception SQLException if a database access error occurs or the
  449. * driver does not support batch statements. Throws {@link BatchUpdateException}
  450. * (a subclass of <code>SQLException</code>) if one of the commands sent to the
  451. * database fails to execute properly or attempts to return a result set.
  452. * @since 1.3
  453. */
  454. int[] executeBatch() throws SQLException;
  455. /**
  456. * Retrieves the <code>Connection</code> object
  457. * that produced this <code>Statement</code> object.
  458. * @return the connection that produced this statement
  459. * @exception SQLException if a database access error occurs
  460. * @since 1.2
  461. */
  462. Connection getConnection() throws SQLException;
  463. //--------------------------JDBC 3.0-----------------------------
  464. /**
  465. * The constant indicating that the current <code>ResultSet</code> object
  466. * should be closed when calling <code>getMoreResults</code>.
  467. *
  468. * @since 1.4
  469. */
  470. int CLOSE_CURRENT_RESULT = 1;
  471. /**
  472. * The constant indicating that the current <code>ResultSet</code> object
  473. * should not be closed when calling <code>getMoreResults</code>.
  474. *
  475. * @since 1.4
  476. */
  477. int KEEP_CURRENT_RESULT = 2;
  478. /**
  479. * The constant indicating that all <code>ResultSet</code> objects that
  480. * have previously been kept open should be closed when calling
  481. * <code>getMoreResults</code>.
  482. *
  483. * @since 1.4
  484. */
  485. int CLOSE_ALL_RESULTS = 3;
  486. /**
  487. * The constant indicating that a batch statement executed successfully
  488. * but that no count of the number of rows it affected is available.
  489. *
  490. * @since 1.4
  491. */
  492. int SUCCESS_NO_INFO = -2;
  493. /**
  494. * The constant indicating that an error occured while executing a
  495. * batch statement.
  496. *
  497. * @since 1.4
  498. */
  499. int EXECUTE_FAILED = -3;
  500. /**
  501. * The constant indicating that generated keys should be made
  502. * available for retrieval.
  503. *
  504. * @since 1.4
  505. */
  506. int RETURN_GENERATED_KEYS = 1;
  507. /**
  508. * The constant indicating that generated keys should not be made
  509. * available for retrieval.
  510. *
  511. * @since 1.4
  512. */
  513. int NO_GENERATED_KEYS = 2;
  514. /**
  515. * Moves to this <code>Statement</code> object's next result, deals with
  516. * any current <code>ResultSet</code> object(s) according to the instructions
  517. * specified by the given flag, and returns
  518. * <code>true</code> if the next result is a <code>ResultSet</code> object.
  519. *
  520. * <P>There are no more results when the following is true:
  521. * <PRE>
  522. * // stmt is a Statement object
  523. * ((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))
  524. * </PRE>
  525. *
  526. * @param current one of the following <code>Statement</code>
  527. * constants indicating what should happen to current
  528. * <code>ResultSet</code> objects obtained using the method
  529. * <code>getResultSet</code>:
  530. * <code>Statement.CLOSE_CURRENT_RESULT</code>,
  531. * <code>Statement.KEEP_CURRENT_RESULT</code>, or
  532. * <code>Statement.CLOSE_ALL_RESULTS</code>
  533. * @return <code>true</code> if the next result is a <code>ResultSet</code>
  534. * object; <code>false</code> if it is an update count or there are no
  535. * more results
  536. * @exception SQLException if a database access error occurs or the argument
  537. * supplied is not one of the following:
  538. * <code>Statement.CLOSE_CURRENT_RESULT</code>,
  539. * <code>Statement.KEEP_CURRENT_RESULT</code>, or
  540. * <code>Statement.CLOSE_ALL_RESULTS</code>
  541. * @since 1.4
  542. * @see #execute
  543. */
  544. boolean getMoreResults(int current) throws SQLException;
  545. /**
  546. * Retrieves any auto-generated keys created as a result of executing this
  547. * <code>Statement</code> object. If this <code>Statement</code> object did
  548. * not generate any keys, an empty <code>ResultSet</code>
  549. * object is returned.
  550. *
  551. * @return a <code>ResultSet</code> object containing the auto-generated key(s)
  552. * generated by the execution of this <code>Statement</code> object
  553. * @exception SQLException if a database access error occurs
  554. * @since 1.4
  555. */
  556. ResultSet getGeneratedKeys() throws SQLException;
  557. /**
  558. * Executes the given SQL statement and signals the driver with the
  559. * given flag about whether the
  560. * auto-generated keys produced by this <code>Statement</code> object
  561. * should be made available for retrieval.
  562. *
  563. * @param sql must be an SQL <code>INSERT</code>, <code>UPDATE</code> or
  564. * <code>DELETE</code> statement or an SQL statement that
  565. * returns nothing
  566. * @param autoGeneratedKeys a flag indicating whether auto-generated keys
  567. * should be made available for retrieval;
  568. * one of the following constants:
  569. * <code>Statement.RETURN_GENERATED_KEYS</code>
  570. * <code>Statement.NO_GENERATED_KEYS</code>
  571. * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
  572. * or <code>DELETE</code> statements, or <code>0</code> for SQL
  573. * statements that return nothing
  574. * @exception SQLException if a database access error occurs, the given
  575. * SQL statement returns a <code>ResultSet</code> object, or
  576. * the given constant is not one of those allowed
  577. * @since 1.4
  578. */
  579. int executeUpdate(String sql, int autoGeneratedKeys) throws SQLException;
  580. /**
  581. * Executes the given SQL statement and signals the driver that the
  582. * auto-generated keys indicated in the given array should be made available
  583. * for retrieval. The driver will ignore the array if the SQL statement
  584. * is not an <code>INSERT</code> statement.
  585. *
  586. * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
  587. * <code>DELETE</code> statement or an SQL statement that returns nothing,
  588. * such as an SQL DDL statement
  589. * @param columnIndexes an array of column indexes indicating the columns
  590. * that should be returned from the inserted row
  591. * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
  592. * or <code>DELETE</code> statements, or 0 for SQL statements
  593. * that return nothing
  594. * @exception SQLException if a database access error occurs, the SQL
  595. * statement returns a <code>ResultSet</code> object, or the
  596. * second argument supplied to this method is not an <code>int</code> array
  597. * whose elements are valid column indexes
  598. * @since 1.4
  599. */
  600. int executeUpdate(String sql, int columnIndexes[]) throws SQLException;
  601. /**
  602. * Executes the given SQL statement and signals the driver that the
  603. * auto-generated keys indicated in the given array should be made available
  604. * for retrieval. The driver will ignore the array if the SQL statement
  605. * is not an <code>INSERT</code> statement.
  606. *
  607. * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
  608. * <code>DELETE</code> statement or an SQL statement that returns nothing
  609. * @param columnNames an array of the names of the columns that should be
  610. * returned from the inserted row
  611. * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
  612. * or <code>DELETE</code> statements, or 0 for SQL statements
  613. * that return nothing
  614. * @exception SQLException if a database access error occurs, the SQL
  615. * statement returns a <code>ResultSet</code> object, or the
  616. * second argument supplied to this method is not a <code>String</code> array
  617. * whose elements are valid column names
  618. *
  619. * @since 1.4
  620. */
  621. int executeUpdate(String sql, String columnNames[]) throws SQLException;
  622. /**
  623. * Executes the given SQL statement, which may return multiple results,
  624. * and signals the driver that any
  625. * auto-generated keys should be made available
  626. * for retrieval. The driver will ignore this signal if the SQL statement
  627. * is not an <code>INSERT</code> statement.
  628. * <P>
  629. * In some (uncommon) situations, a single SQL statement may return
  630. * multiple result sets and/or update counts. Normally you can ignore
  631. * this unless you are (1) executing a stored procedure that you know may
  632. * return multiple results or (2) you are dynamically executing an
  633. * unknown SQL string.
  634. * <P>
  635. * The <code>execute</code> method executes an SQL statement and indicates the
  636. * form of the first result. You must then use the methods
  637. * <code>getResultSet</code> or <code>getUpdateCount</code>
  638. * to retrieve the result, and <code>getMoreResults</code> to
  639. * move to any subsequent result(s).
  640. *
  641. * @param sql any SQL statement
  642. * @param autoGeneratedKeys a constant indicating whether auto-generated
  643. * keys should be made available for retrieval using the method
  644. * <code>getGeneratedKeys</code> one of the following constants:
  645. * <code>Statement.RETURN_GENERATED_KEYS</code> or
  646. * <code>Statement.NO_GENERATED_KEYS</code>
  647. * @return <code>true</code> if the first result is a <code>ResultSet</code>
  648. * object; <code>false</code> if it is an update count or there are
  649. * no results
  650. * @exception SQLException if a database access error occurs or the second
  651. * parameter supplied to this method is not
  652. * <code>Statement.RETURN_GENERATED_KEYS</code> or
  653. * <code>Statement.NO_GENERATED_KEYS</code>.
  654. * @see #getResultSet
  655. * @see #getUpdateCount
  656. * @see #getMoreResults
  657. * @see #getGeneratedKeys
  658. *
  659. * @since 1.4
  660. */
  661. boolean execute(String sql, int autoGeneratedKeys) throws SQLException;
  662. /**
  663. * Executes the given SQL statement, which may return multiple results,
  664. * and signals the driver that the
  665. * auto-generated keys indicated in the given array should be made available
  666. * for retrieval. This array contains the indexes of the columns in the
  667. * target table that contain the auto-generated keys that should be made
  668. * available. The driver will ignore the array if the given SQL statement
  669. * is not an <code>INSERT</code> statement.
  670. * <P>
  671. * Under some (uncommon) situations, a single SQL statement may return
  672. * multiple result sets and/or update counts. Normally you can ignore
  673. * this unless you are (1) executing a stored procedure that you know may
  674. * return multiple results or (2) you are dynamically executing an
  675. * unknown SQL string.
  676. * <P>
  677. * The <code>execute</code> method executes an SQL statement and indicates the
  678. * form of the first result. You must then use the methods
  679. * <code>getResultSet</code> or <code>getUpdateCount</code>
  680. * to retrieve the result, and <code>getMoreResults</code> to
  681. * move to any subsequent result(s).
  682. *
  683. * @param sql any SQL statement
  684. * @param columnIndexes an array of the indexes of the columns in the
  685. * inserted row that should be made available for retrieval by a
  686. * call to the method <code>getGeneratedKeys</code>
  687. * @return <code>true</code> if the first result is a <code>ResultSet</code>
  688. * object; <code>false</code> if it is an update count or there
  689. * are no results
  690. * @exception SQLException if a database access error occurs or the
  691. * elements in the <code>int</code> array passed to this method
  692. * are not valid column indexes
  693. * @see #getResultSet
  694. * @see #getUpdateCount
  695. * @see #getMoreResults
  696. *
  697. * @since 1.4
  698. */
  699. boolean execute(String sql, int columnIndexes[]) throws SQLException;
  700. /**
  701. * Executes the given SQL statement, which may return multiple results,
  702. * and signals the driver that the
  703. * auto-generated keys indicated in the given array should be made available
  704. * for retrieval. This array contains the names of the columns in the
  705. * target table that contain the auto-generated keys that should be made
  706. * available. The driver will ignore the array if the given SQL statement
  707. * is not an <code>INSERT</code> statement.
  708. * <P>
  709. * In some (uncommon) situations, a single SQL statement may return
  710. * multiple result sets and/or update counts. Normally you can ignore
  711. * this unless you are (1) executing a stored procedure that you know may
  712. * return multiple results or (2) you are dynamically executing an
  713. * unknown SQL string.
  714. * <P>
  715. * The <code>execute</code> method executes an SQL statement and indicates the
  716. * form of the first result. You must then use the methods
  717. * <code>getResultSet</code> or <code>getUpdateCount</code>
  718. * to retrieve the result, and <code>getMoreResults</code> to
  719. * move to any subsequent result(s).
  720. *
  721. * @param sql any SQL statement
  722. * @param columnNames an array of the names of the columns in the inserted
  723. * row that should be made available for retrieval by a call to the
  724. * method <code>getGeneratedKeys</code>
  725. * @return <code>true</code> if the next result is a <code>ResultSet</code>
  726. * object; <code>false</code> if it is an update count or there
  727. * are no more results
  728. * @exception SQLException if a database access error occurs or the
  729. * elements of the <code>String</code> array passed to this
  730. * method are not valid column names
  731. * @see #getResultSet
  732. * @see #getUpdateCount
  733. * @see #getMoreResults
  734. * @see #getGeneratedKeys
  735. *
  736. * @since 1.4
  737. */
  738. boolean execute(String sql, String columnNames[]) throws SQLException;
  739. /**
  740. * Retrieves the result set holdability for <code>ResultSet</code> objects
  741. * generated by this <code>Statement</code> object.
  742. *
  743. * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
  744. * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
  745. * @exception SQLException if a database access error occurs
  746. *
  747. * @since 1.4
  748. */
  749. int getResultSetHoldability() throws SQLException;
  750. }