0001: /* Copyright (c) 2001-2005, The HSQL Development Group
0002: * All rights reserved.
0003: *
0004: * Redistribution and use in source and binary forms, with or without
0005: * modification, are permitted provided that the following conditions are met:
0006: *
0007: * Redistributions of source code must retain the above copyright notice, this
0008: * list of conditions and the following disclaimer.
0009: *
0010: * Redistributions in binary form must reproduce the above copyright notice,
0011: * this list of conditions and the following disclaimer in the documentation
0012: * and/or other materials provided with the distribution.
0013: *
0014: * Neither the name of the HSQL Development Group nor the names of its
0015: * contributors may be used to endorse or promote products derived from this
0016: * software without specific prior written permission.
0017: *
0018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0020: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0021: * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
0022: * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
0023: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
0024: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
0025: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
0026: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
0027: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
0028: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
0029: */
0030:
0031: package org.hsqldb.jdbc;
0032:
0033: //#ifdef JAVA2
0034: import java.sql.BatchUpdateException;
0035:
0036: //#endif JAVA2
0037: import java.sql.Connection;
0038: import java.sql.ResultSet;
0039: import java.sql.SQLException;
0040: import java.sql.SQLWarning;
0041: import java.sql.Statement;
0042:
0043: import org.hsqldb.HsqlException;
0044: import org.hsqldb.Result;
0045: import org.hsqldb.ResultConstants;
0046: import org.hsqldb.Trace;
0047: import org.hsqldb.Types;
0048:
0049: // fredt@users 20020320 - patch 1.7.0 - JDBC 2 support and error trapping
0050: // JDBC 2 methods can now be called from jdk 1.1.x - see javadoc comments
0051: // SCROLL_INSENSITIVE and FORWARD_ONLY types for ResultSet are now supported
0052: // boucherb@users 20020509 - added "throws SQLException" to all methods where
0053: // it was missing here but specified in the java.sql.Statement interface,
0054: // updated generic documentation to JDK 1.4, and added JDBC3 methods and docs
0055: // boucherb@users and fredt@users - 20020505 extensive review and update
0056: // of docs and behaviour to comply with java.sql specification
0057: // fredt@users 20030620 - patch 1.7.2 - rewritten and simplified
0058: // boucherb@users 200404xx - javadoc updates toward 1.7.2 final
0059:
0060: /**
0061: * <!-- start generic documentation -->
0062: * The object used for executing a static SQL statement
0063: * and returning the results it produces.
0064: * <P>
0065: * By default, only one <code>ResultSet</code> object per <code>Statement</code>
0066: * object can be open at the same time. Therefore, if the reading of one
0067: * <code>ResultSet</code> object is interleaved
0068: * with the reading of another, each must have been generated by
0069: * different <code>Statement</code> objects. All execution methods in the
0070: * <code>Statement</code> interface implicitly close a statment's current
0071: * <code>ResultSet</code> object if an open one exists.<p>
0072: * <!-- end generic documentation-->
0073: *
0074: * <!-- start release-specific documentation -->
0075: * <div class="ReleaseSpecificDocumentation">
0076: * <h3>HSQLDB-Specific Information:</h3><p>
0077: *
0078: * <b>JRE 1.1.x Notes:</b> <p>
0079: *
0080: * In general, JDBC 2 support requires Java 1.2 and above, and JDBC3 requires
0081: * Java 1.4 and above. In HSQLDB, support for methods introduced in different
0082: * versions of JDBC depends on the JDK version used for compiling and building
0083: * HSQLDB.<p>
0084: *
0085: * Since 1.7.0, all JDBC 2 methods can be called while executing under the
0086: * version 1.1.x
0087: * <em>Java Runtime Environment</em><sup><font size="-2">TM</font></sup>.
0088: * However, in addition to this technique requiring explicit casts to the
0089: * org.hsqldb.jdbcXXX classes, some of these method calls require
0090: * <code>int</code> values that are defined only in the JDBC 2 or greater
0091: * version of the {@link java.sql.ResultSet ResultSet} interface. For this
0092: * reason these values are defined in {@link jdbcResultSet jdbcResultSet}.<p>
0093: *
0094: * In a JRE 1.1.x environment, calling JDBC 2 methods that take or return the
0095: * JDBC2-only <code>ResultSet</code> values can be achieved by referring
0096: * to them in parameter specifications and return value comparisons,
0097: * respectively, as follows: <p>
0098: *
0099: * <pre class="JavaCodeExample">
0100: * jdbcResultSet.FETCH_FORWARD
0101: * jdbcResultSet.TYPE_FORWARD_ONLY
0102: * jdbcResultSet.TYPE_SCROLL_INSENSITIVE
0103: * jdbcResultSet.CONCUR_READ_ONLY
0104: * //etc.
0105: * </pre> <p>
0106: *
0107: * However, please note that code written to use HSQLDB JDBC 2 features under
0108: * JDK 1.1.x will not be compatible for use with other JDBC 2 drivers. Please
0109: * also note that this feature is offered solely as a convenience to developers
0110: * who must work under JDK 1.1.x due to operating constraints, yet wish to
0111: * use some of the more advanced features available under the JDBC 2
0112: * specification. <p>
0113: *
0114: * (fredt@users)<br>
0115: * (boucherb@users)<p>
0116: *
0117: * </div>
0118: * <!-- end release-specific documentation -->
0119: *
0120: * @author boucherb@users
0121: * @author fredt@user
0122: * @version 1.8.0
0123: * @see jdbcConnection#createStatement
0124: * @see jdbcResultSet
0125: */
0126: public class jdbcStatement implements Statement {
0127:
0128: /**
0129: * Whether this Statement has been explicitly closed. A jdbcConnection
0130: * object now explicitly closes all of its open jdbcXXXStatement objects
0131: * when it is closed.
0132: */
0133: volatile boolean isClosed;
0134:
0135: /** Is escape processing enabled? */
0136: private boolean isEscapeProcessing = true;
0137:
0138: /** The connection used to execute this statement. */
0139: protected jdbcConnection connection;
0140:
0141: /** The maximum number of rows to generate when executing this statement. */
0142: protected int maxRows;
0143:
0144: /** The result of executing this statement. */
0145: protected Result resultIn;
0146:
0147: /** The result set type obtained by executing this statement. */
0148: protected int rsType = jdbcResultSet.TYPE_FORWARD_ONLY;
0149:
0150: /** Used by this statement to communicate non-batched requests. */
0151: protected Result resultOut = new Result(
0152: ResultConstants.SQLEXECDIRECT);
0153:
0154: /** Use by this statement to communicate batched execution requests */
0155: protected Result batchResultOut = null;
0156:
0157: // boucherb@users
0158: // NOTE:
0159: // This method is synchronized since resultIn is an instance attribute
0160: // and thus it is theoretically possible that a race condition occurs
0161: // in which a different thread executes fetchResult(sql), replacing
0162: // resultIn before it gets assigned propery to the new result set.
0163: // fredt - this class is not supposed to be called multi-threaded -
0164: // For example, if two threads call execute() then both call getResult() in
0165: // the wrong order, the ResultSet object for one call could actually belong
0166: // to the other call.
0167:
0168: /**
0169: * <!-- start generic documentation -->
0170: * Executes the given SQL statement, which returns a single
0171: * <code>ResultSet</code> object. <p>
0172: * <!-- end generic documentation -->
0173: * <!-- start release-specific documentation -->
0174: * <div class="ReleaseSpecificDocumentation">
0175: * <h3>HSQLDB-Specific Information:</h3> <p>
0176: *
0177: * This method should not be used for statements other than SELECT queries.<p>
0178: *
0179: * Including 1.7.2, HSQLDB does not throw an exception when the statement
0180: * is a DDL statement or an UPDATE or DELETE statement. This will certainly
0181: * change in future version.
0182: * </div>
0183: * <!-- end release-specific documentation -->
0184: *
0185: * @param sql an SQL statement to be sent to the database, typically a
0186: * static SQL <code>SELECT</code> statement
0187: * @return a <code>ResultSet</code> object that contains the data produced
0188: * by the given query; never <code>null</code>
0189: * @exception SQLException if a database access error occurs or the given
0190: * SQL statement produces anything other than a single
0191: * <code>ResultSet</code> object
0192: */
0193: public ResultSet executeQuery(String sql) throws SQLException {
0194:
0195: checkClosed();
0196: connection.clearWarningsNoCheck();
0197: fetchResult(sql);
0198:
0199: return new jdbcResultSet(this , resultIn,
0200: connection.connProperties, connection.isNetConn);
0201: }
0202:
0203: /**
0204: * <!-- start generic documentation -->
0205: * Executes the given SQL statement, which may be an <code>INSERT</code>,
0206: * <code>UPDATE</code>, or <code>DELETE</code> statement or an
0207: * SQL statement that returns nothing, such as an SQL DDL statement. <p>
0208: * <!-- end generic documentation -->
0209: *
0210: * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
0211: * <code>DELETE</code> statement or an SQL statement that returns nothing
0212: * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
0213: * or <code>DELETE</code> statements, or <code>0</code> for SQL statements
0214: * that return nothing
0215: * @exception SQLException if a database access error occurs or the given
0216: * SQL statement produces a <code>ResultSet</code> object
0217: */
0218: public int executeUpdate(String sql) throws SQLException {
0219:
0220: checkClosed();
0221: connection.clearWarningsNoCheck();
0222: fetchResult(sql);
0223:
0224: if (resultIn == null || resultIn.isData()) {
0225:
0226: /**
0227: * @todo: - fredt@users - check for type of statement _must_ be done
0228: * in the engine and error returned _without_ executing
0229: */
0230: throw new SQLException(Trace
0231: .getMessage(Trace.jdbcStatement_executeUpdate));
0232: } else if (resultIn.isError()) {
0233: Util.throwError(resultIn);
0234: }
0235:
0236: return resultIn.getUpdateCount();
0237: }
0238:
0239: /**
0240: * <!-- start generic documentation -->
0241: * Releases this <code>Statement</code> object's database
0242: * and JDBC resources immediately instead of waiting for
0243: * this to happen when it is automatically closed.
0244: * It is generally good practice to release resources as soon as
0245: * you are finished with them to avoid tying up database
0246: * resources.
0247: * <P>
0248: * Calling the method <code>close</code> on a <code>Statement</code>
0249: * object that is already closed has no effect.
0250: * <P>
0251: * <B>Note:</B> A <code>Statement</code> object is automatically closed
0252: * when it is garbage collected. When a <code>Statement</code> object is
0253: * closed, its current <code>ResultSet</code> object, if one exists, is
0254: * also closed. <p>
0255: * <!-- end generic documentation -->
0256: *
0257: * @exception SQLException if a database access error occurs
0258: */
0259: public synchronized void close() throws SQLException {
0260:
0261: if (isClosed) {
0262: return;
0263: }
0264:
0265: batchResultOut = null;
0266: connection = null;
0267: resultIn = null;
0268: resultOut = null;
0269: isClosed = true;
0270: }
0271:
0272: //----------------------------------------------------------------------
0273:
0274: /**
0275: * <!-- start generic documentation -->
0276: * Retrieves the maximum number of bytes that can be
0277: * returned for character and binary column values in a <code>ResultSet</code>
0278: * object produced by this <code>Statement</code> object.
0279: * This limit applies only to <code>BINARY</code>,
0280: * <code>VARBINARY</code>, <code>LONGVARBINARY</code>, <code>CHAR</code>,
0281: * <code>VARCHAR</code>, and <code>LONGVARCHAR</code>
0282: * columns. If the limit is exceeded, the excess data is silently
0283: * discarded. <p>
0284: * <!-- end generic documentation -->
0285: *
0286: * <!-- start release-specific documentation -->
0287: * <div class="ReleaseSpecificDocumentation">
0288: * <h3>HSQLDB-Specific Information:</h3> <p>
0289: *
0290: * Including 1.7.2, HSQLDB always returns zero, meaning there
0291: * is no limit.
0292: * </div>
0293: * <!-- end release-specific documentation -->
0294: *
0295: * @return the current column size limit for columns storing character and
0296: * binary values; zero means there is no limit
0297: * @exception SQLException if a database access error occurs
0298: * @see #setMaxFieldSize
0299: */
0300: public int getMaxFieldSize() throws SQLException {
0301:
0302: checkClosed();
0303:
0304: return 0;
0305: }
0306:
0307: /**
0308: * <!-- start generic documentation -->
0309: * Sets the limit for the maximum number of bytes in a <code>ResultSet</code>
0310: * column storing character or binary values to
0311: * the given number of bytes. This limit applies
0312: * only to <code>BINARY</code>, <code>VARBINARY</code>,
0313: * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>, and
0314: * <code>LONGVARCHAR</code> fields. If the limit is exceeded, the excess data
0315: * is silently discarded. For maximum portability, use values
0316: * greater than 256. <p>
0317: * <!-- emd generic documentation -->
0318: *
0319: * <!-- start release-specific documentation -->
0320: * <div class="ReleaseSpecificDocumentation">
0321: * <h3>HSQLDB-Specific Information:</h3> <p>
0322: *
0323: * Including 1.7.2, calls to this method are simply ignored; HSQLDB always
0324: * stores the full number of bytes when dealing with any of the field types
0325: * mentioned above. These types all have an absolute maximum element upper
0326: * bound determined by the Java array index limit
0327: * java.lang.Integer.MAX_VALUE. For XXXBINARY types, this translates to
0328: * Integer.MAX_VALUE bytes. For XXXCHAR types, this translates to
0329: * 2 * Integer.MAX_VALUE bytes (2 bytes / character)
0330: * </div>
0331: * <!-- end release-specific documentation -->
0332: *
0333: * @param max the new column size limit in bytes; zero means there is no limit
0334: * @exception SQLException if a database access error occurs
0335: * or the condition max >= 0 is not satisfied
0336: * @see #getMaxFieldSize
0337: */
0338: public void setMaxFieldSize(int max) throws SQLException {
0339:
0340: checkClosed();
0341:
0342: if (max < 0) {
0343: throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
0344: }
0345: }
0346:
0347: /**
0348: * <!-- start generic documentation -->
0349: * Retrieves the maximum number of rows that a
0350: * <code>ResultSet</code> object produced by this
0351: * <code>Statement</code> object can contain. If this limit is exceeded,
0352: * the excess rows are silently dropped. <p>
0353: * <!-- start generic documentation -->
0354: *
0355: * @return the current maximum number of rows for a <code>ResultSet</code>
0356: * object produced by this <code>Statement</code> object;
0357: * zero means there is no limit
0358: * @exception SQLException if a database access error occurs
0359: * @see #setMaxRows
0360: */
0361: public int getMaxRows() throws SQLException {
0362:
0363: checkClosed();
0364:
0365: return maxRows;
0366: }
0367:
0368: /**
0369: * <!-- start generic documentation -->
0370: * Sets the limit for the maximum number of rows that any
0371: * <code>ResultSet</code> object can contain to the given number.
0372: * If the limit is exceeded, the excess
0373: * rows are silently dropped. <p>
0374: * <!-- end generic documentation -->
0375: *
0376: * @param max the new max rows limit; zero means there is no limit
0377: * @exception SQLException if a database access error occurs
0378: * or the condition max >= 0 is not satisfied
0379: * @see #getMaxRows
0380: */
0381: public void setMaxRows(int max) throws SQLException {
0382:
0383: checkClosed();
0384:
0385: if (max < 0) {
0386: throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
0387: }
0388:
0389: maxRows = max;
0390: }
0391:
0392: /**
0393: * <!-- start generic documentation -->
0394: * Sets escape processing on or off.
0395: * If escape scanning is on (the default), the driver will do
0396: * escape substitution before sending the SQL statement to the database.
0397: *
0398: * Note: Since prepared statements have usually been parsed prior
0399: * to making this call, disabling escape processing for
0400: * <code>PreparedStatements</code> objects will have no effect. <p>
0401: * <!-- end generic documentation -->
0402: *
0403: * @param enable <code>true</code> to enable escape processing;
0404: * <code>false</code> to disable it
0405: * @exception SQLException if a database access error occurs
0406: */
0407: public void setEscapeProcessing(boolean enable) throws SQLException {
0408:
0409: checkClosed();
0410:
0411: isEscapeProcessing = enable;
0412: }
0413:
0414: /**
0415: * <!-- start generic documentation -->
0416: * Retrieves the number of seconds the driver will
0417: * wait for a <code>Statement</code> object to execute. If the
0418: * limit is exceeded, an <code>SQLException</code> is thrown. <p>
0419: * <!-- end generic documentation -->
0420: *
0421: * <!-- start release-specific documentation -->
0422: * <div class="ReleaseSpecificDocumentation">
0423: * <h3>HSQLDB-Specific Information:</h3> <p>
0424: *
0425: * Including 1.7.2, HSQLDB always returns zero, meaning there
0426: * is no limit.
0427: * </div>
0428: * <!-- end release-specific documentation -->
0429: *
0430: * @return the current query timeout limit in seconds; zero means there is
0431: * no limit
0432: * @exception SQLException if a database access error occurs
0433: * @see #setQueryTimeout
0434: */
0435: public int getQueryTimeout() throws SQLException {
0436:
0437: checkClosed();
0438:
0439: return 0;
0440: }
0441:
0442: /**
0443: * <!-- start generic documentation -->
0444: * Sets the number of seconds the driver will wait for a
0445: * <code>Statement</code> object to execute to the given number of seconds.
0446: * If the limit is exceeded, an <code>SQLException</code> is thrown. <p>
0447: * <!-- end generic documentation -->
0448: *
0449: * <!-- start release-specific documentation -->
0450: * <div class="ReleaseSpecificDocumentation">
0451: * <h3>HSQLDB-Specific Information:</h3> <p>
0452: *
0453: * Including 1.7.2, calls to this method are ignored; HSQLDB waits an
0454: * unlimited amount of time for statement execution
0455: * requests to return.
0456: * </div>
0457: * <!-- end release-specific documentation -->
0458: *
0459: * @param seconds the new query timeout limit in seconds; zero means
0460: * there is no limit
0461: * @exception SQLException if a database access error occurs
0462: * or the condition seconds >= 0 is not satisfied
0463: * @see #getQueryTimeout
0464: */
0465: public void setQueryTimeout(int seconds) throws SQLException {
0466:
0467: checkClosed();
0468:
0469: if (seconds < 0) {
0470: throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT);
0471: }
0472: }
0473:
0474: /**
0475: * <!-- start generic documentation -->
0476: * Cancels this <code>Statement</code> object if both the DBMS and
0477: * driver support aborting an SQL statement.
0478: * This method can be used by one thread to cancel a statement that
0479: * is being executed by another thread. <p>
0480: * <!-- end generic documentation -->
0481: *
0482: * <!-- start release-specific documentation -->
0483: * <div class="ReleaseSpecificDocumentation">
0484: * <h3>HSQLDB-Specific Information:</h3> <p>
0485: *
0486: * Including 1.7.2, HSQLDB does <i>not</i> support aborting a SQL
0487: * statement; calls to this method are ignored.
0488: * </div>
0489: * <!-- end release-specific documentation -->
0490: *
0491: * @exception SQLException if a database access error occurs
0492: */
0493: public void cancel() throws SQLException {
0494: checkClosed();
0495: }
0496:
0497: /**
0498: * <!-- start generic documentation -->
0499: * Retrieves the first warning reported by calls on this <code>Statement</code> object.
0500: * Subsequent <code>Statement</code> object warnings will be chained to this
0501: * <code>SQLWarning</code> object.
0502: *
0503: * <p>The warning chain is automatically cleared each time
0504: * a statement is (re)executed. This method may not be called on a closed
0505: * <code>Statement</code> object; doing so will cause an <code>SQLException</code>
0506: * to be thrown.
0507: *
0508: * <P><B>Note:</B> If you are processing a <code>ResultSet</code> object, any
0509: * warnings associated with reads on that <code>ResultSet</code> object
0510: * will be chained on it rather than on the <code>Statement</code>
0511: * object that produced it. <p>
0512: * <!-- end generic documentation -->
0513: *
0514: * <!-- start release-specific documentation -->
0515: * <div class="ReleaseSpecificDocumentation">
0516: * <h3>HSQLDB-Specific Information:</h3> <p>
0517: *
0518: * Including 1.7.2, HSQLDB never produces Statement warnings;
0519: * this method always returns null.
0520: * </div>
0521: * <!-- end release-specific documentation -->
0522: *
0523: * @return the first <code>SQLWarning</code> object or <code>null</code>
0524: * if there are no warnings
0525: * @exception SQLException if a database access error occurs or this
0526: * method is called on a closed statement
0527: */
0528: public SQLWarning getWarnings() throws SQLException {
0529:
0530: checkClosed();
0531:
0532: return null;
0533: }
0534:
0535: /**
0536: * <!-- start generic documentation -->
0537: * Clears all the warnings reported on this <code>Statement</code>
0538: * object. After a call to this method,
0539: * the method <code>getWarnings</code> will return
0540: * <code>null</code> until a new warning is reported for this
0541: * <code>Statement</code> object. <p>
0542: * <!-- end generic documentation -->
0543: *
0544: * <!-- start release-specific documentation -->
0545: * <div class="ReleaseSpecificDocumentation">
0546: * <h3>HSQLDB-Specific Information:</h3> <p>
0547: *
0548: * Including HSQLDB 1.7.2, <code>SQLWarning</code> objects are
0549: * never produced for Statement Objects; calls to this method are
0550: * ignored.
0551: * </div>
0552: * <!-- end release-specific documentation -->
0553: *
0554: * @exception SQLException if a database access error occurs
0555: */
0556: public void clearWarnings() throws SQLException {
0557: checkClosed();
0558: }
0559:
0560: /**
0561: * <!-- start generic documentation -->
0562: * Sets the SQL cursor name to the given <code>String</code>, which
0563: * will be used by subsequent <code>Statement</code> object
0564: * <code>execute</code> methods. This name can then be
0565: * used in SQL positioned update or delete statements to identify the
0566: * current row in the <code>ResultSet</code> object generated by this
0567: * statement. If the database does not support positioned update/delete,
0568: * this method is a noop. To insure that a cursor has the proper isolation
0569: * level to support updates, the cursor's <code>SELECT</code> statement
0570: * should have the form <code>SELECT FOR UPDATE</code>. If
0571: * <code>FOR UPDATE</code> is not present, positioned updates may fail.
0572: *
0573: * <P><B>Note:</B> By definition, the execution of positioned updates and
0574: * deletes must be done by a different <code>Statement</code> object than
0575: * the one that generated the <code>ResultSet</code> object being used for
0576: * positioning. Also, cursor names must be unique within a connection. <p>
0577: * <!-- end generic documentation -->
0578: *
0579: * <!-- start release-specific documentation -->
0580: * <div class="ReleaseSpecificDocumentation">
0581: * <h3>HSQLDB-Specific Information:</h3> <p>
0582: *
0583: * Including 1.7.2, HSQLDB does not support named cursors,
0584: * updateable results or table locking via <code>SELECT FOR UPDATE</code>;
0585: * calls to this method are ignored.
0586: * </div>
0587: * <!-- end release-specific documentation -->
0588: *
0589: * @param name the new cursor name, which must be unique within
0590: * a connection
0591: * @exception SQLException if a database access error occurs
0592: */
0593: public void setCursorName(String name) throws SQLException {
0594: checkClosed();
0595: }
0596:
0597: //----------------------- Multiple Results --------------------------
0598:
0599: /**
0600: * <!-- start generic documentation -->
0601: * Executes the given SQL statement, which may return multiple results.
0602: * In some (uncommon) situations, a single SQL statement may return
0603: * multiple result sets and/or update counts. Normally you can ignore
0604: * this unless you are (1) executing a stored procedure that you know may
0605: * return multiple results or (2) you are dynamically executing an
0606: * unknown SQL string.
0607: * <P>
0608: * The <code>execute</code> method executes an SQL statement and indicates the
0609: * form of the first result. You must then use the methods
0610: * <code>getResultSet</code> or <code>getUpdateCount</code>
0611: * to retrieve the result, and <code>getMoreResults</code> to
0612: * move to any subsequent result(s). <p>
0613: * <!-- end generic documentation -->
0614: *
0615: * @param sql any SQL statement
0616: * @return <code>true</code> if the first result is a <code>ResultSet</code>
0617: * object; <code>false</code> if it is an update count or there are
0618: * no results
0619: * @exception SQLException if a database access error occurs
0620: * @see #getResultSet
0621: * @see #getUpdateCount
0622: * @see #getMoreResults
0623: */
0624: public boolean execute(String sql) throws SQLException {
0625:
0626: checkClosed();
0627: connection.clearWarningsNoCheck();
0628: fetchResult(sql);
0629:
0630: return resultIn.isData();
0631: }
0632:
0633: /**
0634: * <!-- start generic documentation -->
0635: * Retrieves the current result as a <code>ResultSet</code> object.
0636: * This method should be called only once per result. <p>
0637: * <!-- end generic documentation -->
0638: *
0639: * <!-- start release-specific documentation -->
0640: * <div class="ReleaseSpecificDocumentation">
0641: * <h3>HSQLDB-Specific Information:</h3> <p>
0642: *
0643: * Without an interceding call to executeXXX, each invocation of this
0644: * method will produce a new, initialized ResultSet instance referring to
0645: * the current result, if any.
0646: * </div>
0647: * <!-- end release-specific documentation -->
0648: *
0649: * @return the current result as a <code>ResultSet</code> object or
0650: * <code>null</code> if the result is an update count or there
0651: * are no more results
0652: * @exception SQLException if a database access error occurs
0653: * @see #execute
0654: */
0655: public ResultSet getResultSet() throws SQLException {
0656:
0657: checkClosed();
0658:
0659: return resultIn == null || !resultIn.isData() ? null
0660: : new jdbcResultSet(this , resultIn,
0661: connection.connProperties, connection.isNetConn);
0662: }
0663:
0664: /**
0665: * <!-- start generic documentation -->
0666: * Retrieves the current result as an update count;
0667: * if the result is a <code>ResultSet</code> object or there are no more results, -1
0668: * is returned. This method should be called only once per result. <p>
0669: * <!-- end generic documentation -->
0670: *
0671: * @return the current result as an update count; -1 if the current result is a
0672: * <code>ResultSet</code> object or there are no more results
0673: * @exception SQLException if a database access error occurs
0674: * @see #execute
0675: */
0676: public int getUpdateCount() throws SQLException {
0677:
0678: // fredt - omit checkClosed() in order to be able to handle the result of a
0679: // SHUTDOWN query
0680: // checkClosed();
0681: return (resultIn == null || resultIn.isData()) ? -1 : resultIn
0682: .getUpdateCount();
0683: }
0684:
0685: /**
0686: * <!-- start generic documentation -->
0687: * Moves to this <code>Statement</code> object's next result, returns
0688: * <code>true</code> if it is a <code>ResultSet</code> object, and
0689: * implicitly closes any current <code>ResultSet</code>
0690: * object(s) obtained with the method <code>getResultSet</code>.
0691: *
0692: * <P>There are no more results when the following is true:
0693: * <PRE>
0694: * <code>(!getMoreResults() && (getUpdateCount() == -1)</code>
0695: * </PRE> <p>
0696: * <!-- end generic documentation -->
0697: *
0698: * @return <code>true</code> if the next result is a <code>ResultSet</code>
0699: * object; <code>false</code> if it is an update count or there are
0700: * no more results
0701: * @exception SQLException if a database access error occurs
0702: * @see #execute
0703: */
0704: public boolean getMoreResults() throws SQLException {
0705:
0706: checkClosed();
0707:
0708: resultIn = null;
0709:
0710: return false;
0711: }
0712:
0713: //--------------------------JDBC 2.0-----------------------------
0714:
0715: /**
0716: * <!-- start generic documentation -->
0717: * Gives the driver a hint as to the direction in which
0718: * rows will be processed in <code>ResultSet</code>
0719: * objects created using this <code>Statement</code> object. The
0720: * default value is <code>ResultSet.FETCH_FORWARD</code>.
0721: * <P>
0722: * Note that this method sets the default fetch direction for
0723: * result sets generated by this <code>Statement</code> object.
0724: * Each result set has its own methods for getting and setting
0725: * its own fetch direction. <p>
0726: * <!-- end generic documentation -->
0727: *
0728: * <!-- start release-specific documentation -->
0729: * <div class="ReleaseSpecificDocumentation">
0730: * <h3>HSQLDB-Specific Information:</h3> <p>
0731: *
0732: * Including 1.7.2, HSQLDB supports only <code>FETCH_FORWARD</code>. <p>
0733: *
0734: * Setting any other value will throw an <code>SQLException</code>
0735: * stating that the operation is not supported.
0736: * </div>
0737: * <!-- end release-specific documentation -->
0738: *
0739: * @param direction the initial direction for processing rows
0740: * @exception SQLException if a database access error occurs
0741: * or the given direction
0742: * is not one of <code>ResultSet.FETCH_FORWARD</code>,
0743: * <code>ResultSet.FETCH_REVERSE</code>, or
0744: * <code>ResultSet.FETCH_UNKNOWN</code> <p>
0745: *
0746: * HSQLDB throws for all values except <code>FETCH_FORWARD</code>
0747: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0748: * for jdbcStatement)
0749: * @see #getFetchDirection
0750: */
0751: public void setFetchDirection(int direction) throws SQLException {
0752:
0753: checkClosed();
0754:
0755: if (direction != jdbcResultSet.FETCH_FORWARD) {
0756: throw Util.notSupported();
0757: }
0758: }
0759:
0760: /**
0761: * <!-- start generic documentation -->
0762: * Retrieves the direction for fetching rows from
0763: * database tables that is the default for result sets
0764: * generated from this <code>Statement</code> object.
0765: * If this <code>Statement</code> object has not set
0766: * a fetch direction by calling the method <code>setFetchDirection</code>,
0767: * the return value is implementation-specific. <p>
0768: * <!-- end generic documentation -->
0769: *
0770: * <!-- start release-specific documentation -->
0771: * <div class="ReleaseSpecificDocumentation">
0772: * <h3>HSQLDB-Specific Information:</h3> <p>
0773: *
0774: * Including 1.7.2, HSQLDB always returns FETCH_FORWARD.
0775: * </div>
0776: * <!-- end release-specific documentation -->
0777: *
0778: * @return the default fetch direction for result sets generated
0779: * from this <code>Statement</code> object
0780: * @exception SQLException if a database access error occurs
0781: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0782: * for jdbcStatement)
0783: * @see #setFetchDirection
0784: */
0785: public int getFetchDirection() throws SQLException {
0786:
0787: checkClosed();
0788:
0789: return jdbcResultSet.FETCH_FORWARD;
0790: }
0791:
0792: /**
0793: * <!-- start generic documentation -->
0794: * Gives the JDBC driver a hint as to the number of rows that should
0795: * be fetched from the database when more rows are needed. The number
0796: * of rows specified affects only result sets created using this
0797: * statement. If the value specified is zero, then the hint is ignored.
0798: * The default value is zero. <p>
0799: * <!-- start generic documentation -->
0800: *
0801: * <!-- start release-specific documentation -->
0802: * <div class="ReleaseSpecificDocumentation">
0803: * <h3>HSQLDB-Specific Information:</h3> <p>
0804: *
0805: * Including 1.7.2, calls to this method are ignored;
0806: * HSQLDB fetches each result completely as part of
0807: * executing its statement.
0808: * </div>
0809: * <!-- end release-specific documentation -->
0810: *
0811: * @param rows the number of rows to fetch
0812: * @exception SQLException if a database access error occurs, or the
0813: * condition 0 <= <code>rows</code> <= <code>this.getMaxRows()</code>
0814: * is not satisfied. <p>
0815: *
0816: * HSQLDB never throws an exception, since calls to this method
0817: * are always ignored.
0818: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0819: * for jdbcStatement)
0820: * @see #getFetchSize
0821: */
0822: public void setFetchSize(int rows) throws SQLException {
0823: checkClosed();
0824: }
0825:
0826: /**
0827: * <!-- start generic documentation -->
0828: * Retrieves the number of result set rows that is the default
0829: * fetch size for <code>ResultSet</code> objects
0830: * generated from this <code>Statement</code> object.
0831: * If this <code>Statement</code> object has not set
0832: * a fetch size by calling the method <code>setFetchSize</code>,
0833: * the return value is implementation-specific. <p>
0834: * <!-- end generic documentation -->
0835: *
0836: * <!-- start release-specific documentation -->
0837: * <div class="ReleaseSpecificDocumentation">
0838: * <b>HSQLDB-Specific Information</b> <p>
0839: *
0840: * Including 1.7.2, this method always returns 0.
0841: * HSQLDB fetches each result completely as part of
0842: * executing its statement
0843: * </div>
0844: * <!-- end release-specific documentation -->
0845: *
0846: * @return the default fetch size for result sets generated
0847: * from this <code>Statement</code> object
0848: * @exception SQLException if a database access error occurs
0849: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0850: * for jdbcStatement)
0851: * @see #setFetchSize
0852: */
0853: public int getFetchSize() throws SQLException {
0854:
0855: checkClosed();
0856:
0857: return 0;
0858: }
0859:
0860: /**
0861: * <!-- start generic documentation -->
0862: * Retrieves the result set concurrency for <code>ResultSet</code> objects
0863: * generated by this <code>Statement</code> object. <p>
0864: * <!-- end generic documentation -->
0865: *
0866: * <!-- start release-specific documentation -->
0867: * <div class="ReleaseSpecificDocumentation">
0868: * <h3>HSQLDB-Specific Information:</h3> <p>
0869: *
0870: * Including 1.7.2, HSQLDB supports only
0871: * <code>CONCUR_READ_ONLY</code> concurrency.
0872: * </div>
0873: * <!-- end release-specific documentation -->
0874: *
0875: * @return either <code>ResultSet.CONCUR_READ_ONLY</code> or
0876: * <code>ResultSet.CONCUR_UPDATABLE</code> (not supported)
0877: * @exception SQLException if a database access error occurs
0878: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0879: * for jdbcStatement)
0880: */
0881: public int getResultSetConcurrency() throws SQLException {
0882:
0883: checkClosed();
0884:
0885: return jdbcResultSet.CONCUR_READ_ONLY;
0886: }
0887:
0888: /**
0889: * <!-- start generic documentation -->
0890: * Retrieves the result set type for <code>ResultSet</code> objects
0891: * generated by this <code>Statement</code> object. <p>
0892: * <!-- end generic documentation -->
0893: *
0894: * <!-- start release-specific documentation -->
0895: * <div class="ReleaseSpecificDocumentation">
0896: * <h3>HSQLDB-Specific Information:</h3> <p>
0897: *
0898: * HSQLDB 1.7.0 and later versions support <code>TYPE_FORWARD_ONLY</code>
0899: * and <code>TYPE_SCROLL_INSENSITIVE</code>.
0900: * </div>
0901: * <!-- end release-specific documentation -->
0902: *
0903: * @return one of <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0904: * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0905: * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> (not supported) <p>
0906: *
0907: * <b>Note:</b> Up to and including 1.7.1, HSQLDB never returns
0908: * <code>TYPE_SCROLL_SENSITIVE</code>
0909: * @exception SQLException if a database access error occurs
0910: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0911: * for jdbcStatement)
0912: */
0913: public int getResultSetType() throws SQLException {
0914:
0915: // fredt - omit checkClosed() in order to be able to handle the result of a
0916: // SHUTDOWN query
0917: // checkClosed();
0918: return rsType;
0919: }
0920:
0921: /**
0922: * <!-- start generic documentation -->
0923: * Adds the given SQL command to the current list of commmands for this
0924: * <code>Statement</code> object. The commands in this list can be
0925: * executed as a batch by calling the method <code>executeBatch</code>.
0926: * <P>
0927: * <B>NOTE:</B> This method is optional. <p>
0928: * <!-- end generic documentation -->
0929: *
0930: * <!-- start release-specific documentation -->
0931: * <div class="ReleaseSpecificDocumentation">
0932: * <h3>HSQLDB-Specific Information:</h3> <p>
0933: *
0934: * Starting with 1.7.2, this feature is supported.
0935: * </div>
0936: * <!-- end release-specific documentation -->
0937: *
0938: * @param sql typically this is a static SQL <code>INSERT</code> or
0939: * <code>UPDATE</code> statement
0940: * @exception SQLException if a database access error occurs, or the
0941: * driver does not support batch updates
0942: * @see #executeBatch
0943: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0944: * for jdbcStatement)
0945: */
0946: public void addBatch(String sql) throws SQLException {
0947:
0948: checkClosed();
0949:
0950: if (isEscapeProcessing) {
0951: sql = connection.nativeSQL(sql);
0952: }
0953:
0954: if (batchResultOut == null) {
0955: batchResultOut = new Result(
0956: ResultConstants.BATCHEXECDIRECT,
0957: new int[] { Types.VARCHAR }, 0);
0958: }
0959:
0960: batchResultOut.add(new Object[] { sql });
0961: }
0962:
0963: /**
0964: * <!-- start generic documentation -->
0965: * Empties this <code>Statement</code> object's current list of
0966: * SQL commands.
0967: * <P>
0968: * <B>NOTE:</B> This method is optional. <p>
0969: * <!-- start generic documentation -->
0970: *
0971: * <!-- start release-specific documentation -->
0972: * <div class="ReleaseSpecificDocumentation">
0973: * <h3>HSQLDB-Specific Information:</h3> <p>
0974: *
0975: * Starting with HSQLDB 1.7.2, this feature is supported.
0976: * </div>
0977: * <!-- end release-specific documentation -->
0978: *
0979: * @exception SQLException if a database access error occurs or the
0980: * driver does not support batch updates
0981: * @see #addBatch
0982: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
0983: * for jdbcStatement)
0984: */
0985: public void clearBatch() throws SQLException {
0986:
0987: checkClosed();
0988:
0989: if (batchResultOut != null) {
0990: batchResultOut.clear();
0991: }
0992: }
0993:
0994: /**
0995: * <!-- start generic documentation -->
0996: * Submits a batch of commands to the database for execution and
0997: * if all commands execute successfully, returns an array of update counts.
0998: * The <code>int</code> elements of the array that is returned are ordered
0999: * to correspond to the commands in the batch, which are ordered
1000: * according to the order in which they were added to the batch.
1001: * The elements in the array returned by the method <code>executeBatch</code>
1002: * may be one of the following:
1003: * <OL>
1004: * <LI>A number greater than or equal to zero -- indicates that the
1005: * command was processed successfully and is an update count giving the
1006: * number of rows in the database that were affected by the command's
1007: * execution
1008: * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
1009: * processed successfully but that the number of rows affected is
1010: * unknown
1011: * <P>
1012: * If one of the commands in a batch update fails to execute properly,
1013: * this method throws a <code>BatchUpdateException</code>, and a JDBC
1014: * driver may or may not continue to process the remaining commands in
1015: * the batch. However, the driver's behavior must be consistent with a
1016: * particular DBMS, either always continuing to process commands or never
1017: * continuing to process commands. If the driver continues processing
1018: * after a failure, the array returned by the method
1019: * <code>BatchUpdateException.getUpdateCounts</code>
1020: * will contain as many elements as there are commands in the batch, and
1021: * at least one of the elements will be the following:
1022: * <P>
1023: * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
1024: * to execute successfully and occurs only if a driver continues to
1025: * process commands after a command fails
1026: * </OL>
1027: * <P>
1028: * A driver is not required to implement this method.
1029: * The possible implementations and return values have been modified in
1030: * the Java 2 SDK, Standard Edition, version 1.3 to
1031: * accommodate the option of continuing to proccess commands in a batch
1032: * update after a <code>BatchUpdateException</code> obejct has been thrown. <p>
1033: * <!-- end generic documentation -->
1034: *
1035: * <!-- start release-specific documentation -->
1036: * <div class="ReleaseSpecificDocumentation">
1037: * <h3>HSQLDB-Specific Information:</h3> <p>
1038: *
1039: * Starting with HSQLDB 1.7.2, this feature is supported. <p>
1040: *
1041: * HSQLDB stops execution of commands in a batch when one of the commands
1042: * results in an exception. The size of the returned array equals the
1043: * number of commands that were executed successfully.<p>
1044: *
1045: * When the product is built under the JAVA1 target, an exception
1046: * is never thrown and it is the responsibility of the client software to
1047: * check the size of the returned update count array to determine if any
1048: * batch items failed. To build and run under the JAVA2 target, JDK/JRE
1049: * 1.3 or higher must be used.
1050: * </div>
1051: * <!-- end release-specific documentation -->
1052: *
1053: * @return an array of update counts containing one element for each
1054: * command in the batch. The elements of the array are ordered according
1055: * to the order in which commands were added to the batch.
1056: * @exception SQLException if a database access error occurs or the
1057: * driver does not support batch statements. Throws
1058: * {@link java.sql.BatchUpdateException}
1059: * (a subclass of <code>java.sql.SQLException</code>) if one of the commands
1060: * sent to the database fails to execute properly or attempts to return a
1061: * result set.
1062: * @since JDK 1.3 (JDK 1.1.x developers: read the new overview
1063: * for jdbcStatement)
1064: */
1065: public int[] executeBatch() throws SQLException {
1066:
1067: int[] updateCounts;
1068: int batchCount;
1069: HsqlException he;
1070:
1071: checkClosed();
1072: connection.clearWarningsNoCheck();
1073:
1074: if (batchResultOut == null) {
1075: batchResultOut = new Result(
1076: ResultConstants.BATCHEXECDIRECT,
1077: new int[] { Types.VARCHAR }, 0);
1078: }
1079:
1080: batchCount = batchResultOut.getSize();
1081:
1082: try {
1083: resultIn = connection.sessionProxy.execute(batchResultOut);
1084: } catch (HsqlException e) {
1085: batchResultOut.clear();
1086:
1087: throw Util.sqlException(e);
1088: }
1089:
1090: batchResultOut.clear();
1091:
1092: if (resultIn.isError()) {
1093: Util.throwError(resultIn);
1094: }
1095:
1096: updateCounts = resultIn.getUpdateCounts();
1097:
1098: //#ifdef JAVA2
1099: if (updateCounts.length != batchCount) {
1100: throw new BatchUpdateException("failed batch", updateCounts);
1101: }
1102:
1103: //#endif JAVA2
1104: return updateCounts;
1105: }
1106:
1107: /**
1108: * <!-- start generic documentation -->
1109: * Retrieves the <code>Connection</code> object
1110: * that produced this <code>Statement</code> object. <p>
1111: * <!-- end generic documentation -->
1112: *
1113: * @return the connection that produced this statement
1114: * @exception SQLException if a database access error occurs
1115: * @since JDK 1.2 (JDK 1.1.x developers: read the new overview
1116: * for jdbcStatement)
1117: */
1118: public Connection getConnection() throws SQLException {
1119:
1120: checkClosed();
1121:
1122: return connection;
1123: }
1124:
1125: //--------------------------JDBC 3.0-----------------------------
1126:
1127: /**
1128: * <!-- start generic documentation -->
1129: * Moves to this <code>Statement</code> object's next result, deals with
1130: * any current <code>ResultSet</code> object(s) according to the instructions
1131: * specified by the given flag, and returns
1132: * <code>true</code> if the next result is a <code>ResultSet</code> object.
1133: *
1134: * <P>There are no more results when the following is true:
1135: * <PRE>
1136: * <code>(!getMoreResults() && (getUpdateCount() == -1)</code>
1137: * </PRE> <p>
1138: * <!-- end generic documentation -->
1139: *
1140: * <!-- start release-specific documentation -->
1141: * <div class="ReleaseSpecificDocumentation">
1142: * <h3>HSQLDB-Specific Information:</h3> <p>
1143: *
1144: * HSQLDB 1.7.2 does not support this feature. <p>
1145: *
1146: * Calling this method always throws an <code>SQLException</code>,
1147: * stating that the function is not supported.
1148: * </div>
1149: * <!-- end release-specific documentation -->
1150: *
1151: * @param current one of the following <code>Statement</code>
1152: * constants indicating what should happen to current
1153: * <code>ResultSet</code> objects obtained using the method
1154: * <code>getResultSet</code:
1155: * <code>CLOSE_CURRENT_RESULT</code>,
1156: * <code>KEEP_CURRENT_RESULT</code>, or
1157: * <code>CLOSE_ALL_RESULTS</code>
1158: * @return <code>true</code> if the next result is a <code>ResultSet</code>
1159: * object; <code>false</code> if it is an update count or there are no
1160: * more results
1161: * @exception SQLException if a database access error occurs
1162: * @since JDK 1.4, HSQLDB 1.7
1163: * @see #execute
1164: */
1165: //#ifdef JDBC3
1166: public boolean getMoreResults(int current) throws SQLException {
1167: throw Util.notSupported();
1168: }
1169:
1170: //#endif JDBC3
1171:
1172: /**
1173: * <!-- start generic documentation -->
1174: * Retrieves any auto-generated keys created as a result of executing this
1175: * <code>Statement</code> object. If this <code>Statement</code> object did
1176: * not generate any keys, an empty <code>ResultSet</code>
1177: * object is returned. <p>
1178: * <!-- end generic documentation -->
1179: *
1180: * <!-- start release-specific documentation -->
1181: * <div class="ReleaseSpecificDocumentation">
1182: * <h3>HSQLDB-Specific Information:</h3> <p>
1183: *
1184: * HSQLDB 1.7.2 does not support this feature. <p>
1185: *
1186: * Calling this method always throws an <code>SQLException</code>,
1187: * stating that the function is not supported.
1188: * </div>
1189: * <!-- end release-specific documentation -->
1190: *
1191: * @return a <code>ResultSet</code> object containing the auto-generated key(s)
1192: * generated by the execution of this <code>Statement</code> object
1193: * @exception SQLException if a database access error occurs
1194: * @since JDK 1.4, HSQLDB 1.7
1195: */
1196: //#ifdef JDBC3
1197: public ResultSet getGeneratedKeys() throws SQLException {
1198: throw Util.notSupported();
1199: }
1200:
1201: //#endif JDBC3
1202:
1203: /**
1204: * <!-- start generic documentation -->
1205: * Executes the given SQL statement and signals the driver with the
1206: * given flag about whether the
1207: * auto-generated keys produced by this <code>Statement</code> object
1208: * should be made available for retrieval. <p>
1209: * <!-- end generic documentation -->
1210: *
1211: * <!-- start release-specific documentation -->
1212: * <div class="ReleaseSpecificDocumentation">
1213: * <h3>HSQLDB-Specific Information:</h3> <p>
1214: *
1215: * HSQLDB 1.7.2 does not support this feature. <p>
1216: *
1217: * Calling this method always throws an <code>SQLException</code>,
1218: * stating that the function is not supported.
1219: * </div>
1220: * <!-- end release-specific documentation -->
1221: *
1222: * @param sql must be an SQL <code>INSERT</code>, <code>UPDATE</code> or
1223: * <code>DELETE</code> statement or an SQL statement that
1224: * returns nothing
1225: * @param autoGeneratedKeys a flag indicating whether auto-generated keys
1226: * should be made available for retrieval;
1227: * one of the following constants:
1228: * <code>Statement.RETURN_GENERATED_KEYS</code>
1229: * <code>Statement.NO_GENERATED_KEYS</code>
1230: * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
1231: * or <code>DELETE</code> statements, or <code>0</code> for SQL
1232: * statements that return nothing
1233: * @exception SQLException if a database access error occurs, the given
1234: * SQL statement returns a <code>ResultSet</code> object, or
1235: * the given constant is not one of those allowed
1236: * @since JDK 1.4, HSQLDB 1.7
1237: */
1238: //#ifdef JDBC3
1239: public int executeUpdate(String sql, int autoGeneratedKeys)
1240: throws SQLException {
1241: throw Util.notSupported();
1242: }
1243:
1244: //#endif JDBC3
1245:
1246: /**
1247: * <!-- start generic documentation -->
1248: * Executes the given SQL statement and signals the driver that the
1249: * auto-generated keys indicated in the given array should be made available
1250: * for retrieval. The driver will ignore the array if the SQL statement
1251: * is not an <code>INSERT</code> statement. <p>
1252: * <!-- end generic documentation -->
1253: *
1254: * <!-- start release-specific documentation -->
1255: * <div class="ReleaseSpecificDocumentation">
1256: * <h3>HSQLDB-Specific Information:</h3> <p>
1257: *
1258: * HSQLDB 1.7.2 does not support this feature. <p>
1259: *
1260: * Calling this method always throws an <code>SQLException</code>,
1261: * stating that the function is not supported.
1262: * </div>
1263: * <!-- end release-specific documentation -->
1264: *
1265: * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
1266: * <code>DELETE</code> statement or an SQL statement that returns nothing,
1267: * such as an SQL DDL statement
1268: * @param columnIndexes an array of column indexes indicating the columns
1269: * that should be returned from the inserted row
1270: * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
1271: * or <code>DELETE</code> statements, or 0 for SQL statements
1272: * that return nothing
1273: * @exception SQLException if a database access error occurs or the SQL
1274: * statement returns a <code>ResultSet</code> object
1275: * @since JDK 1.4, HSQLDB 1.7
1276: */
1277: //#ifdef JDBC3
1278: public int executeUpdate(String sql, int[] columnIndexes)
1279: throws SQLException {
1280: throw Util.notSupported();
1281: }
1282:
1283: //#endif JDBC3
1284:
1285: /**
1286: * <!-- start generic documentation -->
1287: * Executes the given SQL statement and signals the driver that the
1288: * auto-generated keys indicated in the given array should be made available
1289: * for retrieval. The driver will ignore the array if the SQL statement
1290: * is not an <code>INSERT</code> statement. <p>
1291: * <!-- end generic documentation -->
1292: *
1293: * <!-- start release-specific documentation -->
1294: * <div class="ReleaseSpecificDocumentation">
1295: * <h3>HSQLDB-Specific Information:</h3> <p>
1296: *
1297: * HSQLDB 1.7.2 does not support this feature. <p>
1298: *
1299: * Calling this method always throws an <code>SQLException</code>,
1300: * stating that the function is not supported.
1301: * </div>
1302: * <!-- end release-specific documentation -->
1303: *
1304: * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
1305: * <code>DELETE</code> statement or an SQL statement that returns nothing
1306: * @param columnNames an array of the names of the columns that should be
1307: * returned from the inserted row
1308: * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
1309: * or <code>DELETE</code> statements, or 0 for SQL statements
1310: * that return nothing
1311: * @exception SQLException if a database access error occurs
1312: * @since JDK 1.4, HSQLDB 1.7
1313: */
1314: //#ifdef JDBC3
1315: public int executeUpdate(String sql, String[] columnNames)
1316: throws SQLException {
1317: throw Util.notSupported();
1318: }
1319:
1320: //#endif JDBC3
1321:
1322: /**
1323: * <!-- start generic documentation -->
1324: * Executes the given SQL statement, which may return multiple results,
1325: * and signals the driver that any
1326: * auto-generated keys should be made available
1327: * for retrieval. The driver will ignore this signal if the SQL statement
1328: * is not an <code>INSERT</code> statement.
1329: * <P>
1330: * In some (uncommon) situations, a single SQL statement may return
1331: * multiple result sets and/or update counts. Normally you can ignore
1332: * this unless you are (1) executing a stored procedure that you know may
1333: * return multiple results or (2) you are dynamically executing an
1334: * unknown SQL string.
1335: * <P>
1336: * The <code>execute</code> method executes an SQL statement and indicates the
1337: * form of the first result. You must then use the methods
1338: * <code>getResultSet</code> or <code>getUpdateCount</code>
1339: * to retrieve the result, and <code>getMoreResults</code> to
1340: * move to any subsequent result(s). <p>
1341: * <!-- end generic documentation -->
1342: *
1343: * <!-- start release-specific documentation -->
1344: * <div class="ReleaseSpecificDocumentation">
1345: * <h3>HSQLDB-Specific Information:</h3> <p>
1346: *
1347: * HSQLDB 1.7.2 does not support this feature. <p>
1348: *
1349: * Calling this method always throws an <code>SQLException</code>,
1350: * stating that the function is not supported.
1351: * </div>
1352: * <!-- end release-specific documentation -->
1353: *
1354: * @param sql any SQL statement
1355: * @param autoGeneratedKeys a constant indicating whether auto-generated
1356: * keys should be made available for retrieval using the method
1357: * <code>getGeneratedKeys</code>; one of the following constants:
1358: * <code>Statement.RETURN_GENERATED_KEYS</code> or
1359: * <code>Statement.NO_GENERATED_KEYS</code>
1360: * @return <code>true</code> if the first result is a <code>ResultSet</code>
1361: * object; <code>false</code> if it is an update count or there are
1362: * no results
1363: * @exception SQLException if a database access error occurs
1364: * @see #getResultSet
1365: * @see #getUpdateCount
1366: * @see #getMoreResults
1367: * @see #getGeneratedKeys
1368: * @since JDK 1.4, HSQLDB 1.7
1369: */
1370: //#ifdef JDBC3
1371: public boolean execute(String sql, int autoGeneratedKeys)
1372: throws SQLException {
1373: throw Util.notSupported();
1374: }
1375:
1376: //#endif JDBC3
1377:
1378: /**
1379: * <!-- start generic documentation -->
1380: * Executes the given SQL statement, which may return multiple results,
1381: * and signals the driver that the
1382: * auto-generated keys indicated in the given array should be made available
1383: * for retrieval. This array contains the indexes of the columns in the
1384: * target table that contain the auto-generated keys that should be made
1385: * available. The driver will ignore the array if the given SQL statement
1386: * is not an <code>INSERT</code> statement.
1387: * <P>
1388: * Under some (uncommon) situations, a single SQL statement may return
1389: * multiple result sets and/or update counts. Normally you can ignore
1390: * this unless you are (1) executing a stored procedure that you know may
1391: * return multiple results or (2) you are dynamically executing an
1392: * unknown SQL string.
1393: * <P>
1394: * The <code>execute</code> method executes an SQL statement and indicates the
1395: * form of the first result. You must then use the methods
1396: * <code>getResultSet</code> or <code>getUpdateCount</code>
1397: * to retrieve the result, and <code>getMoreResults</code> to
1398: * move to any subsequent result(s). <p>
1399: * <!-- end generic documentation -->
1400: *
1401: * <!-- start release-specific documentation -->
1402: * <div class="ReleaseSpecificDocumentation">
1403: * <h3>HSQLDB-Specific Information:</h3> <p>
1404: *
1405: * HSQLDB 1.7.2 does not support this feature. <p>
1406: *
1407: * Calling this method always throws an <code>SQLException</code>,
1408: * stating that the function is not supported.
1409: * </div>
1410: * <!-- end release-specific documentation -->
1411: *
1412: * @param sql any SQL statement
1413: * @param columnIndexes an array of the indexes of the columns in the
1414: * inserted row that should be made available for retrieval by a
1415: * call to the method <code>getGeneratedKeys</code>
1416: * @return <code>true</code> if the first result is a <code>ResultSet</code>
1417: * object; <code>false</code> if it is an update count or there
1418: * are no results
1419: * @exception SQLException if a database access error occurs
1420: * @see #getResultSet
1421: * @see #getUpdateCount
1422: * @see #getMoreResults
1423: * @since JDK 1.4, HSQLDB 1.7
1424: */
1425: //#ifdef JDBC3
1426: public boolean execute(String sql, int[] columnIndexes)
1427: throws SQLException {
1428: throw Util.notSupported();
1429: }
1430:
1431: //#endif JDBC3
1432:
1433: /**
1434: * <!-- start generic documentation -->
1435: * Executes the given SQL statement, which may return multiple results,
1436: * and signals the driver that the
1437: * auto-generated keys indicated in the given array should be made available
1438: * for retrieval. This array contains the names of the columns in the
1439: * target table that contain the auto-generated keys that should be made
1440: * available. The driver will ignore the array if the given SQL statement
1441: * is not an <code>INSERT</code> statement.
1442: * <P>
1443: * In some (uncommon) situations, a single SQL statement may return
1444: * multiple result sets and/or update counts. Normally you can ignore
1445: * this unless you are (1) executing a stored procedure that you know may
1446: * return multiple results or (2) you are dynamically executing an
1447: * unknown SQL string.
1448: * <P>
1449: * The <code>execute</code> method executes an SQL statement and indicates the
1450: * form of the first result. You must then use the methods
1451: * <code>getResultSet</code> or <code>getUpdateCount</code>
1452: * to retrieve the result, and <code>getMoreResults</code> to
1453: * move to any subsequent result(s). <p>
1454: * <!-- end generic documentation -->
1455: *
1456: * <!-- start release-specific documentation -->
1457: * <div class="ReleaseSpecificDocumentation">
1458: * <h3>HSQLDB-Specific Information:</h3> <p>
1459: *
1460: * HSQLDB 1.7.2 does not support this feature. <p>
1461: *
1462: * Calling this method always throws an <code>SQLException</code>,
1463: * stating that the function is not supported.
1464: * </div>
1465: * <!-- end release-specific documentation -->
1466: *
1467: * @param sql any SQL statement
1468: * @param columnNames an array of the names of the columns in the inserted
1469: * row that should be made available for retrieval by a call to the
1470: * method <code>getGeneratedKeys</code>
1471: * @return <code>true</code> if the next result is a <code>ResultSet</code>
1472: * object; <code>false</code> if it is an update count or there
1473: * are no more results
1474: * @exception SQLException if a database access error occurs
1475: * @see #getResultSet
1476: * @see #getUpdateCount
1477: * @see #getMoreResults
1478: * @see #getGeneratedKeys
1479: * @since JDK 1.4, HSQLDB 1.7
1480: */
1481: //#ifdef JDBC3
1482: public boolean execute(String sql, String[] columnNames)
1483: throws SQLException {
1484: throw Util.notSupported();
1485: }
1486:
1487: //#endif JDBC3
1488:
1489: /**
1490: * <!-- start generic documentation -->
1491: * Retrieves the result set holdability for <code>ResultSet</code> objects
1492: * generated by this <code>Statement</code> object. <p>
1493: * <!-- end generic documentation -->
1494: *
1495: * <!-- start release-specific documentation -->
1496: * <div class="ReleaseSpecificDocumentation">
1497: * <h3>HSQLDB-Specific Information:</h3> <p>
1498: *
1499: * Starting with 1.7.2, this method returns HOLD_CURSORS_OVER_COMMIT
1500: * </div>
1501: * <!-- end release-specific documentation -->
1502: *
1503: * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
1504: * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
1505: * @exception SQLException if a database access error occurs
1506: * @since JDK 1.4, HSQLDB 1.7
1507: */
1508: //#ifdef JDBC3
1509: public int getResultSetHoldability() throws SQLException {
1510: return jdbcResultSet.HOLD_CURSORS_OVER_COMMIT;
1511: }
1512:
1513: //#endif JDBC3
1514: // -------------------- Internal Implementation ----------------------------
1515:
1516: /**
1517: * Constructs a new jdbcStatement with the specified connection and
1518: * result type.
1519: *
1520: * @param c the connection on which this statement will execute
1521: * @param type the kind of results this will return
1522: */
1523: jdbcStatement(jdbcConnection c, int type) {
1524:
1525: // PRE: assume connection is not null and is not closed
1526: // PRE: assume type is a valid result set type code
1527: connection = c;
1528: rsType = type;
1529: }
1530:
1531: /**
1532: * Retrieves whether this statement is closed.
1533: */
1534: synchronized boolean isClosed() {
1535: return isClosed;
1536: }
1537:
1538: /**
1539: * An internal check for closed statements.
1540: *
1541: * @throws SQLException when the connection is closed
1542: */
1543: void checkClosed() throws SQLException {
1544:
1545: if (isClosed) {
1546: throw Util.sqlException(Trace.STATEMENT_IS_CLOSED);
1547: }
1548:
1549: if (connection.isClosed) {
1550: throw Util.sqlException(Trace.CONNECTION_IS_CLOSED);
1551: }
1552: }
1553:
1554: /**
1555: * Internal result producer for jdbcStatement (sqlExecDirect mode). <p>
1556: *
1557: * @param sql a character sequence representing the SQL to be executed
1558: * @throws SQLException when a database access error occurs
1559: */
1560: private void fetchResult(String sql) throws SQLException {
1561:
1562: if (isEscapeProcessing) {
1563: sql = connection.nativeSQL(sql);
1564: }
1565:
1566: resultIn = null;
1567:
1568: resultOut.setMainString(sql);
1569: resultOut.setMaxRows(maxRows);
1570:
1571: try {
1572: resultIn = connection.sessionProxy.execute(resultOut);
1573:
1574: if (resultIn.isError()) {
1575: throw new HsqlException(resultIn);
1576: }
1577: } catch (HsqlException e) {
1578: throw Util.sqlException(e);
1579: }
1580: }
1581: }
|