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