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