1 /*
2 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.sql;
27
28 import java.math.BigDecimal;
29 import java.util.Calendar;
30 import java.io.Reader;
31 import java.io.InputStream;
32
33 /**
34 * The interface used to execute SQL stored procedures. The JDBC API
35 * provides a stored procedure SQL escape syntax that allows stored procedures
36 * to be called in a standard way for all RDBMSs. This escape syntax has one
37 * form that includes a result parameter and one that does not. If used, the result
38 * parameter must be registered as an OUT parameter. The other parameters
39 * can be used for input, output or both. Parameters are referred to
40 * sequentially, by number, with the first parameter being 1.
41 * <PRE>
42 * {?= call <procedure-name>[(<arg1>,<arg2>, ...)]}
43 * {call <procedure-name>[(<arg1>,<arg2>, ...)]}
44 * </PRE>
45 * <P>
46 * IN parameter values are set using the <code>set</code> methods inherited from
47 * {@link PreparedStatement}. The type of all OUT parameters must be
48 * registered prior to executing the stored procedure; their values
49 * are retrieved after execution via the <code>get</code> methods provided here.
50 * <P>
51 * A <code>CallableStatement</code> can return one {@link ResultSet} object or
52 * multiple <code>ResultSet</code> objects. Multiple
53 * <code>ResultSet</code> objects are handled using operations
54 * inherited from {@link Statement}.
55 * <P>
56 * For maximum portability, a call's <code>ResultSet</code> objects and
57 * update counts should be processed prior to getting the values of output
58 * parameters.
59 * <P>
60 *
61 * @see Connection#prepareCall
62 * @see ResultSet
63 */
64
65 public interface CallableStatement extends PreparedStatement {
66
67 /**
68 * Registers the OUT parameter in ordinal position
69 * <code>parameterIndex</code> to the JDBC type
70 * <code>sqlType</code>. All OUT parameters must be registered
71 * before a stored procedure is executed.
72 * <p>
73 * The JDBC type specified by <code>sqlType</code> for an OUT
74 * parameter determines the Java type that must be used
75 * in the <code>get</code> method to read the value of that parameter.
76 * <p>
77 * If the JDBC type expected to be returned to this output parameter
78 * is specific to this particular database, <code>sqlType</code>
79 * should be <code>java.sql.Types.OTHER</code>. The method
80 * {@link #getObject} retrieves the value.
81 *
82 * @param parameterIndex the first parameter is 1, the second is 2,
83 * and so on
84 * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
85 * If the parameter is of JDBC type <code>NUMERIC</code>
86 * or <code>DECIMAL</code>, the version of
87 * <code>registerOutParameter</code> that accepts a scale value
88 * should be used.
89 *
90 * @exception SQLException if the parameterIndex is not valid;
91 * if a database access error occurs or
92 * this method is called on a closed <code>CallableStatement</code>
93 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
94 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
95 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
96 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
97 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
98 * or <code>STRUCT</code> data type and the JDBC driver does not support
99 * this data type
100 * @see Types
101 */
102 void registerOutParameter(int parameterIndex, int sqlType)
103 throws SQLException;
104
105 /**
106 * Registers the parameter in ordinal position
107 * <code>parameterIndex</code> to be of JDBC type
108 * <code>sqlType</code>. All OUT parameters must be registered
109 * before a stored procedure is executed.
110 * <p>
111 * The JDBC type specified by <code>sqlType</code> for an OUT
112 * parameter determines the Java type that must be used
113 * in the <code>get</code> method to read the value of that parameter.
114 * <p>
115 * This version of <code>registerOutParameter</code> should be
116 * used when the parameter is of JDBC type <code>NUMERIC</code>
117 * or <code>DECIMAL</code>.
118 *
119 * @param parameterIndex the first parameter is 1, the second is 2,
120 * and so on
121 * @param sqlType the SQL type code defined by <code>java.sql.Types</code>.
122 * @param scale the desired number of digits to the right of the
123 * decimal point. It must be greater than or equal to zero.
124 * @exception SQLException if the parameterIndex is not valid;
125 * if a database access error occurs or
126 * this method is called on a closed <code>CallableStatement</code>
127 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
128 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
129 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
130 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
131 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
132 * or <code>STRUCT</code> data type and the JDBC driver does not support
133 * this data type
134 * @see Types
135 */
136 void registerOutParameter(int parameterIndex, int sqlType, int scale)
137 throws SQLException;
138
139 /**
140 * Retrieves whether the last OUT parameter read had the value of
141 * SQL <code>NULL</code>. Note that this method should be called only after
142 * calling a getter method; otherwise, there is no value to use in
143 * determining whether it is <code>null</code> or not.
144 *
145 * @return <code>true</code> if the last parameter read was SQL
146 * <code>NULL</code>; <code>false</code> otherwise
147 * @exception SQLException if a database access error occurs or
148 * this method is called on a closed <code>CallableStatement</code>
149 */
150 boolean wasNull() throws SQLException;
151
152 /**
153 * Retrieves the value of the designated JDBC <code>CHAR</code>,
154 * <code>VARCHAR</code>, or <code>LONGVARCHAR</code> parameter as a
155 * <code>String</code> in the Java programming language.
156 * <p>
157 * For the fixed-length type JDBC <code>CHAR</code>,
158 * the <code>String</code> object
159 * returned has exactly the same value the SQL
160 * <code>CHAR</code> value had in the
161 * database, including any padding added by the database.
162 *
163 * @param parameterIndex the first parameter is 1, the second is 2,
164 * and so on
165 * @return the parameter value. If the value is SQL <code>NULL</code>,
166 * the result
167 * is <code>null</code>.
168 * @exception SQLException if the parameterIndex is not valid;
169 * if a database access error occurs or
170 * this method is called on a closed <code>CallableStatement</code>
171 * @see #setString
172 */
173 String getString(int parameterIndex) throws SQLException;
174
175 /**
176 * Retrieves the value of the designated JDBC <code>BIT</code>
177 * or <code>BOOLEAN</code> parameter as a
178 * <code>boolean</code> in the Java programming language.
179 *
180 * @param parameterIndex the first parameter is 1, the second is 2,
181 * and so on
182 * @return the parameter value. If the value is SQL <code>NULL</code>,
183 * the result is <code>false</code>.
184 * @exception SQLException if the parameterIndex is not valid;
185 * if a database access error occurs or
186 * this method is called on a closed <code>CallableStatement</code>
187 * @see #setBoolean
188 */
189 boolean getBoolean(int parameterIndex) throws SQLException;
190
191 /**
192 * Retrieves the value of the designated JDBC <code>TINYINT</code> parameter
193 * as a <code>byte</code> in the Java programming language.
194 *
195 * @param parameterIndex the first parameter is 1, the second is 2,
196 * and so on
197 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
198 * is <code>0</code>.
199 * @exception SQLException if the parameterIndex is not valid;
200 * if a database access error occurs or
201 * this method is called on a closed <code>CallableStatement</code>
202 * @see #setByte
203 */
204 byte getByte(int parameterIndex) throws SQLException;
205
206 /**
207 * Retrieves the value of the designated JDBC <code>SMALLINT</code> parameter
208 * as a <code>short</code> in the Java programming language.
209 *
210 * @param parameterIndex the first parameter is 1, the second is 2,
211 * and so on
212 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
213 * is <code>0</code>.
214 * @exception SQLException if the parameterIndex is not valid;
215 * if a database access error occurs or
216 * this method is called on a closed <code>CallableStatement</code>
217 * @see #setShort
218 */
219 short getShort(int parameterIndex) throws SQLException;
220
221 /**
222 * Retrieves the value of the designated JDBC <code>INTEGER</code> parameter
223 * as an <code>int</code> in the Java programming language.
224 *
225 * @param parameterIndex the first parameter is 1, the second is 2,
226 * and so on
227 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
228 * is <code>0</code>.
229 * @exception SQLException if the parameterIndex is not valid;
230 * if a database access error occurs or
231 * this method is called on a closed <code>CallableStatement</code>
232 * @see #setInt
233 */
234 int getInt(int parameterIndex) throws SQLException;
235
236 /**
237 * Retrieves the value of the designated JDBC <code>BIGINT</code> parameter
238 * as a <code>long</code> in the Java programming language.
239 *
240 * @param parameterIndex the first parameter is 1, the second is 2,
241 * and so on
242 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
243 * is <code>0</code>.
244 * @exception SQLException if the parameterIndex is not valid;
245 * if a database access error occurs or
246 * this method is called on a closed <code>CallableStatement</code>
247 * @see #setLong
248 */
249 long getLong(int parameterIndex) throws SQLException;
250
251 /**
252 * Retrieves the value of the designated JDBC <code>FLOAT</code> parameter
253 * as a <code>float</code> in the Java programming language.
254 *
255 * @param parameterIndex the first parameter is 1, the second is 2,
256 * and so on
257 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
258 * is <code>0</code>.
259 * @exception SQLException if the parameterIndex is not valid;
260 * if a database access error occurs or
261 * this method is called on a closed <code>CallableStatement</code>
262 * @see #setFloat
263 */
264 float getFloat(int parameterIndex) throws SQLException;
265
266 /**
267 * Retrieves the value of the designated JDBC <code>DOUBLE</code> parameter as a <code>double</code>
268 * in the Java programming language.
269 * @param parameterIndex the first parameter is 1, the second is 2,
270 * and so on
271 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
272 * is <code>0</code>.
273 * @exception SQLException if the parameterIndex is not valid;
274 * if a database access error occurs or
275 * this method is called on a closed <code>CallableStatement</code>
276 * @see #setDouble
277 */
278 double getDouble(int parameterIndex) throws SQLException;
279
280 /**
281 * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
282 * <code>java.math.BigDecimal</code> object with <i>scale</i> digits to
283 * the right of the decimal point.
284 * @param parameterIndex the first parameter is 1, the second is 2,
285 * and so on
286 * @param scale the number of digits to the right of the decimal point
287 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
288 * is <code>null</code>.
289 * @exception SQLException if the parameterIndex is not valid;
290 * if a database access error occurs or
291 * this method is called on a closed <code>CallableStatement</code>
292 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
293 * this method
294 * @deprecated use <code>getBigDecimal(int parameterIndex)</code>
295 * or <code>getBigDecimal(String parameterName)</code>
296 * @see #setBigDecimal
297 */
298 BigDecimal getBigDecimal(int parameterIndex, int scale)
299 throws SQLException;
300
301 /**
302 * Retrieves the value of the designated JDBC <code>BINARY</code> or
303 * <code>VARBINARY</code> parameter as an array of <code>byte</code>
304 * values in the Java programming language.
305 * @param parameterIndex the first parameter is 1, the second is 2,
306 * and so on
307 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
308 * is <code>null</code>.
309 * @exception SQLException if the parameterIndex is not valid;
310 * if a database access error occurs or
311 * this method is called on a closed <code>CallableStatement</code>
312 * @see #setBytes
313 */
314 byte[] getBytes(int parameterIndex) throws SQLException;
315
316 /**
317 * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
318 * <code>java.sql.Date</code> object.
319 * @param parameterIndex the first parameter is 1, the second is 2,
320 * and so on
321 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
322 * is <code>null</code>.
323 * @exception SQLException if the parameterIndex is not valid;
324 * if a database access error occurs or
325 * this method is called on a closed <code>CallableStatement</code>
326 * @see #setDate
327 */
328 java.sql.Date getDate(int parameterIndex) throws SQLException;
329
330 /**
331 * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
332 * <code>java.sql.Time</code> object.
333 *
334 * @param parameterIndex the first parameter is 1, the second is 2,
335 * and so on
336 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
337 * is <code>null</code>.
338 * @exception SQLException if the parameterIndex is not valid;
339 * if a database access error occurs or
340 * this method is called on a closed <code>CallableStatement</code>
341 * @see #setTime
342 */
343 java.sql.Time getTime(int parameterIndex) throws SQLException;
344
345 /**
346 * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
347 * <code>java.sql.Timestamp</code> object.
348 *
349 * @param parameterIndex the first parameter is 1, the second is 2,
350 * and so on
351 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
352 * is <code>null</code>.
353 * @exception SQLException if the parameterIndex is not valid;
354 * if a database access error occurs or
355 * this method is called on a closed <code>CallableStatement</code>
356 * @see #setTimestamp
357 */
358 java.sql.Timestamp getTimestamp(int parameterIndex)
359 throws SQLException;
360
361 //----------------------------------------------------------------------
362 // Advanced features:
363
364
365 /**
366 * Retrieves the value of the designated parameter as an <code>Object</code>
367 * in the Java programming language. If the value is an SQL <code>NULL</code>,
368 * the driver returns a Java <code>null</code>.
369 * <p>
370 * This method returns a Java object whose type corresponds to the JDBC
371 * type that was registered for this parameter using the method
372 * <code>registerOutParameter</code>. By registering the target JDBC
373 * type as <code>java.sql.Types.OTHER</code>, this method can be used
374 * to read database-specific abstract data types.
375 *
376 * @param parameterIndex the first parameter is 1, the second is 2,
377 * and so on
378 * @return A <code>java.lang.Object</code> holding the OUT parameter value
379 * @exception SQLException if the parameterIndex is not valid;
380 * if a database access error occurs or
381 * this method is called on a closed <code>CallableStatement</code>
382 * @see Types
383 * @see #setObject
384 */
385 Object getObject(int parameterIndex) throws SQLException;
386
387
388 //--------------------------JDBC 2.0-----------------------------
389
390 /**
391 * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
392 * <code>java.math.BigDecimal</code> object with as many digits to the
393 * right of the decimal point as the value contains.
394 * @param parameterIndex the first parameter is 1, the second is 2,
395 * and so on
396 * @return the parameter value in full precision. If the value is
397 * SQL <code>NULL</code>, the result is <code>null</code>.
398 * @exception SQLException if the parameterIndex is not valid;
399 * if a database access error occurs or
400 * this method is called on a closed <code>CallableStatement</code>
401 * @see #setBigDecimal
402 * @since 1.2
403 */
404 BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
405
406 /**
407 * Returns an object representing the value of OUT parameter
408 * <code>parameterIndex</code> and uses <code>map</code> for the custom
409 * mapping of the parameter value.
410 * <p>
411 * This method returns a Java object whose type corresponds to the
412 * JDBC type that was registered for this parameter using the method
413 * <code>registerOutParameter</code>. By registering the target
414 * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
415 * be used to read database-specific abstract data types.
416 * @param parameterIndex the first parameter is 1, the second is 2, and so on
417 * @param map the mapping from SQL type names to Java classes
418 * @return a <code>java.lang.Object</code> holding the OUT parameter value
419 * @exception SQLException if the parameterIndex is not valid;
420 * if a database access error occurs or
421 * this method is called on a closed <code>CallableStatement</code>
422 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
423 * this method
424 * @see #setObject
425 * @since 1.2
426 */
427 Object getObject(int parameterIndex, java.util.Map<String,Class<?>> map)
428 throws SQLException;
429
430 /**
431 * Retrieves the value of the designated JDBC <code>REF(<structured-type>)</code>
432 * parameter as a {@link java.sql.Ref} object in the Java programming language.
433 * @param parameterIndex the first parameter is 1, the second is 2,
434 * and so on
435 * @return the parameter value as a <code>Ref</code> object in the
436 * Java programming language. If the value was SQL <code>NULL</code>, the value
437 * <code>null</code> is returned.
438 * @exception SQLException if the parameterIndex is not valid;
439 * if a database access error occurs or
440 * this method is called on a closed <code>CallableStatement</code>
441 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
442 * this method
443 * @since 1.2
444 */
445 Ref getRef (int parameterIndex) throws SQLException;
446
447 /**
448 * Retrieves the value of the designated JDBC <code>BLOB</code> parameter as a
449 * {@link java.sql.Blob} object in the Java programming language.
450 * @param parameterIndex the first parameter is 1, the second is 2, and so on
451 * @return the parameter value as a <code>Blob</code> object in the
452 * Java programming language. If the value was SQL <code>NULL</code>, the value
453 * <code>null</code> is returned.
454 * @exception SQLException if the parameterIndex is not valid;
455 * if a database access error occurs or
456 * this method is called on a closed <code>CallableStatement</code>
457 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
458 * this method
459 * @since 1.2
460 */
461 Blob getBlob (int parameterIndex) throws SQLException;
462
463 /**
464 * Retrieves the value of the designated JDBC <code>CLOB</code> parameter as a
465 * <code>java.sql.Clob</code> object in the Java programming language.
466 * @param parameterIndex the first parameter is 1, the second is 2, and
467 * so on
468 * @return the parameter value as a <code>Clob</code> object in the
469 * Java programming language. If the value was SQL <code>NULL</code>, the
470 * value <code>null</code> is returned.
471 * @exception SQLException if the parameterIndex is not valid;
472 * if a database access error occurs or
473 * this method is called on a closed <code>CallableStatement</code>
474 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
475 * this method
476 * @since 1.2
477 */
478 Clob getClob (int parameterIndex) throws SQLException;
479
480 /**
481 *
482 * Retrieves the value of the designated JDBC <code>ARRAY</code> parameter as an
483 * {@link java.sql.Array} object in the Java programming language.
484 * @param parameterIndex the first parameter is 1, the second is 2, and
485 * so on
486 * @return the parameter value as an <code>Array</code> object in
487 * the Java programming language. If the value was SQL <code>NULL</code>, the
488 * value <code>null</code> is returned.
489 * @exception SQLException if the parameterIndex is not valid;
490 * if a database access error occurs or
491 * this method is called on a closed <code>CallableStatement</code>
492 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
493 * this method
494 * @since 1.2
495 */
496 Array getArray (int parameterIndex) throws SQLException;
497
498 /**
499 * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
500 * <code>java.sql.Date</code> object, using
501 * the given <code>Calendar</code> object
502 * to construct the date.
503 * With a <code>Calendar</code> object, the driver
504 * can calculate the date taking into account a custom timezone and locale.
505 * If no <code>Calendar</code> object is specified, the driver uses the
506 * default timezone and locale.
507 *
508 * @param parameterIndex the first parameter is 1, the second is 2,
509 * and so on
510 * @param cal the <code>Calendar</code> object the driver will use
511 * to construct the date
512 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
513 * is <code>null</code>.
514 * @exception SQLException if the parameterIndex is not valid;
515 * if a database access error occurs or
516 * this method is called on a closed <code>CallableStatement</code>
517 * @see #setDate
518 * @since 1.2
519 */
520 java.sql.Date getDate(int parameterIndex, Calendar cal)
521 throws SQLException;
522
523 /**
524 * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
525 * <code>java.sql.Time</code> object, using
526 * the given <code>Calendar</code> object
527 * to construct the time.
528 * With a <code>Calendar</code> object, the driver
529 * can calculate the time taking into account a custom timezone and locale.
530 * If no <code>Calendar</code> object is specified, the driver uses the
531 * default timezone and locale.
532 *
533 * @param parameterIndex the first parameter is 1, the second is 2,
534 * and so on
535 * @param cal the <code>Calendar</code> object the driver will use
536 * to construct the time
537 * @return the parameter value; if the value is SQL <code>NULL</code>, the result
538 * is <code>null</code>.
539 * @exception SQLException if the parameterIndex is not valid;
540 * if a database access error occurs or
541 * this method is called on a closed <code>CallableStatement</code>
542 * @see #setTime
543 * @since 1.2
544 */
545 java.sql.Time getTime(int parameterIndex, Calendar cal)
546 throws SQLException;
547
548 /**
549 * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
550 * <code>java.sql.Timestamp</code> object, using
551 * the given <code>Calendar</code> object to construct
552 * the <code>Timestamp</code> object.
553 * With a <code>Calendar</code> object, the driver
554 * can calculate the timestamp taking into account a custom timezone and locale.
555 * If no <code>Calendar</code> object is specified, the driver uses the
556 * default timezone and locale.
557 *
558 *
559 * @param parameterIndex the first parameter is 1, the second is 2,
560 * and so on
561 * @param cal the <code>Calendar</code> object the driver will use
562 * to construct the timestamp
563 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
564 * is <code>null</code>.
565 * @exception SQLException if the parameterIndex is not valid;
566 * if a database access error occurs or
567 * this method is called on a closed <code>CallableStatement</code>
568 * @see #setTimestamp
569 * @since 1.2
570 */
571 java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal)
572 throws SQLException;
573
574
575 /**
576 * Registers the designated output parameter.
577 * This version of
578 * the method <code>registerOutParameter</code>
579 * should be used for a user-defined or <code>REF</code> output parameter. Examples
580 * of user-defined types include: <code>STRUCT</code>, <code>DISTINCT</code>,
581 * <code>JAVA_OBJECT</code>, and named array types.
582 *<p>
583 * All OUT parameters must be registered
584 * before a stored procedure is executed.
585 * <p> For a user-defined parameter, the fully-qualified SQL
586 * type name of the parameter should also be given, while a <code>REF</code>
587 * parameter requires that the fully-qualified type name of the
588 * referenced type be given. A JDBC driver that does not need the
589 * type code and type name information may ignore it. To be portable,
590 * however, applications should always provide these values for
591 * user-defined and <code>REF</code> parameters.
592 *
593 * Although it is intended for user-defined and <code>REF</code> parameters,
594 * this method may be used to register a parameter of any JDBC type.
595 * If the parameter does not have a user-defined or <code>REF</code> type, the
596 * <i>typeName</i> parameter is ignored.
597 *
598 * <P><B>Note:</B> When reading the value of an out parameter, you
599 * must use the getter method whose Java type corresponds to the
600 * parameter's registered SQL type.
601 *
602 * @param parameterIndex the first parameter is 1, the second is 2,...
603 * @param sqlType a value from {@link java.sql.Types}
604 * @param typeName the fully-qualified name of an SQL structured type
605 * @exception SQLException if the parameterIndex is not valid;
606 * if a database access error occurs or
607 * this method is called on a closed <code>CallableStatement</code>
608 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
609 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
610 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
611 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
612 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
613 * or <code>STRUCT</code> data type and the JDBC driver does not support
614 * this data type
615 * @see Types
616 * @since 1.2
617 */
618 void registerOutParameter (int parameterIndex, int sqlType, String typeName)
619 throws SQLException;
620
621 //--------------------------JDBC 3.0-----------------------------
622
623 /**
624 * Registers the OUT parameter named
625 * <code>parameterName</code> to the JDBC type
626 * <code>sqlType</code>. All OUT parameters must be registered
627 * before a stored procedure is executed.
628 * <p>
629 * The JDBC type specified by <code>sqlType</code> for an OUT
630 * parameter determines the Java type that must be used
631 * in the <code>get</code> method to read the value of that parameter.
632 * <p>
633 * If the JDBC type expected to be returned to this output parameter
634 * is specific to this particular database, <code>sqlType</code>
635 * should be <code>java.sql.Types.OTHER</code>. The method
636 * {@link #getObject} retrieves the value.
637 * @param parameterName the name of the parameter
638 * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
639 * If the parameter is of JDBC type <code>NUMERIC</code>
640 * or <code>DECIMAL</code>, the version of
641 * <code>registerOutParameter</code> that accepts a scale value
642 * should be used.
643 * @exception SQLException if parameterName does not correspond to a named
644 * parameter; if a database access error occurs or
645 * this method is called on a closed <code>CallableStatement</code>
646 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
647 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
648 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
649 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
650 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
651 * or <code>STRUCT</code> data type and the JDBC driver does not support
652 * this data type or if the JDBC driver does not support
653 * this method
654 * @since 1.4
655 * @see Types
656 */
657 void registerOutParameter(String parameterName, int sqlType)
658 throws SQLException;
659
660 /**
661 * Registers the parameter named
662 * <code>parameterName</code> to be of JDBC type
663 * <code>sqlType</code>. All OUT parameters must be registered
664 * before a stored procedure is executed.
665 * <p>
666 * The JDBC type specified by <code>sqlType</code> for an OUT
667 * parameter determines the Java type that must be used
668 * in the <code>get</code> method to read the value of that parameter.
669 * <p>
670 * This version of <code>registerOutParameter</code> should be
671 * used when the parameter is of JDBC type <code>NUMERIC</code>
672 * or <code>DECIMAL</code>.
673 *
674 * @param parameterName the name of the parameter
675 * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
676 * @param scale the desired number of digits to the right of the
677 * decimal point. It must be greater than or equal to zero.
678 * @exception SQLException if parameterName does not correspond to a named
679 * parameter; if a database access error occurs or
680 * this method is called on a closed <code>CallableStatement</code>
681 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
682 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
683 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
684 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
685 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
686 * or <code>STRUCT</code> data type and the JDBC driver does not support
687 * this data type or if the JDBC driver does not support
688 * this method
689 * @since 1.4
690 * @see Types
691 */
692 void registerOutParameter(String parameterName, int sqlType, int scale)
693 throws SQLException;
694
695 /**
696 * Registers the designated output parameter. This version of
697 * the method <code>registerOutParameter</code>
698 * should be used for a user-named or REF output parameter. Examples
699 * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
700 * named array types.
701 *<p>
702 * All OUT parameters must be registered
703 * before a stored procedure is executed.
704 * <p>
705 * For a user-named parameter the fully-qualified SQL
706 * type name of the parameter should also be given, while a REF
707 * parameter requires that the fully-qualified type name of the
708 * referenced type be given. A JDBC driver that does not need the
709 * type code and type name information may ignore it. To be portable,
710 * however, applications should always provide these values for
711 * user-named and REF parameters.
712 *
713 * Although it is intended for user-named and REF parameters,
714 * this method may be used to register a parameter of any JDBC type.
715 * If the parameter does not have a user-named or REF type, the
716 * typeName parameter is ignored.
717 *
718 * <P><B>Note:</B> When reading the value of an out parameter, you
719 * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
720 * parameter's registered SQL type.
721 *
722 * @param parameterName the name of the parameter
723 * @param sqlType a value from {@link java.sql.Types}
724 * @param typeName the fully-qualified name of an SQL structured type
725 * @exception SQLException if parameterName does not correspond to a named
726 * parameter; if a database access error occurs or
727 * this method is called on a closed <code>CallableStatement</code>
728 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
729 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
730 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
731 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
732 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
733 * or <code>STRUCT</code> data type and the JDBC driver does not support
734 * this data type or if the JDBC driver does not support
735 * this method
736 * @see Types
737 * @since 1.4
738 */
739 void registerOutParameter (String parameterName, int sqlType, String typeName)
740 throws SQLException;
741
742 /**
743 * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
744 * <code>java.net.URL</code> object.
745 *
746 * @param parameterIndex the first parameter is 1, the second is 2,...
747 * @return a <code>java.net.URL</code> object that represents the
748 * JDBC <code>DATALINK</code> value used as the designated
749 * parameter
750 * @exception SQLException if the parameterIndex is not valid;
751 * if a database access error occurs,
752 * this method is called on a closed <code>CallableStatement</code>,
753 * or if the URL being returned is
754 * not a valid URL on the Java platform
755 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
756 * this method
757 * @see #setURL
758 * @since 1.4
759 */
760 java.net.URL getURL(int parameterIndex) throws SQLException;
761
762 /**
763 * Sets the designated parameter to the given <code>java.net.URL</code> object.
764 * The driver converts this to an SQL <code>DATALINK</code> value when
765 * it sends it to the database.
766 *
767 * @param parameterName the name of the parameter
768 * @param val the parameter value
769 * @exception SQLException if parameterName does not correspond to a named
770 * parameter; if a database access error occurs;
771 * this method is called on a closed <code>CallableStatement</code>
772 * or if a URL is malformed
773 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
774 * this method
775 * @see #getURL
776 * @since 1.4
777 */
778 void setURL(String parameterName, java.net.URL val) throws SQLException;
779
780 /**
781 * Sets the designated parameter to SQL <code>NULL</code>.
782 *
783 * <P><B>Note:</B> You must specify the parameter's SQL type.
784 *
785 * @param parameterName the name of the parameter
786 * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
787 * @exception SQLException if parameterName does not correspond to a named
788 * parameter; if a database access error occurs or
789 * this method is called on a closed <code>CallableStatement</code>
790 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
791 * this method
792 * @since 1.4
793 */
794 void setNull(String parameterName, int sqlType) throws SQLException;
795
796 /**
797 * Sets the designated parameter to the given Java <code>boolean</code> value.
798 * The driver converts this
799 * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
800 *
801 * @param parameterName the name of the parameter
802 * @param x the parameter value
803 * @exception SQLException if parameterName does not correspond to a named
804 * parameter; if a database access error occurs or
805 * this method is called on a closed <code>CallableStatement</code>
806 * @see #getBoolean
807 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
808 * this method
809 * @since 1.4
810 */
811 void setBoolean(String parameterName, boolean x) throws SQLException;
812
813 /**
814 * Sets the designated parameter to the given Java <code>byte</code> value.
815 * The driver converts this
816 * to an SQL <code>TINYINT</code> value when it sends it to the database.
817 *
818 * @param parameterName the name of the parameter
819 * @param x the parameter value
820 * @exception SQLException if parameterName does not correspond to a named
821 * parameter; if a database access error occurs or
822 * this method is called on a closed <code>CallableStatement</code>
823 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
824 * this method
825 * @see #getByte
826 * @since 1.4
827 */
828 void setByte(String parameterName, byte x) throws SQLException;
829
830 /**
831 * Sets the designated parameter to the given Java <code>short</code> value.
832 * The driver converts this
833 * to an SQL <code>SMALLINT</code> value when it sends it to the database.
834 *
835 * @param parameterName the name of the parameter
836 * @param x the parameter value
837 * @exception SQLException if parameterName does not correspond to a named
838 * parameter; if a database access error occurs or
839 * this method is called on a closed <code>CallableStatement</code>
840 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
841 * this method
842 * @see #getShort
843 * @since 1.4
844 */
845 void setShort(String parameterName, short x) throws SQLException;
846
847 /**
848 * Sets the designated parameter to the given Java <code>int</code> value.
849 * The driver converts this
850 * to an SQL <code>INTEGER</code> value when it sends it to the database.
851 *
852 * @param parameterName the name of the parameter
853 * @param x the parameter value
854 * @exception SQLException if parameterName does not correspond to a named
855 * parameter; if a database access error occurs or
856 * this method is called on a closed <code>CallableStatement</code>
857 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
858 * this method
859 * @see #getInt
860 * @since 1.4
861 */
862 void setInt(String parameterName, int x) throws SQLException;
863
864 /**
865 * Sets the designated parameter to the given Java <code>long</code> value.
866 * The driver converts this
867 * to an SQL <code>BIGINT</code> value when it sends it to the database.
868 *
869 * @param parameterName the name of the parameter
870 * @param x the parameter value
871 * @exception SQLException if parameterName does not correspond to a named
872 * parameter; if a database access error occurs or
873 * this method is called on a closed <code>CallableStatement</code>
874 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
875 * this method
876 * @see #getLong
877 * @since 1.4
878 */
879 void setLong(String parameterName, long x) throws SQLException;
880
881 /**
882 * Sets the designated parameter to the given Java <code>float</code> value.
883 * The driver converts this
884 * to an SQL <code>FLOAT</code> value when it sends it to the database.
885 *
886 * @param parameterName the name of the parameter
887 * @param x the parameter value
888 * @exception SQLException if parameterName does not correspond to a named
889 * parameter; if a database access error occurs or
890 * this method is called on a closed <code>CallableStatement</code>
891 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
892 * this method
893 * @see #getFloat
894 * @since 1.4
895 */
896 void setFloat(String parameterName, float x) throws SQLException;
897
898 /**
899 * Sets the designated parameter to the given Java <code>double</code> value.
900 * The driver converts this
901 * to an SQL <code>DOUBLE</code> value when it sends it to the database.
902 *
903 * @param parameterName the name of the parameter
904 * @param x the parameter value
905 * @exception SQLException if parameterName does not correspond to a named
906 * parameter; if a database access error occurs or
907 * this method is called on a closed <code>CallableStatement</code>
908 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
909 * this method
910 * @see #getDouble
911 * @since 1.4
912 */
913 void setDouble(String parameterName, double x) throws SQLException;
914
915 /**
916 * Sets the designated parameter to the given
917 * <code>java.math.BigDecimal</code> value.
918 * The driver converts this to an SQL <code>NUMERIC</code> value when
919 * it sends it to the database.
920 *
921 * @param parameterName the name of the parameter
922 * @param x the parameter value
923 * @exception SQLException if parameterName does not correspond to a named
924 * parameter; if a database access error occurs or
925 * this method is called on a closed <code>CallableStatement</code>
926 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
927 * this method
928 * @see #getBigDecimal
929 * @since 1.4
930 */
931 void setBigDecimal(String parameterName, BigDecimal x) throws SQLException;
932
933 /**
934 * Sets the designated parameter to the given Java <code>String</code> value.
935 * The driver converts this
936 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
937 * (depending on the argument's
938 * size relative to the driver's limits on <code>VARCHAR</code> values)
939 * when it sends it to the database.
940 *
941 * @param parameterName the name of the parameter
942 * @param x the parameter value
943 * @exception SQLException if parameterName does not correspond to a named
944 * parameter; if a database access error occurs or
945 * this method is called on a closed <code>CallableStatement</code>
946 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
947 * this method
948 * @see #getString
949 * @since 1.4
950 */
951 void setString(String parameterName, String x) throws SQLException;
952
953 /**
954 * Sets the designated parameter to the given Java array of bytes.
955 * The driver converts this to an SQL <code>VARBINARY</code> or
956 * <code>LONGVARBINARY</code> (depending on the argument's size relative
957 * to the driver's limits on <code>VARBINARY</code> values) when it sends
958 * it to the database.
959 *
960 * @param parameterName the name of the parameter
961 * @param x the parameter value
962 * @exception SQLException if parameterName does not correspond to a named
963 * parameter; if a database access error occurs or
964 * this method is called on a closed <code>CallableStatement</code>
965 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
966 * this method
967 * @see #getBytes
968 * @since 1.4
969 */
970 void setBytes(String parameterName, byte x[]) throws SQLException;
971
972 /**
973 * Sets the designated parameter to the given <code>java.sql.Date</code> value
974 * using the default time zone of the virtual machine that is running
975 * the application.
976 * The driver converts this
977 * to an SQL <code>DATE</code> value when it sends it to the database.
978 *
979 * @param parameterName the name of the parameter
980 * @param x the parameter value
981 * @exception SQLException if parameterName does not correspond to a named
982 * parameter; if a database access error occurs or
983 * this method is called on a closed <code>CallableStatement</code>
984 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
985 * this method
986 * @see #getDate
987 * @since 1.4
988 */
989 void setDate(String parameterName, java.sql.Date x)
990 throws SQLException;
991
992 /**
993 * Sets the designated parameter to the given <code>java.sql.Time</code> value.
994 * The driver converts this
995 * to an SQL <code>TIME</code> value when it sends it to the database.
996 *
997 * @param parameterName the name of the parameter
998 * @param x the parameter value
999 * @exception SQLException if parameterName does not correspond to a named
1000 * parameter; if a database access error occurs or
1001 * this method is called on a closed <code>CallableStatement</code>
1002 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1003 * this method
1004 * @see #getTime
1005 * @since 1.4
1006 */
1007 void setTime(String parameterName, java.sql.Time x)
1008 throws SQLException;
1009
1010 /**
1011 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
1012 * The driver
1013 * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
1014 * database.
1015 *
1016 * @param parameterName the name of the parameter
1017 * @param x the parameter value
1018 * @exception SQLException if parameterName does not correspond to a named
1019 * parameter; if a database access error occurs or
1020 * this method is called on a closed <code>CallableStatement</code>
1021 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1022 * this method
1023 * @see #getTimestamp
1024 * @since 1.4
1025 */
1026 void setTimestamp(String parameterName, java.sql.Timestamp x)
1027 throws SQLException;
1028
1029 /**
1030 * Sets the designated parameter to the given input stream, which will have
1031 * the specified number of bytes.
1032 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1033 * parameter, it may be more practical to send it via a
1034 * <code>java.io.InputStream</code>. Data will be read from the stream
1035 * as needed until end-of-file is reached. The JDBC driver will
1036 * do any necessary conversion from ASCII to the database char format.
1037 *
1038 * <P><B>Note:</B> This stream object can either be a standard
1039 * Java stream object or your own subclass that implements the
1040 * standard interface.
1041 *
1042 * @param parameterName the name of the parameter
1043 * @param x the Java input stream that contains the ASCII parameter value
1044 * @param length the number of bytes in the stream
1045 * @exception SQLException if parameterName does not correspond to a named
1046 * parameter; if a database access error occurs or
1047 * this method is called on a closed <code>CallableStatement</code>
1048 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1049 * this method
1050 * @since 1.4
1051 */
1052 void setAsciiStream(String parameterName, java.io.InputStream x, int length)
1053 throws SQLException;
1054
1055 /**
1056 * Sets the designated parameter to the given input stream, which will have
1057 * the specified number of bytes.
1058 * When a very large binary value is input to a <code>LONGVARBINARY</code>
1059 * parameter, it may be more practical to send it via a
1060 * <code>java.io.InputStream</code> object. The data will be read from the stream
1061 * as needed until end-of-file is reached.
1062 *
1063 * <P><B>Note:</B> This stream object can either be a standard
1064 * Java stream object or your own subclass that implements the
1065 * standard interface.
1066 *
1067 * @param parameterName the name of the parameter
1068 * @param x the java input stream which contains the binary parameter value
1069 * @param length the number of bytes in the stream
1070 * @exception SQLException if parameterName does not correspond to a named
1071 * parameter; if a database access error occurs or
1072 * this method is called on a closed <code>CallableStatement</code>
1073 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1074 * this method
1075 * @since 1.4
1076 */
1077 void setBinaryStream(String parameterName, java.io.InputStream x,
1078 int length) throws SQLException;
1079
1080 /**
1081 * Sets the value of the designated parameter with the given object. The second
1082 * argument must be an object type; for integral values, the
1083 * <code>java.lang</code> equivalent objects should be used.
1084 *
1085 * <p>The given Java object will be converted to the given targetSqlType
1086 * before being sent to the database.
1087 *
1088 * If the object has a custom mapping (is of a class implementing the
1089 * interface <code>SQLData</code>),
1090 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1091 * to the SQL data stream.
1092 * If, on the other hand, the object is of a class implementing
1093 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1094 * <code>Struct</code>, <code>java.net.URL</code>,
1095 * or <code>Array</code>, the driver should pass it to the database as a
1096 * value of the corresponding SQL type.
1097 * <P>
1098 * Note that this method may be used to pass datatabase-
1099 * specific abstract data types.
1100 *
1101 * @param parameterName the name of the parameter
1102 * @param x the object containing the input parameter value
1103 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1104 * sent to the database. The scale argument may further qualify this type.
1105 * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1106 * this is the number of digits after the decimal point. For all other
1107 * types, this value will be ignored.
1108 * @exception SQLException if parameterName does not correspond to a named
1109 * parameter; if a database access error occurs or
1110 * this method is called on a closed <code>CallableStatement</code>
1111 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1112 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1113 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1114 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1115 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1116 * or <code>STRUCT</code> data type and the JDBC driver does not support
1117 * this data type
1118 * @see Types
1119 * @see #getObject
1120 * @since 1.4
1121 */
1122 void setObject(String parameterName, Object x, int targetSqlType, int scale)
1123 throws SQLException;
1124
1125 /**
1126 * Sets the value of the designated parameter with the given object.
1127 * This method is like the method <code>setObject</code>
1128 * above, except that it assumes a scale of zero.
1129 *
1130 * @param parameterName the name of the parameter
1131 * @param x the object containing the input parameter value
1132 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1133 * sent to the database
1134 * @exception SQLException if parameterName does not correspond to a named
1135 * parameter; if a database access error occurs or
1136 * this method is called on a closed <code>CallableStatement</code>
1137 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1138 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1139 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1140 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1141 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1142 * or <code>STRUCT</code> data type and the JDBC driver does not support
1143 * this data type
1144 * @see #getObject
1145 * @since 1.4
1146 */
1147 void setObject(String parameterName, Object x, int targetSqlType)
1148 throws SQLException;
1149
1150 /**
1151 * Sets the value of the designated parameter with the given object.
1152 * The second parameter must be of type <code>Object</code>; therefore, the
1153 * <code>java.lang</code> equivalent objects should be used for built-in types.
1154 *
1155 * <p>The JDBC specification specifies a standard mapping from
1156 * Java <code>Object</code> types to SQL types. The given argument
1157 * will be converted to the corresponding SQL type before being
1158 * sent to the database.
1159 * <p>Note that this method may be used to pass datatabase-
1160 * specific abstract data types, by using a driver-specific Java
1161 * type.
1162 *
1163 * If the object is of a class implementing the interface <code>SQLData</code>,
1164 * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1165 * to write it to the SQL data stream.
1166 * If, on the other hand, the object is of a class implementing
1167 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1168 * <code>Struct</code>, <code>java.net.URL</code>,
1169 * or <code>Array</code>, the driver should pass it to the database as a
1170 * value of the corresponding SQL type.
1171 * <P>
1172 * This method throws an exception if there is an ambiguity, for example, if the
1173 * object is of a class implementing more than one of the interfaces named above.
1174 *<p>
1175 *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to
1176 * the backend. For maximum portability, the <code>setNull</code> or the
1177 * <code>setObject(String parameterName, Object x, int sqlType)</code>
1178 * method should be used
1179 * instead of <code>setObject(String parameterName, Object x)</code>.
1180 *<p>
1181 * @param parameterName the name of the parameter
1182 * @param x the object containing the input parameter value
1183 * @exception SQLException if parameterName does not correspond to a named
1184 * parameter; if a database access error occurs,
1185 * this method is called on a closed <code>CallableStatement</code> or if the given
1186 * <code>Object</code> parameter is ambiguous
1187 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1188 * this method
1189 * @see #getObject
1190 * @since 1.4
1191 */
1192 void setObject(String parameterName, Object x) throws SQLException;
1193
1194
1195 /**
1196 * Sets the designated parameter to the given <code>Reader</code>
1197 * object, which is the given number of characters long.
1198 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1199 * parameter, it may be more practical to send it via a
1200 * <code>java.io.Reader</code> object. The data will be read from the stream
1201 * as needed until end-of-file is reached. The JDBC driver will
1202 * do any necessary conversion from UNICODE to the database char format.
1203 *
1204 * <P><B>Note:</B> This stream object can either be a standard
1205 * Java stream object or your own subclass that implements the
1206 * standard interface.
1207 *
1208 * @param parameterName the name of the parameter
1209 * @param reader the <code>java.io.Reader</code> object that
1210 * contains the UNICODE data used as the designated parameter
1211 * @param length the number of characters in the stream
1212 * @exception SQLException if parameterName does not correspond to a named
1213 * parameter; if a database access error occurs or
1214 * this method is called on a closed <code>CallableStatement</code>
1215 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1216 * this method
1217 * @since 1.4
1218 */
1219 void setCharacterStream(String parameterName,
1220 java.io.Reader reader,
1221 int length) throws SQLException;
1222
1223 /**
1224 * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1225 * using the given <code>Calendar</code> object. The driver uses
1226 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1227 * which the driver then sends to the database. With a
1228 * a <code>Calendar</code> object, the driver can calculate the date
1229 * taking into account a custom timezone. If no
1230 * <code>Calendar</code> object is specified, the driver uses the default
1231 * timezone, which is that of the virtual machine running the application.
1232 *
1233 * @param parameterName the name of the parameter
1234 * @param x the parameter value
1235 * @param cal the <code>Calendar</code> object the driver will use
1236 * to construct the date
1237 * @exception SQLException if parameterName does not correspond to a named
1238 * parameter; if a database access error occurs or
1239 * this method is called on a closed <code>CallableStatement</code>
1240 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1241 * this method
1242 * @see #getDate
1243 * @since 1.4
1244 */
1245 void setDate(String parameterName, java.sql.Date x, Calendar cal)
1246 throws SQLException;
1247
1248 /**
1249 * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1250 * using the given <code>Calendar</code> object. The driver uses
1251 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1252 * which the driver then sends to the database. With a
1253 * a <code>Calendar</code> object, the driver can calculate the time
1254 * taking into account a custom timezone. If no
1255 * <code>Calendar</code> object is specified, the driver uses the default
1256 * timezone, which is that of the virtual machine running the application.
1257 *
1258 * @param parameterName the name of the parameter
1259 * @param x the parameter value
1260 * @param cal the <code>Calendar</code> object the driver will use
1261 * to construct the time
1262 * @exception SQLException if parameterName does not correspond to a named
1263 * parameter; if a database access error occurs or
1264 * this method is called on a closed <code>CallableStatement</code>
1265 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1266 * this method
1267 * @see #getTime
1268 * @since 1.4
1269 */
1270 void setTime(String parameterName, java.sql.Time x, Calendar cal)
1271 throws SQLException;
1272
1273 /**
1274 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1275 * using the given <code>Calendar</code> object. The driver uses
1276 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1277 * which the driver then sends to the database. With a
1278 * a <code>Calendar</code> object, the driver can calculate the timestamp
1279 * taking into account a custom timezone. If no
1280 * <code>Calendar</code> object is specified, the driver uses the default
1281 * timezone, which is that of the virtual machine running the application.
1282 *
1283 * @param parameterName the name of the parameter
1284 * @param x the parameter value
1285 * @param cal the <code>Calendar</code> object the driver will use
1286 * to construct the timestamp
1287 * @exception SQLException if parameterName does not correspond to a named
1288 * parameter; if a database access error occurs or
1289 * this method is called on a closed <code>CallableStatement</code>
1290 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1291 * this method
1292 * @see #getTimestamp
1293 * @since 1.4
1294 */
1295 void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
1296 throws SQLException;
1297
1298 /**
1299 * Sets the designated parameter to SQL <code>NULL</code>.
1300 * This version of the method <code>setNull</code> should
1301 * be used for user-defined types and REF type parameters. Examples
1302 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
1303 * named array types.
1304 *
1305 * <P><B>Note:</B> To be portable, applications must give the
1306 * SQL type code and the fully-qualified SQL type name when specifying
1307 * a NULL user-defined or REF parameter. In the case of a user-defined type
1308 * the name is the type name of the parameter itself. For a REF
1309 * parameter, the name is the type name of the referenced type.
1310 * <p>
1311 * Although it is intended for user-defined and Ref parameters,
1312 * this method may be used to set a null parameter of any JDBC type.
1313 * If the parameter does not have a user-defined or REF type, the given
1314 * typeName is ignored.
1315 *
1316 *
1317 * @param parameterName the name of the parameter
1318 * @param sqlType a value from <code>java.sql.Types</code>
1319 * @param typeName the fully-qualified name of an SQL user-defined type;
1320 * ignored if the parameter is not a user-defined type or
1321 * SQL <code>REF</code> value
1322 * @exception SQLException if parameterName does not correspond to a named
1323 * parameter; if a database access error occurs or
1324 * this method is called on a closed <code>CallableStatement</code>
1325 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1326 * this method
1327 * @since 1.4
1328 */
1329 void setNull (String parameterName, int sqlType, String typeName)
1330 throws SQLException;
1331
1332 /**
1333 * Retrieves the value of a JDBC <code>CHAR</code>, <code>VARCHAR</code>,
1334 * or <code>LONGVARCHAR</code> parameter as a <code>String</code> in
1335 * the Java programming language.
1336 * <p>
1337 * For the fixed-length type JDBC <code>CHAR</code>,
1338 * the <code>String</code> object
1339 * returned has exactly the same value the SQL
1340 * <code>CHAR</code> value had in the
1341 * database, including any padding added by the database.
1342 * @param parameterName the name of the parameter
1343 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1344 * is <code>null</code>.
1345 * @exception SQLException if parameterName does not correspond to a named
1346 * parameter; if a database access error occurs or
1347 * this method is called on a closed <code>CallableStatement</code>
1348 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1349 * this method
1350 * @see #setString
1351 * @since 1.4
1352 */
1353 String getString(String parameterName) throws SQLException;
1354
1355 /**
1356 * Retrieves the value of a JDBC <code>BIT</code> or <code>BOOLEAN</code>
1357 * parameter as a
1358 * <code>boolean</code> in the Java programming language.
1359 * @param parameterName the name of the parameter
1360 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1361 * is <code>false</code>.
1362 * @exception SQLException if parameterName does not correspond to a named
1363 * parameter; if a database access error occurs or
1364 * this method is called on a closed <code>CallableStatement</code>
1365 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1366 * this method
1367 * @see #setBoolean
1368 * @since 1.4
1369 */
1370 boolean getBoolean(String parameterName) throws SQLException;
1371
1372 /**
1373 * Retrieves the value of a JDBC <code>TINYINT</code> parameter as a <code>byte</code>
1374 * in the Java programming language.
1375 * @param parameterName the name of the parameter
1376 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1377 * is <code>0</code>.
1378 * @exception SQLException if parameterName does not correspond to a named
1379 * parameter; if a database access error occurs or
1380 * this method is called on a closed <code>CallableStatement</code>
1381 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1382 * this method
1383 * @see #setByte
1384 * @since 1.4
1385 */
1386 byte getByte(String parameterName) throws SQLException;
1387
1388 /**
1389 * Retrieves the value of a JDBC <code>SMALLINT</code> parameter as a <code>short</code>
1390 * in the Java programming language.
1391 * @param parameterName the name of the parameter
1392 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1393 * is <code>0</code>.
1394 * @exception SQLException if parameterName does not correspond to a named
1395 * parameter; if a database access error occurs or
1396 * this method is called on a closed <code>CallableStatement</code>
1397 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1398 * this method
1399 * @see #setShort
1400 * @since 1.4
1401 */
1402 short getShort(String parameterName) throws SQLException;
1403
1404 /**
1405 * Retrieves the value of a JDBC <code>INTEGER</code> parameter as an <code>int</code>
1406 * in the Java programming language.
1407 *
1408 * @param parameterName the name of the parameter
1409 * @return the parameter value. If the value is SQL <code>NULL</code>,
1410 * the result is <code>0</code>.
1411 * @exception SQLException if parameterName does not correspond to a named
1412 * parameter; if a database access error occurs or
1413 * this method is called on a closed <code>CallableStatement</code>
1414 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1415 * this method
1416 * @see #setInt
1417 * @since 1.4
1418 */
1419 int getInt(String parameterName) throws SQLException;
1420
1421 /**
1422 * Retrieves the value of a JDBC <code>BIGINT</code> parameter as a <code>long</code>
1423 * in the Java programming language.
1424 *
1425 * @param parameterName the name of the parameter
1426 * @return the parameter value. If the value is SQL <code>NULL</code>,
1427 * the result is <code>0</code>.
1428 * @exception SQLException if parameterName does not correspond to a named
1429 * parameter; if a database access error occurs or
1430 * this method is called on a closed <code>CallableStatement</code>
1431 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1432 * this method
1433 * @see #setLong
1434 * @since 1.4
1435 */
1436 long getLong(String parameterName) throws SQLException;
1437
1438 /**
1439 * Retrieves the value of a JDBC <code>FLOAT</code> parameter as a <code>float</code>
1440 * in the Java programming language.
1441 * @param parameterName the name of the parameter
1442 * @return the parameter value. If the value is SQL <code>NULL</code>,
1443 * the result is <code>0</code>.
1444 * @exception SQLException if parameterName does not correspond to a named
1445 * parameter; if a database access error occurs or
1446 * this method is called on a closed <code>CallableStatement</code>
1447 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1448 * this method
1449 * @see #setFloat
1450 * @since 1.4
1451 */
1452 float getFloat(String parameterName) throws SQLException;
1453
1454 /**
1455 * Retrieves the value of a JDBC <code>DOUBLE</code> parameter as a <code>double</code>
1456 * in the Java programming language.
1457 * @param parameterName the name of the parameter
1458 * @return the parameter value. If the value is SQL <code>NULL</code>,
1459 * the result is <code>0</code>.
1460 * @exception SQLException if parameterName does not correspond to a named
1461 * parameter; if a database access error occurs or
1462 * this method is called on a closed <code>CallableStatement</code>
1463 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1464 * this method
1465 * @see #setDouble
1466 * @since 1.4
1467 */
1468 double getDouble(String parameterName) throws SQLException;
1469
1470 /**
1471 * Retrieves the value of a JDBC <code>BINARY</code> or <code>VARBINARY</code>
1472 * parameter as an array of <code>byte</code> values in the Java
1473 * programming language.
1474 * @param parameterName the name of the parameter
1475 * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1476 * <code>null</code>.
1477 * @exception SQLException if parameterName does not correspond to a named
1478 * parameter; if a database access error occurs or
1479 * this method is called on a closed <code>CallableStatement</code>
1480 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1481 * this method
1482 * @see #setBytes
1483 * @since 1.4
1484 */
1485 byte[] getBytes(String parameterName) throws SQLException;
1486
1487 /**
1488 * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1489 * <code>java.sql.Date</code> object.
1490 * @param parameterName the name of the parameter
1491 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1492 * is <code>null</code>.
1493 * @exception SQLException if parameterName does not correspond to a named
1494 * parameter; if a database access error occurs or
1495 * this method is called on a closed <code>CallableStatement</code>
1496 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1497 * this method
1498 * @see #setDate
1499 * @since 1.4
1500 */
1501 java.sql.Date getDate(String parameterName) throws SQLException;
1502
1503 /**
1504 * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1505 * <code>java.sql.Time</code> object.
1506 * @param parameterName the name of the parameter
1507 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1508 * is <code>null</code>.
1509 * @exception SQLException if parameterName does not correspond to a named
1510 * parameter; if a database access error occurs or
1511 * this method is called on a closed <code>CallableStatement</code>
1512 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1513 * this method
1514 * @see #setTime
1515 * @since 1.4
1516 */
1517 java.sql.Time getTime(String parameterName) throws SQLException;
1518
1519 /**
1520 * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1521 * <code>java.sql.Timestamp</code> object.
1522 * @param parameterName the name of the parameter
1523 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1524 * is <code>null</code>.
1525 * @exception SQLException if parameterName does not correspond to a named
1526 * parameter; if a database access error occurs or
1527 * this method is called on a closed <code>CallableStatement</code>
1528 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1529 * this method
1530 * @see #setTimestamp
1531 * @since 1.4
1532 */
1533 java.sql.Timestamp getTimestamp(String parameterName) throws SQLException;
1534
1535 /**
1536 * Retrieves the value of a parameter as an <code>Object</code> in the Java
1537 * programming language. If the value is an SQL <code>NULL</code>, the
1538 * driver returns a Java <code>null</code>.
1539 * <p>
1540 * This method returns a Java object whose type corresponds to the JDBC
1541 * type that was registered for this parameter using the method
1542 * <code>registerOutParameter</code>. By registering the target JDBC
1543 * type as <code>java.sql.Types.OTHER</code>, this method can be used
1544 * to read database-specific abstract data types.
1545 * @param parameterName the name of the parameter
1546 * @return A <code>java.lang.Object</code> holding the OUT parameter value.
1547 * @exception SQLException if parameterName does not correspond to a named
1548 * parameter; if a database access error occurs or
1549 * this method is called on a closed <code>CallableStatement</code>
1550 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1551 * this method
1552 * @see Types
1553 * @see #setObject
1554 * @since 1.4
1555 */
1556 Object getObject(String parameterName) throws SQLException;
1557
1558 /**
1559 * Retrieves the value of a JDBC <code>NUMERIC</code> parameter as a
1560 * <code>java.math.BigDecimal</code> object with as many digits to the
1561 * right of the decimal point as the value contains.
1562 * @param parameterName the name of the parameter
1563 * @return the parameter value in full precision. If the value is
1564 * SQL <code>NULL</code>, the result is <code>null</code>.
1565 * @exception SQLExceptionif parameterName does not correspond to a named
1566 * parameter; if a database access error occurs or
1567 * this method is called on a closed <code>CallableStatement</code>
1568 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1569 * this method
1570 * @see #setBigDecimal
1571 * @since 1.4
1572 */
1573 BigDecimal getBigDecimal(String parameterName) throws SQLException;
1574
1575 /**
1576 * Returns an object representing the value of OUT parameter
1577 * <code>parameterName</code> and uses <code>map</code> for the custom
1578 * mapping of the parameter value.
1579 * <p>
1580 * This method returns a Java object whose type corresponds to the
1581 * JDBC type that was registered for this parameter using the method
1582 * <code>registerOutParameter</code>. By registering the target
1583 * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
1584 * be used to read database-specific abstract data types.
1585 * @param parameterName the name of the parameter
1586 * @param map the mapping from SQL type names to Java classes
1587 * @return a <code>java.lang.Object</code> holding the OUT parameter value
1588 * @exception SQLException if parameterName does not correspond to a named
1589 * parameter; if a database access error occurs or
1590 * this method is called on a closed <code>CallableStatement</code>
1591 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1592 * this method
1593 * @see #setObject
1594 * @since 1.4
1595 */
1596 Object getObject(String parameterName, java.util.Map<String,Class<?>> map)
1597 throws SQLException;
1598
1599 /**
1600 * Retrieves the value of a JDBC <code>REF(<structured-type>)</code>
1601 * parameter as a {@link java.sql.Ref} object in the Java programming language.
1602 *
1603 * @param parameterName the name of the parameter
1604 * @return the parameter value as a <code>Ref</code> object in the
1605 * Java programming language. If the value was SQL <code>NULL</code>,
1606 * the value <code>null</code> is returned.
1607 * @exception SQLException if parameterName does not correspond to a named
1608 * parameter; if a database access error occurs or
1609 * this method is called on a closed <code>CallableStatement</code>
1610 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1611 * this method
1612 * @since 1.4
1613 */
1614 Ref getRef (String parameterName) throws SQLException;
1615
1616 /**
1617 * Retrieves the value of a JDBC <code>BLOB</code> parameter as a
1618 * {@link java.sql.Blob} object in the Java programming language.
1619 *
1620 * @param parameterName the name of the parameter
1621 * @return the parameter value as a <code>Blob</code> object in the
1622 * Java programming language. If the value was SQL <code>NULL</code>,
1623 * the value <code>null</code> is returned.
1624 * @exception SQLException if parameterName does not correspond to a named
1625 * parameter; if a database access error occurs or
1626 * this method is called on a closed <code>CallableStatement</code>
1627 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1628 * this method
1629 * @since 1.4
1630 */
1631 Blob getBlob (String parameterName) throws SQLException;
1632
1633 /**
1634 * Retrieves the value of a JDBC <code>CLOB</code> parameter as a
1635 * <code>java.sql.Clob</code> object in the Java programming language.
1636 * @param parameterName the name of the parameter
1637 * @return the parameter value as a <code>Clob</code> object in the
1638 * Java programming language. If the value was SQL <code>NULL</code>,
1639 * the value <code>null</code> is returned.
1640 * @exception SQLException if parameterName does not correspond to a named
1641 * parameter; if a database access error occurs or
1642 * this method is called on a closed <code>CallableStatement</code>
1643 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1644 * this method
1645 * @since 1.4
1646 */
1647 Clob getClob (String parameterName) throws SQLException;
1648
1649 /**
1650 * Retrieves the value of a JDBC <code>ARRAY</code> parameter as an
1651 * {@link java.sql.Array} object in the Java programming language.
1652 *
1653 * @param parameterName the name of the parameter
1654 * @return the parameter value as an <code>Array</code> object in
1655 * Java programming language. If the value was SQL <code>NULL</code>,
1656 * the value <code>null</code> is returned.
1657 * @exception SQLException if parameterName does not correspond to a named
1658 * parameter; if a database access error occurs or
1659 * this method is called on a closed <code>CallableStatement</code>
1660 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1661 * this method
1662 * @since 1.4
1663 */
1664 Array getArray (String parameterName) throws SQLException;
1665
1666 /**
1667 * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1668 * <code>java.sql.Date</code> object, using
1669 * the given <code>Calendar</code> object
1670 * to construct the date.
1671 * With a <code>Calendar</code> object, the driver
1672 * can calculate the date taking into account a custom timezone and locale.
1673 * If no <code>Calendar</code> object is specified, the driver uses the
1674 * default timezone and locale.
1675 *
1676 * @param parameterName the name of the parameter
1677 * @param cal the <code>Calendar</code> object the driver will use
1678 * to construct the date
1679 * @return the parameter value. If the value is SQL <code>NULL</code>,
1680 * the result is <code>null</code>.
1681 * @exception SQLException if parameterName does not correspond to a named
1682 * parameter; if a database access error occurs or
1683 * this method is called on a closed <code>CallableStatement</code>
1684 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1685 * this method
1686 * @see #setDate
1687 * @since 1.4
1688 */
1689 java.sql.Date getDate(String parameterName, Calendar cal)
1690 throws SQLException;
1691
1692 /**
1693 * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1694 * <code>java.sql.Time</code> object, using
1695 * the given <code>Calendar</code> object
1696 * to construct the time.
1697 * With a <code>Calendar</code> object, the driver
1698 * can calculate the time taking into account a custom timezone and locale.
1699 * If no <code>Calendar</code> object is specified, the driver uses the
1700 * default timezone and locale.
1701 *
1702 * @param parameterName the name of the parameter
1703 * @param cal the <code>Calendar</code> object the driver will use
1704 * to construct the time
1705 * @return the parameter value; if the value is SQL <code>NULL</code>, the result is
1706 * <code>null</code>.
1707 * @exception SQLException if parameterName does not correspond to a named
1708 * parameter; if a database access error occurs or
1709 * this method is called on a closed <code>CallableStatement</code>
1710 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1711 * this method
1712 * @see #setTime
1713 * @since 1.4
1714 */
1715 java.sql.Time getTime(String parameterName, Calendar cal)
1716 throws SQLException;
1717
1718 /**
1719 * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1720 * <code>java.sql.Timestamp</code> object, using
1721 * the given <code>Calendar</code> object to construct
1722 * the <code>Timestamp</code> object.
1723 * With a <code>Calendar</code> object, the driver
1724 * can calculate the timestamp taking into account a custom timezone and locale.
1725 * If no <code>Calendar</code> object is specified, the driver uses the
1726 * default timezone and locale.
1727 *
1728 *
1729 * @param parameterName the name of the parameter
1730 * @param cal the <code>Calendar</code> object the driver will use
1731 * to construct the timestamp
1732 * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1733 * <code>null</code>.
1734 * @exception SQLException if parameterName does not correspond to a named
1735 * parameter; if a database access error occurs or
1736 * this method is called on a closed <code>CallableStatement</code>
1737 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1738 * this method
1739 * @see #setTimestamp
1740 * @since 1.4
1741 */
1742 java.sql.Timestamp getTimestamp(String parameterName, Calendar cal)
1743 throws SQLException;
1744
1745 /**
1746 * Retrieves the value of a JDBC <code>DATALINK</code> parameter as a
1747 * <code>java.net.URL</code> object.
1748 *
1749 * @param parameterName the name of the parameter
1750 * @return the parameter value as a <code>java.net.URL</code> object in the
1751 * Java programming language. If the value was SQL <code>NULL</code>, the
1752 * value <code>null</code> is returned.
1753 * @exception SQLException if parameterName does not correspond to a named
1754 * parameter; if a database access error occurs,
1755 * this method is called on a closed <code>CallableStatement</code>,
1756 * or if there is a problem with the URL
1757 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1758 * this method
1759 * @see #setURL
1760 * @since 1.4
1761 */
1762 java.net.URL getURL(String parameterName) throws SQLException;
1763
1764 //------------------------- JDBC 4.0 -----------------------------------
1765
1766 /**
1767 * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1768 * <code>java.sql.RowId</code> object.
1769 *
1770 * @param parameterIndex the first parameter is 1, the second is 2,...
1771 * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1772 * value is used as the designated parameter. If the parameter contains
1773 * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1774 * @throws SQLException if the parameterIndex is not valid;
1775 * if a database access error occurs or
1776 * this method is called on a closed <code>CallableStatement</code>
1777 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1778 * this method
1779 * @since 1.6
1780 */
1781 RowId getRowId(int parameterIndex) throws SQLException;
1782
1783 /**
1784 * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1785 * <code>java.sql.RowId</code> object.
1786 *
1787 * @param parameterName the name of the parameter
1788 * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1789 * value is used as the designated parameter. If the parameter contains
1790 * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1791 * @throws SQLException if parameterName does not correspond to a named
1792 * parameter; if a database access error occurs or
1793 * this method is called on a closed <code>CallableStatement</code>
1794 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1795 * this method
1796 * @since 1.6
1797 */
1798 RowId getRowId(String parameterName) throws SQLException;
1799
1800 /**
1801 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1802 * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1803 * database.
1804 *
1805 * @param parameterName the name of the parameter
1806 * @param x the parameter value
1807 * @throws SQLException if parameterName does not correspond to a named
1808 * parameter; if a database access error occurs or
1809 * this method is called on a closed <code>CallableStatement</code>
1810 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1811 * this method
1812 * @since 1.6
1813 */
1814 void setRowId(String parameterName, RowId x) throws SQLException;
1815
1816 /**
1817 * Sets the designated parameter to the given <code>String</code> object.
1818 * The driver converts this to a SQL <code>NCHAR</code> or
1819 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1820 * @param parameterName the name of the parameter to be set
1821 * @param value the parameter value
1822 * @throws SQLException if parameterName does not correspond to a named
1823 * parameter; if the driver does not support national
1824 * character sets; if the driver can detect that a data conversion
1825 * error could occur; if a database access error occurs or
1826 * this method is called on a closed <code>CallableStatement</code>
1827 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1828 * this method
1829 * @since 1.6
1830 */
1831 void setNString(String parameterName, String value)
1832 throws SQLException;
1833
1834 /**
1835 * Sets the designated parameter to a <code>Reader</code> object. The
1836 * <code>Reader</code> reads the data till end-of-file is reached. The
1837 * driver does the necessary conversion from Java character format to
1838 * the national character set in the database.
1839 * @param parameterName the name of the parameter to be set
1840 * @param value the parameter value
1841 * @param length the number of characters in the parameter data.
1842 * @throws SQLException if parameterName does not correspond to a named
1843 * parameter; if the driver does not support national
1844 * character sets; if the driver can detect that a data conversion
1845 * error could occur; if a database access error occurs or
1846 * this method is called on a closed <code>CallableStatement</code>
1847 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1848 * this method
1849 * @since 1.6
1850 */
1851 void setNCharacterStream(String parameterName, Reader value, long length)
1852 throws SQLException;
1853
1854 /**
1855 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
1856 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
1857 * object maps to a SQL <code>NCLOB</code>.
1858 * @param parameterName the name of the parameter to be set
1859 * @param value the parameter value
1860 * @throws SQLException if parameterName does not correspond to a named
1861 * parameter; if the driver does not support national
1862 * character sets; if the driver can detect that a data conversion
1863 * error could occur; if a database access error occurs or
1864 * this method is called on a closed <code>CallableStatement</code>
1865 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1866 * this method
1867 * @since 1.6
1868 */
1869 void setNClob(String parameterName, NClob value) throws SQLException;
1870
1871 /**
1872 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1873 * of characters specified by length otherwise a <code>SQLException</code> will be
1874 * generated when the <code>CallableStatement</code> is executed.
1875 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1876 * because it informs the driver that the parameter value should be sent to
1877 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1878 * driver may have to do extra work to determine whether the parameter
1879 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1880 * @param parameterName the name of the parameter to be set
1881 * @param reader An object that contains the data to set the parameter value to.
1882 * @param length the number of characters in the parameter data.
1883 * @throws SQLException if parameterName does not correspond to a named
1884 * parameter; if the length specified is less than zero;
1885 * a database access error occurs or
1886 * this method is called on a closed <code>CallableStatement</code>
1887 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1888 * this method
1889 *
1890 * @since 1.6
1891 */
1892 void setClob(String parameterName, Reader reader, long length)
1893 throws SQLException;
1894
1895 /**
1896 * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number
1897 * of characters specified by length, otherwise a <code>SQLException</code> will be
1898 * generated when the <code>CallableStatement</code> is executed.
1899 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1900 * method because it informs the driver that the parameter value should be
1901 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1902 * the driver may have to do extra work to determine whether the parameter
1903 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1904 *
1905 * @param parameterName the name of the parameter to be set
1906 * the second is 2, ...
1907 *
1908 * @param inputStream An object that contains the data to set the parameter
1909 * value to.
1910 * @param length the number of bytes in the parameter data.
1911 * @throws SQLException if parameterName does not correspond to a named
1912 * parameter; if the length specified
1913 * is less than zero; if the number of bytes in the inputstream does not match
1914 * the specfied length; if a database access error occurs or
1915 * this method is called on a closed <code>CallableStatement</code>
1916 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1917 * this method
1918 *
1919 * @since 1.6
1920 */
1921 void setBlob(String parameterName, InputStream inputStream, long length)
1922 throws SQLException;
1923 /**
1924 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1925 * of characters specified by length otherwise a <code>SQLException</code> will be
1926 * generated when the <code>CallableStatement</code> is executed.
1927 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1928 * because it informs the driver that the parameter value should be sent to
1929 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream&
Save This Page