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


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 import java.math.BigDecimal ;
35 import java.sql.CallableStatement ;
36 import java.sql.Date ;
37 import java.sql.Time ;
38 import java.sql.Timestamp ;
39 import java.sql.SQLException ;
40 import java.util.Calendar ;
41
42 //#ifdef JAVA2
43 import java.sql.Array ;
44 import java.sql.Blob ;
45 import java.sql.Clob ;
46 import java.sql.Ref ;
47 import java.util.Map ;
48
49 //#endif JAVA2
50 import org.hsqldb.HsqlException;
51 import org.hsqldb.Trace;
52 import org.hsqldb.lib.IntValueHashMap;
53
54 // boucherb@users patch 1.7.2 - CallableStatement impl removed
55 // from jdbcPreparedStatement and moved here; sundry changes elsewhere to
56 // comply
57 // TODO: 1.7.2 Alpha N :: DONE
58 // maybe implement set-by-parameter-name. We have an informal spec,
59 // being "@p1" => 1, "@p2" => 2, etc. Problems: return value is "@p0"
60 // and there is no support for registering the return value as an out
61 // parameter.
62 // TODO: 1.8.x
63 // engine and client-side mechanisms for adding, retrieving,
64 // navigating (and perhaps controlling holdability of) multiple
65 // results generated from a single execution.
66 // boucherb@users 2004-03/04-xx - patch 1.7.2 - some minor code cleanup
67 // - parameter map NPE correction
68 // - embedded SQL/SQLCLI client usability
69 // (parameter naming changed from @n to @pn)
70 // boucherb@users 2004-04-xx - doc 1.7.2 - javadocs added/updated
71
72 /**
73  * <!-- start generic documentation -->
74  *
75  * The interface used to execute SQL stored procedures. The JDBC API
76  * provides a stored procedure SQL escape syntax that allows stored
77  * procedures to be called in a standard way for all RDBMSs. This escape
78  * syntax has one form that includes a result parameter and one that does
79  * not. If used, the result parameter must be registered as an OUT parameter.
80  * The other parameters can be used for input, output or both. Parameters
81  * are referred to sequentially, by number, with the first parameter being 1.
82  * <PRE>
83  * {?= call &lt;procedure-name&gt;[&lt;arg1&gt;,&lt;arg2&gt;, ...]}
84  * {call &lt;procedure-name&gt;[&lt;arg1&gt;,&lt;arg2&gt;, ...]}
85  * </PRE>
86  * <P>
87  * IN parameter values are set using the <code>set</code> methods inherited from
88  * {@link PreparedStatement}. The type of all OUT parameters must be
89  * registered prior to executing the stored procedure; their values
90  * are retrieved after execution via the <code>get</code> methods provided here.
91  * <P>
92  * A <code>CallableStatement</code> can return one {@link ResultSet} object or
93  * multiple <code>ResultSet</code> objects. Multiple
94  * <code>ResultSet</code> objects are handled using operations
95  * inherited from {@link Statement}.
96  * <P>
97  * For maximum portability, a call's <code>ResultSet</code> objects and
98  * update counts should be processed prior to getting the values of output
99  * parameters.
100  * <P>
101  * <!-- end generic documentation -->
102  * <!-- start Release-specific documentation -->
103  * <div class="ReleaseSpecificDocumentation">
104  * <h3>HSQLDB-Specific Information:</h3> <p>
105  *
106  * Since 1.7.2, the JDBC CallableStatement interface implementation has been
107  * broken out of the jdbcPreparedStatement class into this one. <p>
108  *
109  * With 1.7.2, some of the previously unsupported features of this interface
110  * are now supported, such as the parameterName-based setter methods. <p>
111  *
112  * More importantly, jdbcCallableStatement objects are now backed by a true
113  * compiled parameteric representation. Hence, there are now significant
114  * performance gains to be had by using a CallableStatement object instead of
115  * a Statement object, if a short-running CALL statement is to be executed more
116  * than a small number of times. Moreover, the recent work lays the foundation
117  * for work in a subsequenct release to support CallableStatement OUT and
118  * IN OUT style parameters, as well as the generation and retrieval of multiple
119  * results in response to the execution of a CallableStatement object. <p>
120  *
121  * For a more in-depth discussion of performance issues regarding 1.7.2
122  * prepared and callable statement objects, please see overview section of
123  * {@link jdbcPreparedStatement jdbcPreparedStatment}.
124  *
125  * <hr>
126  *
127  * As with many DBMS, HSQLDB support for stored procedures is not provided in
128  * a completely standard fashion. <p>
129  *
130  * Beyond the XOpen/ODBC extended scalar functions, stored procedures are
131  * typically supported in ways that vary greatly from one DBMS implementation
132  * to the next. So, it is almost guaranteed that the code for a stored
133  * procedure written under a specific DBMS product will not work without
134  * at least some modification in the context of another vendor's product
135  * or even across a single vendor's product lines. Moving stored procedures
136  * from one DBMS product line to another almost invariably involves complex
137  * porting issues and often may not be possible at all. <em>Be warned</em>. <p>
138  *
139  * At present, HSQLDB stored procedures map directly onto the methods of
140  * compiled Java classes found on the classpath of the engine at runtime. This
141  * is done in a non-standard but fairly efficient way by issuing a class
142  * grant (and possibly method aliases) of the form: <p>
143  *
144  * <PRE class="SqlCodeExample">
145  * GRANT ALL ON CLASS &quot;package.class&quot; TO [&lt;user-name&gt; | PUBLIC]
146  * CREATE ALIAS &ltcall-alias&gt; FOR &quot;package.class.method&quot; -- optional
147  * </PRE>
148  *
149  * This has the effect of allowing the specified user(s) to access the
150  * set of uniquely named public static methods of the specified class,
151  * in either the role of SQL functions or stored procedures.
152
153  * For example: <p>
154  *
155  * <PRE class="SqlCodeExample">
156  * CONNECT &lt;admin-user&gt; PASSWORD &lt;admin-user-password&gt;;
157  * GRANT ALL ON CLASS &quot;org.myorg.MyClass&quot; TO PUBLIC;
158  * CREATE ALIAS sp_my_method FOR &quot;org.myorg.MyClass.myMethod&quot;
159  * CONNECT &lt;any-user&gt; PASSWORD &lt;any-user-password&gt;;
160  * SELECT &quot;org.myorg.MyClass.myMethod&quot;(column_1) FROM table_1;
161  * SELECT sp_my_method(column_1) FROM table_1;
162  * CALL 2 + &quot;org.myorg.MyClass.myMethod&quot;(-5);
163  * CALL 2 + sp_my_method(-5);
164  * </PRE>
165  *
166  * Please note the use of the term &quot;uniquely named&quot; above. Including
167  * 1.7.2, no support is provided to deterministically resolve overloaded
168  * method names, and there can be issues with inherited methods as well;
169  * currently, it is strongly recommended that developers creating stored
170  * procedure library classes for HSQLDB simply avoid designs such that SQL
171  * stored procedure calls attempt to resolve to: <p>
172  *
173  * <ol>
174  * <li>inherited public static methods
175  * <li>overloaded public static methods
176  * </ol>
177  *
178  * Also, please note that <code>OUT</code> and <code>IN OUT</code> parameters
179  * are not yet supported due to some unresolved low level support issues. <p>
180  *
181  * Including 1.7.2, the HSQLDB stored procedure call mechanism is essentially a
182  * thin wrap of the HSQLDB SQL function call mechanism, extended to include the
183  * more general HSQLDB SQL expression evaluation mechanism. In addition to
184  * stored procedure calls that resolve directly to Java method invocations, the
185  * extention provides the ability to evaluate simple SQL expressions, possibly
186  * containing Java method invocations, outside any <code>INSERT</code>,
187  * <code>UPDATE</code>, <code>DELETE</code> or <code>SELECT</code> statement
188  * context. <p>
189  *
190  * With HSQLDB, executing a <code>CALL</code> statement that produces an opaque
191  * (OTHER) or known scalar object reference has virtually the same effect as:
192  *
193  * <PRE class="SqlCodeExample">
194  * CREATE TABLE DUAL (dummy VARCHAR);
195  * INSERT INTO DUAL VALUES(NULL);
196  * SELECT &lt;simple-expression&gt; FROM DUAL;
197  * </PRE>
198  *
199  * As a transitional measure, HSQLDB provides the ability to materialize a
200  * general result set in response to stored procedure execution. In this case,
201  * the stored procedure's Java method descriptor must specify a return type of
202  * java.lang.Object for external use (although at any point in the devlopment
203  * cycle, other, proprietary return types may accepted internally for engine
204  * development purposes).
205
206  * When HSQLDB detects that the runtime class of the resulting Object is
207  * elligible, an automatic internal unwrapping is performed to correctly
208  * expose the underlying result set to the client, whether local or remote. <p>
209  *
210  * Additionally, HSQLDB automatically detects if java.sql.Connection is
211  * the class of the first argument of any underlying Java method(s). If so,
212  * then the engine transparently supplies the internal Connection object
213  * corresponding to the Session executing the call, adjusting the positions
214  * of other arguments to suite the SQL context. <p>
215  *
216  * The features above are not intended to be permanent. Rather, the intention
217  * is to offer more general and powerful mechanisms in a future release;
218  * it is recommend to use them only as a temporary convenience. <p>
219  *
220  * For instance, one might be well advised to future-proof by writing
221  * HSQLDB-specific adapter methods that in turn call the real logic of an
222  * underlying generalized JDBC stored procedure library. <p>
223  *
224  * Here is a very simple example of an HSQLDB stored procedure generating a
225  * user-defined result set:
226  *
227  * <pre class="JavaCodeExample">
228  * <span class="JavaKeyWord">package</span> mypackage;
229  *
230  * <span class="JavaKeyWord">class</span> MyClass {
231  *
232  * <span class="JavaKeyWord">public static</span> Object <b>mySp</b>(Connection conn) <span class="JavaKeyWord">throws</span> SQLException {
233  * <span class="JavaKeyWord">return</span> conn.<b>createStatement</b>().<b>executeQuery</b>(<span class="JavaStringLiteral">"select * from my_table"</span>);
234  * }
235  * }
236  * </pre>
237  *
238  * Here is a refinement demonstrating no more than the bare essence of the idea
239  * behind a more portable style:
240  *
241  * <pre class="JavaCodeExample">
242  * <span class="JavaKeyWord">package</span> mypackage;
243  *
244  * <span class="JavaKeyWord">import</span> java.sql.ResultSet;
245  * <span class="JavaKeyWord">import</span> java.sql.SQLException;
246  *
247  * <span class="JavaKeyWord">class</span> MyLibraryClass {
248  *
249  * <span class="JavaKeyWord">public static</span> ResultSet <b>mySp()</b> <span class="JavaKeyWord">throws</span> SQLException {
250  * <span class="JavaKeyWord">return</span> ctx.<b>getConnection</b>().<b>createStatement</b>().<b>executeQuery</b>(<span class="JavaStringLiteral">"select * from my_table"</span>);
251  * }
252  * }
253  *
254  * //--
255  *
256  * <span class="JavaKeyWord">package</span> myadaptorpackage;
257  *
258  * <span class="JavaKeyWord">import</span> java.sql.Connection;
259  * <span class="JavaKeyWord">import</span> java.sql.SQLException;
260  *
261  * <span class="JavaKeyWord">class</span> MyAdaptorClass {
262  *
263  * <span class="JavaKeyWord">public static</span> Object <b>mySp</b>(Connection conn) <span class="JavaKeyWord">throws</span> SQLException {
264  * MyLibraryClass.<b>getCtx()</b>.<b>setConnection</b>(conn);
265  * <span class="JavaKeyWord">return</span> MyLibraryClass.<b>mySp</b>();
266  * }
267  * }
268  * </pre>
269  *
270  * In a future release, it is intended to provided some new features
271  * that will support writing fairly portable JDBC-based stored procedure
272  * code: <P>
273  *
274  * <ul>
275  * <li> Support for the <span class="JavaStringLiteral">"jdbc:default:connection"</span>
276  * standard database connection url. <p>
277  *
278  * <li> A well-defined specification of the behaviour of the HSQLDB execution
279  * stack under stored procedure calls. <p>
280  *
281  * <li> A well-defined, pure JDBC specification for generating multiple
282  * results from HSQLDB stored procedures for client retrieval.
283  * </ul>
284  *
285  * (boucherb@users)
286  * </div>
287  * <!-- end Release-specific documentation -->
288  *
289  * @author boucherb@users
290  * @version 1.7.2
291  * @since 1.7.2
292  * @see jdbcConnection#prepareCall
293  * @see jdbcResultSet
294  */
295 public class jdbcCallableStatement extends jdbcPreparedStatement
296 implements CallableStatement {
297
298     /** parameter name => parameter index */
299     private IntValueHashMap parameterNameMap;
300
301     /** parameter index => registered OUT type */
302
303     // private IntKeyIntValueHashMap outRegistrationMap;
304
305     /**
306      * Constructs a new jdbcCallableStatement with the specified connection and
307      * result type.
308      *
309      * @param c the connection on which this statement will execute
310      * @param sql the SQL statement this object represents
311      * @param type the type of result this statement will produce
312      * @throws HsqlException if the statement is not accepted by the database
313      * @throws SQLException if preprocessing by driver fails
314      */
315     public jdbcCallableStatement(jdbcConnection c, String sql,
316                                  int type)
317                                  throws HsqlException, SQLException {
318
319         super(c, sql, type);
320
321         String [] names;
322         String name;
323
324         // outRegistrationMap = new IntKeyIntValueHashMap();
325 parameterNameMap = new IntValueHashMap();
326
327         if (pmdDescriptor != null && pmdDescriptor.metaData != null) {
328             names = pmdDescriptor.metaData.colNames;
329
330             for (int i = 0; i < names.length; i++) {
331                 name = names[i];
332
333                 // PRE: should never happen in practice
334 if (name == null || name.length() == 0) {
335                     continue; // throw?
336 }
337
338                 parameterNameMap.put(name, i);
339             }
340         }
341     }
342
343     /**
344      * Retrieves the parameter index corresponding to the given
345      * parameter name. <p>
346      *
347      * @param parameterName to look up
348      * @throws SQLException if not found
349      * @return index for name
350      */
351     int findParameterIndex(String parameterName) throws SQLException {
352
353         checkClosed();
354
355         int index = parameterNameMap.get(parameterName, -1);
356
357         if (index >= 0) {
358             return index + 1;
359         }
360
361         throw Util.sqlException(Trace.COLUMN_NOT_FOUND, parameterName);
362     }
363
364     /**
365      * Does the specialized work required to free this object's resources and
366      * that of it's parent classes. <p>
367      *
368      * @throws SQLException if a database access error occurs
369      */
370     public void close() throws SQLException {
371
372         if (isClosed()) {
373             return;
374         }
375
376         // outRegistrationMap = null;
377 parameterNameMap = null;
378
379         super.close();
380     }
381
382     /**
383      * Performs an internal check for OUT or IN OUT column index validity. <p>
384      *
385      * @param i the one-based column index to check
386      * @throws SQLException if there is no such OUT or IN OUT column
387      */
388     private void checkGetParameterIndex(int i) throws SQLException {
389
390         checkClosed();
391
392         if (i < 1 || i > parameterModes.length) {
393             String msg = "Parameter index out of bounds: " + i;
394
395             throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT, msg);
396         }
397 /*
398         int mode = parameterModes[i - 1];
399
400         switch (mode) {
401
402             default :
403                 String msg = "Not OUT or IN OUT mode: " + mode
404                              + " for parameter: " + i;
405
406                 throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT, msg);
407             case Expression.PARAM_IN_OUT :
408             case Expression.PARAM_OUT :
409                 break;
410
411             // this is OK
412         }
413  */
414     }
415
416     /**
417      * Checks if the parameter of the given index has been successfully
418      * registered as an OUT parameter. <p>
419      *
420      * @param parameterIndex to check
421      * @throws SQLException if not registered
422      */
423     /*
424     private void checkIsRegisteredParameterIndex(int parameterIndex)
425     throws SQLException {
426
427         int type;
428         String msg;
429
430         checkClosed();
431
432         type = outRegistrationMap.get(parameterIndex, Integer.MIN_VALUE);
433
434         if (type == Integer.MIN_VALUE) {
435             msg = "Parameter not registered: " + parameterIndex;
436
437             throw Util.sqlException(Trace.INVALID_JDBC_ARGUMENT, msg);
438         }
439     }
440     */
441
442 // ----------------------------------- JDBC 1 ----------------------------------
443
444     /**
445      * <!-- start generic documentation -->
446      * Registers the OUT parameter in ordinal position
447      * <code>parameterIndex</code> to the JDBC type
448      * <code>sqlType</code>. All OUT parameters must be registered
449      * before a stored procedure is executed.
450      * <p>
451      * The JDBC type specified by <code>sqlType</code> for an OUT
452      * parameter determines the Java type that must be used
453      * in the <code>get</code> method to read the value of that parameter.
454      * <p>
455      * If the JDBC type expected to be returned to this output parameter
456      * is specific to this particular database, <code>sqlType</code>
457      * should be <code>java.sql.Types.OTHER</code>. The method
458      * {@link #getObject} retrieves the value. <p>
459      * <!-- end generic documentation -->
460      *
461      * <!-- start release-specific documentation -->
462      * <div class="ReleaseSpecificDocumentation">
463      * <h3>HSQLDB-Specific Information:</h3> <p>
464      *
465      * HSQLDB 1.7.2 does not support this feature. <p>
466      *
467      * Calling this method always throws an <code>SQLException</code>.
468      * </div>
469      * <!-- end release-specific documentation -->
470      *
471      * @param parameterIndex the first parameter is 1, the second is 2,
472      * and so on
473      * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
474      * If the parameter is of JDBC type <code>NUMERIC</code>
475      * or <code>DECIMAL</code>, the version of
476      * <code>registerOutParameter</code> that accepts a scale value
477      * should be used.
478      * @exception SQLException if a database access error occurs
479      * @see java.sql.Types
480      */
481     public void registerOutParameter(int parameterIndex,
482                                      int sqlType) throws SQLException {
483         throw Util.notSupported();
484     }
485
486     /**
487      * <!-- start generic documentation -->
488      * Registers the parameter in ordinal position
489      * <code>parameterIndex</code> to be of JDBC type
490      * <code>sqlType</code>. This method must be called
491      * before a stored procedure is executed.
492      * <p>
493      * The JDBC type specified by <code>sqlType</code> for an OUT
494      * parameter determines the Java type that must be used
495      * in the <code>get</code> method to read the value of that parameter.
496      * <p>
497      * This version of <code>registerOutParameter</code> should be
498      * used when the parameter is of JDBC type <code>NUMERIC</code>
499      * or <code>DECIMAL</code>. <p>
500      * <!-- end generic documentation -->
501      *
502      * <!-- start release-specific documentation -->
503      * <div class="ReleaseSpecificDocumentation">
504      * <h3>HSQLDB-Specific Information:</h3> <p>
505      *
506      * HSQLDB 1.7.2 does not support this feature. <p>
507      *
508      * Calling this method always throws an <code>SQLException</code>.
509      * </div>
510      * <!-- end release-specific documentation -->
511      *
512      * @param parameterIndex the first parameter is 1, the second is 2,
513      * and so on
514      * @param sqlType the SQL type code defined by <code>java.sql.Types</code>.
515      * @param scale the desired number of digits to the right of the
516      * decimal point. It must be greater than or equal to zero.
517      * @exception SQLException if a database access error occurs
518      * @see java.sql.Types
519      */
520     public void registerOutParameter(int parameterIndex, int sqlType,
521                                      int scale) throws SQLException {
522         registerOutParameter(parameterIndex, sqlType);
523     }
524
525     /**
526      * <!-- start generic documentation -->
527      * Retrieves whether the last OUT parameter read had the value of
528      * SQL <code>NULL</code>. Note that this method should be called only
529      * after calling a getter method; otherwise, there is no value to use in
530      * determining whether it is <code>null</code> or not. <p>
531      * <!-- end generic documentation -->
532      *
533      * <!-- start release-specific documentation -->
534      * <div class="ReleaseSpecificDocumentation">
535      * <h3>HSQLDB-Specific Information:</h3> <p>
536      *
537      * HSQLDB 1.7.2 does not support this feature. <p>
538      *
539      * Calling this method always throws an <code>SQLException</code>.
540      * </div>
541      * <!-- end release-specific documentation -->
542      *
543      * @return <code>true</code> if the last parameter read was SQL
544      * <code>NULL</code>; <code>false</code> otherwise
545      * @exception SQLException if a database access error occurs
546      */
547     public boolean wasNull() throws SQLException {
548         throw Util.notSupported();
549     }
550
551     /**
552      * <!-- start generic documentation -->
553      * Retrieves the value of the designated JDBC <code>CHAR</code>,
554      * <code>VARCHAR</code>, or <code>LONGVARCHAR</code> parameter as a
555      * <code>String</code> in the Java programming language.
556      * <p>
557      * For the fixed-length type JDBC <code>CHAR</code>,
558      * the <code>String</code> object
559      * returned has exactly the same value the (JDBC4 clarification:) SQL
560      * <code>CHAR</code> value had in the
561      * database, including any padding added by the database. <p>
562      * <!-- end generic documentation -->
563      *
564      * <!-- start release-specific documentation -->
565      * <div class="ReleaseSpecificDocumentation">
566      * <h3>HSQLDB-Specific Information:</h3> <p>
567      *
568      * HSQLDB 1.7.2 does not support this feature. <p>
569      *
570      * Calling this method always throws an <code>SQLException</code>.
571      * </div>
572      * <!-- end release-specific documentation -->
573      *
574      * @param parameterIndex the first parameter is 1, the second is 2,
575      * and so on
576      * @return the parameter value. If the value is SQL <code>NULL</code>,
577      * the result
578      * is <code>null</code>.
579      * @exception SQLException if a database access error occurs
580      * @see #setString
581      */
582     public String getString(int parameterIndex) throws SQLException {
583         throw Util.notSupported();
584     }
585
586     /**
587      * <!-- start generic documentation -->
588      * Retrieves the value of the designated JDBC <code>BIT</code> parameter
589      * as a <code>boolean</code> in the Java programming language. <p>
590      * <!-- end generic documentation -->
591      *
592      * <!-- start release-specific documentation -->
593      * <div class="ReleaseSpecificDocumentation">
594      * <h3>HSQLDB-Specific Information:</h3> <p>
595      *
596      * HSQLDB 1.7.2 does not support this feature. <p>
597      *
598      * Calling this method always throws an <code>SQLException</code>.
599      * </div>
600      * <!-- end release-specific documentation -->
601      *
602      * @param parameterIndex the first parameter is 1, the second is 2,
603      * and so on
604      * @return the parameter value. If the value is SQL <code>NULL</code>,
605      * the result is <code>false</code>.
606      * @exception SQLException if a database access error occurs
607      * @see #setBoolean
608      */
609     public boolean getBoolean(int parameterIndex) throws SQLException {
610         throw Util.notSupported();
611     }
612
613     /**
614      * <!-- start generic documentation -->
615      * Retrieves the value of the designated JDBC <code>TINYINT</code>
616      * parameter as a <code>byte</code> in the Java programming language. <p>
617      * <!-- end generic documentation -->
618      *
619      * <!-- start release-specific documentation -->
620      * <div class="ReleaseSpecificDocumentation">
621      * <h3>HSQLDB-Specific Information:</h3> <p>
622      *
623      * HSQLDB 1.7.2 does not support this feature. <p>
624      *
625      * Calling this method always throws an <code>SQLException</code>.
626      * </div>
627      * <!-- end release-specific documentation -->
628      *
629      * @param parameterIndex the first parameter is 1, the second is 2,
630      * and so on
631      * @return the parameter value. If the value is SQL <code>NULL</code>,
632      * the result is <code>0</code>.
633      * @exception SQLException if a database access error occurs
634      * @see #setByte
635      */
636     public byte getByte(int parameterIndex) throws SQLException {
637         throw Util.notSupported();
638     }
639
640     /**
641      * <!-- start generic documentation -->
642      * Retrieves the value of the designated JDBC <code>SMALLINT</code>
643      * parameter as a <code>short</code> in the Java programming language. <p>
644      * <!-- end generic documentation -->
645      *
646      * <!-- start release-specific documentation -->
647      * <div class="ReleaseSpecificDocumentation">
648      * <h3>HSQLDB-Specific Information:</h3> <p>
649      *
650      * HSQLDB 1.7.2 does not support this feature. <p>
651      *
652      * Calling this method always throws an <code>SQLException</code>.
653      * </div>
654      * <!-- end release-specific documentation -->
655      *
656      * @param parameterIndex the first parameter is 1, the second is 2,
657      * and so on
658      * @return the parameter value. If the value is SQL <code>NULL</code>,
659      * the result is <code>0</code>.
660      * @exception SQLException if a database access error occurs
661      * @see #setShort
662      */
663     public short getShort(int parameterIndex) throws SQLException {
664         throw Util.notSupported();
665     }
666
667     /**
668      * <!-- start generic documentation -->
669      * Retrieves the value of the designated JDBC <code>INTEGER</code>
670      * parameter as an <code>int</code> in the Java programming language. <p>
671      * <!-- end generic documentation -->
672      *
673      * <!-- start release-specific documentation -->
674      * <div class="ReleaseSpecificDocumentation">
675      * <h3>HSQLDB-Specific Information:</h3> <p>
676      *
677      * HSQLDB 1.7.2 does not support this feature. <p>
678      *
679      * Calling this method always throws an <code>SQLException</code>.
680      * </div>
681      * <!-- end release-specific documentation -->
682      *
683      * @param parameterIndex the first parameter is 1, the second is 2,
684      * and so on
685      * @return the parameter value. If the value is SQL <code>NULL</code>,
686      * the result is <code>0</code>.
687      * @exception SQLException if a database access error occurs
688      * @see #setInt
689      */
690     public int getInt(int parameterIndex) throws SQLException {
691         throw Util.notSupported();
692     }
693
694     /**
695      * <!-- start generic documentation -->
696      * Retrieves the value of the designated JDBC <code>BIGINT</code>
697      * parameter as a <code>long</code> in the Java programming language. <p>
698      * <!-- end generic documentation -->
699      *
700      * <!-- start release-specific documentation -->
701      * <div class="ReleaseSpecificDocumentation">
702      * <h3>HSQLDB-Specific Information:</h3> <p>
703      *
704      * HSQLDB 1.7.2 does not support this feature. <p>
705      *
706      * Calling this method always throws an <code>SQLException</code>.
707      * </div>
708      * <!-- end release-specific documentation -->
709      *
710      * @param parameterIndex the first parameter is 1, the second is 2,
711      * and so on
712      * @return the parameter value. If the value is SQL <code>NULL</code>,
713      * the result is <code>0</code>.
714      * @exception SQLException if a database access error occurs
715      * @see #setLong
716      */
717     public long getLong(int parameterIndex) throws SQLException {
718         throw Util.notSupported();
719     }
720
721     /**
722      * <!-- start generic documentation -->
723      * Retrieves the value of the designated JDBC <code>FLOAT</code>
724      * parameter as a <code>float</code> in the Java programming language. <p>
725      * <!-- end generic documentation -->
726      *
727      * <!-- start release-specific documentation -->
728      * <div class="ReleaseSpecificDocumentation">
729      * <h3>HSQLDB-Specific Information:</h3> <p>
730      *
731      * HSQLDB 1.7.2 does not support this feature. <p>
732      *
733      * Calling this method always throws an <code>SQLException</code>.
734      * </div>
735      * <!-- end release-specific documentation -->
736      *
737      * @param parameterIndex the first parameter is 1, the second is 2,
738      * and so on
739      * @return the parameter value. If the value is SQL <code>NULL</code>, the
740      * result is <code>0</code>.
741      * @exception SQLException if a database access error occurs
742      * @see #setFloat
743      */
744     public float getFloat(int parameterIndex) throws SQLException {
745         throw Util.notSupported();
746     }
747
748     /**
749      * <!-- start generic documentation -->
750      * Retrieves the value of the designated JDBC <code>DOUBLE</code>
751      * parameter as a <code>double</code> in the Java programming language. <p>
752      * <!-- end generic documentation -->
753      *
754      * <!-- start release-specific documentation -->
755      * <div class="ReleaseSpecificDocumentation">
756      * <h3>HSQLDB-Specific Information:</h3> <p>
757      *
758      * HSQLDB 1.7.2 does not support this feature. <p>
759      *
760      * Calling this method always throws an <code>SQLException</code>.
761      * </div>
762      * <!-- end release-specific documentation -->
763      *
764      * @param parameterIndex the first parameter is 1, the second is 2,
765      * and so on
766      * @return the parameter value. If the value is SQL <code>NULL</code>,
767      * the result is <code>0</code>.
768      * @exception SQLException if a database access error occurs
769      * @see #setDouble
770      */
771     public double getDouble(int parameterIndex) throws SQLException {
772         throw Util.notSupported();
773     }
774
775     /**
776      * <!-- start generic documentation -->
777      * Retrieves the value of the designated JDBC <code>NUMERIC</code>
778      * parameter as a <code>java.math.BigDecimal</code> object with
779      * <i>scale</i> digits to the right of the decimal point. <p>
780      * <!-- end generic documentation -->
781      *
782      * <!-- start release-specific documentation -->
783      * <div class="ReleaseSpecificDocumentation">
784      * <h3>HSQLDB-Specific Information:</h3> <p>
785      *
786      * HSQLDB 1.7.2 does not support this feature. <p>
787      *
788      * Calling this method always throws an <code>SQLException</code>.
789      * </div>
790      * <!-- end release-specific documentation -->
791      *
792      * @param parameterIndex the first parameter is 1, the second is 2,
793      * and so on
794      * @param scale the number of digits to the right of the decimal point
795      * @return the parameter value. If the value is SQL <code>NULL</code>,
796      * the result is <code>null</code>.
797      * @exception SQLException if a database access error occurs
798      * @deprecated use <code>getBigDecimal(int parameterIndex)</code>
799      * or <code>getBigDecimal(String parameterName)</code>
800      * @see #setBigDecimal
801      */
802
803 //#ifdef DEPRECATEDJDBC
804 public BigDecimal getBigDecimal(int parameterIndex,
805                                     int scale) throws SQLException {
806         throw Util.notSupported();
807     }
808
809 //#endif
810
811     /**
812      * <!-- start generic documentation -->
813      * Retrieves the value of the designated JDBC <code>BINARY</code> or
814      * <code>VARBINARY</code> parameter as an array of <code>byte</code>
815      * values in the Java programming language. <p>
816      * <!-- end generic documentation -->
817      *
818      * <!-- start release-specific documentation -->
819      * <div class="ReleaseSpecificDocumentation">
820      * <h3>HSQLDB-Specific Information:</h3> <p>
821      *
822      * HSQLDB 1.7.2 does not support this feature. <p>
823      *
824      * Calling this method always throws an <code>SQLException</code>.
825      * </div>
826      * <!-- end release-specific documentation -->
827      * @param parameterIndex the first parameter is 1, the second is 2,
828      * and so on
829      * @return the parameter value. If the value is SQL <code>NULL</code>,
830      * the result is <code>null</code>.
831      * @exception SQLException if a database access error occurs
832      * @see #setBytes
833      */
834     public byte[] getBytes(int parameterIndex) throws SQLException {
835         throw Util.notSupported();
836     }
837
838     /**
839      * <!-- start generic documentation -->
840      * Retrieves the value of the designated JDBC <code>DATE</code> parameter
841      * as a <code>java.sql.Date</code> object. <p>
842      * <!-- end generic documentation -->
843      *
844      * <!-- start release-specific documentation -->
845      * <div class="ReleaseSpecificDocumentation">
846      * <h3>HSQLDB-Specific Information:</h3> <p>
847      *
848      * HSQLDB 1.7.2 does not support this feature. <p>
849      *
850      * Calling this method always throws an <code>SQLException</code>.
851      * </div>
852      * <!-- end release-specific documentation -->
853      * @param parameterIndex the first parameter is 1, the second is 2,
854      * and so on
855      * @return the parameter value. If the value is SQL <code>NULL</code>, the
856      * result is <code>null</code>.
857      * @exception SQLException if a database access error occurs
858      * @see #setDate
859      */
860     public Date getDate(int parameterIndex) throws SQLException {
861         throw Util.notSupported();
862     }
863
864     /**
865      * <!-- start generic documentation -->
866      * Retrieves the value of the designated JDBC <code>TIME</code> parameter
867      * as a <code>java.sql.Time</code> object. <p>
868      * <!-- end generic documentation -->
869      *
870      * <!-- start release-specific documentation -->
871      * <div class="ReleaseSpecificDocumentation">
872      * <h3>HSQLDB-Specific Information:</h3> <p>
873      *
874      * HSQLDB 1.7.2 does not support this feature. <p>
875      *
876      * Calling this method always throws an <code>SQLException</code>.
877      * </div>
878      * <!-- end release-specific documentation -->
879      *
880      * @param parameterIndex the first parameter is 1, the second is 2,
881      * and so on
882      * @return the parameter value. If the value is SQL <code>NULL</code>,
883      * the result is <code>null</code>.
884      * @exception SQLException if a database access error occurs
885      * @see #setTime
886      */
887     public Time getTime(int parameterIndex) throws SQLException {
888         throw Util.notSupported();
889     }
890
891     /**
892      * <!-- start generic documentation -->
893      * Retrieves the value of the designated JDBC <code>TIMESTAMP</code>
894      * parameter as a <code>java.sql.Timestamp</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.2 does not support this feature. <p>
902      *
903      * Calling this method always throws an <code>SQLException</code>.
904      * </div>
905      * <!-- end release-specific documentation -->
906      *
907      * @param parameterIndex the first parameter is 1, the second is 2,
908      * and so on
909      * @return the parameter value. If the value is SQL <code>NULL</code>,
910      * the result is <code>null</code>.
911      * @exception SQLException if a database access error occurs
912      * @see #setTimestamp
913      */
914     public Timestamp getTimestamp(int parameterIndex) throws SQLException {
915         throw Util.notSupported();
916     }
917
918     /**
919      * <!-- start generic documentation -->
920      * Retrieves the value of the designated parameter as an <code>Object</code>
921      * in the Java programming language. If the value is an SQL <code>NULL</code>,
922      * the driver returns a Java <code>null</code>.
923      * <p>
924      * This method returns a Java object whose type corresponds to the JDBC
925      * type that was registered for this parameter using the method
926      * <code>registerOutParameter</code>. By registering the target JDBC
927      * type as <code>java.sql.Types.OTHER</code>, this method can be used
928      * to read database-specific abstract data types. <p>
929      * <!-- end generic documentation -->
930      *
931      * <!-- start release-specific documentation -->
932      * <div class="ReleaseSpecificDocumentation">
933      * <h3>HSQLDB-Specific Information:</h3> <p>
934      *
935      * HSQLDB 1.7.2 does not support this feature. <p>
936      * Calling this method always throws an <code>SQLException</code>.
937      * </div>
938      * <!-- end release-specific documentation -->
939      *
940      * @param parameterIndex the first parameter is 1, the second is 2,
941      * and so on
942      * @return A <code>java.lang.Object</code> holding the OUT parameter value
943      * @exception SQLException if a database access error occurs
944      * @see java.sql.Types
945      * @see #setObject
946      */
947     public Object getObject(int parameterIndex) throws SQLException {
948         throw Util.notSupported();
949     }
950
951 // ----------------------------------- JDBC 2 ----------------------------------
952
953     /**
954      * <!-- start generic documentation -->
955      * Retrieves the value of the designated JDBC <code>NUMERIC</code>
956      * parameter as a <code>java.math.BigDecimal</code> object with as many
957      * digits to the right of the decimal point as the value contains. <p>
958      * <!-- end generic documentation -->
959      *
960      * <!-- start release-specific documentation -->
961      * <div class="ReleaseSpecificDocumentation">
962      * <h3>HSQLDB-Specific Information:</h3> <p>
963      *
964      * HSQLDB 1.7.2 does not support this feature. <p>
965      *
966      * Calling this method always throws an <code>SQLException</code>.
967      * </div>
968      * <!-- end release-specific documentation -->
969      *
970      * @param parameterIndex the first parameter is 1, the second is 2,
971      * and so on
972      * @return the parameter value in full precision. If the value is
973      * SQL <code>NULL</code>, the result is <code>null</code>.
974      * @exception SQLException if a database access error occurs
975      * @see #setBigDecimal
976      * @since JDK 1.2 (JDK 1.1.x developers: read the new overview for
977      * jdbcPreparedStatement)
978      */
979     public BigDecimal getBigDecimal(int parameterIndex) throws SQLException {
980         throw Util.notSupported();
981     }
982
983     /**
984      * <!-- start generic documentation -->
985      * Returns an object representing the value of OUT parameter
986      * <code>parameterIndex</code> and uses <code>map</code> for the custom
987      * mapping of the parameter value.
988      * <p>
989      * This method returns a Java object whose type corresponds to the
990      * JDBC type that was registered for this parameter using the method
991      * <code>registerOutParameter</code>. By registering the target
992      * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
993      * be used to read database-specific abstract data types. <p>
994      * <!-- end generic documentation -->
995      *
996      * <!-- start release-specific documentation -->
997      * <div class="ReleaseSpecificDocumentation">
998      * <h3>HSQLDB-Specific Information:</h3> <p>
999      *
1000     * HSQLDB 1.7.2 does not support this feature. <p>
1001     *
1002     * Calling this method always throws an <code>SQLException</code>.
1003     * </div>
1004     * <!-- end release-specific documentation -->
1005     *
1006     * @param parameterIndex the first parameter is 1, the second is 2, and so on
1007     * @param map the mapping from SQL type names to Java classes
1008     * @return a <code>java.lang.Object</code> holding the OUT parameter value
1009     * @exception SQLException if a database access error occurs
1010     * @see #setObject
1011     * @since JDK 1.2 (JDK 1.1.x developers: read the new overview for
1012     * jdbcPreparedStatement)
1013     */
1014    public Object getObject(int parameterIndex, Map map) throws SQLException {
1015        throw Util.notSupported();
1016    }
1017
1018    /**
1019     * <!-- start generic documentation -->
1020     * Retrieves the value of the designated JDBC
1021     * <code>REF(&lt;structured-type&gt;)</code> parameter as a
1022     * {@link java.sql.Ref} object in the Java programming language. <p>
1023     * <!-- end generic documentation -->
1024     *
1025     * <!-- start release-specific documentation -->
1026     * <div class="ReleaseSpecificDocumentation">
1027     * <h3>HSQLDB-Specific Information:</h3> <p>
1028     *
1029     * HSQLDB 1.7.2 does not support this feature. <p>
1030     *
1031     * Calling this method always throws an <code>SQLException</code>.
1032     * </div>
1033     * <!-- end release-specific documentation -->
1034     *
1035     * @param parameterIndex the first parameter is 1, the second is 2,
1036     * and so on
1037     * @return the parameter value as a <code>Ref</code> object in the
1038     * Java programming language. If the value was SQL &