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