1 /*
2 * Copyright (c) 1996, 2010, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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 @Deprecated
299 BigDecimal getBigDecimal(int parameterIndex, int scale)
300 throws SQLException;
301
302 /**
303 * Retrieves the value of the designated JDBC <code>BINARY</code> or
304 * <code>VARBINARY</code> parameter as an array of <code>byte</code>
305 * values in the Java programming language.
306 * @param parameterIndex the first parameter is 1, the second is 2,
307 * and so on
308 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
309 * is <code>null</code>.
310 * @exception SQLException if the parameterIndex is not valid;
311 * if a database access error occurs or
312 * this method is called on a closed <code>CallableStatement</code>
313 * @see #setBytes
314 */
315 byte[] getBytes(int parameterIndex) throws SQLException;
316
317 /**
318 * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
319 * <code>java.sql.Date</code> object.
320 * @param parameterIndex the first parameter is 1, the second is 2,
321 * and so on
322 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
323 * is <code>null</code>.
324 * @exception SQLException if the parameterIndex is not valid;
325 * if a database access error occurs or
326 * this method is called on a closed <code>CallableStatement</code>
327 * @see #setDate
328 */
329 java.sql.Date getDate(int parameterIndex) throws SQLException;
330
331 /**
332 * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
333 * <code>java.sql.Time</code> object.
334 *
335 * @param parameterIndex the first parameter is 1, the second is 2,
336 * and so on
337 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
338 * is <code>null</code>.
339 * @exception SQLException if the parameterIndex is not valid;
340 * if a database access error occurs or
341 * this method is called on a closed <code>CallableStatement</code>
342 * @see #setTime
343 */
344 java.sql.Time getTime(int parameterIndex) throws SQLException;
345
346 /**
347 * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
348 * <code>java.sql.Timestamp</code> object.
349 *
350 * @param parameterIndex the first parameter is 1, the second is 2,
351 * and so on
352 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
353 * is <code>null</code>.
354 * @exception SQLException if the parameterIndex is not valid;
355 * if a database access error occurs or
356 * this method is called on a closed <code>CallableStatement</code>
357 * @see #setTimestamp
358 */
359 java.sql.Timestamp getTimestamp(int parameterIndex)
360 throws SQLException;
361
362 //----------------------------------------------------------------------
363 // Advanced features:
364
365
366 /**
367 * Retrieves the value of the designated parameter as an <code>Object</code>
368 * in the Java programming language. If the value is an SQL <code>NULL</code>,
369 * the driver returns a Java <code>null</code>.
370 * <p>
371 * This method returns a Java object whose type corresponds to the JDBC
372 * type that was registered for this parameter using the method
373 * <code>registerOutParameter</code>. By registering the target JDBC
374 * type as <code>java.sql.Types.OTHER</code>, this method can be used
375 * to read database-specific abstract data types.
376 *
377 * @param parameterIndex the first parameter is 1, the second is 2,
378 * and so on
379 * @return A <code>java.lang.Object</code> holding the OUT parameter value
380 * @exception SQLException if the parameterIndex is not valid;
381 * if a database access error occurs or
382 * this method is called on a closed <code>CallableStatement</code>
383 * @see Types
384 * @see #setObject
385 */
386 Object getObject(int parameterIndex) throws SQLException;
387
388
389 //--------------------------JDBC 2.0-----------------------------
390
391 /**
392 * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
393 * <code>java.math.BigDecimal</code> object with as many digits to the
394 * right of the decimal point as the value contains.
395 * @param parameterIndex the first parameter is 1, the second is 2,
396 * and so on
397 * @return the parameter value in full precision. If the value is
398 * SQL <code>NULL</code>, the result is <code>null</code>.
399 * @exception SQLException if the parameterIndex is not valid;
400 * if a database access error occurs or
401 * this method is called on a closed <code>CallableStatement</code>
402 * @see #setBigDecimal
403 * @since 1.2
404 */
405 BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
406
407 /**
408 * Returns an object representing the value of OUT parameter
409 * <code>parameterIndex</code> and uses <code>map</code> for the custom
410 * mapping of the parameter value.
411 * <p>
412 * This method returns a Java object whose type corresponds to the
413 * JDBC type that was registered for this parameter using the method
414 * <code>registerOutParameter</code>. By registering the target
415 * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
416 * be used to read database-specific abstract data types.
417 * @param parameterIndex the first parameter is 1, the second is 2, and so on
418 * @param map the mapping from SQL type names to Java classes
419 * @return a <code>java.lang.Object</code> holding the OUT parameter value
420 * @exception SQLException if the parameterIndex is not valid;
421 * if a database access error occurs or
422 * this method is called on a closed <code>CallableStatement</code>
423 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
424 * this method
425 * @see #setObject
426 * @since 1.2
427 */
428 Object getObject(int parameterIndex, java.util.Map<String,Class<?>> map)
429 throws SQLException;
430
431 /**
432 * Retrieves the value of the designated JDBC <code>REF(<structured-type>)</code>
433 * parameter as a {@link java.sql.Ref} object in the Java programming language.
434 * @param parameterIndex the first parameter is 1, the second is 2,
435 * and so on
436 * @return the parameter value as a <code>Ref</code> object in the
437 * Java programming language. If the value was SQL <code>NULL</code>, the value
438 * <code>null</code> is returned.
439 * @exception SQLException if the parameterIndex is not valid;
440 * if a database access error occurs or
441 * this method is called on a closed <code>CallableStatement</code>
442 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
443 * this method
444 * @since 1.2
445 */
446 Ref getRef (int parameterIndex) throws SQLException;
447
448 /**
449 * Retrieves the value of the designated JDBC <code>BLOB</code> parameter as a
450 * {@link java.sql.Blob} object in the Java programming language.
451 * @param parameterIndex the first parameter is 1, the second is 2, and so on
452 * @return the parameter value as a <code>Blob</code> object in the
453 * Java programming language. If the value was SQL <code>NULL</code>, the value
454 * <code>null</code> is returned.
455 * @exception SQLException if the parameterIndex is not valid;
456 * if a database access error occurs or
457 * this method is called on a closed <code>CallableStatement</code>
458 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
459 * this method
460 * @since 1.2
461 */
462 Blob getBlob (int parameterIndex) throws SQLException;
463
464 /**
465 * Retrieves the value of the designated JDBC <code>CLOB</code> parameter as a
466 * <code>java.sql.Clob</code> object in the Java programming language.
467 * @param parameterIndex the first parameter is 1, the second is 2, and
468 * so on
469 * @return the parameter value as a <code>Clob</code> object in the
470 * Java programming language. If the value was SQL <code>NULL</code>, the
471 * value <code>null</code> is returned.
472 * @exception SQLException if the parameterIndex is not valid;
473 * if a database access error occurs or
474 * this method is called on a closed <code>CallableStatement</code>
475 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
476 * this method
477 * @since 1.2
478 */
479 Clob getClob (int parameterIndex) throws SQLException;
480
481 /**
482 *
483 * Retrieves the value of the designated JDBC <code>ARRAY</code> parameter as an
484 * {@link java.sql.Array} object in the Java programming language.
485 * @param parameterIndex the first parameter is 1, the second is 2, and
486 * so on
487 * @return the parameter value as an <code>Array</code> object in
488 * the Java programming language. If the value was SQL <code>NULL</code>, the
489 * value <code>null</code> is returned.
490 * @exception SQLException if the parameterIndex is not valid;
491 * if a database access error occurs or
492 * this method is called on a closed <code>CallableStatement</code>
493 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
494 * this method
495 * @since 1.2
496 */
497 Array getArray (int parameterIndex) throws SQLException;
498
499 /**
500 * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
501 * <code>java.sql.Date</code> object, using
502 * the given <code>Calendar</code> object
503 * to construct the date.
504 * With a <code>Calendar</code> object, the driver
505 * can calculate the date taking into account a custom timezone and locale.
506 * If no <code>Calendar</code> object is specified, the driver uses the
507 * default timezone and locale.
508 *
509 * @param parameterIndex the first parameter is 1, the second is 2,
510 * and so on
511 * @param cal the <code>Calendar</code> object the driver will use
512 * to construct the date
513 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
514 * is <code>null</code>.
515 * @exception SQLException if the parameterIndex is not valid;
516 * if a database access error occurs or
517 * this method is called on a closed <code>CallableStatement</code>
518 * @see #setDate
519 * @since 1.2
520 */
521 java.sql.Date getDate(int parameterIndex, Calendar cal)
522 throws SQLException;
523
524 /**
525 * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
526 * <code>java.sql.Time</code> object, using
527 * the given <code>Calendar</code> object
528 * to construct the time.
529 * With a <code>Calendar</code> object, the driver
530 * can calculate the time taking into account a custom timezone and locale.
531 * If no <code>Calendar</code> object is specified, the driver uses the
532 * default timezone and locale.
533 *
534 * @param parameterIndex the first parameter is 1, the second is 2,
535 * and so on
536 * @param cal the <code>Calendar</code> object the driver will use
537 * to construct the time
538 * @return the parameter value; if the value is SQL <code>NULL</code>, the result
539 * is <code>null</code>.
540 * @exception SQLException if the parameterIndex is not valid;
541 * if a database access error occurs or
542 * this method is called on a closed <code>CallableStatement</code>
543 * @see #setTime
544 * @since 1.2
545 */
546 java.sql.Time getTime(int parameterIndex, Calendar cal)
547 throws SQLException;
548
549 /**
550 * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
551 * <code>java.sql.Timestamp</code> object, using
552 * the given <code>Calendar</code> object to construct
553 * the <code>Timestamp</code> object.
554 * With a <code>Calendar</code> object, the driver
555 * can calculate the timestamp taking into account a custom timezone and locale.
556 * If no <code>Calendar</code> object is specified, the driver uses the
557 * default timezone and locale.
558 *
559 *
560 * @param parameterIndex the first parameter is 1, the second is 2,
561 * and so on
562 * @param cal the <code>Calendar</code> object the driver will use
563 * to construct the timestamp
564 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
565 * is <code>null</code>.
566 * @exception SQLException if the parameterIndex is not valid;
567 * if a database access error occurs or
568 * this method is called on a closed <code>CallableStatement</code>
569 * @see #setTimestamp
570 * @since 1.2
571 */
572 java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal)
573 throws SQLException;
574
575
576 /**
577 * Registers the designated output parameter.
578 * This version of
579 * the method <code>registerOutParameter</code>
580 * should be used for a user-defined or <code>REF</code> output parameter. Examples
581 * of user-defined types include: <code>STRUCT</code>, <code>DISTINCT</code>,
582 * <code>JAVA_OBJECT</code>, and named array types.
583 *<p>
584 * All OUT parameters must be registered
585 * before a stored procedure is executed.
586 * <p> For a user-defined parameter, the fully-qualified SQL
587 * type name of the parameter should also be given, while a <code>REF</code>
588 * parameter requires that the fully-qualified type name of the
589 * referenced type be given. A JDBC driver that does not need the
590 * type code and type name information may ignore it. To be portable,
591 * however, applications should always provide these values for
592 * user-defined and <code>REF</code> parameters.
593 *
594 * Although it is intended for user-defined and <code>REF</code> parameters,
595 * this method may be used to register a parameter of any JDBC type.
596 * If the parameter does not have a user-defined or <code>REF</code> type, the
597 * <i>typeName</i> parameter is ignored.
598 *
599 * <P><B>Note:</B> When reading the value of an out parameter, you
600 * must use the getter method whose Java type corresponds to the
601 * parameter's registered SQL type.
602 *
603 * @param parameterIndex the first parameter is 1, the second is 2,...
604 * @param sqlType a value from {@link java.sql.Types}
605 * @param typeName the fully-qualified name of an SQL structured type
606 * @exception SQLException if the parameterIndex is not valid;
607 * if a database access error occurs or
608 * this method is called on a closed <code>CallableStatement</code>
609 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
610 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
611 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
612 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
613 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
614 * or <code>STRUCT</code> data type and the JDBC driver does not support
615 * this data type
616 * @see Types
617 * @since 1.2
618 */
619 void registerOutParameter (int parameterIndex, int sqlType, String typeName)
620 throws SQLException;
621
622 //--------------------------JDBC 3.0-----------------------------
623
624 /**
625 * Registers the OUT parameter named
626 * <code>parameterName</code> to the JDBC type
627 * <code>sqlType</code>. All OUT parameters must be registered
628 * before a stored procedure is executed.
629 * <p>
630 * The JDBC type specified by <code>sqlType</code> for an OUT
631 * parameter determines the Java type that must be used
632 * in the <code>get</code> method to read the value of that parameter.
633 * <p>
634 * If the JDBC type expected to be returned to this output parameter
635 * is specific to this particular database, <code>sqlType</code>
636 * should be <code>java.sql.Types.OTHER</code>. The method
637 * {@link #getObject} retrieves the value.
638 * @param parameterName the name of the parameter
639 * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
640 * If the parameter is of JDBC type <code>NUMERIC</code>
641 * or <code>DECIMAL</code>, the version of
642 * <code>registerOutParameter</code> that accepts a scale value
643 * should be used.
644 * @exception SQLException if parameterName does not correspond to a named
645 * parameter; if a database access error occurs or
646 * this method is called on a closed <code>CallableStatement</code>
647 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
648 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
649 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
650 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
651 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
652 * or <code>STRUCT</code> data type and the JDBC driver does not support
653 * this data type or if the JDBC driver does not support
654 * this method
655 * @since 1.4
656 * @see Types
657 */
658 void registerOutParameter(String parameterName, int sqlType)
659 throws SQLException;
660
661 /**
662 * Registers the parameter named
663 * <code>parameterName</code> to be of JDBC type
664 * <code>sqlType</code>. All OUT parameters must be registered
665 * before a stored procedure is executed.
666 * <p>
667 * The JDBC type specified by <code>sqlType</code> for an OUT
668 * parameter determines the Java type that must be used
669 * in the <code>get</code> method to read the value of that parameter.
670 * <p>
671 * This version of <code>registerOutParameter</code> should be
672 * used when the parameter is of JDBC type <code>NUMERIC</code>
673 * or <code>DECIMAL</code>.
674 *
675 * @param parameterName the name of the parameter
676 * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
677 * @param scale the desired number of digits to the right of the
678 * decimal point. It must be greater than or equal to zero.
679 * @exception SQLException if parameterName does not correspond to a named
680 * parameter; if a database access error occurs or
681 * this method is called on a closed <code>CallableStatement</code>
682 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
683 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
684 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
685 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
686 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
687 * or <code>STRUCT</code> data type and the JDBC driver does not support
688 * this data type or if the JDBC driver does not support
689 * this method
690 * @since 1.4
691 * @see Types
692 */
693 void registerOutParameter(String parameterName, int sqlType, int scale)
694 throws SQLException;
695
696 /**
697 * Registers the designated output parameter. This version of
698 * the method <code>registerOutParameter</code>
699 * should be used for a user-named or REF output parameter. Examples
700 * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
701 * named array types.
702 *<p>
703 * All OUT parameters must be registered
704 * before a stored procedure is executed.
705 * <p>
706 * For a user-named parameter the fully-qualified SQL
707 * type name of the parameter should also be given, while a REF
708 * parameter requires that the fully-qualified type name of the
709 * referenced type be given. A JDBC driver that does not need the
710 * type code and type name information may ignore it. To be portable,
711 * however, applications should always provide these values for
712 * user-named and REF parameters.
713 *
714 * Although it is intended for user-named and REF parameters,
715 * this method may be used to register a parameter of any JDBC type.
716 * If the parameter does not have a user-named or REF type, the
717 * typeName parameter is ignored.
718 *
719 * <P><B>Note:</B> When reading the value of an out parameter, you
720 * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
721 * parameter's registered SQL type.
722 *
723 * @param parameterName the name of the parameter
724 * @param sqlType a value from {@link java.sql.Types}
725 * @param typeName the fully-qualified name of an SQL structured type
726 * @exception SQLException if parameterName does not correspond to a named
727 * parameter; if a database access error occurs or
728 * this method is called on a closed <code>CallableStatement</code>
729 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
730 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
731 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
732 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
733 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
734 * or <code>STRUCT</code> data type and the JDBC driver does not support
735 * this data type or if the JDBC driver does not support
736 * this method
737 * @see Types
738 * @since 1.4
739 */
740 void registerOutParameter (String parameterName, int sqlType, String typeName)
741 throws SQLException;
742
743 /**
744 * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
745 * <code>java.net.URL</code> object.
746 *
747 * @param parameterIndex the first parameter is 1, the second is 2,...
748 * @return a <code>java.net.URL</code> object that represents the
749 * JDBC <code>DATALINK</code> value used as the designated
750 * parameter
751 * @exception SQLException if the parameterIndex is not valid;
752 * if a database access error occurs,
753 * this method is called on a closed <code>CallableStatement</code>,
754 * or if the URL being returned is
755 * not a valid URL on the Java platform
756 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
757 * this method
758 * @see #setURL
759 * @since 1.4
760 */
761 java.net.URL getURL(int parameterIndex) throws SQLException;
762
763 /**
764 * Sets the designated parameter to the given <code>java.net.URL</code> object.
765 * The driver converts this to an SQL <code>DATALINK</code> value when
766 * it sends it to the database.
767 *
768 * @param parameterName the name of the parameter
769 * @param val the parameter value
770 * @exception SQLException if parameterName does not correspond to a named
771 * parameter; if a database access error occurs;
772 * this method is called on a closed <code>CallableStatement</code>
773 * or if a URL is malformed
774 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
775 * this method
776 * @see #getURL
777 * @since 1.4
778 */
779 void setURL(String parameterName, java.net.URL val) throws SQLException;
780
781 /**
782 * Sets the designated parameter to SQL <code>NULL</code>.
783 *
784 * <P><B>Note:</B> You must specify the parameter's SQL type.
785 *
786 * @param parameterName the name of the parameter
787 * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
788 * @exception SQLException if parameterName does not correspond to a named
789 * parameter; if a database access error occurs or
790 * this method is called on a closed <code>CallableStatement</code>
791 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
792 * this method
793 * @since 1.4
794 */
795 void setNull(String parameterName, int sqlType) throws SQLException;
796
797 /**
798 * Sets the designated parameter to the given Java <code>boolean</code> value.
799 * The driver converts this
800 * to an SQL <code>BIT</code> or <code>BOOLEAN</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 parameterName does not correspond to a named
805 * parameter; if a database access error occurs or
806 * this method is called on a closed <code>CallableStatement</code>
807 * @see #getBoolean
808 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
809 * this method
810 * @since 1.4
811 */
812 void setBoolean(String parameterName, boolean x) throws SQLException;
813
814 /**
815 * Sets the designated parameter to the given Java <code>byte</code> value.
816 * The driver converts this
817 * to an SQL <code>TINYINT</code> value when it sends it to the database.
818 *
819 * @param parameterName the name of the parameter
820 * @param x the parameter value
821 * @exception SQLException if parameterName does not correspond to a named
822 * parameter; if a database access error occurs or
823 * this method is called on a closed <code>CallableStatement</code>
824 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
825 * this method
826 * @see #getByte
827 * @since 1.4
828 */
829 void setByte(String parameterName, byte x) throws SQLException;
830
831 /**
832 * Sets the designated parameter to the given Java <code>short</code> value.
833 * The driver converts this
834 * to an SQL <code>SMALLINT</code> value when it sends it to the database.
835 *
836 * @param parameterName the name of the parameter
837 * @param x the parameter value
838 * @exception SQLException if parameterName does not correspond to a named
839 * parameter; if a database access error occurs or
840 * this method is called on a closed <code>CallableStatement</code>
841 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
842 * this method
843 * @see #getShort
844 * @since 1.4
845 */
846 void setShort(String parameterName, short x) throws SQLException;
847
848 /**
849 * Sets the designated parameter to the given Java <code>int</code> value.
850 * The driver converts this
851 * to an SQL <code>INTEGER</code> value when it sends it to the database.
852 *
853 * @param parameterName the name of the parameter
854 * @param x the parameter value
855 * @exception SQLException if parameterName does not correspond to a named
856 * parameter; if a database access error occurs or
857 * this method is called on a closed <code>CallableStatement</code>
858 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
859 * this method
860 * @see #getInt
861 * @since 1.4
862 */
863 void setInt(String parameterName, int x) throws SQLException;
864
865 /**
866 * Sets the designated parameter to the given Java <code>long</code> value.
867 * The driver converts this
868 * to an SQL <code>BIGINT</code> value when it sends it to the database.
869 *
870 * @param parameterName the name of the parameter
871 * @param x the parameter value
872 * @exception SQLException if parameterName does not correspond to a named
873 * parameter; if a database access error occurs or
874 * this method is called on a closed <code>CallableStatement</code>
875 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
876 * this method
877 * @see #getLong
878 * @since 1.4
879 */
880 void setLong(String parameterName, long x) throws SQLException;
881
882 /**
883 * Sets the designated parameter to the given Java <code>float</code> value.
884 * The driver converts this
885 * to an SQL <code>FLOAT</code> value when it sends it to the database.
886 *
887 * @param parameterName the name of the parameter
888 * @param x the parameter value
889 * @exception SQLException if parameterName does not correspond to a named
890 * parameter; if a database access error occurs or
891 * this method is called on a closed <code>CallableStatement</code>
892 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
893 * this method
894 * @see #getFloat
895 * @since 1.4
896 */
897 void setFloat(String parameterName, float x) throws SQLException;
898
899 /**
900 * Sets the designated parameter to the given Java <code>double</code> value.
901 * The driver converts this
902 * to an SQL <code>DOUBLE</code> value when it sends it to the database.
903 *
904 * @param parameterName the name of the parameter
905 * @param x the parameter value
906 * @exception SQLException if parameterName does not correspond to a named
907 * parameter; if a database access error occurs or
908 * this method is called on a closed <code>CallableStatement</code>
909 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
910 * this method
911 * @see #getDouble
912 * @since 1.4
913 */
914 void setDouble(String parameterName, double x) throws SQLException;
915
916 /**
917 * Sets the designated parameter to the given
918 * <code>java.math.BigDecimal</code> value.
919 * The driver converts this to an SQL <code>NUMERIC</code> value when
920 * it sends it to the database.
921 *
922 * @param parameterName the name of the parameter
923 * @param x the parameter value
924 * @exception SQLException if parameterName does not correspond to a named
925 * parameter; if a database access error occurs or
926 * this method is called on a closed <code>CallableStatement</code>
927 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
928 * this method
929 * @see #getBigDecimal
930 * @since 1.4
931 */
932 void setBigDecimal(String parameterName, BigDecimal x) throws SQLException;
933
934 /**
935 * Sets the designated parameter to the given Java <code>String</code> value.
936 * The driver converts this
937 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
938 * (depending on the argument's
939 * size relative to the driver's limits on <code>VARCHAR</code> values)
940 * when it sends it to the database.
941 *
942 * @param parameterName the name of the parameter
943 * @param x the parameter value
944 * @exception SQLException if parameterName does not correspond to a named
945 * parameter; if a database access error occurs or
946 * this method is called on a closed <code>CallableStatement</code>
947 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
948 * this method
949 * @see #getString
950 * @since 1.4
951 */
952 void setString(String parameterName, String x) throws SQLException;
953
954 /**
955 * Sets the designated parameter to the given Java array of bytes.
956 * The driver converts this to an SQL <code>VARBINARY</code> or
957 * <code>LONGVARBINARY</code> (depending on the argument's size relative
958 * to the driver's limits on <code>VARBINARY</code> values) when it sends
959 * it to the database.
960 *
961 * @param parameterName the name of the parameter
962 * @param x the parameter value
963 * @exception SQLException if parameterName does not correspond to a named
964 * parameter; if a database access error occurs or
965 * this method is called on a closed <code>CallableStatement</code>
966 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
967 * this method
968 * @see #getBytes
969 * @since 1.4
970 */
971 void setBytes(String parameterName, byte x[]) throws SQLException;
972
973 /**
974 * Sets the designated parameter to the given <code>java.sql.Date</code> value
975 * using the default time zone of the virtual machine that is running
976 * the application.
977 * The driver converts this
978 * to an SQL <code>DATE</code> value when it sends it to the database.
979 *
980 * @param parameterName the name of the parameter
981 * @param x the parameter value
982 * @exception SQLException if parameterName does not correspond to a named
983 * parameter; if a database access error occurs or
984 * this method is called on a closed <code>CallableStatement</code>
985 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
986 * this method
987 * @see #getDate
988 * @since 1.4
989 */
990 void setDate(String parameterName, java.sql.Date x)
991 throws SQLException;
992
993 /**
994 * Sets the designated parameter to the given <code>java.sql.Time</code> value.
995 * The driver converts this
996 * to an SQL <code>TIME</code> value when it sends it to the database.
997 *
998 * @param parameterName the name of the parameter
999 * @param x the parameter value
1000 * @exception SQLException if parameterName does not correspond to a named
1001 * parameter; if a database access error occurs or
1002 * this method is called on a closed <code>CallableStatement</code>
1003 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1004 * this method
1005 * @see #getTime
1006 * @since 1.4
1007 */
1008 void setTime(String parameterName, java.sql.Time x)
1009 throws SQLException;
1010
1011 /**
1012 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
1013 * The driver
1014 * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
1015 * database.
1016 *
1017 * @param parameterName the name of the parameter
1018 * @param x the parameter value
1019 * @exception SQLException if parameterName does not correspond to a named
1020 * parameter; if a database access error occurs or
1021 * this method is called on a closed <code>CallableStatement</code>
1022 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1023 * this method
1024 * @see #getTimestamp
1025 * @since 1.4
1026 */
1027 void setTimestamp(String parameterName, java.sql.Timestamp x)
1028 throws SQLException;
1029
1030 /**
1031 * Sets the designated parameter to the given input stream, which will have
1032 * the specified number of bytes.
1033 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1034 * parameter, it may be more practical to send it via a
1035 * <code>java.io.InputStream</code>. Data will be read from the stream
1036 * as needed until end-of-file is reached. The JDBC driver will
1037 * do any necessary conversion from ASCII to the database char format.
1038 *
1039 * <P><B>Note:</B> This stream object can either be a standard
1040 * Java stream object or your own subclass that implements the
1041 * standard interface.
1042 *
1043 * @param parameterName the name of the parameter
1044 * @param x the Java input stream that contains the ASCII parameter value
1045 * @param length the number of bytes in the stream
1046 * @exception SQLException if parameterName does not correspond to a named
1047 * parameter; if a database access error occurs or
1048 * this method is called on a closed <code>CallableStatement</code>
1049 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1050 * this method
1051 * @since 1.4
1052 */
1053 void setAsciiStream(String parameterName, java.io.InputStream x, int length)
1054 throws SQLException;
1055
1056 /**
1057 * Sets the designated parameter to the given input stream, which will have
1058 * the specified number of bytes.
1059 * When a very large binary value is input to a <code>LONGVARBINARY</code>
1060 * parameter, it may be more practical to send it via a
1061 * <code>java.io.InputStream</code> object. The data will be read from the stream
1062 * as needed until end-of-file is reached.
1063 *
1064 * <P><B>Note:</B> This stream object can either be a standard
1065 * Java stream object or your own subclass that implements the
1066 * standard interface.
1067 *
1068 * @param parameterName the name of the parameter
1069 * @param x the java input stream which contains the binary parameter value
1070 * @param length the number of bytes in the stream
1071 * @exception SQLException if parameterName does not correspond to a named
1072 * parameter; if a database access error occurs or
1073 * this method is called on a closed <code>CallableStatement</code>
1074 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1075 * this method
1076 * @since 1.4
1077 */
1078 void setBinaryStream(String parameterName, java.io.InputStream x,
1079 int length) throws SQLException;
1080
1081 /**
1082 * Sets the value of the designated parameter with the given object. The second
1083 * argument must be an object type; for integral values, the
1084 * <code>java.lang</code> equivalent objects should be used.
1085 *
1086 * <p>The given Java object will be converted to the given targetSqlType
1087 * before being sent to the database.
1088 *
1089 * If the object has a custom mapping (is of a class implementing the
1090 * interface <code>SQLData</code>),
1091 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1092 * to the SQL data stream.
1093 * If, on the other hand, the object is of a class implementing
1094 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1095 * <code>Struct</code>, <code>java.net.URL</code>,
1096 * or <code>Array</code>, the driver should pass it to the database as a
1097 * value of the corresponding SQL type.
1098 * <P>
1099 * Note that this method may be used to pass datatabase-
1100 * specific abstract data types.
1101 *
1102 * @param parameterName the name of the parameter
1103 * @param x the object containing the input parameter value
1104 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1105 * sent to the database. The scale argument may further qualify this type.
1106 * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1107 * this is the number of digits after the decimal point. For all other
1108 * types, this value will be ignored.
1109 * @exception SQLException if parameterName does not correspond to a named
1110 * parameter; if a database access error occurs or
1111 * this method is called on a closed <code>CallableStatement</code>
1112 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1113 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1114 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1115 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1116 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1117 * or <code>STRUCT</code> data type and the JDBC driver does not support
1118 * this data type
1119 * @see Types
1120 * @see #getObject
1121 * @since 1.4
1122 */
1123 void setObject(String parameterName, Object x, int targetSqlType, int scale)
1124 throws SQLException;
1125
1126 /**
1127 * Sets the value of the designated parameter with the given object.
1128 * This method is like the method <code>setObject</code>
1129 * above, except that it assumes a scale of zero.
1130 *
1131 * @param parameterName the name of the parameter
1132 * @param x the object containing the input parameter value
1133 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1134 * sent to the database
1135 * @exception SQLException if parameterName does not correspond to a named
1136 * parameter; if a database access error occurs or
1137 * this method is called on a closed <code>CallableStatement</code>
1138 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1139 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1140 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1141 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1142 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1143 * or <code>STRUCT</code> data type and the JDBC driver does not support
1144 * this data type
1145 * @see #getObject
1146 * @since 1.4
1147 */
1148 void setObject(String parameterName, Object x, int targetSqlType)
1149 throws SQLException;
1150
1151 /**
1152 * Sets the value of the designated parameter with the given object.
1153 * The second parameter must be of type <code>Object</code>; therefore, the
1154 * <code>java.lang</code> equivalent objects should be used for built-in types.
1155 *
1156 * <p>The JDBC specification specifies a standard mapping from
1157 * Java <code>Object</code> types to SQL types. The given argument
1158 * will be converted to the corresponding SQL type before being
1159 * sent to the database.
1160 * <p>Note that this method may be used to pass datatabase-
1161 * specific abstract data types, by using a driver-specific Java
1162 * type.
1163 *
1164 * If the object is of a class implementing the interface <code>SQLData</code>,
1165 * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1166 * to write it to the SQL data stream.
1167 * If, on the other hand, the object is of a class implementing
1168 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1169 * <code>Struct</code>, <code>java.net.URL</code>,
1170 * or <code>Array</code>, the driver should pass it to the database as a
1171 * value of the corresponding SQL type.
1172 * <P>
1173 * This method throws an exception if there is an ambiguity, for example, if the
1174 * object is of a class implementing more than one of the interfaces named above.
1175 *<p>
1176 *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to
1177 * the backend. For maximum portability, the <code>setNull</code> or the
1178 * <code>setObject(String parameterName, Object x, int sqlType)</code>
1179 * method should be used
1180 * instead of <code>setObject(String parameterName, Object x)</code>.
1181 *<p>
1182 * @param parameterName the name of the parameter
1183 * @param x the object containing the input parameter value
1184 * @exception SQLException if parameterName does not correspond to a named
1185 * parameter; if a database access error occurs,
1186 * this method is called on a closed <code>CallableStatement</code> or if the given
1187 * <code>Object</code> parameter is ambiguous
1188 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1189 * this method
1190 * @see #getObject
1191 * @since 1.4
1192 */
1193 void setObject(String parameterName, Object x) throws SQLException;
1194
1195
1196 /**
1197 * Sets the designated parameter to the given <code>Reader</code>
1198 * object, which is the given number of characters long.
1199 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1200 * parameter, it may be more practical to send it via a
1201 * <code>java.io.Reader</code> object. The data will be read from the stream
1202 * as needed until end-of-file is reached. The JDBC driver will
1203 * do any necessary conversion from UNICODE to the database char format.
1204 *
1205 * <P><B>Note:</B> This stream object can either be a standard
1206 * Java stream object or your own subclass that implements the
1207 * standard interface.
1208 *
1209 * @param parameterName the name of the parameter
1210 * @param reader the <code>java.io.Reader</code> object that
1211 * contains the UNICODE data used as the designated parameter
1212 * @param length the number of characters in the stream
1213 * @exception SQLException if parameterName does not correspond to a named
1214 * parameter; if a database access error occurs or
1215 * this method is called on a closed <code>CallableStatement</code>
1216 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1217 * this method
1218 * @since 1.4
1219 */
1220 void setCharacterStream(String parameterName,
1221 java.io.Reader reader,
1222 int length) throws SQLException;
1223
1224 /**
1225 * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1226 * using the given <code>Calendar</code> object. The driver uses
1227 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1228 * which the driver then sends to the database. With a
1229 * a <code>Calendar</code> object, the driver can calculate the date
1230 * taking into account a custom timezone. If no
1231 * <code>Calendar</code> object is specified, the driver uses the default
1232 * timezone, which is that of the virtual machine running the application.
1233 *
1234 * @param parameterName the name of the parameter
1235 * @param x the parameter value
1236 * @param cal the <code>Calendar</code> object the driver will use
1237 * to construct the date
1238 * @exception SQLException if parameterName does not correspond to a named
1239 * parameter; if a database access error occurs or
1240 * this method is called on a closed <code>CallableStatement</code>
1241 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1242 * this method
1243 * @see #getDate
1244 * @since 1.4
1245 */
1246 void setDate(String parameterName, java.sql.Date x, Calendar cal)
1247 throws SQLException;
1248
1249 /**
1250 * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1251 * using the given <code>Calendar</code> object. The driver uses
1252 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1253 * which the driver then sends to the database. With a
1254 * a <code>Calendar</code> object, the driver can calculate the time
1255 * taking into account a custom timezone. If no
1256 * <code>Calendar</code> object is specified, the driver uses the default
1257 * timezone, which is that of the virtual machine running the application.
1258 *
1259 * @param parameterName the name of the parameter
1260 * @param x the parameter value
1261 * @param cal the <code>Calendar</code> object the driver will use
1262 * to construct the time
1263 * @exception SQLException if parameterName does not correspond to a named
1264 * parameter; if a database access error occurs or
1265 * this method is called on a closed <code>CallableStatement</code>
1266 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1267 * this method
1268 * @see #getTime
1269 * @since 1.4
1270 */
1271 void setTime(String parameterName, java.sql.Time x, Calendar cal)
1272 throws SQLException;
1273
1274 /**
1275 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1276 * using the given <code>Calendar</code> object. The driver uses
1277 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1278 * which the driver then sends to the database. With a
1279 * a <code>Calendar</code> object, the driver can calculate the timestamp
1280 * taking into account a custom timezone. If no
1281 * <code>Calendar</code> object is specified, the driver uses the default
1282 * timezone, which is that of the virtual machine running the application.
1283 *
1284 * @param parameterName the name of the parameter
1285 * @param x the parameter value
1286 * @param cal the <code>Calendar</code> object the driver will use
1287 * to construct the timestamp
1288 * @exception SQLException if parameterName does not correspond to a named
1289 * parameter; if a database access error occurs or
1290 * this method is called on a closed <code>CallableStatement</code>
1291 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1292 * this method
1293 * @see #getTimestamp
1294 * @since 1.4
1295 */
1296 void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
1297 throws SQLException;
1298
1299 /**
1300 * Sets the designated parameter to SQL <code>NULL</code>.
1301 * This version of the method <code>setNull</code> should
1302 * be used for user-defined types and REF type parameters. Examples
1303 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
1304 * named array types.
1305 *
1306 * <P><B>Note:</B> To be portable, applications must give the
1307 * SQL type code and the fully-qualified SQL type name when specifying
1308 * a NULL user-defined or REF parameter. In the case of a user-defined type
1309 * the name is the type name of the parameter itself. For a REF
1310 * parameter, the name is the type name of the referenced type.
1311 * <p>
1312 * Although it is intended for user-defined and Ref parameters,
1313 * this method may be used to set a null parameter of any JDBC type.
1314 * If the parameter does not have a user-defined or REF type, the given
1315 * typeName is ignored.
1316 *
1317 *
1318 * @param parameterName the name of the parameter
1319 * @param sqlType a value from <code>java.sql.Types</code>
1320 * @param typeName the fully-qualified name of an SQL user-defined type;
1321 * ignored if the parameter is not a user-defined type or
1322 * SQL <code>REF</code> value
1323 * @exception SQLException if parameterName does not correspond to a named
1324 * parameter; if a database access error occurs or
1325 * this method is called on a closed <code>CallableStatement</code>
1326 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1327 * this method
1328 * @since 1.4
1329 */
1330 void setNull (String parameterName, int sqlType, String typeName)
1331 throws SQLException;
1332
1333 /**
1334 * Retrieves the value of a JDBC <code>CHAR</code>, <code>VARCHAR</code>,
1335 * or <code>LONGVARCHAR</code> parameter as a <code>String</code> in
1336 * the Java programming language.
1337 * <p>
1338 * For the fixed-length type JDBC <code>CHAR</code>,
1339 * the <code>String</code> object
1340 * returned has exactly the same value the SQL
1341 * <code>CHAR</code> value had in the
1342 * database, including any padding added by the database.
1343 * @param parameterName the name of the parameter
1344 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1345 * is <code>null</code>.
1346 * @exception SQLException if parameterName does not correspond to a named
1347 * parameter; if a database access error occurs or
1348 * this method is called on a closed <code>CallableStatement</code>
1349 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1350 * this method
1351 * @see #setString
1352 * @since 1.4
1353 */
1354 String getString(String parameterName) throws SQLException;
1355
1356 /**
1357 * Retrieves the value of a JDBC <code>BIT</code> or <code>BOOLEAN</code>
1358 * parameter as a
1359 * <code>boolean</code> in the Java programming language.
1360 * @param parameterName the name of the parameter
1361 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1362 * is <code>false</code>.
1363 * @exception SQLException if parameterName does not correspond to a named
1364 * parameter; if a database access error occurs or
1365 * this method is called on a closed <code>CallableStatement</code>
1366 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1367 * this method
1368 * @see #setBoolean
1369 * @since 1.4
1370 */
1371 boolean getBoolean(String parameterName) throws SQLException;
1372
1373 /**
1374 * Retrieves the value of a JDBC <code>TINYINT</code> parameter as a <code>byte</code>
1375 * in the Java programming language.
1376 * @param parameterName the name of the parameter
1377 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1378 * is <code>0</code>.
1379 * @exception SQLException if parameterName does not correspond to a named
1380 * parameter; if a database access error occurs or
1381 * this method is called on a closed <code>CallableStatement</code>
1382 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1383 * this method
1384 * @see #setByte
1385 * @since 1.4
1386 */
1387 byte getByte(String parameterName) throws SQLException;
1388
1389 /**
1390 * Retrieves the value of a JDBC <code>SMALLINT</code> parameter as a <code>short</code>
1391 * in the Java programming language.
1392 * @param parameterName the name of the parameter
1393 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1394 * is <code>0</code>.
1395 * @exception SQLException if parameterName does not correspond to a named
1396 * parameter; if a database access error occurs or
1397 * this method is called on a closed <code>CallableStatement</code>
1398 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1399 * this method
1400 * @see #setShort
1401 * @since 1.4
1402 */
1403 short getShort(String parameterName) throws SQLException;
1404
1405 /**
1406 * Retrieves the value of a JDBC <code>INTEGER</code> parameter as an <code>int</code>
1407 * in the Java programming language.
1408 *
1409 * @param parameterName the name of the parameter
1410 * @return the parameter value. If the value is SQL <code>NULL</code>,
1411 * the result is <code>0</code>.
1412 * @exception SQLException if parameterName does not correspond to a named
1413 * parameter; if a database access error occurs or
1414 * this method is called on a closed <code>CallableStatement</code>
1415 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1416 * this method
1417 * @see #setInt
1418 * @since 1.4
1419 */
1420 int getInt(String parameterName) throws SQLException;
1421
1422 /**
1423 * Retrieves the value of a JDBC <code>BIGINT</code> parameter as a <code>long</code>
1424 * in the Java programming language.
1425 *
1426 * @param parameterName the name of the parameter
1427 * @return the parameter value. If the value is SQL <code>NULL</code>,
1428 * the result is <code>0</code>.
1429 * @exception SQLException if parameterName does not correspond to a named
1430 * parameter; if a database access error occurs or
1431 * this method is called on a closed <code>CallableStatement</code>
1432 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1433 * this method
1434 * @see #setLong
1435 * @since 1.4
1436 */
1437 long getLong(String parameterName) throws SQLException;
1438
1439 /**
1440 * Retrieves the value of a JDBC <code>FLOAT</code> parameter as a <code>float</code>
1441 * in the Java programming language.
1442 * @param parameterName the name of the parameter
1443 * @return the parameter value. If the value is SQL <code>NULL</code>,
1444 * the result is <code>0</code>.
1445 * @exception SQLException if parameterName does not correspond to a named
1446 * parameter; if a database access error occurs or
1447 * this method is called on a closed <code>CallableStatement</code>
1448 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1449 * this method
1450 * @see #setFloat
1451 * @since 1.4
1452 */
1453 float getFloat(String parameterName) throws SQLException;
1454
1455 /**
1456 * Retrieves the value of a JDBC <code>DOUBLE</code> parameter as a <code>double</code>
1457 * in the Java programming language.
1458 * @param parameterName the name of the parameter
1459 * @return the parameter value. If the value is SQL <code>NULL</code>,
1460 * the result is <code>0</code>.
1461 * @exception SQLException if parameterName does not correspond to a named
1462 * parameter; if a database access error occurs or
1463 * this method is called on a closed <code>CallableStatement</code>
1464 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1465 * this method
1466 * @see #setDouble
1467 * @since 1.4
1468 */
1469 double getDouble(String parameterName) throws SQLException;
1470
1471 /**
1472 * Retrieves the value of a JDBC <code>BINARY</code> or <code>VARBINARY</code>
1473 * parameter as an array of <code>byte</code> values in the Java
1474 * programming language.
1475 * @param parameterName the name of the parameter
1476 * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1477 * <code>null</code>.
1478 * @exception SQLException if parameterName does not correspond to a named
1479 * parameter; if a database access error occurs or
1480 * this method is called on a closed <code>CallableStatement</code>
1481 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1482 * this method
1483 * @see #setBytes
1484 * @since 1.4
1485 */
1486 byte[] getBytes(String parameterName) throws SQLException;
1487
1488 /**
1489 * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1490 * <code>java.sql.Date</code> object.
1491 * @param parameterName the name of the parameter
1492 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1493 * is <code>null</code>.
1494 * @exception SQLException if parameterName does not correspond to a named
1495 * parameter; if a database access error occurs or
1496 * this method is called on a closed <code>CallableStatement</code>
1497 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1498 * this method
1499 * @see #setDate
1500 * @since 1.4
1501 */
1502 java.sql.Date getDate(String parameterName) throws SQLException;
1503
1504 /**
1505 * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1506 * <code>java.sql.Time</code> object.
1507 * @param parameterName the name of the parameter
1508 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1509 * is <code>null</code>.
1510 * @exception SQLException if parameterName does not correspond to a named
1511 * parameter; if a database access error occurs or
1512 * this method is called on a closed <code>CallableStatement</code>
1513 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1514 * this method
1515 * @see #setTime
1516 * @since 1.4
1517 */
1518 java.sql.Time getTime(String parameterName) throws SQLException;
1519
1520 /**
1521 * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1522 * <code>java.sql.Timestamp</code> object.
1523 * @param parameterName the name of the parameter
1524 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1525 * is <code>null</code>.
1526 * @exception SQLException if parameterName does not correspond to a named
1527 * parameter; if a database access error occurs or
1528 * this method is called on a closed <code>CallableStatement</code>
1529 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1530 * this method
1531 * @see #setTimestamp
1532 * @since 1.4
1533 */
1534 java.sql.Timestamp getTimestamp(String parameterName) throws SQLException;
1535
1536 /**
1537 * Retrieves the value of a parameter as an <code>Object</code> in the Java
1538 * programming language. If the value is an SQL <code>NULL</code>, the
1539 * driver returns a Java <code>null</code>.
1540 * <p>
1541 * This method returns a Java object whose type corresponds to the JDBC
1542 * type that was registered for this parameter using the method
1543 * <code>registerOutParameter</code>. By registering the target JDBC
1544 * type as <code>java.sql.Types.OTHER</code>, this method can be used
1545 * to read database-specific abstract data types.
1546 * @param parameterName the name of the parameter
1547 * @return A <code>java.lang.Object</code> holding the OUT parameter value.
1548 * @exception SQLException if parameterName does not correspond to a named
1549 * parameter; if a database access error occurs or
1550 * this method is called on a closed <code>CallableStatement</code>
1551 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1552 * this method
1553 * @see Types
1554 * @see #setObject
1555 * @since 1.4
1556 */
1557 Object getObject(String parameterName) throws SQLException;
1558
1559 /**
1560 * Retrieves the value of a JDBC <code>NUMERIC</code> parameter as a
1561 * <code>java.math.BigDecimal</code> object with as many digits to the
1562 * right of the decimal point as the value contains.
1563 * @param parameterName the name of the parameter
1564 * @return the parameter value in full precision. If the value is
1565 * SQL <code>NULL</code>, the result is <code>null</code>.
1566 * @exception SQLExceptionif parameterName does not correspond to a named
1567 * parameter; if a database access error occurs or
1568 * this method is called on a closed <code>CallableStatement</code>
1569 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1570 * this method
1571 * @see #setBigDecimal
1572 * @since 1.4
1573 */
1574 BigDecimal getBigDecimal(String parameterName) throws SQLException;
1575
1576 /**
1577 * Returns an object representing the value of OUT parameter
1578 * <code>parameterName</code> and uses <code>map</code> for the custom
1579 * mapping of the parameter value.
1580 * <p>
1581 * This method returns a Java object whose type corresponds to the
1582 * JDBC type that was registered for this parameter using the method
1583 * <code>registerOutParameter</code>. By registering the target
1584 * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
1585 * be used to read database-specific abstract data types.
1586 * @param parameterName the name of the parameter
1587 * @param map the mapping from SQL type names to Java classes
1588 * @return a <code>java.lang.Object</code> holding the OUT parameter value
1589 * @exception SQLException if parameterName does not correspond to a named
1590 * parameter; if a database access error occurs or
1591 * this method is called on a closed <code>CallableStatement</code>
1592 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1593 * this method
1594 * @see #setObject
1595 * @since 1.4
1596 */
1597 Object getObject(String parameterName, java.util.Map<String,Class<?>> map)
1598 throws SQLException;
1599
1600 /**
1601 * Retrieves the value of a JDBC <code>REF(<structured-type>)</code>
1602 * parameter as a {@link java.sql.Ref} object in the Java programming language.
1603 *
1604 * @param parameterName the name of the parameter
1605 * @return the parameter value as a <code>Ref</code> object in the
1606 * Java programming language. If the value was SQL <code>NULL</code>,
1607 * the value <code>null</code> is returned.
1608 * @exception SQLException if parameterName does not correspond to a named
1609 * parameter; if a database access error occurs or
1610 * this method is called on a closed <code>CallableStatement</code>
1611 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1612 * this method
1613 * @since 1.4
1614 */
1615 Ref getRef (String parameterName) throws SQLException;
1616
1617 /**
1618 * Retrieves the value of a JDBC <code>BLOB</code> parameter as a
1619 * {@link java.sql.Blob} object in the Java programming language.
1620 *
1621 * @param parameterName the name of the parameter
1622 * @return the parameter value as a <code>Blob</code> object in the
1623 * Java programming language. If the value was SQL <code>NULL</code>,
1624 * the value <code>null</code> is returned.
1625 * @exception SQLException if parameterName does not correspond to a named
1626 * parameter; if a database access error occurs or
1627 * this method is called on a closed <code>CallableStatement</code>
1628 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1629 * this method
1630 * @since 1.4
1631 */
1632 Blob getBlob (String parameterName) throws SQLException;
1633
1634 /**
1635 * Retrieves the value of a JDBC <code>CLOB</code> parameter as a
1636 * <code>java.sql.Clob</code> object in the Java programming language.
1637 * @param parameterName the name of the parameter
1638 * @return the parameter value as a <code>Clob</code> object in the
1639 * Java programming language. If the value was SQL <code>NULL</code>,
1640 * the value <code>null</code> is returned.
1641 * @exception SQLException if parameterName does not correspond to a named
1642 * parameter; if a database access error occurs or
1643 * this method is called on a closed <code>CallableStatement</code>
1644 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1645 * this method
1646 * @since 1.4
1647 */
1648 Clob getClob (String parameterName) throws SQLException;
1649
1650 /**
1651 * Retrieves the value of a JDBC <code>ARRAY</code> parameter as an
1652 * {@link java.sql.Array} object in the Java programming language.
1653 *
1654 * @param parameterName the name of the parameter
1655 * @return the parameter value as an <code>Array</code> object in
1656 * Java programming language. If the value was SQL <code>NULL</code>,
1657 * the value <code>null</code> is returned.
1658 * @exception SQLException if parameterName does not correspond to a named
1659 * parameter; if a database access error occurs or
1660 * this method is called on a closed <code>CallableStatement</code>
1661 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1662 * this method
1663 * @since 1.4
1664 */
1665 Array getArray (String parameterName) throws SQLException;
1666
1667 /**
1668 * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1669 * <code>java.sql.Date</code> object, using
1670 * the given <code>Calendar</code> object
1671 * to construct the date.
1672 * With a <code>Calendar</code> object, the driver
1673 * can calculate the date taking into account a custom timezone and locale.
1674 * If no <code>Calendar</code> object is specified, the driver uses the
1675 * default timezone and locale.
1676 *
1677 * @param parameterName the name of the parameter
1678 * @param cal the <code>Calendar</code> object the driver will use
1679 * to construct the date
1680 * @return the parameter value. If the value is SQL <code>NULL</code>,
1681 * the result is <code>null</code>.
1682 * @exception SQLException if parameterName does not correspond to a named
1683 * parameter; if a database access error occurs or
1684 * this method is called on a closed <code>CallableStatement</code>
1685 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1686 * this method
1687 * @see #setDate
1688 * @since 1.4
1689 */
1690 java.sql.Date getDate(String parameterName, Calendar cal)
1691 throws SQLException;
1692
1693 /**
1694 * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1695 * <code>java.sql.Time</code> object, using
1696 * the given <code>Calendar</code> object
1697 * to construct the time.
1698 * With a <code>Calendar</code> object, the driver
1699 * can calculate the time taking into account a custom timezone and locale.
1700 * If no <code>Calendar</code> object is specified, the driver uses the
1701 * default timezone and locale.
1702 *
1703 * @param parameterName the name of the parameter
1704 * @param cal the <code>Calendar</code> object the driver will use
1705 * to construct the time
1706 * @return the parameter value; if the value is SQL <code>NULL</code>, the result is
1707 * <code>null</code>.
1708 * @exception SQLException if parameterName does not correspond to a named
1709 * parameter; if a database access error occurs or
1710 * this method is called on a closed <code>CallableStatement</code>
1711 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1712 * this method
1713 * @see #setTime
1714 * @since 1.4
1715 */
1716 java.sql.Time getTime(String parameterName, Calendar cal)
1717 throws SQLException;
1718
1719 /**
1720 * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1721 * <code>java.sql.Timestamp</code> object, using
1722 * the given <code>Calendar</code> object to construct
1723 * the <code>Timestamp</code> object.
1724 * With a <code>Calendar</code> object, the driver
1725 * can calculate the timestamp taking into account a custom timezone and locale.
1726 * If no <code>Calendar</code> object is specified, the driver uses the
1727 * default timezone and locale.
1728 *
1729 *
1730 * @param parameterName the name of the parameter
1731 * @param cal the <code>Calendar</code> object the driver will use
1732 * to construct the timestamp
1733 * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1734 * <code>null</code>.
1735 * @exception SQLException if parameterName does not correspond to a named
1736 * parameter; if a database access error occurs or
1737 * this method is called on a closed <code>CallableStatement</code>
1738 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1739 * this method
1740 * @see #setTimestamp
1741 * @since 1.4
1742 */
1743 java.sql.Timestamp getTimestamp(String parameterName, Calendar cal)
1744 throws SQLException;
1745
1746 /**
1747 * Retrieves the value of a JDBC <code>DATALINK</code> parameter as a
1748 * <code>java.net.URL</code> object.
1749 *
1750 * @param parameterName the name of the parameter
1751 * @return the parameter value as a <code>java.net.URL</code> object in the
1752 * Java programming language. If the value was SQL <code>NULL</code>, the
1753 * value <code>null</code> is returned.
1754 * @exception SQLException if parameterName does not correspond to a named
1755 * parameter; if a database access error occurs,
1756 * this method is called on a closed <code>CallableStatement</code>,
1757 * or if there is a problem with the URL
1758 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1759 * this method
1760 * @see #setURL
1761 * @since 1.4
1762 */
1763 java.net.URL getURL(String parameterName) throws SQLException;
1764
1765 //------------------------- JDBC 4.0 -----------------------------------
1766
1767 /**
1768 * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1769 * <code>java.sql.RowId</code> object.
1770 *
1771 * @param parameterIndex the first parameter is 1, the second is 2,...
1772 * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1773 * value is used as the designated parameter. If the parameter contains
1774 * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1775 * @throws SQLException if the parameterIndex is not valid;
1776 * if a database access error occurs or
1777 * this method is called on a closed <code>CallableStatement</code>
1778 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1779 * this method
1780 * @since 1.6
1781 */
1782 RowId getRowId(int parameterIndex) throws SQLException;
1783
1784 /**
1785 * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1786 * <code>java.sql.RowId</code> object.
1787 *
1788 * @param parameterName the name of the parameter
1789 * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1790 * value is used as the designated parameter. If the parameter contains
1791 * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1792 * @throws SQLException if parameterName does not correspond to a named
1793 * parameter; if a database access error occurs or
1794 * this method is called on a closed <code>CallableStatement</code>
1795 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1796 * this method
1797 * @since 1.6
1798 */
1799 RowId getRowId(String parameterName) throws SQLException;
1800
1801 /**
1802 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1803 * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1804 * database.
1805 *
1806 * @param parameterName the name of the parameter
1807 * @param x the parameter value
1808 * @throws SQLException if parameterName does not correspond to a named
1809 * parameter; if a database access error occurs or
1810 * this method is called on a closed <code>CallableStatement</code>
1811 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1812 * this method
1813 * @since 1.6
1814 */
1815 void setRowId(String parameterName, RowId x) throws SQLException;
1816
1817 /**
1818 * Sets the designated parameter to the given <code>String</code> object.
1819 * The driver converts this to a SQL <code>NCHAR</code> or
1820 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1821 * @param parameterName the name of the parameter to be set
1822 * @param value the parameter value
1823 * @throws SQLException if parameterName does not correspond to a named
1824 * parameter; if the driver does not support national
1825 * character sets; if the driver can detect that a data conversion
1826 * error could occur; if a database access error occurs or
1827 * this method is called on a closed <code>CallableStatement</code>
1828 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1829 * this method
1830 * @since 1.6
1831 */
1832 void setNString(String parameterName, String value)
1833 throws SQLException;
1834
1835 /**
1836 * Sets the designated parameter to a <code>Reader</code> object. The
1837 * <code>Reader</code> reads the data till end-of-file is reached. The
1838 * driver does the necessary conversion from Java character format to
1839 * the national character set in the database.
1840 * @param parameterName the name of the parameter to be set
1841 * @param value the parameter value
1842 * @param length the number of characters in the parameter data.
1843 * @throws SQLException if parameterName does not correspond to a named
1844 * parameter; if the driver does not support national
1845 * character sets; if the driver can detect that a data conversion
1846 * error could occur; if a database access error occurs or
1847 * this method is called on a closed <code>CallableStatement</code>
1848 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1849 * this method
1850 * @since 1.6
1851 */
1852 void setNCharacterStream(String parameterName, Reader value, long length)
1853 throws SQLException;
1854
1855 /**
1856 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
1857 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
1858 * object maps to a SQL <code>NCLOB</code>.
1859 * @param parameterName the name of the parameter to be set
1860 * @param value the parameter value
1861 * @throws SQLException if parameterName does not correspond to a named
1862 * parameter; if the driver does not support national
1863 * character sets; if the driver can detect that a data conversion
1864 * error could occur; if a database access error occurs or
1865 * this method is called on a closed <code>CallableStatement</code>
1866 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1867 * this method
1868 * @since 1.6
1869 */
1870 void setNClob(String parameterName, NClob value) throws SQLException;
1871
1872 /**
1873 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1874 * of characters specified by length otherwise a <code>SQLException</code> will be
1875 * generated when the <code>CallableStatement</code> is executed.
1876 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1877 * because it informs the driver that the parameter value should be sent to
1878 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1879 * driver may have to do extra work to determine whether the parameter
1880 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1881 * @param parameterName the name of the parameter to be set
1882 * @param reader An object that contains the data to set the parameter value to.
1883 * @param length the number of characters in the parameter data.
1884 * @throws SQLException if parameterName does not correspond to a named
1885 * parameter; if the length specified is less than zero;
1886 * a database access error occurs or
1887 * this method is called on a closed <code>CallableStatement</code>
1888 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1889 * this method
1890 *
1891 * @since 1.6
1892 */
1893 void setClob(String parameterName, Reader reader, long length)
1894 throws SQLException;
1895
1896 /**
1897 * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number
1898 * of characters specified by length, otherwise a <code>SQLException</code> will be
1899 * generated when the <code>CallableStatement</code> is executed.
1900 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1901 * method because it informs the driver that the parameter value should be
1902 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1903 * the driver may have to do extra work to determine whether the parameter
1904 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1905 *
1906 * @param parameterName the name of the parameter to be set
1907 * the second is 2, ...
1908 *
1909 * @param inputStream An object that contains the data to set the parameter
1910 * value to.
1911 * @param length the number of bytes in the parameter data.
1912 * @throws SQLException if parameterName does not correspond to a named
1913 * parameter; if the length specified
1914 * is less than zero; if the number of bytes in the inputstream does not match
1915 * the specfied length; if a database access error occurs or
1916 * this method is called on a closed <code>CallableStatement</code>
1917 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1918 * this method
1919 *
1920 * @since 1.6
1921 */
1922 void setBlob(String parameterName, InputStream inputStream, long length)
1923 throws SQLException;
1924 /**
1925 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1926 * of characters specified by length otherwise a <code>SQLException</code> will be
1927 * generated when the <code>CallableStatement</code> is executed.
1928 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1929 * because it informs the driver that the parameter value should be sent to
1930 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
1931 * driver may have to do extra work to determine whether the parameter
1932 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
1933 *
1934 * @param parameterName the name of the parameter to be set
1935 * @param reader An object that contains the data to set the parameter value to.
1936 * @param length the number of characters in the parameter data.
1937 * @throws SQLException if parameterName does not correspond to a named
1938 * parameter; if the length specified is less than zero;
1939 * if the driver does not support national
1940 * character sets; if the driver can detect that a data conversion
1941 * error could occur; if a database access error occurs or
1942 * this method is called on a closed <code>CallableStatement</code>
1943 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1944 * this method
1945 * @since 1.6
1946 */
1947 void setNClob(String parameterName, Reader reader, long length)
1948 throws SQLException;
1949
1950 /**
1951 * Retrieves the value of the designated JDBC <code>NCLOB</code> parameter as a
1952 * <code>java.sql.NClob</code> object in the Java programming language.
1953 *
1954 * @param parameterIndex the first parameter is 1, the second is 2, and
1955 * so on
1956 * @return the parameter value as a <code>NClob</code> object in the
1957 * Java programming language. If the value was SQL <code>NULL</code>, the
1958 * value <code>null</code> is returned.
1959 * @exception SQLException if the parameterIndex is not valid;
1960 * if the driver does not support national
1961 * character sets; if the driver can detect that a data conversion
1962 * error could occur; if a database access error occurs or
1963 * this method is called on a closed <code>CallableStatement</code>
1964 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1965 * this method
1966 * @since 1.6
1967 */
1968 NClob getNClob (int parameterIndex) throws SQLException;
1969
1970
1971 /**
1972 * Retrieves the value of a JDBC <code>NCLOB</code> parameter as a
1973 * <code>java.sql.NClob</code> object in the Java programming language.
1974 * @param parameterName the name of the parameter
1975 * @return the parameter value as a <code>NClob</code> object in the
1976 * Java programming language. If the value was SQL <code>NULL</code>,
1977 * the value <code>null</code> is returned.
1978 * @exception SQLException if parameterName does not correspond to a named
1979 * parameter; if the driver does not support national
1980 * character sets; if the driver can detect that a data conversion
1981 * error could occur; if a database access error occurs or
1982 * this method is called on a closed <code>CallableStatement</code>
1983 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1984 * this method
1985 * @since 1.6
1986 */
1987 NClob getNClob (String parameterName) throws SQLException;
1988
1989 /**
1990 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1991 * <code>SQL XML</code> value when it sends it to the database.
1992 *
1993 * @param parameterName the name of the parameter
1994 * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
1995 * @throws SQLException if parameterName does not correspond to a named
1996 * parameter; if a database access error occurs;
1997 * this method is called on a closed <code>CallableStatement</code> or
1998 * the <code>java.xml.transform.Result</code>,
1999 * <code>Writer</code> or <code>OutputStream</code> has not been closed for the <code>SQLXML</code> object
2000 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2001 * this method
2002 *
2003 * @since 1.6
2004 */
2005 void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException;
2006
2007 /**
2008 * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2009 * <code>java.sql.SQLXML</code> object in the Java programming language.
2010 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2011 * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2012 * @throws SQLException if the parameterIndex is not valid;
2013 * if a database access error occurs or
2014 * this method is called on a closed <code>CallableStatement</code>
2015 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2016 * this method
2017 * @since 1.6
2018 */
2019 SQLXML getSQLXML(int parameterIndex) throws SQLException;
2020
2021 /**
2022 * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2023 * <code>java.sql.SQLXML</code> object in the Java programming language.
2024 * @param parameterName the name of the parameter
2025 * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2026 * @throws SQLException if parameterName does not correspond to a named
2027 * parameter; if a database access error occurs or
2028 * this method is called on a closed <code>CallableStatement</code>
2029 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2030 * this method
2031 * @since 1.6
2032 */
2033 SQLXML getSQLXML(String parameterName) throws SQLException;
2034
2035 /**
2036 * Retrieves the value of the designated <code>NCHAR</code>,
2037 * <code>NVARCHAR</code>
2038 * or <code>LONGNVARCHAR</code> parameter as
2039 * a <code>String</code> in the Java programming language.
2040 * <p>
2041 * For the fixed-length type JDBC <code>NCHAR</code>,
2042 * the <code>String</code> object
2043 * returned has exactly the same value the SQL
2044 * <code>NCHAR</code> value had in the
2045 * database, including any padding added by the database.
2046 *
2047 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2048 * @return a <code>String</code> object that maps an
2049 * <code>NCHAR</code>, <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
2050 * @exception SQLException if the parameterIndex is not valid;
2051 * if a database access error occurs or
2052 * this method is called on a closed <code>CallableStatement</code>
2053 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2054 * this method
2055 * @since 1.6
2056 * @see #setNString
2057 */
2058 String getNString(int parameterIndex) throws SQLException;
2059
2060
2061 /**
2062 * Retrieves the value of the designated <code>NCHAR</code>,
2063 * <code>NVARCHAR</code>
2064 * or <code>LONGNVARCHAR</code> parameter as
2065 * a <code>String</code> in the Java programming language.
2066 * <p>
2067 * For the fixed-length type JDBC <code>NCHAR</code>,
2068 * the <code>String</code> object
2069 * returned has exactly the same value the SQL
2070 * <code>NCHAR</code> value had in the
2071 * database, including any padding added by the database.
2072 *
2073 * @param parameterName the name of the parameter
2074 * @return a <code>String</code> object that maps an
2075 * <code>NCHAR</code>, <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
2076 * @exception SQLException if parameterName does not correspond to a named
2077 * parameter;
2078 * if a database access error occurs or
2079 * this method is called on a closed <code>CallableStatement</code>
2080 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2081 * this method
2082 * @since 1.6
2083 * @see #setNString
2084 */
2085 String getNString(String parameterName) throws SQLException;
2086
2087 /**
2088 * Retrieves the value of the designated parameter as a
2089 * <code>java.io.Reader</code> object in the Java programming language.
2090 * It is intended for use when
2091 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
2092 * and <code>LONGNVARCHAR</code> parameters.
2093 *
2094 * @return a <code>java.io.Reader</code> object that contains the parameter
2095 * value; if the value is SQL <code>NULL</code>, the value returned is
2096 * <code>null</code> in the Java programming language.
2097 * @param parameterIndex the first parameter is 1, the second is 2, ...
2098 * @exception SQLException if the parameterIndex is not valid;
2099 * if a database access error occurs or
2100 * this method is called on a closed <code>CallableStatement</code>
2101 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2102 * this method
2103 * @since 1.6
2104 */
2105 java.io.Reader getNCharacterStream(int parameterIndex) throws SQLException;
2106
2107 /**
2108 * Retrieves the value of the designated parameter as a
2109 * <code>java.io.Reader</code> object in the Java programming language.
2110 * It is intended for use when
2111 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
2112 * and <code>LONGNVARCHAR</code> parameters.
2113 *
2114 * @param parameterName the name of the parameter
2115 * @return a <code>java.io.Reader</code> object that contains the parameter
2116 * value; if the value is SQL <code>NULL</code>, the value returned is
2117 * <code>null</code> in the Java programming language
2118 * @exception SQLException if parameterName does not correspond to a named
2119 * parameter; if a database access error occurs or
2120 * this method is called on a closed <code>CallableStatement</code>
2121 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2122 * this method
2123 * @since 1.6
2124 */
2125 java.io.Reader getNCharacterStream(String parameterName) throws SQLException;
2126
2127 /**
2128 * Retrieves the value of the designated parameter as a
2129 * <code>java.io.Reader</code> object in the Java programming language.
2130 *
2131 * @return a <code>java.io.Reader</code> object that contains the parameter
2132 * value; if the value is SQL <code>NULL</code>, the value returned is
2133 * <code>null</code> in the Java programming language.
2134 * @param parameterIndex the first parameter is 1, the second is 2, ...
2135 * @exception SQLException if the parameterIndex is not valid; if a database access error occurs or
2136 * this method is called on a closed <code>CallableStatement</code>
2137 * @since 1.6
2138 */
2139 java.io.Reader getCharacterStream(int parameterIndex) throws SQLException;
2140
2141 /**
2142 * Retrieves the value of the designated parameter as a
2143 * <code>java.io.Reader</code> object in the Java programming language.
2144 *
2145 * @param parameterName the name of the parameter
2146 * @return a <code>java.io.Reader</code> object that contains the parameter
2147 * value; if the value is SQL <code>NULL</code>, the value returned is
2148 * <code>null</code> in the Java programming language
2149 * @exception SQLException if parameterName does not correspond to a named
2150 * parameter; if a database access error occurs or
2151 * this method is called on a closed <code>CallableStatement</code>
2152 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2153 * this method
2154 * @since 1.6
2155 */
2156 java.io.Reader getCharacterStream(String parameterName) throws SQLException;
2157
2158 /**
2159 * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
2160 * The driver converts this to an SQL <code>BLOB</code> value when it
2161 * sends it to the database.
2162 *
2163 * @param parameterName the name of the parameter
2164 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
2165 * @exception SQLException if parameterName does not correspond to a named
2166 * parameter; if a database access error occurs or
2167 * this method is called on a closed <code>CallableStatement</code>
2168 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2169 * this method
2170 * @since 1.6
2171 */
2172 void setBlob (String parameterName, Blob x) throws SQLException;
2173
2174 /**
2175 * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
2176 * The driver converts this to an SQL <code>CLOB</code> value when it
2177 * sends it to the database.
2178 *
2179 * @param parameterName the name of the parameter
2180 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
2181 * @exception SQLException if parameterName does not correspond to a named
2182 * parameter; if a database access error occurs or
2183 * this method is called on a closed <code>CallableStatement</code>
2184 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2185 * this method
2186 * @since 1.6
2187 */
2188 void setClob (String parameterName, Clob x) throws SQLException;
2189 /**
2190 * Sets the designated parameter to the given input stream, which will have
2191 * the specified number of bytes.
2192 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2193 * parameter, it may be more practical to send it via a
2194 * <code>java.io.InputStream</code>. Data will be read from the stream
2195 * as needed until end-of-file is reached. The JDBC driver will
2196 * do any necessary conversion from ASCII to the database char format.
2197 *
2198 * <P><B>Note:</B> This stream object can either be a standard
2199 * Java stream object or your own subclass that implements the
2200 * standard interface.
2201 *
2202 * @param parameterName the name of the parameter
2203 * @param x the Java input stream that contains the ASCII parameter value
2204 * @param length the number of bytes in the stream
2205 * @exception SQLException if parameterName does not correspond to a named
2206 * parameter; if a database access error occurs or
2207 * this method is called on a closed <code>CallableStatement</code>
2208 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2209 * this method
2210 * @since 1.6
2211 */
2212 void setAsciiStream(String parameterName, java.io.InputStream x, long length)
2213 throws SQLException;
2214
2215 /**
2216 * Sets the designated parameter to the given input stream, which will have
2217 * the specified number of bytes.
2218 * When a very large binary value is input to a <code>LONGVARBINARY</code>
2219 * parameter, it may be more practical to send it via a
2220 * <code>java.io.InputStream</code> object. The data will be read from the stream
2221 * as needed until end-of-file is reached.
2222 *
2223 * <P><B>Note:</B> This stream object can either be a standard
2224 * Java stream object or your own subclass that implements the
2225 * standard interface.
2226 *
2227 * @param parameterName the name of the parameter
2228 * @param x the java input stream which contains the binary parameter value
2229 * @param length the number of bytes in the stream
2230 * @exception SQLException if parameterName does not correspond to a named
2231 * parameter; if a database access error occurs or
2232 * this method is called on a closed <code>CallableStatement</code>
2233 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2234 * this method
2235 * @since 1.6
2236 */
2237 void setBinaryStream(String parameterName, java.io.InputStream x,
2238 long length) throws SQLException;
2239 /**
2240 * Sets the designated parameter to the given <code>Reader</code>
2241 * object, which is the given number of characters long.
2242 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2243 * parameter, it may be more practical to send it via a
2244 * <code>java.io.Reader</code> object. The data will be read from the stream
2245 * as needed until end-of-file is reached. The JDBC driver will
2246 * do any necessary conversion from UNICODE to the database char format.
2247 *
2248 * <P><B>Note:</B> This stream object can either be a standard
2249 * Java stream object or your own subclass that implements the
2250 * standard interface.
2251 *
2252 * @param parameterName the name of the parameter
2253 * @param reader the <code>java.io.Reader</code> object that
2254 * contains the UNICODE data used as the designated parameter
2255 * @param length the number of characters in the stream
2256 * @exception SQLException if parameterName does not correspond to a named
2257 * parameter; if a database access error occurs or
2258 * this method is called on a closed <code>CallableStatement</code>
2259 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2260 * this method
2261 * @since 1.6
2262 */
2263 void setCharacterStream(String parameterName,
2264 java.io.Reader reader,
2265 long length) throws SQLException;
2266 //--
2267 /**
2268 * Sets the designated parameter to the given input stream.
2269 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2270 * parameter, it may be more practical to send it via a
2271 * <code>java.io.InputStream</code>. Data will be read from the stream
2272 * as needed until end-of-file is reached. The JDBC driver will
2273 * do any necessary conversion from ASCII to the database char format.
2274 *
2275 * <P><B>Note:</B> This stream object can either be a standard
2276 * Java stream object or your own subclass that implements the
2277 * standard interface.
2278 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2279 * it might be more efficient to use a version of
2280 * <code>setAsciiStream</code> which takes a length parameter.
2281 *
2282 * @param parameterName the name of the parameter
2283 * @param x the Java input stream that contains the ASCII parameter value
2284 * @exception SQLException if parameterName does not correspond to a named
2285 * parameter; if a database access error occurs or
2286 * this method is called on a closed <code>CallableStatement</code>
2287 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2288 * @since 1.6
2289 */
2290 void setAsciiStream(String parameterName, java.io.InputStream x)
2291 throws SQLException;
2292 /**
2293 * Sets the designated parameter to the given input stream.
2294 * When a very large binary value is input to a <code>LONGVARBINARY</code>
2295 * parameter, it may be more practical to send it via a
2296 * <code>java.io.InputStream</code> object. The data will be read from the
2297 * stream as needed until end-of-file is reached.
2298 *
2299 * <P><B>Note:</B> This stream object can either be a standard
2300 * Java stream object or your own subclass that implements the
2301 * standard interface.
2302 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2303 * it might be more efficient to use a version of
2304 * <code>setBinaryStream</code> which takes a length parameter.
2305 *
2306 * @param parameterName the name of the parameter
2307 * @param x the java input stream which contains the binary parameter value
2308 * @exception SQLException if parameterName does not correspond to a named
2309 * parameter; if a database access error occurs or
2310 * this method is called on a closed <code>CallableStatement</code>
2311 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2312 * @since 1.6
2313 */
2314 void setBinaryStream(String parameterName, java.io.InputStream x)
2315 throws SQLException;
2316 /**
2317 * Sets the designated parameter to the given <code>Reader</code>
2318 * object.
2319 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2320 * parameter, it may be more practical to send it via a
2321 * <code>java.io.Reader</code> object. The data will be read from the stream
2322 * as needed until end-of-file is reached. The JDBC driver will
2323 * do any necessary conversion from UNICODE to the database char format.
2324 *
2325 * <P><B>Note:</B> This stream object can either be a standard
2326 * Java stream object or your own subclass that implements the
2327 * standard interface.
2328 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2329 * it might be more efficient to use a version of
2330 * <code>setCharacterStream</code> which takes a length parameter.
2331 *
2332 * @param parameterName the name of the parameter
2333 * @param reader the <code>java.io.Reader</code> object that contains the
2334 * Unicode data
2335 * @exception SQLException if parameterName does not correspond to a named
2336 * parameter; if a database access error occurs or
2337 * this method is called on a closed <code>CallableStatement</code>
2338 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2339 * @since 1.6
2340 */
2341 void setCharacterStream(String parameterName,
2342 java.io.Reader reader) throws SQLException;
2343 /**
2344 * Sets the designated parameter to a <code>Reader</code> object. The
2345 * <code>Reader</code> reads the data till end-of-file is reached. The
2346 * driver does the necessary conversion from Java character format to
2347 * the national character set in the database.
2348
2349 * <P><B>Note:</B> This stream object can either be a standard
2350 * Java stream object or your own subclass that implements the
2351 * standard interface.
2352 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2353 * it might be more efficient to use a version of
2354 * <code>setNCharacterStream</code> which takes a length parameter.
2355 *
2356 * @param parameterName the name of the parameter
2357 * @param value the parameter value
2358 * @throws SQLException if parameterName does not correspond to a named
2359 * parameter; if the driver does not support national
2360 * character sets; if the driver can detect that a data conversion
2361 * error could occur; if a database access error occurs; or
2362 * this method is called on a closed <code>CallableStatement</code>
2363 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2364 * @since 1.6
2365 */
2366 void setNCharacterStream(String parameterName, Reader value) throws SQLException;
2367
2368 /**
2369 * Sets the designated parameter to a <code>Reader</code> object.
2370 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2371 * because it informs the driver that the parameter value should be sent to
2372 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
2373 * driver may have to do extra work to determine whether the parameter
2374 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
2375 *
2376 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2377 * it might be more efficient to use a version of
2378 * <code>setClob</code> which takes a length parameter.
2379 *
2380 * @param parameterName the name of the parameter
2381 * @param reader An object that contains the data to set the parameter value to.
2382 * @throws SQLException if parameterName does not correspond to a named
2383 * parameter; if a database access error occurs or this method is called on
2384 * a closed <code>CallableStatement</code>
2385 *
2386 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2387 * @since 1.6
2388 */
2389 void setClob(String parameterName, Reader reader)
2390 throws SQLException;
2391
2392 /**
2393 * Sets the designated parameter to a <code>InputStream</code> object.
2394 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
2395 * method because it informs the driver that the parameter value should be
2396 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
2397 * the driver may have to do extra work to determine whether the parameter
2398 * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
2399 *
2400 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2401 * it might be more efficient to use a version of
2402 * <code>setBlob</code> which takes a length parameter.
2403 *
2404 * @param parameterName the name of the parameter
2405 * @param inputStream An object that contains the data to set the parameter
2406 * value to.
2407 * @throws SQLException if parameterName does not correspond to a named
2408 * parameter; if a database access error occurs or
2409 * this method is called on a closed <code>CallableStatement</code>
2410 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2411 *
2412 * @since 1.6
2413 */
2414 void setBlob(String parameterName, InputStream inputStream)
2415 throws SQLException;
2416 /**
2417 * Sets the designated parameter to a <code>Reader</code> object.
2418 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2419 * because it informs the driver that the parameter value should be sent to
2420 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2421 * driver may have to do extra work to determine whether the parameter
2422 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2423 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2424 * it might be more efficient to use a version of
2425 * <code>setNClob</code> which takes a length parameter.
2426 *
2427 * @param parameterName the name of the parameter
2428 * @param reader An object that contains the data to set the parameter value to.
2429 * @throws SQLException if parameterName does not correspond to a named
2430 * parameter; if the driver does not support national character sets;
2431 * if the driver can detect that a data conversion
2432 * error could occur; if a database access error occurs or
2433 * this method is called on a closed <code>CallableStatement</code>
2434 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2435 *
2436 * @since 1.6
2437 */
2438 void setNClob(String parameterName, Reader reader)
2439 throws SQLException;
2440
2441 //------------------------- JDBC 4.1 -----------------------------------
2442
2443
2444 /**
2445 *<p>Returns an object representing the value of OUT parameter
2446 * {@code parameterIndex} and will convert from the
2447 * SQL type of the parameter to the requested Java data type, if the
2448 * conversion is supported. If the conversion is not
2449 * supported or null is specified for the type, a
2450 * <code>SQLException</code> is thrown.
2451 *<p>
2452 * At a minimum, an implementation must support the conversions defined in
2453 * Appendix B, Table B-3 and conversion of appropriate user defined SQL
2454 * types to a Java type which implements {@code SQLData}, or {@code Struct}.
2455 * Additional conversions may be supported and are vendor defined.
2456 *
2457 * @param parameterIndex the first parameter is 1, the second is 2, and so on
2458 * @param type Class representing the Java data type to convert the
2459 * designated parameter to.
2460 * @return an instance of {@code type} holding the OUT parameter value
2461 * @throws SQLException if conversion is not supported, type is null or
2462 * another error occurs. The getCause() method of the
2463 * exception may provide a more detailed exception, for example, if
2464 * a conversion error occurs
2465 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support
2466 * this method
2467 * @since 1.7
2468 */
2469 public <T> T getObject(int parameterIndex, Class<T> type) throws SQLException;
2470
2471
2472 /**
2473 *<p>Returns an object representing the value of OUT parameter
2474 * {@code parameterName} and will convert from the
2475 * SQL type of the parameter to the requested Java data type, if the
2476 * conversion is supported. If the conversion is not
2477 * supported or null is specified for the type, a
2478 * <code>SQLException</code> is thrown.
2479 *<p>
2480 * At a minimum, an implementation must support the conversions defined in
2481 * Appendix B, Table B-3 and conversion of appropriate user defined SQL
2482 * types to a Java type which implements {@code SQLData}, or {@code Struct}.
2483 * Additional conversions may be supported and are vendor defined.
2484 *
2485 * @param parameterName the name of the parameter
2486 * @param type Class representing the Java data type to convert
2487 * the designated parameter to.
2488 * @return an instance of {@code type} holding the OUT parameter
2489 * value
2490 * @throws SQLException if conversion is not supported, type is null or
2491 * another error occurs. The getCause() method of the
2492 * exception may provide a more detailed exception, for example, if
2493 * a conversion error occurs
2494 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support
2495 * this method
2496 * @since 1.7
2497 */
2498 public <T> T getObject(String parameterName, Class<T> type) throws SQLException;
2499
2500 }