Source code: org/hsqldb/jdbcStatement.java
1 /* Copyrights and Licenses
2 *
3 * This product includes Hypersonic SQL.
4 * Originally developed by Thomas Mueller and the Hypersonic SQL Group.
5 *
6 * Copyright (c) 1995-2000 by the Hypersonic SQL Group. All rights reserved.
7 * Redistribution and use in source and binary forms, with or without modification, are permitted
8 * provided that the following conditions are met:
9 * - Redistributions of source code must retain the above copyright notice, this list of conditions
10 * and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright notice, this list of
12 * conditions and the following disclaimer in the documentation and/or other materials
13 * provided with the distribution.
14 * - All advertising materials mentioning features or use of this software must display the
15 * following acknowledgment: "This product includes Hypersonic SQL."
16 * - Products derived from this software may not be called "Hypersonic SQL" nor may
17 * "Hypersonic SQL" appear in their names without prior written permission of the
18 * Hypersonic SQL Group.
19 * - Redistributions of any form whatsoever must retain the following acknowledgment: "This
20 * product includes Hypersonic SQL."
21 * This software is provided "as is" and any expressed or implied warranties, including, but
22 * not limited to, the implied warranties of merchantability and fitness for a particular purpose are
23 * disclaimed. In no event shall the Hypersonic SQL Group or its contributors be liable for any
24 * direct, indirect, incidental, special, exemplary, or consequential damages (including, but
25 * not limited to, procurement of substitute goods or services; loss of use, data, or profits;
26 * or business interruption). However caused any on any theory of liability, whether in contract,
27 * strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this
28 * software, even if advised of the possibility of such damage.
29 * This software consists of voluntary contributions made by many individuals on behalf of the
30 * Hypersonic SQL Group.
31 *
32 *
33 * For work added by the HSQL Development Group:
34 *
35 * Copyright (c) 2001-2002, The HSQL Development Group
36 * All rights reserved.
37 *
38 * Redistribution and use in source and binary forms, with or without
39 * modification, are permitted provided that the following conditions are met:
40 *
41 * Redistributions of source code must retain the above copyright notice, this
42 * list of conditions and the following disclaimer, including earlier
43 * license statements (above) and comply with all above license conditions.
44 *
45 * Redistributions in binary form must reproduce the above copyright notice,
46 * this list of conditions and the following disclaimer in the documentation
47 * and/or other materials provided with the distribution, including earlier
48 * license statements (above) and comply with all above license conditions.
49 *
50 * Neither the name of the HSQL Development Group nor the names of its
51 * contributors may be used to endorse or promote products derived from this
52 * software without specific prior written permission.
53 *
54 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
55 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
56 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
57 * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
58 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
59 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
60 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
61 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
62 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
63 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
64 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
65 */
66
67
68 package org.hsqldb;
69
70 import java.sql.Connection;
71 import java.sql.ResultSet;
72 import java.sql.SQLException;
73 import java.sql.Statement;
74 import java.sql.SQLWarning;
75
76 // fredt@users 20020320 - patch 1.7.0 - JDBC 2 support and error trapping
77 // JDBC 2 methods can now be called from jdk 1.1.x - see javadoc comments
78 // SCROLL_INSENSITIVE and FORWARD_ONLY types for ResultSet are now supported
79 // boucherb@users 20020509 - added "throws SQLException" to all methods where
80 // it was missing here but specified in the java.sql.Statement interface,
81 // updated generic documentation to JDK 1.4, and added JDBC3 methods and docs
82 // boucherb@users and fredt@users 20020409/20020505 extensive review and update
83 // of docs and behaviour to comply with previous and latest java.sql specification
84
85 /**
86 * <!-- start generic documentation -->
87 * The object used for executing a static SQL statement
88 * and returning the results it produces.
89 * <P>
90 * By default, only one <code>ResultSet</code> object per <code>Statement</code>
91 * object can be open at the same time. Therefore, if the reading of one
92 * <code>ResultSet</code> object is interleaved
93 * with the reading of another, each must have been generated by
94 * different <code>Statement</code> objects. All execution methods in the
95 * <code>Statement</code> interface implicitly close a statment's current
96 * <code>ResultSet</code> object if an open one exists.<p>
97 * <!-- end generic documentation-->
98 *
99 * <!-- start release-specific documentation -->
100 * <span class="ReleaseSpecificDocumentation">
101 * <b>HSQLDB-Specific Information:</b><p>
102 *
103 * <b>JRE 1.1.x Notes:</b> <p>
104 *
105 * In general, JDBC 2 support requires Java 1.2 and above, and JDBC3 requires
106 * Java 1.4 and above. In HSQLDB, support for methods introduced in different
107 * versions of JDBC depends on the JDK version used for compiling and building
108 * HSQLDB.<p>
109 *
110 * Since 1.7.0, it is possible to build the product so that
111 * all JDBC 2 methods can be called while executing under the version 1.1.x
112 * <em>Java Runtime Environment</em><sup><font size="-2">TM</font></sup>.
113 * However, some of these method calls require <code>int</code> values that
114 * are defined only in the JDBC 2 or greater version of
115 * <a href="http://java.sun.com/j2se/1.4/docs/api/java/sql/ResultSet.html">
116 * <CODE>ResultSet</CODE></a> interface. For this reason, when the
117 * product is compiled under JDK 1.1.x, these values are defined in
118 * {@link jdbcResultSet jdbcResultSet}.<p>
119 *
120 * In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the
121 * JDBC2-only <CODE>ResultSet</CODE> values can be achieved by referring
122 * to them in parameter specifications and return value comparisons,
123 * respectively, as follows: <p>
124 *
125 * <CODE class="JavaCodeExample">
126 * jdbcResultSet.FETCH_FORWARD<br>
127 * jdbcResultSet.TYPE_FORWARD_ONLY<br>
128 * jdbcResultSet.TYPE_SCROLL_INSENSITIVE<br>
129 * jdbcResultSet.CONCUR_READ_ONLY<br>
130 * </CODE> <p>
131 *
132 * However, please note that code written in such a manner will not be
133 * compatible for use with other JDBC 2 drivers, since they expect and use
134 * <code>ResultSet</code>, rather than <code>jdbcResultSet</code>. Also
135 * note, this feature is offered solely as a convenience to developers
136 * who must work under JDK 1.1.x due to operating constraints, yet wish to
137 * use some of the more advanced features available under the JDBC 2
138 * specification.<p>
139 *
140 * (fredt@users)<br>
141 * (boucherb@users)<p>
142 *
143 * </span>
144 * <!-- end release-specific documentation -->
145 *
146 * @see jdbcConnection#createStatement
147 * @see jdbcResultSet
148 */
149 public class jdbcStatement implements java.sql.Statement {
150
151 /**
152 * Is escape processing enabled?
153 */
154 private boolean bEscapeProcessing = true;
155
156 /**
157 * The connection used to execute this statement.
158 */
159 private jdbcConnection cConnection;
160
161 /**
162 * The maximum number of rows to generate when executing this statement.
163 */
164 private int iMaxRows;
165
166 /**
167 * The result of executing this statement.
168 */
169 private jdbcResultSet rSet;
170
171 /**
172 * The result type obtained by executing this statement.
173 */
174 private int rsType = jdbcResultSet.TYPE_FORWARD_ONLY;
175
176 /**
177 * <!-- start generic documentation -->
178 * Executes the given SQL statement, which returns a single
179 * <code>ResultSet</code> object. <p>
180 * <!-- end generic documentation -->
181 *
182 * <!-- start release-specific documentation -->
183 * <span class="ReleaseSpecificDocumentation">
184 * </span>
185 * <!-- end release-specific documentation -->
186 *
187 *
188 * @param sql an SQL statement to be sent to the database, typically a
189 * static SQL <code>SELECT</code> statement
190 * @return a <code>ResultSet</code> object that contains the data produced
191 * by the given query; never <code>null</code>
192 * @exception SQLException if a database access error occurs or the given
193 * SQL statement produces anything other than a single
194 * <code>ResultSet</code> object
195 */
196 public ResultSet executeQuery(String sql) throws SQLException {
197
198 checkClosed();
199 fetchResult(sql);
200
201 return rSet;
202 }
203
204 /**
205 * <!-- start generic documentation -->
206 * Executes the given SQL statement, which may be an <code>INSERT</code>,
207 * <code>UPDATE</code>, or <code>DELETE</code> statement or an
208 * SQL statement that returns nothing, such as an SQL DDL statement. <p>
209 * <!-- end generic documentation -->
210 *
211 * <!-- start release-specific documentation -->
212 * <span class="ReleaseSpecificDocumentation">
213 * </span>
214 * <!-- end release-specific documentation -->
215 *
216 * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
217 * <code>DELETE</code> statement or an SQL statement that returns nothing
218 * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
219 * or <code>DELETE</code> statements, or <code>0</code> for SQL statements
220 * that return nothing
221 * @exception SQLException if a database access error occurs or the given
222 * SQL statement produces a <code>ResultSet</code> object
223 */
224 public int executeUpdate(String sql) throws SQLException {
225
226 checkClosed();
227 fetchResult(sql);
228
229 if (rSet == null) {
230 return -1;
231 }
232
233 return rSet.getUpdateCount();
234 }
235
236 /**
237 * <!-- start generic documentation -->
238 * Releases this <code>Statement</code> object's database
239 * and JDBC resources immediately instead of waiting for
240 * this to happen when it is automatically closed.
241 * It is generally good practice to release resources as soon as
242 * you are finished with them to avoid tying up database
243 * resources.
244 * <P>
245 * Calling the method <code>close</code> on a <code>Statement</code>
246 * object that is already closed has no effect.
247 * <P>
248 * <B>Note:</B> A <code>Statement</code> object is automatically closed
249 * when it is garbage collected. When a <code>Statement</code> object is
250 * closed, its current <code>ResultSet</code> object, if one exists, is
251 * also closed. <p>
252 * <!-- end generic documentation -->
253 *
254 * <!-- start release-specific documentation -->
255 * <span class="ReleaseSpecificDocumentation">
256 * </span>
257 * <!-- end release-specific documentation -->
258 *
259 * @exception SQLException if a database access error occurs
260 */
261 public void close() throws SQLException {
262
263 if (Trace.TRACE) {
264 Trace.trace();
265 }
266
267 closeOldResult();
268
269 rSet = null;
270 }
271
272 //----------------------------------------------------------------------
273
274 /**
275 * <!-- start generic documentation -->
276 * Retrieves the maximum number of bytes that can be
277 * returned for character and binary column values in a <code>ResultSet</code>
278 * object produced by this <code>Statement</code> object.
279 * This limit applies only to <code>BINARY</code>,
280 * <code>VARBINARY</code>, <code>LONGVARBINARY</code>, <code>CHAR</code>,
281 * <code>VARCHAR</code>, and <code>LONGVARCHAR</code>
282 * columns. If the limit is exceeded, the excess data is silently
283 * discarded. <p>
284 * <!-- end generic documentation -->
285 *
286 * <!-- start release-specific documentation -->
287 * <span class="ReleaseSpecificDocumentation">
288 * <b>HSQLDB-Specific Information:</B> <p>
289 *
290 * Up to and including 1.7.1, HSQLDB always returns zero, meaning there
291 * is no limit. <p>
292 *
293 * </span>
294 * <!-- end release-specific documentation -->
295 *
296 * @return the current column size limit for columns storing character and
297 * binary values; zero means there is no limit
298 * @exception SQLException if a database access error occurs
299 * @see #setMaxFieldSize
300 */
301 public int getMaxFieldSize() throws SQLException {
302
303 if (Trace.TRACE) {
304 Trace.trace();
305 }
306
307 checkClosed();
308
309 return 0;
310 }
311
312 /**
313 * <!-- start generic documentation -->
314 * Sets the limit for the maximum number of bytes in a <code>ResultSet</code>
315 * column storing character or binary values to
316 * the given number of bytes. This limit applies
317 * only to <code>BINARY</code>, <code>VARBINARY</code>,
318 * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>, and
319 * <code>LONGVARCHAR</code> fields. If the limit is exceeded, the excess data
320 * is silently discarded. For maximum portability, use values
321 * greater than 256. <p>
322 * <!-- emd generic documentation -->
323 *
324 * <!-- start release-specific documentation -->
325 * <span class="ReleaseSpecificDocumentation">
326 * <b>HSQLDB-Specific Information:</b> <p>
327 *
328 * Calls to this method are simply ignored; HSQLDB always stores the
329 * full number of bytes when dealing with any of the field types
330 * mentioned above. These types all have an absolute maximum element upper
331 * bound determined by the Java array index limit
332 * java.lang.Integer.MAX_VALUE. For XXXBINARY types, this translates to
333 * Integer.MAX_VALUE bytes. For XXXCHAR types, this translates to
334 * 2 * Integer.MAX_VALUE bytes (2 bytes / character)
335 *
336 * </span>
337 * <!-- end release-specific documentation -->
338 *
339 * @param max the new column size limit in bytes; zero means there is no limit
340 * @exception SQLException if a database access error occurs
341 * or the condition max >= 0 is not satisfied
342 * @see #getMaxFieldSize
343 */
344 public void setMaxFieldSize(int max) throws SQLException {
345
346 if (Trace.TRACE) {
347 Trace.trace();
348 }
349
350 checkClosed();
351 }
352
353 /**
354 * <!-- start generic documentation -->
355 * Retrieves the maximum number of rows that a
356 * <code>ResultSet</code> object produced by this
357 * <code>Statement</code> object can contain. If this limit is exceeded,
358 * the excess rows are silently dropped. <p>
359 * <!-- start generic documentation -->
360 *
361 * <!-- start release-specific documentation -->
362 * <span class="ReleaseSpecificDocumentation">
363 * </span>
364 * <!-- end release-specific documentation -->
365 *
366 * @return the current maximum number of rows for a <code>ResultSet</code>
367 * object produced by this <code>Statement</code> object;
368 * zero means there is no limit
369 * @exception SQLException if a database access error occurs
370 * @see #setMaxRows
371 */
372 public int getMaxRows() throws SQLException {
373
374 if (Trace.TRACE) {
375 Trace.trace();
376 }
377
378 checkClosed();
379
380 return iMaxRows;
381 }
382
383 /**
384 * <!-- start generic documentation -->
385 * Sets the limit for the maximum number of rows that any
386 * <code>ResultSet</code> object can contain to the given number.
387 * If the limit is exceeded, the excess
388 * rows are silently dropped. <p>
389 * <!-- end generic documentation -->
390 *
391 * <!-- start release-specific documentation -->
392 * <span class="ReleaseSpecificDocumentation">
393 * </span>
394 * <!-- end release-specific documentation -->
395 *
396 * @param max the new max rows limit; zero means there is no limit
397 * @exception SQLException if a database access error occurs
398 * or the condition max >= 0 is not satisfied
399 * @see #getMaxRows
400 */
401 public void setMaxRows(int max) throws SQLException {
402
403 if (Trace.TRACE) {
404 Trace.trace();
405 }
406
407 checkClosed();
408
409 iMaxRows = max;
410 }
411
412 /**
413 * <!-- start generic documentation -->
414 * Sets escape processing on or off.
415 * If escape scanning is on (the default), the driver will do
416 * escape substitution before sending the SQL statement to the database.
417 *
418 * Note: Since prepared statements have usually been parsed prior
419 * to making this call, disabling escape processing for
420 * <code>PreparedStatements</code> objects will have no effect. <p>
421 * <!-- end generic documentation -->
422 *
423 * <!-- start release-specific documentation -->
424 * <span class="ReleaseSpecificDocumentation">
425 * <b>HSQLDB-Specific Information:</b> <p>
426 *
427 * Up to HSQLDB 1.6.1, disabling escape processing for
428 * <code>PreparedStatements</code> objects <i>does</i> have an effect. <p>
429 *
430 * HSQLDB 1.7.0 follows the standard behaviour. <p>
431 *
432 * </span>
433 * <!-- end release-specific documentation -->
434 *
435 * @param enable <code>true</code> to enable escape processing;
436 * <code>false</code> to disable it
437 * @exception SQLException if a database access error occurs
438 */
439 public void setEscapeProcessing(boolean enable) throws SQLException {
440
441 if (Trace.TRACE) {
442 Trace.trace();
443 }
444
445 checkClosed();
446
447 // fredt - this is a no-brainer - we just override this method in
448 // jdbcPreparedStatement.java with no action performed
449 //
450 // FIXME:TODO ??? (not sure which category this best fits in)
451 //
452 // In our current implementation, setEscapeProcessing false for a
453 // jdbcXXXStatement *does* actually disable escape processing for
454 // prepared/callable statements. However, the javadocs mention that
455 // prepared/callable statements are usually parsed prior to making a
456 // setEscapeProcessing call, so disabling escape processing for
457 // prepared/callable statements will have no effect.
458 //
459 // The big question is:
460 //
461 // "Why would we want to perform nativeSQL over and over again on
462 // prepared/callable statements (or even regular statements,
463 // if it is redundant)?"
464 //
465 // This is not efficient and makes the standard comments
466 // innacurate against our current implementation. It would be pretty
467 // simple to set up something to preprocess escape processing
468 // for prepared/callable statements, as well as something to
469 // normalize, escape-process, and cache regular statmements (although
470 // normalizing and caching is probably better left completely on the
471 // engine side, rather than here in client-side code).
472 //
473 // boucherb@users 20020425
474 bEscapeProcessing = enable;
475 }
476
477 /**
478 * <!-- start generic documentation -->
479 * Retrieves the number of seconds the driver will
480 * wait for a <code>Statement</code> object to execute. If the
481 * limit is exceeded, a <code>SQLException</code> is thrown. <p>
482 * <!-- end generic documentation -->
483 *
484 * <!-- start release-specific documentation -->
485 * <span class="ReleaseSpecificDocumentation">
486 * <b>HSQLDB-Specific Information:</B> <p>
487 *
488 * Up to and including 1.7.1, HSQLDB always returns zero, meaning there
489 * is no limit. <p>
490 *
491 * </span>
492 * <!-- end release-specific documentation -->
493 *
494 * @return the current query timeout limit in seconds; zero means there is
495 * no limit
496 * @exception SQLException if a database access error occurs
497 * @see #setQueryTimeout
498 */
499 public int getQueryTimeout() throws SQLException {
500
501 if (Trace.TRACE) {
502 Trace.trace();
503 }
504
505 checkClosed();
506
507 return 0;
508 }
509
510 /**
511 * <!-- start generic documentation -->
512 * Sets the number of seconds the driver will wait for a
513 * <code>Statement</code> object to execute to the given number of seconds.
514 * If the limit is exceeded, an <code>SQLException</code> is thrown. <p>
515 * <!-- end generic documentation -->
516 *
517 * <!-- start release-specific documentation -->
518 * <span class="ReleaseSpecificDocumentation">
519 * <b>HSQLDB-Specific Information:</b> <p>
520 *
521 * Calls to this method are simply ignored; up to and including 1.7.1,
522 * HSQLDB waits an unlimited amount of time for statement execution
523 * requests to return. <p>
524 *
525 * </span>
526 * <!-- end release-specific documentation -->
527 *
528 * @param seconds the new query timeout limit in seconds; zero means
529 * there is no limit
530 * @exception SQLException if a database access error occurs
531 * or the condition seconds >= 0 is not satisfied
532 * @see #getQueryTimeout
533 */
534 public void setQueryTimeout(int seconds) throws SQLException {
535
536 if (Trace.TRACE) {
537 Trace.trace();
538 }
539
540 checkClosed();
541 }
542
543 /**
544 * <!-- start generic documentation -->
545 * Cancels this <code>Statement</code> object if both the DBMS and
546 * driver support aborting an SQL statement.
547 * This method can be used by one thread to cancel a statement that
548 * is being executed by another thread. <p>
549 * <!-- end generic documentation -->
550 *
551 * <!-- start release-specific documentation -->
552 * <span class="ReleaseSpecificDocumentation">
553 * <B>HSQLDB-Specific Information:</B> <p>
554 *
555 * Up to and including HSQLDB 1.7.0, aborting a SQL statement is
556 * <i>not</i> supported, and calls to this method are simply ignored. <p>
557 *
558 * </span>
559 * <!-- end release-specific documentation -->
560 *
561 * @exception SQLException if a database access error occurs
562 */
563 public void cancel() throws SQLException {
564
565 if (Trace.TRACE) {
566 Trace.trace();
567 }
568
569 checkClosed();
570 }
571
572 /**
573 * <!-- start generic documentation -->
574 * Retrieves the first warning reported by calls on this <code>Statement</code> object.
575 * Subsequent <code>Statement</code> object warnings will be chained to this
576 * <code>SQLWarning</code> object.
577 *
578 * <p>The warning chain is automatically cleared each time
579 * a statement is (re)executed. This method may not be called on a closed
580 * <code>Statement</code> object; doing so will cause an <code>SQLException</code>
581 * to be thrown.
582 *
583 * <P><B>Note:</B> If you are processing a <code>ResultSet</code> object, any
584 * warnings associated with reads on that <code>ResultSet</code> object
585 * will be chained on it rather than on the <code>Statement</code>
586 * object that produced it. <p>
587 * <!-- end generic documentation -->
588 *
589 * <!-- start release-specific documentation -->
590 * <span class="ReleaseSpecificDocumentation">
591 * <b>HSQLDB-Specific Information:</b> <p>
592 *
593 * Up to and including 1.7.1, HSQLDB never produces warnings and
594 * always returns null.<p>
595 *
596 * </span>
597 * <!-- end release-specific documentation -->
598 *
599 * @return the first <code>SQLWarning</code> object or <code>null</code>
600 * if there are no warnings
601 * @exception SQLException if a database access error occurs or this
602 * method is called on a closed statement
603 */
604 public SQLWarning getWarnings() throws SQLException {
605
606 if (Trace.TRACE) {
607 Trace.trace();
608 }
609
610 checkClosed();
611
612 return null;
613 }
614
615 /**
616 * <!-- start generic documentation -->
617 * Clears all the warnings reported on this <code>Statement</code>
618 * object. After a call to this method,
619 * the method <code>getWarnings</code> will return
620 * <code>null</code> until a new warning is reported for this
621 * <code>Statement</code> object. <p>
622 * <!-- end generic documentation -->
623 *
624 * <!-- start release-specific documentation -->
625 * <span class="ReleaseSpecificDocumentation">
626 * <B>HSQLDB-Specific Information:</B> <p>
627 *
628 * Up to and including HSQLDB 1.7.0, <CODE>SQLWarning</CODE> objects are
629 * never produced, and calls to this method are simply ignored. <p>
630 *
631 * </span>
632 * <!-- end release-specific documentation -->
633 *
634 * @exception SQLException if a database access error occurs
635 */
636 public void clearWarnings() throws SQLException {
637
638 if (Trace.TRACE) {
639 Trace.trace();
640 }
641
642 checkClosed();
643 }
644
645 /**
646 * <!-- start generic documentation -->
647 * Sets the SQL cursor name to the given <code>String</code>, which
648 * will be used by subsequent <code>Statement</code> object
649 * <code>execute</code> methods. This name can then be
650 * used in SQL positioned update or delete statements to identify the
651 * current row in the <code>ResultSet</code> object generated by this
652 * statement. If the database does not support positioned update/delete,
653 * this method is a noop. To insure that a cursor has the proper isolation
654 * level to support updates, the cursor's <code>SELECT</code> statement
655 * should have the form <code>SELECT FOR UPDATE</code>. If
656 * <code>FOR UPDATE</code> is not present, positioned updates may fail.
657 *
658 * <P><B>Note:</B> By definition, the execution of positioned updates and
659 * deletes must be done by a different <code>Statement</code> object than
660 * the one that generated the <code>ResultSet</code> object being used for
661 * positioning. Also, cursor names must be unique within a connection. <p>
662 * <!-- end generic documentation -->
663 *
664 * <!-- start release-specific documentation -->
665 * <span class="ReleaseSpecificDocumentation">
666 * <b>HSQLDB-Specific Information:</b> <p>
667 *
668 * Up to and including 1.7.1, HSQLDB does not support named cursors,
669 * updateable results or table locking via
670 * <code>SELECT FOR UPDATE</code>, so calls to this method are
671 * simply ignored. <p>
672 *
673 * </span>
674 * <!-- end release-specific documentation -->
675 *
676 * @param name the new cursor name, which must be unique within
677 * a connection
678 * @exception SQLException if a database access error occurs
679 */
680 public void setCursorName(String name) throws SQLException {
681
682 if (Trace.TRACE) {
683 Trace.trace();
684 }
685
686 checkClosed();
687 }
688
689 //----------------------- Multiple Results --------------------------
690
691 /**
692 * <!-- start generic documentation -->
693 * Executes the given SQL statement, which may return multiple results.
694 * In some (uncommon) situations, a single SQL statement may return
695 * multiple result sets and/or update counts. Normally you can ignore
696 * this unless you are (1) executing a stored procedure that you know may
697 * return multiple results or (2) you are dynamically executing an
698 * unknown SQL string.
699 * <P>
700 * The <code>execute</code> method executes an SQL statement and indicates the
701 * form of the first result. You must then use the methods
702 * <code>getResultSet</code> or <code>getUpdateCount</code>
703 * to retrieve the result, and <code>getMoreResults</code> to
704 * move to any subsequent result(s). <p>
705 * <!-- end generic documentation -->
706 *
707 * <!-- start release-specific documentation -->
708 * <span class="ReleaseSpecificDocumentation">
709 * </span>
710 * <!-- end release-specific documentation -->
711 *
712 * @param sql any SQL statement
713 * @return <code>true</code> if the first result is a <code>ResultSet</code>
714 * object; <code>false</code> if it is an update count or there are
715 * no results
716 * @exception SQLException if a database access error occurs
717 * @see #getResultSet
718 * @see #getUpdateCount
719 * @see #getMoreResults
720 */
721 public boolean execute(String sql) throws SQLException {
722
723 if (Trace.TRACE) {
724 Trace.trace();
725 }
726
727 checkClosed();
728 fetchResult(sql);
729
730 if (rSet == null) {
731 return false;
732 }
733
734 return rSet.isResult();
735 }
736
737 /**
738 * <!-- start generic documentation -->
739 * Retrieves the current result as a <code>ResultSet</code> object.
740 * This method should be called only once per result. <p>
741 * <!-- end generic documentation -->
742 *
743 * <!-- start release-specific documentation -->
744 * <span class="ReleaseSpecificDocumentation">
745 * <b>HSQLDB-Specific Information:</b> <p>
746 *
747 * Calling this method multiple times returns multiple references
748 * to the same result, if any.
749 * </span>
750 * <!-- end release-specific documentation -->
751 *
752 * @return the current result as a <code>ResultSet</code> object or
753 * <code>null</code> if the result is an update count or there are no more results
754 * @exception SQLException if a database access error occurs
755 * @see #execute
756 */
757 public ResultSet getResultSet() throws SQLException {
758
759 if (Trace.TRACE) {
760 Trace.trace();
761 }
762
763 checkClosed();
764
765 if ((rSet != null) && rSet.isResult()) {
766 return rSet;
767 }
768
769 return null;
770 }
771
772 /**
773 * <!-- start generic documentation -->
774 * Retrieves the current result as an update count;
775 * if the result is a <code>ResultSet</code> object or there are no more results, -1
776 * is returned. This method should be called only once per result. <p>
777 * <!-- end generic documentation -->
778 *
779 * <!-- start release-specific documentation -->
780 * <span class="ReleaseSpecificDocumentation">
781 * </span>
782 * <!-- end release-specific documentation -->
783 *
784 * @return the current result as an update count; -1 if the current result is a
785 * <code>ResultSet</code> object or there are no more results
786 * @exception SQLException if a database access error occurs
787 * @see #execute
788 */
789 public int getUpdateCount() throws SQLException {
790
791 if (Trace.TRACE) {
792 Trace.trace();
793 }
794
795 checkClosed();
796
797 if (rSet == null) {
798 return -1;
799 }
800
801 return rSet.getUpdateCount();
802 }
803
804 /**
805 * <!-- start generic documentation -->
806 * Moves to this <code>Statement</code> object's next result, returns
807 * <code>true</code> if it is a <code>ResultSet</code> object, and
808 * implicitly closes any current <code>ResultSet</code>
809 * object(s) obtained with the method <code>getResultSet</code>.
810 *
811 * <P>There are no more results when the following is true:
812 * <PRE>
813 * <code>(!getMoreResults() && (getUpdateCount() == -1)</code>
814 * </PRE> <p>
815 * <!-- end generic documentation -->
816 *
817 * <!-- start release-specific documentation -->
818 * <span class="ReleaseSpecificDocumentation">
819 * <b>HSQLDB-Specific Information:</b> <p>
820 *
821 * Up to and including 1.7.1, HSQLDB does not support multiple results. <p>
822 *
823 * Calling this method closes the current result (if any) and always
824 * returns <code>false</code>.
825 * </span>
826 * <!-- end release-specific documentation -->
827 *
828 * @return <code>true</code> if the next result is a <code>ResultSet</code>
829 * object; <code>false</code> if it is an update count or there are
830 * no more results
831 * @exception SQLException if a database access error occurs
832 * @see #execute
833 */
834 public boolean getMoreResults() throws SQLException {
835
836 if (Trace.TRACE) {
837 Trace.trace();
838 }
839
840 checkClosed();
841
842 if (rSet != null) {
843 rSet.close();
844
845 rSet = null;
846 }
847
848 return false;
849 }
850
851 //--------------------------JDBC 2.0-----------------------------
852
853 /**
854 * <!-- start generic documentation -->
855 * Gives the driver a hint as to the direction in which
856 * rows will be processed in <code>ResultSet</code>
857 * objects created using this <code>Statement</code> object. The
858 * default value is <code>ResultSet.FETCH_FORWARD</code>.
859 * <P>
860 * Note that this method sets the default fetch direction for
861 * result sets generated by this <code>Statement</code> object.
862 * Each result set has its own methods for getting and setting
863 * its own fetch direction. <p>
864 * <!-- end generic documentation -->
865 *
866 * <!-- start release-specific documentation -->
867 * <span class="ReleaseSpecificDocumentation">
868 * <b>HSQLDB-Specific Information:</b> <p>
869 *
870 * Up to and including 1.7.1, HSQLDB supports only
871 * <code>FETCH_FORWARD</code>. <p>
872 *
873 * Setting any other value will throw a <CODE>SQLException</CODE>,
874 * stating the the function is not supported.
875 * </span>
876 * <!-- end release-specific documentation -->
877 *
878 * @param direction the initial direction for processing rows
879 * @exception SQLException if a database access error occurs
880 * or the given direction
881 * is not one of <code>ResultSet.FETCH_FORWARD</code>,
882 * <code>ResultSet.FETCH_REVERSE</code>, or
883 * <code>ResultSet.FETCH_UNKNOWN</code> <p>
884 *
885 * HSQLDB throws for all values except <code>FETCH_FORWARD</code>
886 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
887 * for jdbcStatement)
888 * @see #getFetchDirection
889 */
890 public void setFetchDirection(int direction) throws SQLException {
891
892 if (Trace.TRACE) {
893 Trace.trace();
894 }
895
896 checkClosed();
897
898 if (direction != jdbcResultSet.FETCH_FORWARD) {
899 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED);
900 }
901 }
902
903 /**
904 * <!-- start generic documentation -->
905 * Retrieves the direction for fetching rows from
906 * database tables that is the default for result sets
907 * generated from this <code>Statement</code> object.
908 * If this <code>Statement</code> object has not set
909 * a fetch direction by calling the method <code>setFetchDirection</code>,
910 * the return value is implementation-specific. <p>
911 * <!-- end generic documentation -->
912 *
913 * <!-- start release-specific documentation -->
914 * <span class="ReleaseSpecificDocumentation">
915 * <b>HSQLDB-Specific Information:</B> <p>
916 *
917 * Up to and including 1.7.1, HSQLDB always returns FETCH_FORWARD. <p>
918 *
919 * </span>
920 * <!-- end release-specific documentation -->
921 *
922 * @return the default fetch direction for result sets generated
923 * from this <code>Statement</code> object
924 * @exception SQLException if a database access error occurs
925 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
926 * for jdbcStatement)
927 * @see #setFetchDirection
928 */
929 public int getFetchDirection() throws SQLException {
930
931 if (Trace.TRACE) {
932 Trace.trace();
933 }
934
935 checkClosed();
936
937 return jdbcResultSet.FETCH_FORWARD;
938 }
939
940 /**
941 * <!-- start generic documentation -->
942 * Gives the JDBC driver a hint as to the number of rows that should
943 * be fetched from the database when more rows are needed. The number
944 * of rows specified affects only result sets created using this
945 * statement. If the value specified is zero, then the hint is ignored.
946 * The default value is zero. <p>
947 * <!-- start generic documentation -->
948 *
949 * <!-- start release-specific documentation -->
950 * <span class="ReleaseSpecificDocumentation">
951 * <b>HSQLDB-Specific Information:</b> <p>
952 *
953 * Up to and including HSQLDB 1.7.0, calls to this method are simply
954 * ignored; HSQLDB always fetches a result completely as part of e
955 * xecuting its statement.
956 * </span>
957 * <!-- end release-specific documentation -->
958 *
959 * @param rows the number of rows to fetch
960 * @exception SQLException if a database access error occurs, or the
961 * condition 0 <= <code>rows</code> <= <code>this.getMaxRows()</code>
962 * is not satisfied. <p>
963 *
964 * HSQLDB never throws an exception, since calls to this method
965 * are always ignored.
966 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
967 * for jdbcStatement)
968 * @see #getFetchSize
969 */
970 public void setFetchSize(int rows) throws SQLException {
971
972 if (Trace.TRACE) {
973 Trace.trace();
974 }
975
976 checkClosed();
977 }
978
979 /**
980 * <!-- start generic documentation -->
981 * Retrieves the number of result set rows that is the default
982 * fetch size for <code>ResultSet</code> objects
983 * generated from this <code>Statement</code> object.
984 * If this <code>Statement</code> object has not set
985 * a fetch size by calling the method <code>setFetchSize</code>,
986 * the return value is implementation-specific. <p>
987 * <!-- end generic documentation -->
988 *
989 * <!-- start release-specific documentation -->
990 * <span class="ReleaseSpecificDocumentation">
991 * <b>HSQLDB-Specific Information</b> <p>
992 *
993 * Up to and including 1.7.1, this method always returns 0.
994 * That is, HSQLDB always decides the fetch size, that being all the
995 * rows of a result. <p>
996 *
997 * </span>
998 * <!-- end release-specific documentation -->
999 *
1000 * @return the default fetch size for result sets generated
1001 * from this <code>Statement</code> object
1002 * @exception SQLException if a database access error occurs
1003 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1004 * for jdbcStatement)
1005 * @see #setFetchSize
1006 */
1007 public int getFetchSize() throws SQLException {
1008
1009 if (Trace.TRACE) {
1010 Trace.trace();
1011 }
1012
1013 checkClosed();
1014
1015 // FIXME: fredt - changed
1016 // setFetchSize suggests that the attribute is a hint and
1017 // that zero is the "magic number" that lets the driver decide for
1018 // itself what the best fetch is. As such, we should return zero
1019 // here, since we always ignore setFetchSize and simply fetch the
1020 // result entirely.
1021 // boucherb@users 20020425
1022 return 0;
1023 }
1024
1025 /**
1026 * <!-- start generic documentation -->
1027 * Retrieves the result set concurrency for <code>ResultSet</code> objects
1028 * generated by this <code>Statement</code> object. <p>
1029 * <!-- end generic documentation -->
1030 *
1031 * <!-- start release-specific documentation -->
1032 * <span class="ReleaseSpecificDocumentation">
1033 * <b>HSQLDB-Specific Information:</b> <p>
1034 *
1035 * Up to and including 1.7.1, HSQLDB supports only
1036 * <code>CONCUR_READ_ONLY</code> concurrency. <p>
1037 *
1038 * </span>
1039 * <!-- end release-specific documentation -->
1040 *
1041 * @return either <code>ResultSet.CONCUR_READ_ONLY</code> or
1042 * <code>ResultSet.CONCUR_UPDATABLE</code> (not supported)
1043 * @exception SQLException if a database access error occurs
1044 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1045 * for jdbcStatement)
1046 */
1047 public int getResultSetConcurrency() throws SQLException {
1048
1049 if (Trace.TRACE) {
1050 Trace.trace();
1051 }
1052
1053 checkClosed();
1054
1055 return jdbcResultSet.CONCUR_READ_ONLY;
1056 }
1057
1058 /**
1059 * <!-- start generic documentation -->
1060 * Retrieves the result set type for <code>ResultSet</code> objects
1061 * generated by this <code>Statement</code> object. <p>
1062 * <!-- end generic documentation -->
1063 *
1064 * <!-- start release-specific documentation -->
1065 * <span class="ReleaseSpecificDocumentation">
1066 * <b>HSQLDB-Specific Information:</b> <p>
1067 *
1068 * Up to 1.6.1, HSQLDB supported <code>TYPE_FORWARD_ONLY</code> -
1069 * <code>CONCUR_READ_ONLY</code> results only, so <code>ResultSet</code>
1070 * objects created using the returned <code>Statement</code>
1071 * object would <I>always</I> be type <code>TYPE_FORWARD_ONLY</code>
1072 * with <code>CONCUR_READ_ONLY</code> concurrency. <p>
1073 *
1074 * Starting with 1.7.0, HSQLDB also supports
1075 * <code>TYPE_SCROLL_INSENSITIVE</code> results.<p>
1076 *
1077 * </span>
1078 * <!-- end release-specific documentation -->
1079 *
1080 * @return one of <code>ResultSet.TYPE_FORWARD_ONLY</code>,
1081 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
1082 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> (not supported) <p>
1083 *
1084 * <b>Note:</b> Up to and including 1.7.1, HSQLDB never returns
1085 * <code>TYPE_SCROLL_SENSITIVE</code>
1086 * @exception SQLException if a database access error occurs
1087 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1088 * for jdbcStatement)
1089 */
1090 public int getResultSetType() throws SQLException {
1091
1092 if (Trace.TRACE) {
1093 Trace.trace();
1094 }
1095
1096 checkClosed();
1097
1098 return rsType;
1099 }
1100
1101 /**
1102 * <!-- start generic documentation -->
1103 * Adds the given SQL command to the current list of commmands for this
1104 * <code>Statement</code> object. The commands in this list can be
1105 * executed as a batch by calling the method <code>executeBatch</code>.
1106 * <P>
1107 * <B>NOTE:</B> This method is optional. <p>
1108 * <!-- end generic documentation -->
1109 *
1110 * <!-- start release-specific documentation -->
1111 * <span class="ReleaseSpecificDocumentation">
1112 * <b>HSQLDB-Specific Information:</b> <p>
1113 *
1114 * HSQLDB 1.7.1 does not support this feature. <p>
1115 *
1116 * Calling this method always throws a <CODE>SQLException</CODE>,
1117 * stating that the function is not supported. <p>
1118 *
1119 * </span>
1120 * <!-- end release-specific documentation -->
1121 *
1122 * @param sql typically this is a static SQL <code>INSERT</code> or
1123 * <code>UPDATE</code> statement
1124 * @exception SQLException if a database access error occurs, or the
1125 * driver does not support batch updates
1126 * @see #executeBatch
1127 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1128 * for jdbcStatement)
1129 */
1130 public void addBatch(String sql) throws SQLException {
1131
1132 if (Trace.TRACE) {
1133 Trace.trace();
1134 }
1135
1136 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED);
1137 }
1138
1139 /**
1140 * <!-- start generic documentation -->
1141 * Empties this <code>Statement</code> object's current list of
1142 * SQL commands.
1143 * <P>
1144 * <B>NOTE:</B> This method is optional. <p>
1145 * <!-- start generic documentation -->
1146 *
1147 * <!-- start release-specific documentation -->
1148 * <span class="ReleaseSpecificDocumentation">
1149 * <b>HSQLDB-Specific Information:</b> <p>
1150 *
1151 * HSQLDB 1.7.1 does not support this feature. <p>
1152 *
1153 * Calling this method always throws a <CODE>SQLException</CODE>,
1154 * stating that the function is not supported. <p>
1155 *
1156 * </span>
1157 * <!-- end release-specific documentation -->
1158 *
1159 * @exception SQLException if a database access error occurs or the
1160 * driver does not support batch updates
1161 * @see #addBatch
1162 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1163 * for jdbcStatement)
1164 */
1165 public void clearBatch() throws SQLException {
1166
1167 if (Trace.TRACE) {
1168 Trace.trace();
1169 }
1170
1171 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED);
1172 }
1173
1174 /**
1175 * <!-- start generic documentation -->
1176 * Submits a batch of commands to the database for execution and
1177 * if all commands execute successfully, returns an array of update counts.
1178 * The <code>int</code> elements of the array that is returned are ordered
1179 * to correspond to the commands in the batch, which are ordered
1180 * according to the order in which they were added to the batch.
1181 * The elements in the array returned by the method <code>executeBatch</code>
1182 * may be one of the following:
1183 * <OL>
1184 * <LI>A number greater than or equal to zero -- indicates that the
1185 * command was processed successfully and is an update count giving the
1186 * number of rows in the database that were affected by the command's
1187 * execution
1188 * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
1189 * processed successfully but that the number of rows affected is
1190 * unknown
1191 * <P>
1192 * If one of the commands in a batch update fails to execute properly,
1193 * this method throws a <code>BatchUpdateException</code>, and a JDBC
1194 * driver may or may not continue to process the remaining commands in
1195 * the batch. However, the driver's behavior must be consistent with a
1196 * particular DBMS, either always continuing to process commands or never
1197 * continuing to process commands. If the driver continues processing
1198 * after a failure, the array returned by the method
1199 * <code>BatchUpdateException.getUpdateCounts</code>
1200 * will contain as many elements as there are commands in the batch, and
1201 * at least one of the elements will be the following:
1202 * <P>
1203 * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
1204 * to execute successfully and occurs only if a driver continues to
1205 * process commands after a command fails
1206 * </OL>
1207 * <P>
1208 * A driver is not required to implement this method.
1209 * The possible implementations and return values have been modified in
1210 * the Java 2 SDK, Standard Edition, version 1.3 to
1211 * accommodate the option of continuing to proccess commands in a batch
1212 * update after a <code>BatchUpdateException</code> obejct has been thrown. <p>
1213 * <!-- end generic documentation -->
1214 *
1215 * <!-- start release-specific documentation -->
1216 * <span class="ReleaseSpecificDocumentation">
1217 * <b>HSQLDB-Specific Information:</b> <p>
1218 *
1219 * HSQLDB 1.7.1 does not support this feature. <p>
1220 *
1221 * Calling this method always throws a <CODE>SQLException</CODE>,
1222 * stating that the function is not supported. <p>
1223 *
1224 * </span>
1225 * <!-- end release-specific documentation -->
1226 *
1227 * @return an array of update counts containing one element for each
1228 * command in the batch. The elements of the array are ordered according
1229 * to the order in which commands were added to the batch.
1230 * @exception SQLException if a database access error occurs or the
1231 * driver does not support batch statements. Throws
1232 * {@link java.sql.BatchUpdateException}
1233 * (a subclass of <code>java.sql.SQLException</code>) if one of the commands
1234 * sent to the database fails to execute properly or attempts to return a
1235 * result set.
1236 * @since JDK 1.3 (JDK 1.1.x developers: read the new overview
1237 * for jdbcStatement)
1238 */
1239 public int[] executeBatch() throws SQLException {
1240
1241 if (Trace.TRACE) {
1242 Trace.trace();
1243 }
1244
1245 checkClosed();
1246
1247 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED);
1248 }
1249
1250 /**
1251 * <!-- start generic documentation -->
1252 * Retrieves the <code>Connection</code> object
1253 * that produced this <code>Statement</code> object. <p>
1254 * <!-- end generic documentation -->
1255 *
1256 * <!-- start release-specific documentation -->
1257 * <span class="ReleaseSpecificDocumentation">
1258 * </span>
1259 * <!-- end release-specific documentation -->
1260 * @return the connection that produced this statement
1261 * @exception SQLException if a database access error occurs
1262 * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1263 * for jdbcStatement)
1264 */
1265 public Connection getConnection() throws SQLException {
1266
1267 checkClosed();
1268
1269 if (Trace.TRACE) {
1270 Trace.trace();
1271 }
1272
1273 return cConnection;
1274 }
1275
1276 //--------------------------JDBC 3.0-----------------------------
1277
1278 /**
1279 * <!-- start generic documentation -->
1280 * Moves to this <code>Statement</code> object's next result, deals with
1281 * any current <code>ResultSet</code> object(s) according to the instructions
1282 * specified by the given flag, and returns
1283 * <code>true</code> if the next result is a <code>ResultSet</code> object.
1284 *
1285 * <P>There are no more results when the following is true:
1286 * <PRE>
1287 * <code>(!getMoreResults() && (getUpdateCount() == -1)</code>
1288 * </PRE> <p>
1289 * <!-- end generic documentation -->
1290 *
1291 * <!-- start release-specific documentation -->
1292 * <span class="ReleaseSpecificDocumentation">
1293 * <b>HSQLDB-Specific Information:</b> <p>
1294 *
1295 * HSQLDB 1.7.1 does not support this feature. <p>
1296 *
1297 * Calling this method always throws a <CODE>SQLException</CODE>,
1298 * stating that the function is not supported. <p>
1299 *
1300 * </span>
1301 * <!-- end release-specific documentation -->
1302 *
1303 * @param current one of the following <code>Statement</code>
1304 * constants indicating what should happen to current
1305 * <code>ResultSet</code> objects obtained using the method
1306 * <code>getResultSet</code:
1307 * <code>CLOSE_CURRENT_RESULT</code>,
1308 * <code>KEEP_CURRENT_RESULT</code>, or
1309 * <code>CLOSE_ALL_RESULTS</code>
1310 * @return <code>true</code> if the next result is a <code>ResultSet</code>
1311 * object; <code>false</code> if it is an update count or there are no
1312 * more results
1313 * @exception SQLException if a database access error occurs
1314 * @since JDK 1.4, HSQLDB 1.7
1315 * @see #execute
1316 */
1317//#ifdef JDBC3
1318 public boolean getMoreResults(int current) throws SQLException {
1319 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED, "JDBC3");
1320 }
1321
1322
1323
1324//#endif JDBC3
1325
1326 /**
1327 * <!-- start generic documentation -->
1328 * Retrieves any auto-generated keys created as a result of executing this
1329 * <code>Statement</code> object. If this <code>Statement</code> object did
1330 * not generate any keys, an empty <code>ResultSet</code>
1331 * object is returned. <p>
1332 * <!-- end generic documentation -->
1333 *
1334 * <!-- start release-specific documentation -->
1335 * <span class="ReleaseSpecificDocumentation">
1336 * <b>HSQLDB-Specific Information:</b> <p>
1337 *
1338 * HSQLDB 1.7.1 does not support this feature. <p>
1339 *
1340 * Calling this method always throws a <CODE>SQLException</CODE>,
1341 * stating that the function is not supported. <p>
1342 *
1343 * </span>
1344 * <!-- end release-specific documentation -->
1345 *
1346 * @return a <code>ResultSet</code> object containing the auto-generated key(s)
1347 * generated by the execution of this <code>Statement</code> object
1348 * @exception SQLException if a database access error occurs
1349 * @since JDK 1.4, HSQLDB 1.7
1350 */
1351//#ifdef JDBC3
1352 public ResultSet getGeneratedKeys() throws SQLException {
1353 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED, "JDBC3");
1354 }
1355
1356
1357
1358//#endif JDBC3
1359
1360 /**
1361 * <!-- start generic documentation -->
1362 * Executes the given SQL statement and signals the driver with the
1363 * given flag about whether the
1364 * auto-generated keys produced by this <code>Statement</code> object
1365 * should be made available for retrieval. <p>
1366 * <!-- end generic documentation -->
1367 *
1368 * <!-- start release-specific documentation -->
1369 * <span class="ReleaseSpecificDocumentation">
1370 * <b>HSQLDB-Specific Information:</b> <p>
1371 *
1372 * HSQLDB 1.7.1 does not support this feature. <p>
1373 *
1374 * Calling this method always throws a <CODE>SQLException</CODE>,
1375 * stating that the function is not supported. <p>
1376 *
1377 * </span>
1378 * <!-- end release-specific documentation -->
1379 *
1380 * @param sql must be an SQL <code>INSERT</code>, <code>UPDATE</code> or
1381 * <code>DELETE</code> statement or an SQL statement that
1382 * returns nothing
1383 * @param autoGeneratedKeys a flag indicating whether auto-generated keys
1384 * should be made available for retrieval;
1385 * one of the following constants:
1386 * <code>Statement.RETURN_GENERATED_KEYS</code>
1387 * <code>Statement.NO_GENERATED_KEYS</code>
1388 * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
1389 * or <code>DELETE</code> statements, or <code>0</code> for SQL
1390 * statements that return nothing
1391 * @exception SQLException if a database access error occurs, the given
1392 * SQL statement returns a <code>ResultSet</code> object, or
1393 * the given constant is not one of those allowed
1394 * @since JDK 1.4, HSQLDB 1.7
1395 */
1396//#ifdef JDBC3
1397 public int executeUpdate(String sql,
1398 int autoGeneratedKeys) throws SQLException {
1399 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED, "JDBC3");
1400 }
1401
1402
1403
1404//#endif JDBC3
1405
1406 /**
1407 * <!-- start generic documentation -->
1408 * Executes the given SQL statement and signals the driver that the
1409 * auto-generated keys indicated in the given array should be made available
1410 * for retrieval. The driver will ignore the array if the SQL statement
1411 * is not an <code>INSERT</code> statement. <p>
1412 * <!-- end generic documentation -->
1413 *
1414 * <!-- start release-specific documentation -->
1415 * <span class="ReleaseSpecificDocumentation">
1416 * <b>HSQLDB-Specific Information:</b> <p>
1417 *
1418 * HSQLDB 1.7.1 does not support this feature. <p>
1419 *
1420 * Calling this method always throws a <CODE>SQLException</CODE>,
1421 * stating that the function is not supported. <p>
1422 *
1423 * </span>
1424 * <!-- end release-specific documentation -->
1425 *
1426 * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
1427 * <code>DELETE</code> statement or an SQL statement that returns nothing,
1428 * such as an SQL DDL statement
1429 * @param columnIndexes an array of column indexes indicating the columns
1430 * that should be returned from the inserted row
1431 * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
1432 * or <code>DELETE</code> statements, or 0 for SQL statements
1433 * that return nothing
1434 * @exception SQLException if a database access error occurs or the SQL
1435 * statement returns a <code>ResultSet</code> object
1436 * @since JDK 1.4, HSQLDB 1.7
1437 */
1438//#ifdef JDBC3
1439 public int executeUpdate(String sql,
1440 int columnIndexes[]) throws SQLException {
1441 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED, "JDBC3");
1442 }
1443
1444
1445
1446//#endif JDBC3
1447
1448 /**
1449 * <!-- start generic documentation -->
1450 * Executes the given SQL statement and signals the driver that the
1451 * auto-generated keys indicated in the given array should be made available
1452 * for retrieval. The driver will ignore the array if the SQL statement
1453 * is not an <code>INSERT</code> statement. <p>
1454 * <!-- end generic documentation -->
1455 *
1456 * <!-- start release-specific documentation -->
1457 * <span class="ReleaseSpecificDocumentation">
1458 * <b>HSQLDB-Specific Information:</b> <p>
1459 *
1460 * HSQLDB 1.7.1 does not support this feature. <p>
1461 *
1462 * Calling this method always throws a <CODE>SQLException</CODE>,
1463 * stating that the function is not supported. <p>
1464 *
1465 * </span>
1466 * <!-- end release-specific documentation -->
1467 *
1468 * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
1469 * <code>DELETE</code> statement or an SQL statement that returns nothing
1470 * @param columnNames an array of the names of the columns that should be
1471 * returned from the inserted row
1472 * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
1473 * or <code>DELETE</code> statements, or 0 for SQL statements
1474 * that return nothing
1475 * @exception SQLException if a database access error occurs
1476 * @since JDK 1.4, HSQLDB 1.7
1477 */
1478//#ifdef JDBC3
1479 public int executeUpdate(String sql,
1480 String columnNames[]) throws SQLException {
1481 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED, "JDBC3");
1482 }
1483
1484
1485
1486//#endif JDBC3
1487
1488 /**
1489 * <!-- start generic documentation -->
1490 * Executes the given SQL statement, which may return multiple results,
1491 * and signals the driver that any
1492 * auto-generated keys should be made available
1493 * for retrieval. The driver will ignore this signal if the SQL statement
1494 * is not an <code>INSERT</code> statement.
1495 * <P>
1496 * In some (uncommon) situations, a single SQL statement may return
1497 * multiple result sets and/or update counts. Normally you can ignore
1498 * this unless you are (1) executing a stored procedure that you know may
1499 * return multiple results or (2) you are dynamically executing an
1500 * unknown SQL string.
1501 * <P>
1502 * The <code>execute</code> method executes an SQL statement and indicates the
1503 * form of the first result. You must then use the methods
1504 * <code>getResultSet</code> or <code>getUpdateCount</code>
1505 * to retrieve the result, and <code>getMoreResults</code> to
1506 * move to any subsequent result(s). <p>
1507 * <!-- end generic documentation -->
1508 *
1509 * <!-- start release-specific documentation -->
1510 * <span class="ReleaseSpecificDocumentation">
1511 * <b>HSQLDB-Specific Information:</b> <p>
1512 *
1513 * HSQLDB 1.7.1 does not support this feature. <p>
1514 *
1515 * Calling this method always throws a <CODE>SQLException</CODE>,
1516 * stating that the function is not supported. <p>
1517 *
1518 * </span>
1519 * <!-- end release-specific documentation -->
1520 *
1521 * @param sql any SQL statement
1522 * @param autoGeneratedKeys a constant indicating whether auto-generated
1523 * keys should be made available for retrieval using the method
1524 * <code>getGeneratedKeys</code>; one of the following constants:
1525 * <code>Statement.RETURN_GENERATED_KEYS</code> or
1526 * <code>Statement.NO_GENERATED_KEYS</code>
1527 * @return <code>true</code> if the first result is a <code>ResultSet</code>
1528 * object; <code>false</code> if it is an update count or there are
1529 * no results
1530 * @exception SQLException if a database access error occurs
1531 * @see #getResultSet
1532 * @see #getUpdateCount
1533 * @see #getMoreResults
1534 * @see #getGeneratedKeys
1535 * @since JDK 1.4, HSQLDB 1.7
1536 */
1537//#ifdef JDBC3
1538 public boolean execute(String sql,
1539 int autoGeneratedKeys) throws SQLException {
1540 throw Trace.error(Trace.FUNCTION_NOT_SUPPORTED, "JDBC3");
1541 }
1542
1543
1544
1545//#endif JDBC3
1546
1547 /**
1548 * <!-- start generic documentation -->
1549 * Executes the given SQL statement, which may return multiple results,
1550 * and signals the driver that the
1551 * auto-generated keys indicated in the given array should be made available
1552 * for retrieval. This array contains the indexes of the columns in the
1553 * target table that contain the auto-generated keys that should be made
1554 * available. The driver will ignore the array if the given SQL statement
1555 * is not an <code>INSERT</code> statement.
1556 * <P>
1557 * Under some (uncommon) situations, a single SQL statement may return
1558 * multiple result sets and/or update counts. Normally you can ignore
1559 * this unless you are (1) executing a stored procedure that you know may
1560 * return multiple results or (2) you are dynamically executing an
1561 * unknown SQL string.
1562 * <P>
1563 * The <code>execute</code> method executes an SQL statement and indicates the
1564 * form of the first result. You must then use the methods
1565 * <code>getResultSet</code> or <code>getUpdateCount</code>
1566 * to retrieve the result, and <code>getMoreResults</code> to
1567 * move to any subsequent result(s). <p>
1568 * <!-- end generic documentation -->
1569 *
1570 * <!-- start release-specific documentation -->
1571 * <span class="ReleaseSpecificDocumentation">
1572 * <b>HSQLDB-Specific Information:</b> <p>
1573 *
1574 * HSQLDB 1.7.1 does not support this feature. <p>