1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 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 * An object that represents a precompiled SQL statement. 36 * <P>A SQL statement is precompiled and stored in a 37 * <code>PreparedStatement</code> object. This object can then be used to 38 * efficiently execute this statement multiple times. 39 * 40 * <P><B>Note:</B> The setter methods (<code>setShort</code>, <code>setString</code>, 41 * and so on) for setting IN parameter values 42 * must specify types that are compatible with the defined SQL type of 43 * the input parameter. For instance, if the IN parameter has SQL type 44 * <code>INTEGER</code>, then the method <code>setInt</code> should be used. 45 * 46 * <p>If arbitrary parameter type conversions are required, the method 47 * <code>setObject</code> should be used with a target SQL type. 48 * <P> 49 * In the following example of setting a parameter, <code>con</code> represents 50 * an active connection: 51 * <PRE> 52 * PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES 53 * SET SALARY = ? WHERE ID = ?"); 54 * pstmt.setBigDecimal(1, 153833.00) 55 * pstmt.setInt(2, 110592) 56 * </PRE> 57 * 58 * @see Connection#prepareStatement 59 * @see ResultSet 60 */ 61 62 public 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 */ executeQuery()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 */ executeUpdate()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 */ setNull(int parameterIndex, int sqlType)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 */ setBoolean(int parameterIndex, boolean x)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 */ setByte(int parameterIndex, byte x)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 */ setShort(int parameterIndex, short x)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 */ setInt(int parameterIndex, int x)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 */ setLong(int parameterIndex, long x)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 */ setFloat(int parameterIndex, float x)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 */ setDouble(int parameterIndex, double x)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 */ setBigDecimal(int parameterIndex, BigDecimal x)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 */ setString(int parameterIndex, String x)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 */ setBytes(int parameterIndex, byte x[])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 */ setDate(int parameterIndex, java.sql.Date x)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 */ setTime(int parameterIndex, java.sql.Time x)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> */ setTimestamp(int parameterIndex, java.sql.Timestamp x)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 */ setAsciiStream(int parameterIndex, java.io.InputStream x, int length)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 Deprecated. 347 */ 348 @Deprecated setUnicodeStream(int parameterIndex, java.io.InputStream x, int length)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 */ setBinaryStream(int parameterIndex, java.io.InputStream x, int length)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 */ clearParameters()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 * This method is like the method <code>setObject</code> 393 * above, except that it assumes a scale of zero. 394 * 395 * @param parameterIndex the first parameter is 1, the second is 2, ... 396 * @param x the object containing the input parameter value 397 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 398 * sent to the database 399 * @exception SQLException if parameterIndex does not correspond to a parameter 400 * marker in the SQL statement; if a database access error occurs or 401 * this method is called on a closed <code>PreparedStatement</code> 402 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is 403 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 404 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 405 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 406 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 407 * or <code>STRUCT</code> data type and the JDBC driver does not support 408 * this data type 409 * @see Types 410 */ setObject(int parameterIndex, Object x, int targetSqlType)411 void setObject(int parameterIndex, Object x, int targetSqlType) 412 throws SQLException; 413 414 /** 415 * <p>Sets the value of the designated parameter using the given object. 416 * The second parameter must be of type <code>Object</code>; therefore, the 417 * <code>java.lang</code> equivalent objects should be used for built-in types. 418 * 419 * <p>The JDBC specification specifies a standard mapping from 420 * Java <code>Object</code> types to SQL types. The given argument 421 * will be converted to the corresponding SQL type before being 422 * sent to the database. 423 * 424 * <p>Note that this method may be used to pass datatabase- 425 * specific abstract data types, by using a driver-specific Java 426 * type. 427 * 428 * If the object is of a class implementing the interface <code>SQLData</code>, 429 * the JDBC driver should call the method <code>SQLData.writeSQL</code> 430 * to write it to the SQL data stream. 431 * If, on the other hand, the object is of a class implementing 432 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 433 * <code>Struct</code>, <code>java.net.URL</code>, <code>RowId</code>, <code>SQLXML</code> 434 * or <code>Array</code>, the driver should pass it to the database as a 435 * value of the corresponding SQL type. 436 * <P> 437 *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to 438 * the backend. For maximum portability, the <code>setNull</code> or the 439 * <code>setObject(int parameterIndex, Object x, int sqlType)</code> 440 * method should be used 441 * instead of <code>setObject(int parameterIndex, Object x)</code>. 442 *<p> 443 * <b>Note:</b> This method throws an exception if there is an ambiguity, for example, if the 444 * object is of a class implementing more than one of the interfaces named above. 445 * 446 * @param parameterIndex the first parameter is 1, the second is 2, ... 447 * @param x the object containing the input parameter value 448 * @exception SQLException if parameterIndex does not correspond to a parameter 449 * marker in the SQL statement; if a database access error occurs; 450 * this method is called on a closed <code>PreparedStatement</code> 451 * or the type of the given object is ambiguous 452 */ setObject(int parameterIndex, Object x)453 void setObject(int parameterIndex, Object x) throws SQLException; 454 455 /** 456 * Executes the SQL statement in this <code>PreparedStatement</code> object, 457 * which may be any kind of SQL statement. 458 * Some prepared statements return multiple results; the <code>execute</code> 459 * method handles these complex statements as well as the simpler 460 * form of statements handled by the methods <code>executeQuery</code> 461 * and <code>executeUpdate</code>. 462 * <P> 463 * The <code>execute</code> method returns a <code>boolean</code> to 464 * indicate the form of the first result. You must call either the method 465 * <code>getResultSet</code> or <code>getUpdateCount</code> 466 * to retrieve the result; you must call <code>getMoreResults</code> to 467 * move to any subsequent result(s). 468 * 469 * @return <code>true</code> if the first result is a <code>ResultSet</code> 470 * object; <code>false</code> if the first result is an update 471 * count or there is no result 472 * @exception SQLException if a database access error occurs; 473 * this method is called on a closed <code>PreparedStatement</code> 474 * or an argument is supplied to this method 475 * @throws SQLTimeoutException when the driver has determined that the 476 * timeout value that was specified by the {@code setQueryTimeout} 477 * method has been exceeded and has at least attempted to cancel 478 * the currently running {@code Statement} 479 * @see Statement#execute 480 * @see Statement#getResultSet 481 * @see Statement#getUpdateCount 482 * @see Statement#getMoreResults 483 484 */ execute()485 boolean execute() throws SQLException; 486 487 //--------------------------JDBC 2.0----------------------------- 488 489 /** 490 * Adds a set of parameters to this <code>PreparedStatement</code> 491 * object's batch of commands. 492 * 493 * @exception SQLException if a database access error occurs or 494 * this method is called on a closed <code>PreparedStatement</code> 495 * @see Statement#addBatch 496 * @since 1.2 497 */ addBatch()498 void addBatch() throws SQLException; 499 500 /** 501 * Sets the designated parameter to the given <code>Reader</code> 502 * object, which is the given number of characters long. 503 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 504 * parameter, it may be more practical to send it via a 505 * <code>java.io.Reader</code> object. The data will be read from the stream 506 * as needed until end-of-file is reached. The JDBC driver will 507 * do any necessary conversion from UNICODE to the database char format. 508 * 509 * <P><B>Note:</B> This stream object can either be a standard 510 * Java stream object or your own subclass that implements the 511 * standard interface. 512 * 513 * @param parameterIndex the first parameter is 1, the second is 2, ... 514 * @param reader the <code>java.io.Reader</code> object that contains the 515 * Unicode data 516 * @param length the number of characters in the stream 517 * @exception SQLException if parameterIndex does not correspond to a parameter 518 * marker in the SQL statement; if a database access error occurs or 519 * this method is called on a closed <code>PreparedStatement</code> 520 * @since 1.2 521 */ setCharacterStream(int parameterIndex, java.io.Reader reader, int length)522 void setCharacterStream(int parameterIndex, 523 java.io.Reader reader, 524 int length) throws SQLException; 525 526 /** 527 * Sets the designated parameter to the given 528 * <code>REF(<structured-type>)</code> value. 529 * The driver converts this to an SQL <code>REF</code> value when it 530 * sends it to the database. 531 * 532 * @param parameterIndex the first parameter is 1, the second is 2, ... 533 * @param x an SQL <code>REF</code> value 534 * @exception SQLException if parameterIndex does not correspond to a parameter 535 * marker in the SQL statement; if a database access error occurs or 536 * this method is called on a closed <code>PreparedStatement</code> 537 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 538 * @since 1.2 539 */ setRef(int parameterIndex, Ref x)540 void setRef (int parameterIndex, Ref x) throws SQLException; 541 542 /** 543 * Sets the designated parameter to the given <code>java.sql.Blob</code> object. 544 * The driver converts this to an SQL <code>BLOB</code> value when it 545 * sends it to the database. 546 * 547 * @param parameterIndex the first parameter is 1, the second is 2, ... 548 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value 549 * @exception SQLException if parameterIndex does not correspond to a parameter 550 * marker in the SQL statement; if a database access error occurs or 551 * this method is called on a closed <code>PreparedStatement</code> 552 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 553 * @since 1.2 554 */ setBlob(int parameterIndex, Blob x)555 void setBlob (int parameterIndex, Blob x) throws SQLException; 556 557 /** 558 * Sets the designated parameter to the given <code>java.sql.Clob</code> object. 559 * The driver converts this to an SQL <code>CLOB</code> value when it 560 * sends it to the database. 561 * 562 * @param parameterIndex the first parameter is 1, the second is 2, ... 563 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value 564 * @exception SQLException if parameterIndex does not correspond to a parameter 565 * marker in the SQL statement; if a database access error occurs or 566 * this method is called on a closed <code>PreparedStatement</code> 567 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 568 * @since 1.2 569 */ setClob(int parameterIndex, Clob x)570 void setClob (int parameterIndex, Clob x) throws SQLException; 571 572 /** 573 * Sets the designated parameter to the given <code>java.sql.Array</code> object. 574 * The driver converts this to an SQL <code>ARRAY</code> value when it 575 * sends it to the database. 576 * 577 * @param parameterIndex the first parameter is 1, the second is 2, ... 578 * @param x an <code>Array</code> object that maps an SQL <code>ARRAY</code> value 579 * @exception SQLException if parameterIndex does not correspond to a parameter 580 * marker in the SQL statement; if a database access error occurs or 581 * this method is called on a closed <code>PreparedStatement</code> 582 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 583 * @since 1.2 584 */ setArray(int parameterIndex, Array x)585 void setArray (int parameterIndex, Array x) throws SQLException; 586 587 /** 588 * Retrieves a <code>ResultSetMetaData</code> object that contains 589 * information about the columns of the <code>ResultSet</code> object 590 * that will be returned when this <code>PreparedStatement</code> object 591 * is executed. 592 * <P> 593 * Because a <code>PreparedStatement</code> object is precompiled, it is 594 * possible to know about the <code>ResultSet</code> object that it will 595 * return without having to execute it. Consequently, it is possible 596 * to invoke the method <code>getMetaData</code> on a 597 * <code>PreparedStatement</code> object rather than waiting to execute 598 * it and then invoking the <code>ResultSet.getMetaData</code> method 599 * on the <code>ResultSet</code> object that is returned. 600 * <P> 601 * <B>NOTE:</B> Using this method may be expensive for some drivers due 602 * to the lack of underlying DBMS support. 603 * 604 * @return the description of a <code>ResultSet</code> object's columns or 605 * <code>null</code> if the driver cannot return a 606 * <code>ResultSetMetaData</code> object 607 * @exception SQLException if a database access error occurs or 608 * this method is called on a closed <code>PreparedStatement</code> 609 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 610 * this method 611 * @since 1.2 612 */ getMetaData()613 ResultSetMetaData getMetaData() throws SQLException; 614 615 /** 616 * Sets the designated parameter to the given <code>java.sql.Date</code> value, 617 * using the given <code>Calendar</code> object. The driver uses 618 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value, 619 * which the driver then sends to the database. With 620 * a <code>Calendar</code> object, the driver can calculate the date 621 * taking into account a custom timezone. If no 622 * <code>Calendar</code> object is specified, the driver uses the default 623 * timezone, which is that of the virtual machine running the application. 624 * 625 * @param parameterIndex the first parameter is 1, the second is 2, ... 626 * @param x the parameter value 627 * @param cal the <code>Calendar</code> object the driver will use 628 * to construct the date 629 * @exception SQLException if parameterIndex does not correspond to a parameter 630 * marker in the SQL statement; if a database access error occurs or 631 * this method is called on a closed <code>PreparedStatement</code> 632 * @since 1.2 633 */ setDate(int parameterIndex, java.sql.Date x, Calendar cal)634 void setDate(int parameterIndex, java.sql.Date x, Calendar cal) 635 throws SQLException; 636 637 /** 638 * Sets the designated parameter to the given <code>java.sql.Time</code> value, 639 * using the given <code>Calendar</code> object. The driver uses 640 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value, 641 * which the driver then sends to the database. With 642 * a <code>Calendar</code> object, the driver can calculate the time 643 * taking into account a custom timezone. If no 644 * <code>Calendar</code> object is specified, the driver uses the default 645 * timezone, which is that of the virtual machine running the application. 646 * 647 * @param parameterIndex the first parameter is 1, the second is 2, ... 648 * @param x the parameter value 649 * @param cal the <code>Calendar</code> object the driver will use 650 * to construct the time 651 * @exception SQLException if parameterIndex does not correspond to a parameter 652 * marker in the SQL statement; if a database access error occurs or 653 * this method is called on a closed <code>PreparedStatement</code> 654 * @since 1.2 655 */ setTime(int parameterIndex, java.sql.Time x, Calendar cal)656 void setTime(int parameterIndex, java.sql.Time x, Calendar cal) 657 throws SQLException; 658 659 /** 660 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value, 661 * using the given <code>Calendar</code> object. The driver uses 662 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value, 663 * which the driver then sends to the database. With a 664 * <code>Calendar</code> object, the driver can calculate the timestamp 665 * taking into account a custom timezone. If no 666 * <code>Calendar</code> object is specified, the driver uses the default 667 * timezone, which is that of the virtual machine running the application. 668 * 669 * @param parameterIndex the first parameter is 1, the second is 2, ... 670 * @param x the parameter value 671 * @param cal the <code>Calendar</code> object the driver will use 672 * to construct the timestamp 673 * @exception SQLException if parameterIndex does not correspond to a parameter 674 * marker in the SQL statement; if a database access error occurs or 675 * this method is called on a closed <code>PreparedStatement</code> 676 * @since 1.2 677 */ setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal)678 void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) 679 throws SQLException; 680 681 /** 682 * Sets the designated parameter to SQL <code>NULL</code>. 683 * This version of the method <code>setNull</code> should 684 * be used for user-defined types and REF type parameters. Examples 685 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and 686 * named array types. 687 * 688 * <P><B>Note:</B> To be portable, applications must give the 689 * SQL type code and the fully-qualified SQL type name when specifying 690 * a NULL user-defined or REF parameter. In the case of a user-defined type 691 * the name is the type name of the parameter itself. For a REF 692 * parameter, the name is the type name of the referenced type. If 693 * a JDBC driver does not need the type code or type name information, 694 * it may ignore it. 695 * 696 * Although it is intended for user-defined and Ref parameters, 697 * this method may be used to set a null parameter of any JDBC type. 698 * If the parameter does not have a user-defined or REF type, the given 699 * typeName is ignored. 700 * 701 * 702 * @param parameterIndex the first parameter is 1, the second is 2, ... 703 * @param sqlType a value from <code>java.sql.Types</code> 704 * @param typeName the fully-qualified name of an SQL user-defined type; 705 * ignored if the parameter is not a user-defined type or REF 706 * @exception SQLException if parameterIndex does not correspond to a parameter 707 * marker in the SQL statement; if a database access error occurs or 708 * this method is called on a closed <code>PreparedStatement</code> 709 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is 710 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 711 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 712 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 713 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 714 * or <code>STRUCT</code> data type and the JDBC driver does not support 715 * this data type or if the JDBC driver does not support this method 716 * @since 1.2 717 */ setNull(int parameterIndex, int sqlType, String typeName)718 void setNull (int parameterIndex, int sqlType, String typeName) 719 throws SQLException; 720 721 //------------------------- JDBC 3.0 ----------------------------------- 722 723 /** 724 * Sets the designated parameter to the given <code>java.net.URL</code> value. 725 * The driver converts this to an SQL <code>DATALINK</code> value 726 * when it sends it to the database. 727 * 728 * @param parameterIndex the first parameter is 1, the second is 2, ... 729 * @param x the <code>java.net.URL</code> object to be set 730 * @exception SQLException if parameterIndex does not correspond to a parameter 731 * marker in the SQL statement; if a database access error occurs or 732 * this method is called on a closed <code>PreparedStatement</code> 733 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 734 * @since 1.4 735 */ setURL(int parameterIndex, java.net.URL x)736 void setURL(int parameterIndex, java.net.URL x) throws SQLException; 737 738 /** 739 * Retrieves the number, types and properties of this 740 * <code>PreparedStatement</code> object's parameters. 741 * 742 * @return a <code>ParameterMetaData</code> object that contains information 743 * about the number, types and properties for each 744 * parameter marker of this <code>PreparedStatement</code> object 745 * @exception SQLException if a database access error occurs or 746 * this method is called on a closed <code>PreparedStatement</code> 747 * @see ParameterMetaData 748 * @since 1.4 749 */ getParameterMetaData()750 ParameterMetaData getParameterMetaData() throws SQLException; 751 752 //------------------------- JDBC 4.0 ----------------------------------- 753 754 /** 755 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The 756 * driver converts this to a SQL <code>ROWID</code> value when it sends it 757 * to the database 758 * 759 * @param parameterIndex the first parameter is 1, the second is 2, ... 760 * @param x the parameter value 761 * @throws SQLException if parameterIndex does not correspond to a parameter 762 * marker in the SQL statement; if a database access error occurs or 763 * this method is called on a closed <code>PreparedStatement</code> 764 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 765 * 766 * @since 1.6 767 */ setRowId(int parameterIndex, RowId x)768 void setRowId(int parameterIndex, RowId x) throws SQLException; 769 770 771 /** 772 * Sets the designated paramter to the given <code>String</code> object. 773 * The driver converts this to a SQL <code>NCHAR</code> or 774 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value 775 * (depending on the argument's 776 * size relative to the driver's limits on <code>NVARCHAR</code> values) 777 * when it sends it to the database. 778 * 779 * @param parameterIndex of the first parameter is 1, the second is 2, ... 780 * @param value the parameter value 781 * @throws SQLException if parameterIndex does not correspond to a parameter 782 * marker in the SQL statement; if the driver does not support national 783 * character sets; if the driver can detect that a data conversion 784 * error could occur; if a database access error occurs; or 785 * this method is called on a closed <code>PreparedStatement</code> 786 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 787 * @since 1.6 788 */ setNString(int parameterIndex, String value)789 void setNString(int parameterIndex, String value) throws SQLException; 790 791 /** 792 * Sets the designated parameter to a <code>Reader</code> object. The 793 * <code>Reader</code> reads the data till end-of-file is reached. The 794 * driver does the necessary conversion from Java character format to 795 * the national character set in the database. 796 * @param parameterIndex of the first parameter is 1, the second is 2, ... 797 * @param value the parameter value 798 * @param length the number of characters in the parameter data. 799 * @throws SQLException if parameterIndex does not correspond to a parameter 800 * marker in the SQL statement; if the driver does not support national 801 * character sets; if the driver can detect that a data conversion 802 * error could occur; if a database access error occurs; or 803 * this method is called on a closed <code>PreparedStatement</code> 804 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 805 * @since 1.6 806 */ setNCharacterStream(int parameterIndex, Reader value, long length)807 void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException; 808 809 /** 810 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a 811 * SQL <code>NCLOB</code> value when it sends it to the database. 812 * @param parameterIndex of the first parameter is 1, the second is 2, ... 813 * @param value the parameter value 814 * @throws SQLException if parameterIndex does not correspond to a parameter 815 * marker in the SQL statement; if the driver does not support national 816 * character sets; if the driver can detect that a data conversion 817 * error could occur; if a database access error occurs; or 818 * this method is called on a closed <code>PreparedStatement</code> 819 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 820 * @since 1.6 821 */ setNClob(int parameterIndex, NClob value)822 void setNClob(int parameterIndex, NClob value) throws SQLException; 823 824 /** 825 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number 826 * of characters specified by length otherwise a <code>SQLException</code> will be 827 * generated when the <code>PreparedStatement</code> is executed. 828 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 829 * because it informs the driver that the parameter value should be sent to 830 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 831 * driver may have to do extra work to determine whether the parameter 832 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 833 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 834 * @param reader An object that contains the data to set the parameter value to. 835 * @param length the number of characters in the parameter data. 836 * @throws SQLException if parameterIndex does not correspond to a parameter 837 * marker in the SQL statement; if a database access error occurs; this method is called on 838 * a closed <code>PreparedStatement</code> or if the length specified is less than zero. 839 * 840 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 841 * @since 1.6 842 */ setClob(int parameterIndex, Reader reader, long length)843 void setClob(int parameterIndex, Reader reader, long length) 844 throws SQLException; 845 846 /** 847 * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number 848 * of characters specified by length otherwise a <code>SQLException</code> will be 849 * generated when the <code>PreparedStatement</code> is executed. 850 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code> 851 * method because it informs the driver that the parameter value should be 852 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 853 * the driver may have to do extra work to determine whether the parameter 854 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 855 * @param parameterIndex index of the first parameter is 1, 856 * the second is 2, ... 857 * @param inputStream An object that contains the data to set the parameter 858 * value to. 859 * @param length the number of bytes in the parameter data. 860 * @throws SQLException if parameterIndex does not correspond to a parameter 861 * marker in the SQL statement; if a database access error occurs; 862 * this method is called on a closed <code>PreparedStatement</code>; 863 * if the length specified 864 * is less than zero or if the number of bytes in the inputstream does not match 865 * the specfied length. 866 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 867 * 868 * @since 1.6 869 */ setBlob(int parameterIndex, InputStream inputStream, long length)870 void setBlob(int parameterIndex, InputStream inputStream, long length) 871 throws SQLException; 872 /** 873 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number 874 * of characters specified by length otherwise a <code>SQLException</code> will be 875 * generated when the <code>PreparedStatement</code> is executed. 876 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 877 * because it informs the driver that the parameter value should be sent to 878 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 879 * driver may have to do extra work to determine whether the parameter 880 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 881 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 882 * @param reader An object that contains the data to set the parameter value to. 883 * @param length the number of characters in the parameter data. 884 * @throws SQLException if parameterIndex does not correspond to a parameter 885 * marker in the SQL statement; if the length specified is less than zero; 886 * if the driver does not support national character sets; 887 * if the driver can detect that a data conversion 888 * error could occur; if a database access error occurs or 889 * this method is called on a closed <code>PreparedStatement</code> 890 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 891 * 892 * @since 1.6 893 */ setNClob(int parameterIndex, Reader reader, long length)894 void setNClob(int parameterIndex, Reader reader, long length) 895 throws SQLException; 896 897 /** 898 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. 899 * The driver converts this to an 900 * SQL <code>XML</code> value when it sends it to the database. 901 * <p> 902 * 903 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 904 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value 905 * @throws SQLException if parameterIndex does not correspond to a parameter 906 * marker in the SQL statement; if a database access error occurs; 907 * this method is called on a closed <code>PreparedStatement</code> 908 * or the <code>java.xml.transform.Result</code>, 909 * <code>Writer</code> or <code>OutputStream</code> has not been closed for 910 * the <code>SQLXML</code> object 911 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 912 * 913 * @since 1.6 914 */ setSQLXML(int parameterIndex, SQLXML xmlObject)915 void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException; 916 917 /** 918 * <p>Sets the value of the designated parameter with the given object. The second 919 * argument must be an object type; for integral values, the 920 * <code>java.lang</code> equivalent objects should be used. 921 * 922 * If the second argument is an <code>InputStream</code> then the stream must contain 923 * the number of bytes specified by scaleOrLength. If the second argument is a 924 * <code>Reader</code> then the reader must contain the number of characters specified 925 * by scaleOrLength. If these conditions are not true the driver will generate a 926 * <code>SQLException</code> when the prepared statement is executed. 927 * 928 * <p>The given Java object will be converted to the given targetSqlType 929 * before being sent to the database. 930 * 931 * If the object has a custom mapping (is of a class implementing the 932 * interface <code>SQLData</code>), 933 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to 934 * write it to the SQL data stream. 935 * If, on the other hand, the object is of a class implementing 936 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 937 * <code>Struct</code>, <code>java.net.URL</code>, 938 * or <code>Array</code>, the driver should pass it to the database as a 939 * value of the corresponding SQL type. 940 * 941 * <p>Note that this method may be used to pass database-specific 942 * abstract data types. 943 * 944 * @param parameterIndex the first parameter is 1, the second is 2, ... 945 * @param x the object containing the input parameter value 946 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 947 * sent to the database. The scale argument may further qualify this type. 948 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code> 949 * or <code>java.sql.Types.NUMERIC types</code>, 950 * this is the number of digits after the decimal point. For 951 * Java Object types <code>InputStream</code> and <code>Reader</code>, 952 * this is the length 953 * of the data in the stream or reader. For all other types, 954 * this value will be ignored. 955 * @exception SQLException if parameterIndex does not correspond to a parameter 956 * marker in the SQL statement; if a database access error occurs; 957 * this method is called on a closed <code>PreparedStatement</code> or 958 * if the Java Object specified by x is an InputStream 959 * or Reader object and the value of the scale parameter is less 960 * than zero 961 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is 962 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 963 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 964 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 965 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 966 * or <code>STRUCT</code> data type and the JDBC driver does not support 967 * this data type 968 * @see Types 969 * 970 * @since 1.6 971 */ setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength)972 void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) 973 throws SQLException; 974 /** 975 * Sets the designated parameter to the given input stream, which will have 976 * the specified number of bytes. 977 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 978 * parameter, it may be more practical to send it via a 979 * <code>java.io.InputStream</code>. Data will be read from the stream 980 * as needed until end-of-file is reached. The JDBC driver will 981 * do any necessary conversion from ASCII to the database char format. 982 * 983 * <P><B>Note:</B> This stream object can either be a standard 984 * Java stream object or your own subclass that implements the 985 * standard interface. 986 * 987 * @param parameterIndex the first parameter is 1, the second is 2, ... 988 * @param x the Java input stream that contains the ASCII parameter value 989 * @param length the number of bytes in the stream 990 * @exception SQLException if parameterIndex does not correspond to a parameter 991 * marker in the SQL statement; if a database access error occurs or 992 * this method is called on a closed <code>PreparedStatement</code> 993 * @since 1.6 994 */ setAsciiStream(int parameterIndex, java.io.InputStream x, long length)995 void setAsciiStream(int parameterIndex, java.io.InputStream x, long length) 996 throws SQLException; 997 /** 998 * Sets the designated parameter to the given input stream, which will have 999 * the specified number of bytes. 1000 * When a very large binary value is input to a <code>LONGVARBINARY</code> 1001 * parameter, it may be more practical to send it via a 1002 * <code>java.io.InputStream</code> object. The data will be read from the 1003 * stream as needed until end-of-file is reached. 1004 * 1005 * <P><B>Note:</B> This stream object can either be a standard 1006 * Java stream object or your own subclass that implements the 1007 * standard interface. 1008 * 1009 * @param parameterIndex the first parameter is 1, the second is 2, ... 1010 * @param x the java input stream which contains the binary parameter value 1011 * @param length the number of bytes in the stream 1012 * @exception SQLException if parameterIndex does not correspond to a parameter 1013 * marker in the SQL statement; if a database access error occurs or 1014 * this method is called on a closed <code>PreparedStatement</code> 1015 * @since 1.6 1016 */ setBinaryStream(int parameterIndex, java.io.InputStream x, long length)1017 void setBinaryStream(int parameterIndex, java.io.InputStream x, 1018 long length) throws SQLException; 1019 /** 1020 * Sets the designated parameter to the given <code>Reader</code> 1021 * object, which is the given number of characters long. 1022 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 1023 * parameter, it may be more practical to send it via a 1024 * <code>java.io.Reader</code> object. The data will be read from the stream 1025 * as needed until end-of-file is reached. The JDBC driver will 1026 * do any necessary conversion from UNICODE to the database char format. 1027 * 1028 * <P><B>Note:</B> This stream object can either be a standard 1029 * Java stream object or your own subclass that implements the 1030 * standard interface. 1031 * 1032 * @param parameterIndex the first parameter is 1, the second is 2, ... 1033 * @param reader the <code>java.io.Reader</code> object that contains the 1034 * Unicode data 1035 * @param length the number of characters in the stream 1036 * @exception SQLException if parameterIndex does not correspond to a parameter 1037 * marker in the SQL statement; if a database access error occurs or 1038 * this method is called on a closed <code>PreparedStatement</code> 1039 * @since 1.6 1040 */ setCharacterStream(int parameterIndex, java.io.Reader reader, long length)1041 void setCharacterStream(int parameterIndex, 1042 java.io.Reader reader, 1043 long length) throws SQLException; 1044 //----- 1045 /** 1046 * Sets the designated parameter to the given input stream. 1047 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 1048 * parameter, it may be more practical to send it via a 1049 * <code>java.io.InputStream</code>. Data will be read from the stream 1050 * as needed until end-of-file is reached. The JDBC driver will 1051 * do any necessary conversion from ASCII to the database char format. 1052 * 1053 * <P><B>Note:</B> This stream object can either be a standard 1054 * Java stream object or your own subclass that implements the 1055 * standard interface. 1056 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1057 * it might be more efficient to use a version of 1058 * <code>setAsciiStream</code> which takes a length parameter. 1059 * 1060 * @param parameterIndex the first parameter is 1, the second is 2, ... 1061 * @param x the Java input stream that contains the ASCII parameter value 1062 * @exception SQLException if parameterIndex does not correspond to a parameter 1063 * marker in the SQL statement; if a database access error occurs or 1064 * this method is called on a closed <code>PreparedStatement</code> 1065 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1066 * @since 1.6 1067 */ setAsciiStream(int parameterIndex, java.io.InputStream x)1068 void setAsciiStream(int parameterIndex, java.io.InputStream x) 1069 throws SQLException; 1070 /** 1071 * Sets the designated parameter to the given input stream. 1072 * When a very large binary value is input to a <code>LONGVARBINARY</code> 1073 * parameter, it may be more practical to send it via a 1074 * <code>java.io.InputStream</code> object. The data will be read from the 1075 * stream as needed until end-of-file is reached. 1076 * 1077 * <P><B>Note:</B> This stream object can either be a standard 1078 * Java stream object or your own subclass that implements the 1079 * standard interface. 1080 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1081 * it might be more efficient to use a version of 1082 * <code>setBinaryStream</code> which takes a length parameter. 1083 * 1084 * @param parameterIndex the first parameter is 1, the second is 2, ... 1085 * @param x the java input stream which contains the binary parameter value 1086 * @exception SQLException if parameterIndex does not correspond to a parameter 1087 * marker in the SQL statement; if a database access error occurs or 1088 * this method is called on a closed <code>PreparedStatement</code> 1089 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1090 * @since 1.6 1091 */ setBinaryStream(int parameterIndex, java.io.InputStream x)1092 void setBinaryStream(int parameterIndex, java.io.InputStream x) 1093 throws SQLException; 1094 /** 1095 * Sets the designated parameter to the given <code>Reader</code> 1096 * object. 1097 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 1098 * parameter, it may be more practical to send it via a 1099 * <code>java.io.Reader</code> object. The data will be read from the stream 1100 * as needed until end-of-file is reached. The JDBC driver will 1101 * do any necessary conversion from UNICODE to the database char format. 1102 * 1103 * <P><B>Note:</B> This stream object can either be a standard 1104 * Java stream object or your own subclass that implements the 1105 * standard interface. 1106 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1107 * it might be more efficient to use a version of 1108 * <code>setCharacterStream</code> which takes a length parameter. 1109 * 1110 * @param parameterIndex the first parameter is 1, the second is 2, ... 1111 * @param reader the <code>java.io.Reader</code> object that contains the 1112 * Unicode data 1113 * @exception SQLException if parameterIndex does not correspond to a parameter 1114 * marker in the SQL statement; if a database access error occurs or 1115 * this method is called on a closed <code>PreparedStatement</code> 1116 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1117 * @since 1.6 1118 */ setCharacterStream(int parameterIndex, java.io.Reader reader)1119 void setCharacterStream(int parameterIndex, 1120 java.io.Reader reader) throws SQLException; 1121 /** 1122 * Sets the designated parameter to a <code>Reader</code> object. The 1123 * <code>Reader</code> reads the data till end-of-file is reached. The 1124 * driver does the necessary conversion from Java character format to 1125 * the national character set in the database. 1126 1127 * <P><B>Note:</B> This stream object can either be a standard 1128 * Java stream object or your own subclass that implements the 1129 * standard interface. 1130 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1131 * it might be more efficient to use a version of 1132 * <code>setNCharacterStream</code> which takes a length parameter. 1133 * 1134 * @param parameterIndex of the first parameter is 1, the second is 2, ... 1135 * @param value the parameter value 1136 * @throws SQLException if parameterIndex does not correspond to a parameter 1137 * marker in the SQL statement; if the driver does not support national 1138 * character sets; if the driver can detect that a data conversion 1139 * error could occur; if a database access error occurs; or 1140 * this method is called on a closed <code>PreparedStatement</code> 1141 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1142 * @since 1.6 1143 */ setNCharacterStream(int parameterIndex, Reader value)1144 void setNCharacterStream(int parameterIndex, Reader value) throws SQLException; 1145 1146 /** 1147 * Sets the designated parameter to a <code>Reader</code> object. 1148 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1149 * because it informs the driver that the parameter value should be sent to 1150 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1151 * driver may have to do extra work to determine whether the parameter 1152 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1153 * 1154 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1155 * it might be more efficient to use a version of 1156 * <code>setClob</code> which takes a length parameter. 1157 * 1158 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1159 * @param reader An object that contains the data to set the parameter value to. 1160 * @throws SQLException if parameterIndex does not correspond to a parameter 1161 * marker in the SQL statement; if a database access error occurs; this method is called on 1162 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter 1163 * marker in the SQL statement 1164 * 1165 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1166 * @since 1.6 1167 */ setClob(int parameterIndex, Reader reader)1168 void setClob(int parameterIndex, Reader reader) 1169 throws SQLException; 1170 1171 /** 1172 * Sets the designated parameter to a <code>InputStream</code> object. 1173 * This method differs from the <code>setBinaryStream (int, InputStream)</code> 1174 * method because it informs the driver that the parameter value should be 1175 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1176 * the driver may have to do extra work to determine whether the parameter 1177 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1178 * 1179 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1180 * it might be more efficient to use a version of 1181 * <code>setBlob</code> which takes a length parameter. 1182 * 1183 * @param parameterIndex index of the first parameter is 1, 1184 * the second is 2, ... 1185 * @param inputStream An object that contains the data to set the parameter 1186 * value to. 1187 * @throws SQLException if parameterIndex does not correspond to a parameter 1188 * marker in the SQL statement; if a database access error occurs; 1189 * this method is called on a closed <code>PreparedStatement</code> or 1190 * if parameterIndex does not correspond 1191 * to a parameter marker in the SQL statement, 1192 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1193 * 1194 * @since 1.6 1195 */ setBlob(int parameterIndex, InputStream inputStream)1196 void setBlob(int parameterIndex, InputStream inputStream) 1197 throws SQLException; 1198 /** 1199 * Sets the designated parameter to a <code>Reader</code> object. 1200 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1201 * because it informs the driver that the parameter value should be sent to 1202 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 1203 * driver may have to do extra work to determine whether the parameter 1204 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 1205 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1206 * it might be more efficient to use a version of 1207 * <code>setNClob</code> which takes a length parameter. 1208 * 1209 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1210 * @param reader An object that contains the data to set the parameter value to. 1211 * @throws SQLException if parameterIndex does not correspond to a parameter 1212 * marker in the SQL statement; 1213 * if the driver does not support national character sets; 1214 * if the driver can detect that a data conversion 1215 * error could occur; if a database access error occurs or 1216 * this method is called on a closed <code>PreparedStatement</code> 1217 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1218 * 1219 * @since 1.6 1220 */ setNClob(int parameterIndex, Reader reader)1221 void setNClob(int parameterIndex, Reader reader) 1222 throws SQLException; 1223 1224 1225 } 1226