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