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