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