KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > hsqldb > jdbc > jdbcStatement


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