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