Java > Open Source Codes > java > sql > CallableStatement


1 /*
2  * @(#)CallableStatement.java 1.47 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.sql;
9
10 import java.math.BigDecimal ;
11 import java.util.Calendar ;
12
13 /**
14  * The interface used to execute SQL stored procedures. The JDBC API
15  * provides a stored procedure SQL escape syntax that allows stored procedures
16  * to be called in a standard way for all RDBMSs. This escape syntax has one
17  * form that includes a result parameter and one that does not. If used, the result
18  * parameter must be registered as an OUT parameter. The other parameters
19  * can be used for input, output or both. Parameters are referred to
20  * sequentially, by number, with the first parameter being 1.
21  * <PRE>
22  * {?= call &lt;procedure-name&gt;[&lt;arg1&gt;,&lt;arg2&gt;, ...]}
23  * {call &lt;procedure-name&gt;[&lt;arg1&gt;,&lt;arg2&gt;, ...]}
24  * </PRE>
25  * <P>
26  * IN parameter values are set using the <code>set</code> methods inherited from
27  * {@link PreparedStatement}. The type of all OUT parameters must be
28  * registered prior to executing the stored procedure; their values
29  * are retrieved after execution via the <code>get</code> methods provided here.
30  * <P>
31  * A <code>CallableStatement</code> can return one {@link ResultSet} object or
32  * multiple <code>ResultSet</code> objects. Multiple
33  * <code>ResultSet</code> objects are handled using operations
34  * inherited from {@link Statement}.
35  * <P>
36  * For maximum portability, a call's <code>ResultSet</code> objects and
37  * update counts should be processed prior to getting the values of output
38  * parameters.
39  * <P>
40  *
41  * @see Connection#prepareCall
42  * @see ResultSet
43  */
44
45 public interface CallableStatement extends PreparedStatement {
46     
47     /**
48      * Registers the OUT parameter in ordinal position
49      * <code>parameterIndex</code> to the JDBC type
50      * <code>sqlType</code>. All OUT parameters must be registered
51      * before a stored procedure is executed.
52      * <p>
53      * The JDBC type specified by <code>sqlType</code> for an OUT
54      * parameter determines the Java type that must be used
55      * in the <code>get</code> method to read the value of that parameter.
56      * <p>
57      * If the JDBC type expected to be returned to this output parameter
58      * is specific to this particular database, <code>sqlType</code>
59      * should be <code>java.sql.Types.OTHER</code>. The method
60      * {@link #getObject} retrieves the value.
61      *
62      * @param parameterIndex the first parameter is 1, the second is 2,
63      * and so on
64      * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
65      * If the parameter is of JDBC type <code>NUMERIC</code>
66      * or <code>DECIMAL</code>, the version of
67      * <code>registerOutParameter</code> that accepts a scale value
68      * should be used.
69      *
70      * @exception SQLException if a database access error occurs
71      * @see Types
72      */
73     void registerOutParameter(int parameterIndex, int sqlType)
74     throws SQLException ;
75
76     /**
77      * Registers the parameter in ordinal position
78      * <code>parameterIndex</code> to be of JDBC type
79      * <code>sqlType</code>. This method must be called
80      * before a stored procedure is executed.
81      * <p>
82      * The JDBC type specified by <code>sqlType</code> for an OUT
83      * parameter determines the Java type that must be used
84      * in the <code>get</code> method to read the value of that parameter.
85      * <p>
86      * This version of <code>registerOutParameter</code> should be
87      * used when the parameter is of JDBC type <code>NUMERIC</code>
88      * or <code>DECIMAL</code>.
89      *
90      * @param parameterIndex the first parameter is 1, the second is 2,
91      * and so on
92      * @param sqlType the SQL type code defined by <code>java.sql.Types</code>.
93      * @param scale the desired number of digits to the right of the
94      * decimal point. It must be greater than or equal to zero.
95      * @exception SQLException if a database access error occurs
96      * @see Types
97      */
98     void registerOutParameter(int parameterIndex, int sqlType, int scale)
99     throws SQLException ;
100
101     /**
102      * Retrieves whether the last OUT parameter read had the value of
103      * SQL <code>NULL</code>. Note that this method should be called only after
104      * calling a getter method; otherwise, there is no value to use in
105      * determining whether it is <code>null</code> or not.
106      *
107      * @return <code>true</code> if the last parameter read was SQL
108      * <code>NULL</code>; <code>false</code> otherwise
109      * @exception SQLException if a database access error occurs
110      */
111     boolean wasNull() throws SQLException ;
112
113     /**
114      * Retrieves the value of the designated JDBC <code>CHAR</code>,
115      * <code>VARCHAR</code>, or <code>LONGVARCHAR</code> parameter as a
116      * <code>String</code> in the Java programming language.
117      * <p>
118      * For the fixed-length type JDBC <code>CHAR</code>,
119      * the <code>String</code> object
120      * returned has exactly the same value the JDBC
121      * <code>CHAR</code> value had in the
122      * database, including any padding added by the database.
123      *
124      * @param parameterIndex the first parameter is 1, the second is 2,
125      * and so on
126      * @return the parameter value. If the value is SQL <code>NULL</code>,
127      * the result
128      * is <code>null</code>.
129      * @exception SQLException if a database access error occurs
130      * @see #setString
131      */
132     String getString(int parameterIndex) throws SQLException ;
133
134     /**
135      * Retrieves the value of the designated JDBC <code>BIT</code> parameter as a
136      * <code>boolean</code> in the Java programming language.
137      *
138      * @param parameterIndex the first parameter is 1, the second is 2,
139      * and so on
140      * @return the parameter value. If the value is SQL <code>NULL</code>,
141      * the result is <code>false</code>.
142      * @exception SQLException if a database access error occurs
143      * @see #setBoolean
144      */
145     boolean getBoolean(int parameterIndex) throws SQLException ;
146
147     /**
148      * Retrieves the value of the designated JDBC <code>TINYINT</code> parameter
149      * as a <code>byte</code> in the Java programming language.
150      *
151      * @param parameterIndex the first parameter is 1, the second is 2,
152      * and so on
153      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
154      * is <code>0</code>.
155      * @exception SQLException if a database access error occurs
156      * @see #setByte
157      */
158     byte getByte(int parameterIndex) throws SQLException ;
159
160     /**
161      * Retrieves the value of the designated JDBC <code>SMALLINT</code> parameter
162      * as a <code>short</code> in the Java programming language.
163      *
164      * @param parameterIndex the first parameter is 1, the second is 2,
165      * and so on
166      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
167      * is <code>0</code>.
168      * @exception SQLException if a database access error occurs
169      * @see #setShort
170      */
171     short getShort(int parameterIndex) throws SQLException ;
172
173     /**
174      * Retrieves the value of the designated JDBC <code>INTEGER</code> parameter
175      * as an <code>int</code> in the Java programming language.
176      *
177      * @param parameterIndex the first parameter is 1, the second is 2,
178      * and so on
179      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
180      * is <code>0</code>.
181      * @exception SQLException if a database access error occurs
182      * @see #setInt
183      */
184     int getInt(int parameterIndex) throws SQLException ;
185
186     /**
187      * Retrieves the value of the designated JDBC <code>BIGINT</code> parameter
188      * as a <code>long</code> in the Java programming language.
189      *
190      * @param parameterIndex the first parameter is 1, the second is 2,
191      * and so on
192      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
193      * is <code>0</code>.
194      * @exception SQLException if a database access error occurs
195      * @see #setLong
196      */
197     long getLong(int parameterIndex) throws SQLException ;
198
199     /**
200      * Retrieves the value of the designated JDBC <code>FLOAT</code> parameter
201      * as a <code>float</code> in the Java programming language.
202      *
203      * @param parameterIndex the first parameter is 1, the second is 2,
204      * and so on
205      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
206      * is <code>0</code>.
207      * @exception SQLException if a database access error occurs
208      * @see #setFloat
209      */
210     float getFloat(int parameterIndex) throws SQLException ;
211
212     /**
213      * Retrieves the value of the designated JDBC <code>DOUBLE</code> parameter as a <code>double</code>
214      * in the Java programming language.
215      * @param parameterIndex the first parameter is 1, the second is 2,
216      * and so on
217      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
218      * is <code>0</code>.
219      * @exception SQLException if a database access error occurs
220      * @see #setDouble
221      */
222     double getDouble(int parameterIndex) throws SQLException ;
223
224     /**
225      * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
226      * <code>java.math.BigDecimal</code> object with <i>scale</i> digits to
227      * the right of the decimal point.
228      * @param parameterIndex the first parameter is 1, the second is 2,
229      * and so on
230      * @param scale the number of digits to the right of the decimal point
231      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
232      * is <code>null</code>.
233      * @exception SQLException if a database access error occurs
234      * @deprecated use <code>getBigDecimal(int parameterIndex)</code>
235      * or <code>getBigDecimal(String parameterName)</code>
236      * @see #setBigDecimal
237      */
238     @Deprecated
239     BigDecimal getBigDecimal(int parameterIndex, int scale)
240     throws SQLException ;
241
242     /**
243      * Retrieves the value of the designated JDBC <code>BINARY</code> or
244      * <code>VARBINARY</code> parameter as an array of <code>byte</code>
245      * values in the Java programming language.
246      * @param parameterIndex the first parameter is 1, the second is 2,
247      * and so on
248      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
249      * is <code>null</code>.
250      * @exception SQLException if a database access error occurs
251      * @see #setBytes
252      */
253     byte[] getBytes(int parameterIndex) throws SQLException ;
254
255     /**
256      * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
257      * <code>java.sql.Date</code> object.
258      * @param parameterIndex the first parameter is 1, the second is 2,
259      * and so on
260      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
261      * is <code>null</code>.
262      * @exception SQLException if a database access error occurs
263      * @see #setDate
264      */
265     java.sql.Date getDate(int parameterIndex) throws SQLException ;
266
267     /**
268      * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
269      * <code>java.sql.Time</code> object.
270      *
271      * @param parameterIndex the first parameter is 1, the second is 2,
272      * and so on
273      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
274      * is <code>null</code>.
275      * @exception SQLException if a database access error occurs
276      * @see #setTime
277      */
278     java.sql.Time getTime(int parameterIndex) throws SQLException ;
279
280     /**
281      * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
282      * <code>java.sql.Timestamp</code> object.
283      *
284      * @param parameterIndex the first parameter is 1, the second is 2,
285      * and so on
286      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
287      * is <code>null</code>.
288      * @exception SQLException if a database access error occurs
289      * @see #setTimestamp
290      */
291     java.sql.Timestamp getTimestamp(int parameterIndex)
292     throws SQLException ;
293
294     //----------------------------------------------------------------------
295 // Advanced features:
296
297
298     /**
299      * Retrieves the value of the designated parameter as an <code>Object</code>
300      * in the Java programming language. If the value is an SQL <code>NULL</code>,
301      * the driver returns a Java <code>null</code>.
302      * <p>
303      * This method returns a Java object whose type corresponds to the JDBC
304      * type that was registered for this parameter using the method
305      * <code>registerOutParameter</code>. By registering the target JDBC
306      * type as <code>java.sql.Types.OTHER</code>, this method can be used
307      * to read database-specific abstract data types.
308      *
309      * @param parameterIndex the first parameter is 1, the second is 2,
310      * and so on
311      * @return A <code>java.lang.Object</code> holding the OUT parameter value
312      * @exception SQLException if a database access error occurs
313      * @see Types
314      * @see #setObject
315      */
316     Object getObject(int parameterIndex) throws SQLException ;
317
318
319     //--------------------------JDBC 2.0-----------------------------
320
321     /**
322      * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
323      * <code>java.math.BigDecimal</code> object with as many digits to the
324      * right of the decimal point as the value contains.
325      * @param parameterIndex the first parameter is 1, the second is 2,
326      * and so on
327      * @return the parameter value in full precision. If the value is
328      * SQL <code>NULL</code>, the result is <code>null</code>.
329      * @exception SQLException if a database access error occurs
330      * @see #setBigDecimal
331      * @since 1.2
332      */
333     BigDecimal getBigDecimal(int parameterIndex) throws SQLException ;
334
335     /**
336      * Returns an object representing the value of OUT parameter
337      * <code>i</code> and uses <code>map</code> for the custom
338      * mapping of the parameter value.
339      * <p>
340      * This method returns a Java object whose type corresponds to the
341      * JDBC type that was registered for this parameter using the method
342      * <code>registerOutParameter</code>. By registering the target
343      * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
344      * be used to read database-specific abstract data types.
345      * @param i the first parameter is 1, the second is 2, and so on
346      * @param map the mapping from SQL type names to Java classes
347      * @return a <code>java.lang.Object</code> holding the OUT parameter value
348      * @exception SQLException if a database access error occurs
349      * @see #setObject
350      * @since 1.2
351      */
352     Object getObject(int i, java.util.Map <String ,Class <?>> map)
353     throws SQLException ;
354
355     /**
356      * Retrieves the value of the designated JDBC <code>REF(&lt;structured-type&gt;)</code>
357      * parameter as a {@link Ref} object in the Java programming language.
358      * @param i the first parameter is 1, the second is 2,
359      * and so on
360      * @return the parameter value as a <code>Ref</code> object in the
361      * Java programming language. If the value was SQL <code>NULL</code>, the value
362      * <code>null</code> is returned.
363      * @exception SQLException if a database access error occurs
364      * @since 1.2
365      */
366     Ref getRef (int i) throws SQLException ;
367
368     /**
369      * Retrieves the value of the designated JDBC <code>BLOB</code> parameter as a
370      * {@link Blob} object in the Java programming language.
371      * @param i the first parameter is 1, the second is 2, and so on
372      * @return the parameter value as a <code>Blob</code> object in the
373      * Java programming language. If the value was SQL <code>NULL</code>, the value
374      * <code>null</code> is returned.
375      * @exception SQLException if a database access error occurs
376      * @since 1.2
377      */
378     Blob getBlob (int i) throws SQLException ;
379
380     /**
381      * Retrieves the value of the designated JDBC <code>CLOB</code> parameter as a
382      * <code>Clob</code> object in the Java programming language.
383      * @param i the first parameter is 1, the second is 2, and
384      * so on
385      * @return the parameter value as a <code>Clob</code> object in the
386      * Java programming language. If the value was SQL <code>NULL</code>, the
387      * value <code>null</code> is returned.
388      * @exception SQLException if a database access error occurs
389      * @since 1.2
390      */
391     Clob getClob (int i) throws SQLException ;
392
393     /**
394      *
395      * Retrieves the value of the designated JDBC <code>ARRAY</code> parameter as an
396      * {@link Array} object in the Java programming language.
397      * @param i the first parameter is 1, the second is 2, and
398      * so on
399      * @return the parameter value as an <code>Array</code> object in
400      * the Java programming language. If the value was SQL <code>NULL</code>, the
401      * value <code>null</code> is returned.
402      * @exception SQLException if a database access error occurs
403      * @since 1.2
404      */
405     Array getArray (int i) throws SQLException ;
406
407     /**
408      * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
409      * <code>java.sql.Date</code> object, using
410      * the given <code>Calendar</code> object
411      * to construct the date.
412      * With a <code>Calendar</code> object, the driver
413      * can calculate the date taking into account a custom timezone and locale.
414      * If no <code>Calendar</code> object is specified, the driver uses the
415      * default timezone and locale.
416      *
417      * @param parameterIndex the first parameter is 1, the second is 2,
418      * and so on
419      * @param cal the <code>Calendar</code> object the driver will use
420      * to construct the date
421      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
422      * is <code>null</code>.
423      * @exception SQLException if a database access error occurs
424      * @see #setDate
425      * @since 1.2
426      */
427     java.sql.Date getDate(int parameterIndex, Calendar cal)
428     throws SQLException ;
429
430     /**
431      * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
432      * <code>java.sql.Time</code> object, using
433      * the given <code>Calendar</code> object
434      * to construct the time.
435      * With a <code>Calendar</code> object, the driver
436      * can calculate the time taking into account a custom timezone and locale.
437      * If no <code>Calendar</code> object is specified, the driver uses the
438      * default timezone and locale.
439      *
440      * @param parameterIndex the first parameter is 1, the second is 2,
441      * and so on
442      * @param cal the <code>Calendar</code> object the driver will use
443      * to construct the time
444      * @return the parameter value; if the value is SQL <code>NULL</code>, the result
445      * is <code>null</code>.
446      * @exception SQLException if a database access error occurs
447      * @see #setTime
448      * @since 1.2
449      */
450     java.sql.Time getTime(int parameterIndex, Calendar cal)
451     throws SQLException ;
452
453     /**
454      * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
455      * <code>java.sql.Timestamp</code> object, using
456      * the given <code>Calendar</code> object to construct
457      * the <code>Timestamp</code> object.
458      * With a <code>Calendar</code> object, the driver
459      * can calculate the timestamp taking into account a custom timezone and locale.
460      * If no <code>Calendar</code> object is specified, the driver uses the
461      * default timezone and locale.
462      *
463      *
464      * @param parameterIndex the first parameter is 1, the second is 2,
465      * and so on
466      * @param cal the <code>Calendar</code> object the driver will use
467      * to construct the timestamp
468      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
469      * is <code>null</code>.
470      * @exception SQLException if a database access error occurs
471      * @see #setTimestamp
472      * @since 1.2
473      */
474     java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal)
475     throws SQLException ;
476
477
478     /**
479      * Registers the designated output parameter. This version of
480      * the method <code>registerOutParameter</code>
481      * should be used for a user-defined or <code>REF</code> output parameter. Examples
482      * of user-defined types include: <code>STRUCT</code>, <code>DISTINCT</code>,
483      * <code>JAVA_OBJECT</code>, and named array types.
484      *
485      * Before executing a stored procedure call, you must explicitly
486      * call <code>registerOutParameter</code> to register the type from
487      * <code>java.sql.Types</code> for each
488      * OUT parameter. For a user-defined parameter, the fully-qualified SQL
489      * type name of the parameter should also be given, while a <code>REF</code>
490      * parameter requires that the fully-qualified type name of the
491      * referenced type be given. A JDBC driver that does not need the
492      * type code and type name information may ignore it. To be portable,
493      * however, applications should always provide these values for
494      * user-defined and <code>REF</code> parameters.
495      *
496      * Although it is intended for user-defined and <code>REF</code> parameters,
497      * this method may be used to register a parameter of any JDBC type.
498      * If the parameter does not have a user-defined or <code>REF</code> type, the
499      * <i>typeName</i> parameter is ignored.
500      *
501      * <P><B>Note:</B> When reading the value of an out parameter, you
502      * must use the getter method whose Java type corresponds to the
503      * parameter's registered SQL type.
504      *
505      * @param paramIndex the first parameter is 1, the second is 2,...
506      * @param sqlType a value from {@link java.sql.Types}
507      * @param typeName the fully-qualified name of an SQL structured type
508      * @exception SQLException if a database access error occurs
509      * @see Types
510      * @since 1.2
511      */
512     void registerOutParameter (int paramIndex, int sqlType, String typeName)
513     throws SQLException ;
514
515   //--------------------------JDBC 3.0-----------------------------
516
517     /**
518      * Registers the OUT parameter named
519      * <code>parameterName</code> to the JDBC type
520      * <code>sqlType</code>. All OUT parameters must be registered
521      * before a stored procedure is executed.
522      * <p>
523      * The JDBC type specified by <code>sqlType</code> for an OUT
524      * parameter determines the Java type that must be used
525      * in the <code>get</code> method to read the value of that parameter.
526      * <p>
527      * If the JDBC type expected to be returned to this output parameter
528      * is specific to this particular database, <code>sqlType</code>
529      * should be <code>java.sql.Types.OTHER</code>. The method
530      * {@link #getObject} retrieves the value.
531      * @param parameterName the name of the parameter
532      * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
533      * If the parameter is of JDBC type <code>NUMERIC</code>
534      * or <code>DECIMAL</code>, the version of
535      * <code>registerOutParameter</code> that accepts a scale value
536      * should be used.
537      * @exception SQLException if a database access error occurs
538      * @since 1.4
539      * @see Types
540      */
541     void registerOutParameter(String parameterName, int sqlType)
542     throws SQLException ;
543
544     /**
545      * Registers the parameter named
546      * <code>parameterName</code> to be of JDBC type
547      * <code>sqlType</code>. This method must be called
548      * before a stored procedure is executed.
549      * <p>
550      * The JDBC type specified by <code>sqlType</code> for an OUT
551      * parameter determines the Java type that must be used
552      * in the <code>get</code> method to read the value of that parameter.
553      * <p>
554      * This version of <code>registerOutParameter</code> should be
555      * used when the parameter is of JDBC type <code>NUMERIC</code>
556      * or <code>DECIMAL</code>.
557      * @param parameterName the name of the parameter
558      * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
559      * @param scale the desired number of digits to the right of the
560      * decimal point. It must be greater than or equal to zero.
561      * @exception SQLException if a database access error occurs
562      * @since 1.4
563      * @see Types
564      */
565     void registerOutParameter(String parameterName, int sqlType, int scale)
566     throws SQLException ;
567
568     /**
569      * Registers the designated output parameter. This version of
570      * the method <code>registerOutParameter</code>
571      * should be used for a user-named or REF output parameter. Examples
572      * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
573      * named array types.
574      *
575      * Before executing a stored procedure call, you must explicitly
576      * call <code>registerOutParameter</code> to register the type from
577      * <code>java.sql.Types</code> for each
578      * OUT parameter. For a user-named parameter the fully-qualified SQL
579      * type name of the parameter should also be given, while a REF
580      * parameter requires that the fully-qualified type name of the
581      * referenced type be given. A JDBC driver that does not need the
582      * type code and type name information may ignore it. To be portable,
583      * however, applications should always provide these values for
584      * user-named and REF parameters.
585      *
586      * Although it is intended for user-named and REF parameters,
587      * this method may be used to register a parameter of any JDBC type.
588      * If the parameter does not have a user-named or REF type, the
589      * typeName parameter is ignored.
590      *
591      * <P><B>Note:</B> When reading the value of an out parameter, you
592      * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
593      * parameter's registered SQL type.
594      *
595      * @param parameterName the name of the parameter
596      * @param sqlType a value from {@link java.sql.Types}
597      * @param typeName the fully-qualified name of an SQL structured type
598      * @exception SQLException if a database access error occurs
599      * @see Types
600      * @since 1.4
601      */
602     void registerOutParameter (String parameterName, int sqlType, String typeName)
603     throws SQLException ;
604
605     /**
606      * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
607      * <code>java.net.URL</code> object.
608      *
609      * @param parameterIndex the first parameter is 1, the second is 2,...
610      * @return a <code>java.net.URL</code> object that represents the
611      * JDBC <code>DATALINK</code> value used as the designated
612      * parameter
613      * @exception SQLException if a database access error occurs,
614      * or if the URL being returned is
615      * not a valid URL on the Java platform
616      * @see #setURL
617      * @since 1.4
618      */
619     java.net.URL getURL(int parameterIndex) throws SQLException ;
620
621     /**
622      * Sets the designated parameter to the given <code>java.net.URL</code> object.
623      * The driver converts this to an SQL <code>DATALINK</code> value when
624      * it sends it to the database.
625      *
626      * @param parameterName the name of the parameter
627      * @param val the parameter value
628      * @exception SQLException if a database access error occurs,
629      * or if a URL is malformed
630      * @see #getURL
631      * @since 1.4
632      */
633     void setURL(String parameterName, java.net.URL val) throws SQLException ;
634     
635     /**
636      * Sets the designated parameter to SQL <code>NULL</code>.
637      *
638      * <P><B>Note:</B> You must specify the parameter's SQL type.
639      *
640      * @param parameterName the name of the parameter
641      * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
642      * @exception SQLException if a database access error occurs
643      * @since 1.4
644      */
645     void setNull(String parameterName, int sqlType) throws SQLException ;
646
647     /**
648      * Sets the designated parameter to the given Java <code>boolean</code> value.
649      * The driver converts this
650      * to an SQL <code>BIT</code> value when it sends it to the database.
651      *
652      * @param parameterName the name of the parameter
653      * @param x the parameter value
654      * @exception SQLException if a database access error occurs
655      * @see #getBoolean
656      * @since 1.4
657      */
658     void setBoolean(String parameterName, boolean x) throws SQLException ;
659
660     /**
661      * Sets the designated parameter to the given Java <code>byte</code> value.
662      * The driver converts this
663      * to an SQL <code>TINYINT</code> value when it sends it to the database.
664      *
665      * @param parameterName the name of the parameter
666      * @param x the parameter value
667      * @exception SQLException if a database access error occurs
668      * @see #getByte
669      * @since 1.4
670      */
671     void setByte(String parameterName, byte x) throws SQLException ;
672
673     /**
674      * Sets the designated parameter to the given Java <code>short</code> value.
675      * The driver converts this
676      * to an SQL <code>SMALLINT</code> value when it sends it to the database.
677      *
678      * @param parameterName the name of the parameter
679      * @param x the parameter value
680      * @exception SQLException if a database access error occurs
681      * @see #getShort
682      * @since 1.4
683      */
684     void setShort(String parameterName, short x) throws SQLException ;
685
686     /**
687      * Sets the designated parameter to the given Java <code>int</code> value.
688      * The driver converts this
689      * to an SQL <code>INTEGER</code> value when it sends it to the database.
690      *
691      * @param parameterName the name of the parameter
692      * @param x the parameter value
693      * @exception SQLException if a database access error occurs
694      * @see #getInt
695      * @since 1.4
696      */
697     void setInt(String parameterName, int x) throws SQLException ;
698
699     /**
700      * Sets the designated parameter to the given Java <code>long</code> value.
701      * The driver converts this
702      * to an SQL <code>BIGINT</code> value when it sends it to the database.
703      *
704      * @param parameterName the name of the parameter
705      * @param x the parameter value
706      * @exception SQLException if a database access error occurs
707      * @see #getLong
708      * @since 1.4
709      */
710     void setLong(String parameterName, long x) throws SQLException ;
711
712     /**
713      * Sets the designated parameter to the given Java <code>float</code> value.
714      * The driver converts this
715      * to an SQL <code>FLOAT</code> value when it sends it to the database.
716      *
717      * @param parameterName the name of the parameter
718      * @param x the parameter value
719      * @exception SQLException if a database access error occurs
720      * @see #getFloat
721      * @since 1.4
722      */
723     void setFloat(String parameterName, float x) throws SQLException ;
724
725     /**
726      * Sets the designated parameter to the given Java <code>double</code> value.
727      * The driver converts this
728      * to an SQL <code>DOUBLE</code> value when it sends it to the database.
729      *
730      * @param parameterName the name of the parameter
731      * @param x the parameter value
732      * @exception SQLException if a database access error occurs
733      * @see #getDouble
734      * @since 1.4
735      */
736     void setDouble(String parameterName, double x) throws SQLException ;
737
738     /**
739      * Sets the designated parameter to the given
740      * <code>java.math.BigDecimal</code> value.
741      * The driver converts this to an SQL <code>NUMERIC</code> value when
742      * it sends it to the database.
743      *
744      * @param parameterName the name of the parameter
745      * @param x the parameter value
746      * @exception SQLException if a database access error occurs
747      * @see #getBigDecimal
748      * @since 1.4
749      */
750     void setBigDecimal(String parameterName, BigDecimal x) throws SQLException ;
751
752     /**
753      * Sets the designated parameter to the given Java <code>String</code> value.
754      * The driver converts this
755      * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
756      * (depending on the argument's
757      * size relative to the driver's limits on <code>VARCHAR</code> values)
758      * when it sends it to the database.
759      *
760      * @param parameterName the name of the parameter
761      * @param x the parameter value
762      * @exception SQLException if a database access error occurs
763      * @see #getString
764      * @since 1.4
765      */
766     void setString(String parameterName, String x) throws SQLException ;
767
768     /**
769      * Sets the designated parameter to the given Java array of bytes.
770      * The driver converts this to an SQL <code>VARBINARY</code> or
771      * <code>LONGVARBINARY</code> (depending on the argument's size relative
772      * to the driver's limits on <code>VARBINARY</code> values) when it sends
773      * it to the database.
774      *
775      * @param parameterName the name of the parameter
776      * @param x the parameter value
777      * @exception SQLException if a database access error occurs
778      * @see #getBytes
779      * @since 1.4
780      */
781     void setBytes(String parameterName, byte x[]) throws SQLException ;
782
783     /**
784      * Sets the designated parameter to the given <code>java.sql.Date</code> value.
785      * The driver converts this
786      * to an SQL <code>DATE</code> value when it sends it to the database.
787      *
788      * @param parameterName the name of the parameter
789      * @param x the parameter value
790      * @exception SQLException if a database access error occurs
791      * @see #getDate
792      * @since 1.4
793      */
794     void setDate(String parameterName, java.sql.Date x)
795     throws SQLException ;
796
797     /**
798      * Sets the designated parameter to the given <code>java.sql.Time</code> value.
799      * The driver converts this
800      * to an SQL <code>TIME</code> value when it sends it to the database.
801      *
802      * @param parameterName the name of the parameter
803      * @param x the parameter value
804      * @exception SQLException if a database access error occurs
805      * @see #getTime
806      * @since 1.4
807      */
808     void setTime(String parameterName, java.sql.Time x)
809     throws SQLException ;
810
811     /**
812      * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
813      * The driver
814      * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
815      * database.
816      *
817      * @param parameterName the name of the parameter
818      * @param x the parameter value
819      * @exception SQLException if a database access error occurs
820      * @see #getTimestamp
821      * @since 1.4
822      */
823     void setTimestamp(String parameterName, java.sql.Timestamp x)
824     throws SQLException ;
825
826     /**
827      * Sets the designated parameter to the given input stream, which will have
828      * the specified number of bytes.
829      * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
830      * parameter, it may be more practical to send it via a
831      * <code>java.io.InputStream</code>. Data will be read from the stream
832      * as needed until end-of-file is reached. The JDBC driver will
833      * do any necessary conversion from ASCII to the database char format.
834      *
835      * <P><B>Note:</B> This stream object can either be a standard
836      * Java stream object or your own subclass that implements the
837      * standard interface.
838      *
839      * @param parameterName the name of the parameter
840      * @param x the Java input stream that contains the ASCII parameter value
841      * @param length the number of bytes in the stream
842      * @exception SQLException if a database access error occurs
843      * @since 1.4
844      */
845     void setAsciiStream(String parameterName, java.io.InputStream x, int length)
846     throws SQLException ;
847
848     /**
849      * Sets the designated parameter to the given input stream, which will have
850      * the specified number of bytes.
851      * When a very large binary value is input to a <code>LONGVARBINARY</code>
852      * parameter, it may be more practical to send it via a
853      * <code>java.io.InputStream</code> object. The data will be read from the stream
854      * as needed until end-of-file is reached.
855      *
856      * <P><B>Note:</B> This stream object can either be a standard
857      * Java stream object or your own subclass that implements the
858      * standard interface.
859      *
860      * @param parameterName the name of the parameter
861      * @param x the java input stream which contains the binary parameter value
862      * @param length the number of bytes in the stream
863      * @exception SQLException if a database access error occurs
864      * @since 1.4
865      */
866     void setBinaryStream(String parameterName, java.io.InputStream x,
867              int length) throws SQLException ;
868
869     /**
870      * Sets the value of the designated parameter with the given object. The second
871      * argument must be an object type; for integral values, the
872      * <code>java.lang</code> equivalent objects should be used.
873      *
874      * <p>The given Java object will be converted to the given targetSqlType
875      * before being sent to the database.
876      *
877      * If the object has a custom mapping (is of a class implementing the
878      * interface <code>SQLData</code>),
879      * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
880      * to the SQL data stream.
881      * If, on the other hand, the object is of a class implementing
882      * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>Struct</code>,
883      * or <code>Array</code>, the driver should pass it to the database as a
884      * value of the corresponding SQL type.
885      * <P>
886      * Note that this method may be used to pass datatabase-
887      * specific abstract data types.
888      *
889      * @param parameterName the name of the parameter
890      * @param x the object containing the input parameter value
891      * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
892      * sent to the database. The scale argument may further qualify this type.
893      * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
894      * this is the number of digits after the decimal point. For all other
895      * types, this value will be ignored.
896      * @exception SQLException if a database access error occurs
897      * @see Types
898      * @see #getObject
899      * @since 1.4
900      */
901     void setObject(String parameterName, Object x, int targetSqlType, int scale)
902     throws SQLException ;
903
904     /**
905      * Sets the value of the designated parameter with the given object.
906      * This method is like the method <code>setObject</code>
907      * above, except that it assumes a scale of zero.
908      *
909      * @param parameterName the name of the parameter
910      * @param x the object containing the input parameter value
911      * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
912      * sent to the database
913      * @exception SQLException if a database access error occurs
914      * @see #getObject
915      * @since 1.4
916      */
917     void setObject(String parameterName, Object x, int targetSqlType)
918     throws SQLException ;
919
920     /**
921      * Sets the value of the designated parameter with the given object.
922      * The second parameter must be of type <code>Object</code>; therefore, the
923      * <code>java.lang</code> equivalent objects should be used for built-in types.
924      *
925      * <p>The JDBC specification specifies a standard mapping from
926      * Java <code>Object</code> types to SQL types. The given argument
927      * will be converted to the corresponding SQL type before being
928      * sent to the database.
929      *
930      * <p>Note that this method may be used to pass datatabase-
931      * specific abstract data types, by using a driver-specific Java
932      * type.
933      *
934      * If the object is of a class implementing the interface <code>SQLData</code>,
935      * the JDBC driver should call the method <code>SQLData.writeSQL</code>