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