1/* 2 * Copyright (c) 1996, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package java.sql; 27 28import java.math.BigDecimal; 29import java.util.Calendar; 30import java.io.Reader; 31import java.io.InputStream; 32 33/** 34 * An object that represents a precompiled SQL statement. 35 * <P>A SQL statement is precompiled and stored in a 36 * <code>PreparedStatement</code> object. This object can then be used to 37 * efficiently execute this statement multiple times. 38 * 39 * <P><B>Note:</B> The setter methods (<code>setShort</code>, <code>setString</code>, 40 * and so on) for setting IN parameter values 41 * must specify types that are compatible with the defined SQL type of 42 * the input parameter. For instance, if the IN parameter has SQL type 43 * <code>INTEGER</code>, then the method <code>setInt</code> should be used. 44 * 45 * <p>If arbitrary parameter type conversions are required, the method 46 * <code>setObject</code> should be used with a target SQL type. 47 * <P> 48 * In the following example of setting a parameter, <code>con</code> represents 49 * an active connection: 50 * <PRE> 51 * PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES 52 * SET SALARY = ? WHERE ID = ?"); 53 * pstmt.setBigDecimal(1, 153833.00) 54 * pstmt.setInt(2, 110592) 55 * </PRE> 56 * 57 * @see Connection#prepareStatement 58 * @see ResultSet 59 * @since 1.1 60 */ 61 62public interface PreparedStatement extends Statement { 63 64 /** 65 * Executes the SQL query in this <code>PreparedStatement</code> object 66 * and returns the <code>ResultSet</code> object generated by the query. 67 * 68 * @return a <code>ResultSet</code> object that contains the data produced by the 69 * query; never <code>null</code> 70 * @exception SQLException if a database access error occurs; 71 * this method is called on a closed <code>PreparedStatement</code> or the SQL 72 * statement does not return a <code>ResultSet</code> object 73 * @throws SQLTimeoutException when the driver has determined that the 74 * timeout value that was specified by the {@code setQueryTimeout} 75 * method has been exceeded and has at least attempted to cancel 76 * the currently running {@code Statement} 77 */ 78 ResultSet executeQuery() throws SQLException; 79 80 /** 81 * Executes the SQL statement in this <code>PreparedStatement</code> object, 82 * which must be an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or 83 * <code>DELETE</code>; or an SQL statement that returns nothing, 84 * such as a DDL statement. 85 * 86 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements 87 * or (2) 0 for SQL statements that return nothing 88 * @exception SQLException if a database access error occurs; 89 * this method is called on a closed <code>PreparedStatement</code> 90 * or the SQL statement returns a <code>ResultSet</code> object 91 * @throws SQLTimeoutException when the driver has determined that the 92 * timeout value that was specified by the {@code setQueryTimeout} 93 * method has been exceeded and has at least attempted to cancel 94 * the currently running {@code Statement} 95 */ 96 int executeUpdate() throws SQLException; 97 98 /** 99 * Sets the designated parameter to SQL <code>NULL</code>. 100 * 101 * <P><B>Note:</B> You must specify the parameter's SQL type. 102 * 103 * @param parameterIndex the first parameter is 1, the second is 2, ... 104 * @param sqlType the SQL type code defined in <code>java.sql.Types</code> 105 * @exception SQLException if parameterIndex does not correspond to a parameter 106 * marker in the SQL statement; if a database access error occurs or 107 * this method is called on a closed <code>PreparedStatement</code> 108 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is 109 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 110 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 111 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 112 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 113 * or <code>STRUCT</code> data type and the JDBC driver does not support 114 * this data type 115 */ 116 void setNull(int parameterIndex, int sqlType) throws SQLException; 117 118 /** 119 * Sets the designated parameter to the given Java <code>boolean</code> value. 120 * The driver converts this 121 * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database. 122 * 123 * @param parameterIndex the first parameter is 1, the second is 2, ... 124 * @param x the parameter value 125 * @exception SQLException if parameterIndex does not correspond to a parameter 126 * marker in the SQL statement; 127 * if a database access error occurs or 128 * this method is called on a closed <code>PreparedStatement</code> 129 */ 130 void setBoolean(int parameterIndex, boolean x) throws SQLException; 131 132 /** 133 * Sets the designated parameter to the given Java <code>byte</code> value. 134 * The driver converts this 135 * to an SQL <code>TINYINT</code> value when it sends it to the database. 136 * 137 * @param parameterIndex the first parameter is 1, the second is 2, ... 138 * @param x the parameter value 139 * @exception SQLException if parameterIndex does not correspond to a parameter 140 * marker in the SQL statement; if a database access error occurs or 141 * this method is called on a closed <code>PreparedStatement</code> 142 */ 143 void setByte(int parameterIndex, byte x) throws SQLException; 144 145 /** 146 * Sets the designated parameter to the given Java <code>short</code> value. 147 * The driver converts this 148 * to an SQL <code>SMALLINT</code> value when it sends it to the database. 149 * 150 * @param parameterIndex the first parameter is 1, the second is 2, ... 151 * @param x the parameter value 152 * @exception SQLException if parameterIndex does not correspond to a parameter 153 * marker in the SQL statement; if a database access error occurs or 154 * this method is called on a closed <code>PreparedStatement</code> 155 */ 156 void setShort(int parameterIndex, short x) throws SQLException; 157 158 /** 159 * Sets the designated parameter to the given Java <code>int</code> value. 160 * The driver converts this 161 * to an SQL <code>INTEGER</code> value when it sends it to the database. 162 * 163 * @param parameterIndex the first parameter is 1, the second is 2, ... 164 * @param x the parameter value 165 * @exception SQLException if parameterIndex does not correspond to a parameter 166 * marker in the SQL statement; if a database access error occurs or 167 * this method is called on a closed <code>PreparedStatement</code> 168 */ 169 void setInt(int parameterIndex, int x) throws SQLException; 170 171 /** 172 * Sets the designated parameter to the given Java <code>long</code> value. 173 * The driver converts this 174 * to an SQL <code>BIGINT</code> value when it sends it to the database. 175 * 176 * @param parameterIndex the first parameter is 1, the second is 2, ... 177 * @param x the parameter value 178 * @exception SQLException if parameterIndex does not correspond to a parameter 179 * marker in the SQL statement; if a database access error occurs or 180 * this method is called on a closed <code>PreparedStatement</code> 181 */ 182 void setLong(int parameterIndex, long x) throws SQLException; 183 184 /** 185 * Sets the designated parameter to the given Java <code>float</code> value. 186 * The driver converts this 187 * to an SQL <code>REAL</code> value when it sends it to the database. 188 * 189 * @param parameterIndex the first parameter is 1, the second is 2, ... 190 * @param x the parameter value 191 * @exception SQLException if parameterIndex does not correspond to a parameter 192 * marker in the SQL statement; if a database access error occurs or 193 * this method is called on a closed <code>PreparedStatement</code> 194 */ 195 void setFloat(int parameterIndex, float x) throws SQLException; 196 197 /** 198 * Sets the designated parameter to the given Java <code>double</code> value. 199 * The driver converts this 200 * to an SQL <code>DOUBLE</code> value when it sends it to the database. 201 * 202 * @param parameterIndex the first parameter is 1, the second is 2, ... 203 * @param x the parameter value 204 * @exception SQLException if parameterIndex does not correspond to a parameter 205 * marker in the SQL statement; if a database access error occurs or 206 * this method is called on a closed <code>PreparedStatement</code> 207 */ 208 void setDouble(int parameterIndex, double x) throws SQLException; 209 210 /** 211 * Sets the designated parameter to the given <code>java.math.BigDecimal</code> value. 212 * The driver converts this to an SQL <code>NUMERIC</code> value when 213 * it sends it to the database. 214 * 215 * @param parameterIndex the first parameter is 1, the second is 2, ... 216 * @param x the parameter value 217 * @exception SQLException if parameterIndex does not correspond to a parameter 218 * marker in the SQL statement; if a database access error occurs or 219 * this method is called on a closed <code>PreparedStatement</code> 220 */ 221 void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException; 222 223 /** 224 * Sets the designated parameter to the given Java <code>String</code> value. 225 * The driver converts this 226 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value 227 * (depending on the argument's 228 * size relative to the driver's limits on <code>VARCHAR</code> values) 229 * when it sends it to the database. 230 * 231 * @param parameterIndex the first parameter is 1, the second is 2, ... 232 * @param x the parameter value 233 * @exception SQLException if parameterIndex does not correspond to a parameter 234 * marker in the SQL statement; if a database access error occurs or 235 * this method is called on a closed <code>PreparedStatement</code> 236 */ 237 void setString(int parameterIndex, String x) throws SQLException; 238 239 /** 240 * Sets the designated parameter to the given Java array of bytes. The driver converts 241 * this to an SQL <code>VARBINARY</code> or <code>LONGVARBINARY</code> 242 * (depending on the argument's size relative to the driver's limits on 243 * <code>VARBINARY</code> values) when it sends it to the database. 244 * 245 * @param parameterIndex the first parameter is 1, the second is 2, ... 246 * @param x the parameter value 247 * @exception SQLException if parameterIndex does not correspond to a parameter 248 * marker in the SQL statement; if a database access error occurs or 249 * this method is called on a closed <code>PreparedStatement</code> 250 */ 251 void setBytes(int parameterIndex, byte x[]) throws SQLException; 252 253 /** 254 * Sets the designated parameter to the given <code>java.sql.Date</code> value 255 * using the default time zone of the virtual machine that is running 256 * the application. 257 * The driver converts this 258 * to an SQL <code>DATE</code> value when it sends it to the database. 259 * 260 * @param parameterIndex the first parameter is 1, the second is 2, ... 261 * @param x the parameter value 262 * @exception SQLException if parameterIndex does not correspond to a parameter 263 * marker in the SQL statement; if a database access error occurs or 264 * this method is called on a closed <code>PreparedStatement</code> 265 */ 266 void setDate(int parameterIndex, java.sql.Date x) 267 throws SQLException; 268 269 /** 270 * Sets the designated parameter to the given <code>java.sql.Time</code> value. 271 * The driver converts this 272 * to an SQL <code>TIME</code> value when it sends it to the database. 273 * 274 * @param parameterIndex the first parameter is 1, the second is 2, ... 275 * @param x the parameter value 276 * @exception SQLException if parameterIndex does not correspond to a parameter 277 * marker in the SQL statement; if a database access error occurs or 278 * this method is called on a closed <code>PreparedStatement</code> 279 */ 280 void setTime(int parameterIndex, java.sql.Time x) 281 throws SQLException; 282 283 /** 284 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value. 285 * The driver 286 * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the 287 * database. 288 * 289 * @param parameterIndex the first parameter is 1, the second is 2, ... 290 * @param x the parameter value 291 * @exception SQLException if parameterIndex does not correspond to a parameter 292 * marker in the SQL statement; if a database access error occurs or 293 * this method is called on a closed <code>PreparedStatement</code> */ 294 void setTimestamp(int parameterIndex, java.sql.Timestamp x) 295 throws SQLException; 296 297 /** 298 * Sets the designated parameter to the given input stream, which will have 299 * the specified number of bytes. 300 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 301 * parameter, it may be more practical to send it via a 302 * <code>java.io.InputStream</code>. Data will be read from the stream 303 * as needed until end-of-file is reached. The JDBC driver will 304 * do any necessary conversion from ASCII to the database char format. 305 * 306 * <P><B>Note:</B> This stream object can either be a standard 307 * Java stream object or your own subclass that implements the 308 * standard interface. 309 * 310 * @param parameterIndex the first parameter is 1, the second is 2, ... 311 * @param x the Java input stream that contains the ASCII parameter value 312 * @param length the number of bytes in the stream 313 * @exception SQLException if parameterIndex does not correspond to a parameter 314 * marker in the SQL statement; if a database access error occurs or 315 * this method is called on a closed <code>PreparedStatement</code> 316 */ 317 void setAsciiStream(int parameterIndex, java.io.InputStream x, int length) 318 throws SQLException; 319 320 /** 321 * Sets the designated parameter to the given input stream, which 322 * will have the specified number of bytes. 323 * 324 * When a very large Unicode value is input to a <code>LONGVARCHAR</code> 325 * parameter, it may be more practical to send it via a 326 * <code>java.io.InputStream</code> object. The data will be read from the 327 * stream as needed until end-of-file is reached. The JDBC driver will 328 * do any necessary conversion from Unicode to the database char format. 329 * 330 *The byte format of the Unicode stream must be a Java UTF-8, as defined in the 331 *Java Virtual Machine Specification. 332 * 333 * <P><B>Note:</B> This stream object can either be a standard 334 * Java stream object or your own subclass that implements the 335 * standard interface. 336 * 337 * @param parameterIndex the first parameter is 1, the second is 2, ... 338 * @param x a <code>java.io.InputStream</code> object that contains the 339 * Unicode parameter value 340 * @param length the number of bytes in the stream 341 * @exception SQLException if parameterIndex does not correspond to a parameter 342 * marker in the SQL statement; if a database access error occurs or 343 * this method is called on a closed <code>PreparedStatement</code> 344 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 345 * this method 346 * @deprecated Use {@code setCharacterStream} 347 */ 348 @Deprecated(since="1.2") 349 void setUnicodeStream(int parameterIndex, java.io.InputStream x, 350 int length) throws SQLException; 351 352 /** 353 * Sets the designated parameter to the given input stream, which will have 354 * the specified number of bytes. 355 * When a very large binary value is input to a <code>LONGVARBINARY</code> 356 * parameter, it may be more practical to send it via a 357 * <code>java.io.InputStream</code> object. The data will be read from the 358 * stream as needed until end-of-file is reached. 359 * 360 * <P><B>Note:</B> This stream object can either be a standard 361 * Java stream object or your own subclass that implements the 362 * standard interface. 363 * 364 * @param parameterIndex the first parameter is 1, the second is 2, ... 365 * @param x the java input stream which contains the binary parameter value 366 * @param length the number of bytes in the stream 367 * @exception SQLException if parameterIndex does not correspond to a parameter 368 * marker in the SQL statement; if a database access error occurs or 369 * this method is called on a closed <code>PreparedStatement</code> 370 */ 371 void setBinaryStream(int parameterIndex, java.io.InputStream x, 372 int length) throws SQLException; 373 374 /** 375 * Clears the current parameter values immediately. 376 * <P>In general, parameter values remain in force for repeated use of a 377 * statement. Setting a parameter value automatically clears its 378 * previous value. However, in some cases it is useful to immediately 379 * release the resources used by the current parameter values; this can 380 * be done by calling the method <code>clearParameters</code>. 381 * 382 * @exception SQLException if a database access error occurs or 383 * this method is called on a closed <code>PreparedStatement</code> 384 */ 385 void clearParameters() throws SQLException; 386 387 //---------------------------------------------------------------------- 388 // Advanced features: 389 390 /** 391 * Sets the value of the designated parameter with the given object. 392 * 393 * This method is similar to {@link #setObject(int parameterIndex, 394 * Object x, int targetSqlType, int scaleOrLength)}, 395 * except that it assumes a scale of zero. 396 * 397 * @param parameterIndex the first parameter is 1, the second is 2, ... 398 * @param x the object containing the input parameter value 399 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 400 * sent to the database 401 * @exception SQLException if parameterIndex does not correspond to a parameter 402 * marker in the SQL statement; if a database access error occurs or this 403 * method is called on a closed PreparedStatement 404 * @exception SQLFeatureNotSupportedException if 405 * the JDBC driver does not support the specified targetSqlType 406 * @see Types 407 */ 408 void setObject(int parameterIndex, Object x, int targetSqlType) 409 throws SQLException; 410 411 /** 412 * <p>Sets the value of the designated parameter using the given object. 413 * 414 * <p>The JDBC specification specifies a standard mapping from 415 * Java <code>Object</code> types to SQL types. The given argument 416 * will be converted to the corresponding SQL type before being 417 * sent to the database. 418 * 419 * <p>Note that this method may be used to pass database- 420 * specific abstract data types, by using a driver-specific Java 421 * type. 422 * 423 * If the object is of a class implementing the interface <code>SQLData</code>, 424 * the JDBC driver should call the method <code>SQLData.writeSQL</code> 425 * to write it to the SQL data stream. 426 * If, on the other hand, the object is of a class implementing 427 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 428 * <code>Struct</code>, <code>java.net.URL</code>, <code>RowId</code>, <code>SQLXML</code> 429 * or <code>Array</code>, the driver should pass it to the database as a 430 * value of the corresponding SQL type. 431 * <P> 432 *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to 433 * the backend. For maximum portability, the <code>setNull</code> or the 434 * <code>setObject(int parameterIndex, Object x, int sqlType)</code> 435 * method should be used 436 * instead of <code>setObject(int parameterIndex, Object x)</code>. 437 *<p> 438 * <b>Note:</b> This method throws an exception if there is an ambiguity, for example, if the 439 * object is of a class implementing more than one of the interfaces named above. 440 * 441 * @param parameterIndex the first parameter is 1, the second is 2, ... 442 * @param x the object containing the input parameter value 443 * @exception SQLException if parameterIndex does not correspond to a parameter 444 * marker in the SQL statement; if a database access error occurs; 445 * this method is called on a closed <code>PreparedStatement</code> 446 * or the type of the given object is ambiguous 447 */ 448 void setObject(int parameterIndex, Object x) throws SQLException; 449 450 /** 451 * Executes the SQL statement in this <code>PreparedStatement</code> object, 452 * which may be any kind of SQL statement. 453 * Some prepared statements return multiple results; the <code>execute</code> 454 * method handles these complex statements as well as the simpler 455 * form of statements handled by the methods <code>executeQuery</code> 456 * and <code>executeUpdate</code>. 457 * <P> 458 * The <code>execute</code> method returns a <code>boolean</code> to 459 * indicate the form of the first result. You must call either the method 460 * <code>getResultSet</code> or <code>getUpdateCount</code> 461 * to retrieve the result; you must call <code>getMoreResults</code> to 462 * move to any subsequent result(s). 463 * 464 * @return <code>true</code> if the first result is a <code>ResultSet</code> 465 * object; <code>false</code> if the first result is an update 466 * count or there is no result 467 * @exception SQLException if a database access error occurs; 468 * this method is called on a closed <code>PreparedStatement</code> 469 * or an argument is supplied to this method 470 * @throws SQLTimeoutException when the driver has determined that the 471 * timeout value that was specified by the {@code setQueryTimeout} 472 * method has been exceeded and has at least attempted to cancel 473 * the currently running {@code Statement} 474 * @see Statement#execute 475 * @see Statement#getResultSet 476 * @see Statement#getUpdateCount 477 * @see Statement#getMoreResults 478 479 */ 480 boolean execute() throws SQLException; 481 482 //--------------------------JDBC 2.0----------------------------- 483 484 /** 485 * Adds a set of parameters to this <code>PreparedStatement</code> 486 * object's batch of commands. 487 * 488 * @exception SQLException if a database access error occurs or 489 * this method is called on a closed <code>PreparedStatement</code> 490 * @see Statement#addBatch 491 * @since 1.2 492 */ 493 void addBatch() throws SQLException; 494 495 /** 496 * Sets the designated parameter to the given <code>Reader</code> 497 * object, which is the given number of characters long. 498 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 499 * parameter, it may be more practical to send it via a 500 * <code>java.io.Reader</code> object. The data will be read from the stream 501 * as needed until end-of-file is reached. The JDBC driver will 502 * do any necessary conversion from UNICODE to the database char format. 503 * 504 * <P><B>Note:</B> This stream object can either be a standard 505 * Java stream object or your own subclass that implements the 506 * standard interface. 507 * 508 * @param parameterIndex the first parameter is 1, the second is 2, ... 509 * @param reader the <code>java.io.Reader</code> object that contains the 510 * Unicode data 511 * @param length the number of characters in the stream 512 * @exception SQLException if parameterIndex does not correspond to a parameter 513 * marker in the SQL statement; if a database access error occurs or 514 * this method is called on a closed <code>PreparedStatement</code> 515 * @since 1.2 516 */ 517 void setCharacterStream(int parameterIndex, 518 java.io.Reader reader, 519 int length) throws SQLException; 520 521 /** 522 * Sets the designated parameter to the given 523 * <code>REF(<structured-type>)</code> value. 524 * The driver converts this to an SQL <code>REF</code> value when it 525 * sends it to the database. 526 * 527 * @param parameterIndex the first parameter is 1, the second is 2, ... 528 * @param x an SQL <code>REF</code> value 529 * @exception SQLException if parameterIndex does not correspond to a parameter 530 * marker in the SQL statement; if a database access error occurs or 531 * this method is called on a closed <code>PreparedStatement</code> 532 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 533 * @since 1.2 534 */ 535 void setRef (int parameterIndex, Ref x) throws SQLException; 536 537 /** 538 * Sets the designated parameter to the given <code>java.sql.Blob</code> object. 539 * The driver converts this to an SQL <code>BLOB</code> value when it 540 * sends it to the database. 541 * 542 * @param parameterIndex the first parameter is 1, the second is 2, ... 543 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value 544 * @exception SQLException if parameterIndex does not correspond to a parameter 545 * marker in the SQL statement; if a database access error occurs or 546 * this method is called on a closed <code>PreparedStatement</code> 547 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 548 * @since 1.2 549 */ 550 void setBlob (int parameterIndex, Blob x) throws SQLException; 551 552 /** 553 * Sets the designated parameter to the given <code>java.sql.Clob</code> object. 554 * The driver converts this to an SQL <code>CLOB</code> value when it 555 * sends it to the database. 556 * 557 * @param parameterIndex the first parameter is 1, the second is 2, ... 558 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value 559 * @exception SQLException if parameterIndex does not correspond to a parameter 560 * marker in the SQL statement; if a database access error occurs or 561 * this method is called on a closed <code>PreparedStatement</code> 562 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 563 * @since 1.2 564 */ 565 void setClob (int parameterIndex, Clob x) throws SQLException; 566 567 /** 568 * Sets the designated parameter to the given <code>java.sql.Array</code> object. 569 * The driver converts this to an SQL <code>ARRAY</code> value when it 570 * sends it to the database. 571 * 572 * @param parameterIndex the first parameter is 1, the second is 2, ... 573 * @param x an <code>Array</code> object that maps an SQL <code>ARRAY</code> value 574 * @exception SQLException if parameterIndex does not correspond to a parameter 575 * marker in the SQL statement; if a database access error occurs or 576 * this method is called on a closed <code>PreparedStatement</code> 577 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 578 * @since 1.2 579 */ 580 void setArray (int parameterIndex, Array x) throws SQLException; 581 582 /** 583 * Retrieves a <code>ResultSetMetaData</code> object that contains 584 * information about the columns of the <code>ResultSet</code> object 585 * that will be returned when this <code>PreparedStatement</code> object 586 * is executed. 587 * <P> 588 * Because a <code>PreparedStatement</code> object is precompiled, it is 589 * possible to know about the <code>ResultSet</code> object that it will 590 * return without having to execute it. Consequently, it is possible 591 * to invoke the method <code>getMetaData</code> on a 592 * <code>PreparedStatement</code> object rather than waiting to execute 593 * it and then invoking the <code>ResultSet.getMetaData</code> method 594 * on the <code>ResultSet</code> object that is returned. 595 * <P> 596 * <B>NOTE:</B> Using this method may be expensive for some drivers due 597 * to the lack of underlying DBMS support. 598 * 599 * @return the description of a <code>ResultSet</code> object's columns or 600 * <code>null</code> if the driver cannot return a 601 * <code>ResultSetMetaData</code> object 602 * @exception SQLException if a database access error occurs or 603 * this method is called on a closed <code>PreparedStatement</code> 604 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 605 * this method 606 * @since 1.2 607 */ 608 ResultSetMetaData getMetaData() throws SQLException; 609 610 /** 611 * Sets the designated parameter to the given <code>java.sql.Date</code> value, 612 * using the given <code>Calendar</code> object. The driver uses 613 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value, 614 * which the driver then sends to the database. With 615 * a <code>Calendar</code> object, the driver can calculate the date 616 * taking into account a custom timezone. If no 617 * <code>Calendar</code> object is specified, the driver uses the default 618 * timezone, which is that of the virtual machine running the application. 619 * 620 * @param parameterIndex the first parameter is 1, the second is 2, ... 621 * @param x the parameter value 622 * @param cal the <code>Calendar</code> object the driver will use 623 * to construct the date 624 * @exception SQLException if parameterIndex does not correspond to a parameter 625 * marker in the SQL statement; if a database access error occurs or 626 * this method is called on a closed <code>PreparedStatement</code> 627 * @since 1.2 628 */ 629 void setDate(int parameterIndex, java.sql.Date x, Calendar cal) 630 throws SQLException; 631 632 /** 633 * Sets the designated parameter to the given <code>java.sql.Time</code> value, 634 * using the given <code>Calendar</code> object. The driver uses 635 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value, 636 * which the driver then sends to the database. With 637 * a <code>Calendar</code> object, the driver can calculate the time 638 * taking into account a custom timezone. If no 639 * <code>Calendar</code> object is specified, the driver uses the default 640 * timezone, which is that of the virtual machine running the application. 641 * 642 * @param parameterIndex the first parameter is 1, the second is 2, ... 643 * @param x the parameter value 644 * @param cal the <code>Calendar</code> object the driver will use 645 * to construct the time 646 * @exception SQLException if parameterIndex does not correspond to a parameter 647 * marker in the SQL statement; if a database access error occurs or 648 * this method is called on a closed <code>PreparedStatement</code> 649 * @since 1.2 650 */ 651 void setTime(int parameterIndex, java.sql.Time x, Calendar cal) 652 throws SQLException; 653 654 /** 655 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value, 656 * using the given <code>Calendar</code> object. The driver uses 657 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value, 658 * which the driver then sends to the database. With a 659 * <code>Calendar</code> object, the driver can calculate the timestamp 660 * taking into account a custom timezone. If no 661 * <code>Calendar</code> object is specified, the driver uses the default 662 * timezone, which is that of the virtual machine running the application. 663 * 664 * @param parameterIndex the first parameter is 1, the second is 2, ... 665 * @param x the parameter value 666 * @param cal the <code>Calendar</code> object the driver will use 667 * to construct the timestamp 668 * @exception SQLException if parameterIndex does not correspond to a parameter 669 * marker in the SQL statement; if a database access error occurs or 670 * this method is called on a closed <code>PreparedStatement</code> 671 * @since 1.2 672 */ 673 void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) 674 throws SQLException; 675 676 /** 677 * Sets the designated parameter to SQL <code>NULL</code>. 678 * This version of the method <code>setNull</code> should 679 * be used for user-defined types and REF type parameters. Examples 680 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and 681 * named array types. 682 * 683 * <P><B>Note:</B> To be portable, applications must give the 684 * SQL type code and the fully-qualified SQL type name when specifying 685 * a NULL user-defined or REF parameter. In the case of a user-defined type 686 * the name is the type name of the parameter itself. For a REF 687 * parameter, the name is the type name of the referenced type. If 688 * a JDBC driver does not need the type code or type name information, 689 * it may ignore it. 690 * 691 * Although it is intended for user-defined and Ref parameters, 692 * this method may be used to set a null parameter of any JDBC type. 693 * If the parameter does not have a user-defined or REF type, the given 694 * typeName is ignored. 695 * 696 * 697 * @param parameterIndex the first parameter is 1, the second is 2, ... 698 * @param sqlType a value from <code>java.sql.Types</code> 699 * @param typeName the fully-qualified name of an SQL user-defined type; 700 * ignored if the parameter is not a user-defined type or REF 701 * @exception SQLException if parameterIndex does not correspond to a parameter 702 * marker in the SQL statement; if a database access error occurs or 703 * this method is called on a closed <code>PreparedStatement</code> 704 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is 705 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 706 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 707 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 708 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 709 * or <code>STRUCT</code> data type and the JDBC driver does not support 710 * this data type or if the JDBC driver does not support this method 711 * @since 1.2 712 */ 713 void setNull (int parameterIndex, int sqlType, String typeName) 714 throws SQLException; 715 716 //------------------------- JDBC 3.0 ----------------------------------- 717 718 /** 719 * Sets the designated parameter to the given <code>java.net.URL</code> value. 720 * The driver converts this to an SQL <code>DATALINK</code> value 721 * when it sends it to the database. 722 * 723 * @param parameterIndex the first parameter is 1, the second is 2, ... 724 * @param x the <code>java.net.URL</code> object to be set 725 * @exception SQLException if parameterIndex does not correspond to a parameter 726 * marker in the SQL statement; if a database access error occurs or 727 * this method is called on a closed <code>PreparedStatement</code> 728 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 729 * @since 1.4 730 */ 731 void setURL(int parameterIndex, java.net.URL x) throws SQLException; 732 733 /** 734 * Retrieves the number, types and properties of this 735 * <code>PreparedStatement</code> object's parameters. 736 * 737 * @return a <code>ParameterMetaData</code> object that contains information 738 * about the number, types and properties for each 739 * parameter marker of this <code>PreparedStatement</code> object 740 * @exception SQLException if a database access error occurs or 741 * this method is called on a closed <code>PreparedStatement</code> 742 * @see ParameterMetaData 743 * @since 1.4 744 */ 745 ParameterMetaData getParameterMetaData() throws SQLException; 746 747 //------------------------- JDBC 4.0 ----------------------------------- 748 749 /** 750 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The 751 * driver converts this to a SQL <code>ROWID</code> value when it sends it 752 * to the database 753 * 754 * @param parameterIndex the first parameter is 1, the second is 2, ... 755 * @param x the parameter value 756 * @throws SQLException if parameterIndex does not correspond to a parameter 757 * marker in the SQL statement; if a database access error occurs or 758 * this method is called on a closed <code>PreparedStatement</code> 759 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 760 * 761 * @since 1.6 762 */ 763 void setRowId(int parameterIndex, RowId x) throws SQLException; 764 765 766 /** 767 * Sets the designated parameter to the given <code>String</code> object. 768 * The driver converts this to a SQL <code>NCHAR</code> or 769 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value 770 * (depending on the argument's 771 * size relative to the driver's limits on <code>NVARCHAR</code> values) 772 * when it sends it to the database. 773 * 774 * @param parameterIndex of the first parameter is 1, the second is 2, ... 775 * @param value the parameter value 776 * @throws SQLException if parameterIndex does not correspond to a parameter 777 * marker in the SQL statement; if the driver does not support national 778 * character sets; if the driver can detect that a data conversion 779 * error could occur; if a database access error occurs; or 780 * this method is called on a closed <code>PreparedStatement</code> 781 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 782 * @since 1.6 783 */ 784 void setNString(int parameterIndex, String value) throws SQLException; 785 786 /** 787 * Sets the designated parameter to a <code>Reader</code> object. The 788 * <code>Reader</code> reads the data till end-of-file is reached. The 789 * driver does the necessary conversion from Java character format to 790 * the national character set in the database. 791 * @param parameterIndex of the first parameter is 1, the second is 2, ... 792 * @param value the parameter value 793 * @param length the number of characters in the parameter data. 794 * @throws SQLException if parameterIndex does not correspond to a parameter 795 * marker in the SQL statement; if the driver does not support national 796 * character sets; if the driver can detect that a data conversion 797 * error could occur; if a database access error occurs; or 798 * this method is called on a closed <code>PreparedStatement</code> 799 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 800 * @since 1.6 801 */ 802 void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException; 803 804 /** 805 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a 806 * SQL <code>NCLOB</code> value when it sends it to the database. 807 * @param parameterIndex of the first parameter is 1, the second is 2, ... 808 * @param value the parameter value 809 * @throws SQLException if parameterIndex does not correspond to a parameter 810 * marker in the SQL statement; if the driver does not support national 811 * character sets; if the driver can detect that a data conversion 812 * error could occur; if a database access error occurs; or 813 * this method is called on a closed <code>PreparedStatement</code> 814 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 815 * @since 1.6 816 */ 817 void setNClob(int parameterIndex, NClob value) throws SQLException; 818 819 /** 820 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number 821 * of characters specified by length otherwise a <code>SQLException</code> will be 822 * generated when the <code>PreparedStatement</code> is executed. 823 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 824 * because it informs the driver that the parameter value should be sent to 825 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 826 * driver may have to do extra work to determine whether the parameter 827 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 828 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 829 * @param reader An object that contains the data to set the parameter value to. 830 * @param length the number of characters in the parameter data. 831 * @throws SQLException if parameterIndex does not correspond to a parameter 832 * marker in the SQL statement; if a database access error occurs; this method is called on 833 * a closed <code>PreparedStatement</code> or if the length specified is less than zero. 834 * 835 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 836 * @since 1.6 837 */ 838 void setClob(int parameterIndex, Reader reader, long length) 839 throws SQLException; 840 841 /** 842 * Sets the designated parameter to a <code>InputStream</code> object. 843 * The {@code Inputstream} must contain the number 844 * of characters specified by length otherwise a <code>SQLException</code> will be 845 * generated when the <code>PreparedStatement</code> is executed. 846 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code> 847 * method because it informs the driver that the parameter value should be 848 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 849 * the driver may have to do extra work to determine whether the parameter 850 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 851 * @param parameterIndex index of the first parameter is 1, 852 * the second is 2, ... 853 * @param inputStream An object that contains the data to set the parameter 854 * value to. 855 * @param length the number of bytes in the parameter data. 856 * @throws SQLException if parameterIndex does not correspond to a parameter 857 * marker in the SQL statement; if a database access error occurs; 858 * this method is called on a closed <code>PreparedStatement</code>; 859 * if the length specified 860 * is less than zero or if the number of bytes in the {@code InputStream} does not match 861 * the specified length. 862 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 863 * 864 * @since 1.6 865 */ 866 void setBlob(int parameterIndex, InputStream inputStream, long length) 867 throws SQLException; 868 /** 869 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number 870 * of characters specified by length otherwise a <code>SQLException</code> will be 871 * generated when the <code>PreparedStatement</code> is executed. 872 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 873 * because it informs the driver that the parameter value should be sent to 874 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 875 * driver may have to do extra work to determine whether the parameter 876 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 877 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 878 * @param reader An object that contains the data to set the parameter value to. 879 * @param length the number of characters in the parameter data. 880 * @throws SQLException if parameterIndex does not correspond to a parameter 881 * marker in the SQL statement; if the length specified is less than zero; 882 * if the driver does not support national character sets; 883 * if the driver can detect that a data conversion 884 * error could occur; if a database access error occurs or 885 * this method is called on a closed <code>PreparedStatement</code> 886 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 887 * 888 * @since 1.6 889 */ 890 void setNClob(int parameterIndex, Reader reader, long length) 891 throws SQLException; 892 893 /** 894 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. 895 * The driver converts this to an 896 * SQL <code>XML</code> value when it sends it to the database. 897 * 898 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 899 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value 900 * @throws SQLException if parameterIndex does not correspond to a parameter 901 * marker in the SQL statement; if a database access error occurs; 902 * this method is called on a closed <code>PreparedStatement</code> 903 * or the <code>java.xml.transform.Result</code>, 904 * <code>Writer</code> or <code>OutputStream</code> has not been closed for 905 * the <code>SQLXML</code> object 906 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 907 * 908 * @since 1.6 909 */ 910 void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException; 911 912 /** 913 * <p>Sets the value of the designated parameter with the given object. 914 * 915 * If the second argument is an <code>InputStream</code> then the stream must contain 916 * the number of bytes specified by scaleOrLength. If the second argument is a 917 * <code>Reader</code> then the reader must contain the number of characters specified 918 * by scaleOrLength. If these conditions are not true the driver will generate a 919 * <code>SQLException</code> when the prepared statement is executed. 920 * 921 * <p>The given Java object will be converted to the given targetSqlType 922 * before being sent to the database. 923 * 924 * If the object has a custom mapping (is of a class implementing the 925 * interface <code>SQLData</code>), 926 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to 927 * write it to the SQL data stream. 928 * If, on the other hand, the object is of a class implementing 929 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 930 * <code>Struct</code>, <code>java.net.URL</code>, 931 * or <code>Array</code>, the driver should pass it to the database as a 932 * value of the corresponding SQL type. 933 * 934 * <p>Note that this method may be used to pass database-specific 935 * abstract data types. 936 * 937 * @param parameterIndex the first parameter is 1, the second is 2, ... 938 * @param x the object containing the input parameter value 939 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 940 * sent to the database. The scale argument may further qualify this type. 941 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code> 942 * or <code>java.sql.Types.NUMERIC types</code>, 943 * this is the number of digits after the decimal point. For 944 * Java Object types <code>InputStream</code> and <code>Reader</code>, 945 * this is the length 946 * of the data in the stream or reader. For all other types, 947 * this value will be ignored. 948 * @exception SQLException if parameterIndex does not correspond to a parameter 949 * marker in the SQL statement; if a database access error occurs; 950 * this method is called on a closed <code>PreparedStatement</code> or 951 * if the Java Object specified by x is an InputStream 952 * or Reader object and the value of the scale parameter is less 953 * than zero 954 * @exception SQLFeatureNotSupportedException if 955 * the JDBC driver does not support the specified targetSqlType 956 * @see Types 957 * 958 */ 959 void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) 960 throws SQLException; 961 /** 962 * Sets the designated parameter to the given input stream, which will have 963 * the specified number of bytes. 964 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 965 * parameter, it may be more practical to send it via a 966 * <code>java.io.InputStream</code>. Data will be read from the stream 967 * as needed until end-of-file is reached. The JDBC driver will 968 * do any necessary conversion from ASCII to the database char format. 969 * 970 * <P><B>Note:</B> This stream object can either be a standard 971 * Java stream object or your own subclass that implements the 972 * standard interface. 973 * 974 * @param parameterIndex the first parameter is 1, the second is 2, ... 975 * @param x the Java input stream that contains the ASCII parameter value 976 * @param length the number of bytes in the stream 977 * @exception SQLException if parameterIndex does not correspond to a parameter 978 * marker in the SQL statement; if a database access error occurs or 979 * this method is called on a closed <code>PreparedStatement</code> 980 * @since 1.6 981 */ 982 void setAsciiStream(int parameterIndex, java.io.InputStream x, long length) 983 throws SQLException; 984 /** 985 * Sets the designated parameter to the given input stream, which will have 986 * the specified number of bytes. 987 * When a very large binary value is input to a <code>LONGVARBINARY</code> 988 * parameter, it may be more practical to send it via a 989 * <code>java.io.InputStream</code> object. The data will be read from the 990 * stream as needed until end-of-file is reached. 991 * 992 * <P><B>Note:</B> This stream object can either be a standard 993 * Java stream object or your own subclass that implements the 994 * standard interface. 995 * 996 * @param parameterIndex the first parameter is 1, the second is 2, ... 997 * @param x the java input stream which contains the binary parameter value 998 * @param length the number of bytes in the stream 999 * @exception SQLException if parameterIndex does not correspond to a parameter 1000 * marker in the SQL statement; if a database access error occurs or 1001 * this method is called on a closed <code>PreparedStatement</code> 1002 * @since 1.6 1003 */ 1004 void setBinaryStream(int parameterIndex, java.io.InputStream x, 1005 long length) throws SQLException; 1006 /** 1007 * Sets the designated parameter to the given <code>Reader</code> 1008 * object, which is the given number of characters long. 1009 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 1010 * parameter, it may be more practical to send it via a 1011 * <code>java.io.Reader</code> object. The data will be read from the stream 1012 * as needed until end-of-file is reached. The JDBC driver will 1013 * do any necessary conversion from UNICODE to the database char format. 1014 * 1015 * <P><B>Note:</B> This stream object can either be a standard 1016 * Java stream object or your own subclass that implements the 1017 * standard interface. 1018 * 1019 * @param parameterIndex the first parameter is 1, the second is 2, ... 1020 * @param reader the <code>java.io.Reader</code> object that contains the 1021 * Unicode data 1022 * @param length the number of characters in the stream 1023 * @exception SQLException if parameterIndex does not correspond to a parameter 1024 * marker in the SQL statement; if a database access error occurs or 1025 * this method is called on a closed <code>PreparedStatement</code> 1026 * @since 1.6 1027 */ 1028 void setCharacterStream(int parameterIndex, 1029 java.io.Reader reader, 1030 long length) throws SQLException; 1031 //----- 1032 /** 1033 * Sets the designated parameter to the given input stream. 1034 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 1035 * parameter, it may be more practical to send it via a 1036 * <code>java.io.InputStream</code>. Data will be read from the stream 1037 * as needed until end-of-file is reached. The JDBC driver will 1038 * do any necessary conversion from ASCII to the database char format. 1039 * 1040 * <P><B>Note:</B> This stream object can either be a standard 1041 * Java stream object or your own subclass that implements the 1042 * standard interface. 1043 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1044 * it might be more efficient to use a version of 1045 * <code>setAsciiStream</code> which takes a length parameter. 1046 * 1047 * @param parameterIndex the first parameter is 1, the second is 2, ... 1048 * @param x the Java input stream that contains the ASCII parameter value 1049 * @exception SQLException if parameterIndex does not correspond to a parameter 1050 * marker in the SQL statement; if a database access error occurs or 1051 * this method is called on a closed <code>PreparedStatement</code> 1052 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1053 * @since 1.6 1054 */ 1055 void setAsciiStream(int parameterIndex, java.io.InputStream x) 1056 throws SQLException; 1057 /** 1058 * Sets the designated parameter to the given input stream. 1059 * When a very large binary value is input to a <code>LONGVARBINARY</code> 1060 * parameter, it may be more practical to send it via a 1061 * <code>java.io.InputStream</code> object. The data will be read from the 1062 * stream as needed until end-of-file is reached. 1063 * 1064 * <P><B>Note:</B> This stream object can either be a standard 1065 * Java stream object or your own subclass that implements the 1066 * standard interface. 1067 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1068 * it might be more efficient to use a version of 1069 * <code>setBinaryStream</code> which takes a length parameter. 1070 * 1071 * @param parameterIndex the first parameter is 1, the second is 2, ... 1072 * @param x the java input stream which contains the binary parameter value 1073 * @exception SQLException if parameterIndex does not correspond to a parameter 1074 * marker in the SQL statement; if a database access error occurs or 1075 * this method is called on a closed <code>PreparedStatement</code> 1076 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1077 * @since 1.6 1078 */ 1079 void setBinaryStream(int parameterIndex, java.io.InputStream x) 1080 throws SQLException; 1081 /** 1082 * Sets the designated parameter to the given <code>Reader</code> 1083 * object. 1084 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 1085 * parameter, it may be more practical to send it via a 1086 * <code>java.io.Reader</code> object. The data will be read from the stream 1087 * as needed until end-of-file is reached. The JDBC driver will 1088 * do any necessary conversion from UNICODE to the database char format. 1089 * 1090 * <P><B>Note:</B> This stream object can either be a standard 1091 * Java stream object or your own subclass that implements the 1092 * standard interface. 1093 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1094 * it might be more efficient to use a version of 1095 * <code>setCharacterStream</code> which takes a length parameter. 1096 * 1097 * @param parameterIndex the first parameter is 1, the second is 2, ... 1098 * @param reader the <code>java.io.Reader</code> object that contains the 1099 * Unicode data 1100 * @exception SQLException if parameterIndex does not correspond to a parameter 1101 * marker in the SQL statement; if a database access error occurs or 1102 * this method is called on a closed <code>PreparedStatement</code> 1103 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1104 * @since 1.6 1105 */ 1106 void setCharacterStream(int parameterIndex, 1107 java.io.Reader reader) throws SQLException; 1108 /** 1109 * Sets the designated parameter to a <code>Reader</code> object. The 1110 * <code>Reader</code> reads the data till end-of-file is reached. The 1111 * driver does the necessary conversion from Java character format to 1112 * the national character set in the database. 1113 1114 * <P><B>Note:</B> This stream object can either be a standard 1115 * Java stream object or your own subclass that implements the 1116 * standard interface. 1117 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1118 * it might be more efficient to use a version of 1119 * <code>setNCharacterStream</code> which takes a length parameter. 1120 * 1121 * @param parameterIndex of the first parameter is 1, the second is 2, ... 1122 * @param value the parameter value 1123 * @throws SQLException if parameterIndex does not correspond to a parameter 1124 * marker in the SQL statement; if the driver does not support national 1125 * character sets; if the driver can detect that a data conversion 1126 * error could occur; if a database access error occurs; or 1127 * this method is called on a closed <code>PreparedStatement</code> 1128 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1129 * @since 1.6 1130 */ 1131 void setNCharacterStream(int parameterIndex, Reader value) throws SQLException; 1132 1133 /** 1134 * Sets the designated parameter to a <code>Reader</code> object. 1135 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1136 * because it informs the driver that the parameter value should be sent to 1137 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1138 * driver may have to do extra work to determine whether the parameter 1139 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1140 * 1141 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1142 * it might be more efficient to use a version of 1143 * <code>setClob</code> which takes a length parameter. 1144 * 1145 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1146 * @param reader An object that contains the data to set the parameter value to. 1147 * @throws SQLException if parameterIndex does not correspond to a parameter 1148 * marker in the SQL statement; if a database access error occurs; this method is called on 1149 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter 1150 * marker in the SQL statement 1151 * 1152 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1153 * @since 1.6 1154 */ 1155 void setClob(int parameterIndex, Reader reader) 1156 throws SQLException; 1157 1158 /** 1159 * Sets the designated parameter to a <code>InputStream</code> object. 1160 * This method differs from the <code>setBinaryStream (int, InputStream)</code> 1161 * method because it informs the driver that the parameter value should be 1162 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1163 * the driver may have to do extra work to determine whether the parameter 1164 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1165 * 1166 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1167 * it might be more efficient to use a version of 1168 * <code>setBlob</code> which takes a length parameter. 1169 * 1170 * @param parameterIndex index of the first parameter is 1, 1171 * the second is 2, ... 1172 * @param inputStream An object that contains the data to set the parameter 1173 * value to. 1174 * @throws SQLException if parameterIndex does not correspond to a parameter 1175 * marker in the SQL statement; if a database access error occurs; 1176 * this method is called on a closed <code>PreparedStatement</code> or 1177 * if parameterIndex does not correspond 1178 * to a parameter marker in the SQL statement, 1179 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1180 * 1181 * @since 1.6 1182 */ 1183 void setBlob(int parameterIndex, InputStream inputStream) 1184 throws SQLException; 1185 /** 1186 * Sets the designated parameter to a <code>Reader</code> object. 1187 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1188 * because it informs the driver that the parameter value should be sent to 1189 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 1190 * driver may have to do extra work to determine whether the parameter 1191 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 1192 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1193 * it might be more efficient to use a version of 1194 * <code>setNClob</code> which takes a length parameter. 1195 * 1196 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1197 * @param reader An object that contains the data to set the parameter value to. 1198 * @throws SQLException if parameterIndex does not correspond to a parameter 1199 * marker in the SQL statement; 1200 * if the driver does not support national character sets; 1201 * if the driver can detect that a data conversion 1202 * error could occur; if a database access error occurs or 1203 * this method is called on a closed <code>PreparedStatement</code> 1204 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1205 * 1206 * @since 1.6 1207 */ 1208 void setNClob(int parameterIndex, Reader reader) 1209 throws SQLException; 1210 1211 //------------------------- JDBC 4.2 ----------------------------------- 1212 1213 /** 1214 * <p>Sets the value of the designated parameter with the given object. 1215 * 1216 * If the second argument is an {@code InputStream} then the stream 1217 * must contain the number of bytes specified by scaleOrLength. 1218 * If the second argument is a {@code Reader} then the reader must 1219 * contain the number of characters specified by scaleOrLength. If these 1220 * conditions are not true the driver will generate a 1221 * {@code SQLException} when the prepared statement is executed. 1222 * 1223 * <p>The given Java object will be converted to the given targetSqlType 1224 * before being sent to the database. 1225 * 1226 * If the object has a custom mapping (is of a class implementing the 1227 * interface {@code SQLData}), 1228 * the JDBC driver should call the method {@code SQLData.writeSQL} to 1229 * write it to the SQL data stream. 1230 * If, on the other hand, the object is of a class implementing 1231 * {@code Ref}, {@code Blob}, {@code Clob}, {@code NClob}, 1232 * {@code Struct}, {@code java.net.URL}, 1233 * or {@code Array}, the driver should pass it to the database as a 1234 * value of the corresponding SQL type. 1235 * 1236 * <p>Note that this method may be used to pass database-specific 1237 * abstract data types. 1238 *<P> 1239 * The default implementation will throw {@code SQLFeatureNotSupportedException} 1240 * 1241 * @param parameterIndex the first parameter is 1, the second is 2, ... 1242 * @param x the object containing the input parameter value 1243 * @param targetSqlType the SQL type to be sent to the database. The 1244 * scale argument may further qualify this type. 1245 * @param scaleOrLength for {@code java.sql.JDBCType.DECIMAL} 1246 * or {@code java.sql.JDBCType.NUMERIC types}, 1247 * this is the number of digits after the decimal point. For 1248 * Java Object types {@code InputStream} and {@code Reader}, 1249 * this is the length 1250 * of the data in the stream or reader. For all other types, 1251 * this value will be ignored. 1252 * @exception SQLException if parameterIndex does not correspond to a 1253 * parameter marker in the SQL statement; if a database access error occurs 1254 * or this method is called on a closed {@code PreparedStatement} or 1255 * if the Java Object specified by x is an InputStream 1256 * or Reader object and the value of the scale parameter is less 1257 * than zero 1258 * @exception SQLFeatureNotSupportedException if 1259 * the JDBC driver does not support the specified targetSqlType 1260 * @see JDBCType 1261 * @see SQLType 1262 * @since 1.8 1263 */ 1264 default void setObject(int parameterIndex, Object x, SQLType targetSqlType, 1265 int scaleOrLength) throws SQLException { 1266 throw new SQLFeatureNotSupportedException("setObject not implemented"); 1267 } 1268 1269 /** 1270 * Sets the value of the designated parameter with the given object. 1271 * 1272 * This method is similar to {@link #setObject(int parameterIndex, 1273 * Object x, SQLType targetSqlType, int scaleOrLength)}, 1274 * except that it assumes a scale of zero. 1275 *<P> 1276 * The default implementation will throw {@code SQLFeatureNotSupportedException} 1277 * 1278 * @param parameterIndex the first parameter is 1, the second is 2, ... 1279 * @param x the object containing the input parameter value 1280 * @param targetSqlType the SQL type to be sent to the database 1281 * @exception SQLException if parameterIndex does not correspond to a 1282 * parameter marker in the SQL statement; if a database access error occurs 1283 * or this method is called on a closed {@code PreparedStatement} 1284 * @exception SQLFeatureNotSupportedException if 1285 * the JDBC driver does not support the specified targetSqlType 1286 * @see JDBCType 1287 * @see SQLType 1288 * @since 1.8 1289 */ 1290 default void setObject(int parameterIndex, Object x, SQLType targetSqlType) 1291 throws SQLException { 1292 throw new SQLFeatureNotSupportedException("setObject not implemented"); 1293 } 1294 1295 /** 1296 * Executes the SQL statement in this <code>PreparedStatement</code> object, 1297 * which must be an SQL Data Manipulation Language (DML) statement, 1298 * such as <code>INSERT</code>, <code>UPDATE</code> or 1299 * <code>DELETE</code>; or an SQL statement that returns nothing, 1300 * such as a DDL statement. 1301 * <p> 1302 * This method should be used when the returned row count may exceed 1303 * {@link Integer#MAX_VALUE}. 1304 * <p> 1305 * The default implementation will throw {@code UnsupportedOperationException} 1306 * 1307 * @return either (1) the row count for SQL Data Manipulation Language 1308 * (DML) statements or (2) 0 for SQL statements that return nothing 1309 * @exception SQLException if a database access error occurs; 1310 * this method is called on a closed <code>PreparedStatement</code> 1311 * or the SQL statement returns a <code>ResultSet</code> object 1312 * @throws SQLTimeoutException when the driver has determined that the 1313 * timeout value that was specified by the {@code setQueryTimeout} 1314 * method has been exceeded and has at least attempted to cancel 1315 * the currently running {@code Statement} 1316 * @since 1.8 1317 */ 1318 default long executeLargeUpdate() throws SQLException { 1319 throw new UnsupportedOperationException("executeLargeUpdate not implemented"); 1320 } 1321} 1322