View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, 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 datatabase-
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(&lt;structured-type&gt;)</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.  The inputstream must contain  the number
842      * of characters specified by length otherwise a <code>SQLException</code> will be
843      * generated when the <code>PreparedStatement</code> is executed.
844      * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
845      * method because it informs the driver that the parameter value should be
846      * sent to the server as a <code>BLOB</code>.  When the <code>setBinaryStream</code> method is used,
847      * the driver may have to do extra work to determine whether the parameter
848      * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
849      * @param parameterIndex index of the first parameter is 1,
850      * the second is 2, ...
851      * @param inputStream An object that contains the data to set the parameter
852      * value to.
853      * @param length the number of bytes in the parameter data.
854      * @throws SQLException if parameterIndex does not correspond to a parameter
855      * marker in the SQL statement; if a database access error occurs;
856      * this method is called on a closed <code>PreparedStatement</code>;
857      *  if the length specified
858      * is less than zero or if the number of bytes in the inputstream does not match
859      * the specified length.
860      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
861      *
862      * @since 1.6
863      */
864      void setBlob(int parameterIndex, InputStream inputStream, long length)
865         throws SQLException;
866     /**
867      * Sets the designated parameter to a <code>Reader</code> object.  The reader must contain  the number
868      * of characters specified by length otherwise a <code>SQLException</code> will be
869      * generated when the <code>PreparedStatement</code> is executed.
870      * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
871      * because it informs the driver that the parameter value should be sent to
872      * the server as a <code>NCLOB</code>.  When the <code>setCharacterStream</code> method is used, the
873      * driver may have to do extra work to determine whether the parameter
874      * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
875      * @param parameterIndex index of the first parameter is 1, the second is 2, ...
876      * @param reader An object that contains the data to set the parameter value to.
877      * @param length the number of characters in the parameter data.
878      * @throws SQLException if parameterIndex does not correspond to a parameter
879      * marker in the SQL statement; if the length specified is less than zero;
880      * if the driver does not support national character sets;
881      * if the driver can detect that a data conversion
882      *  error could occur;  if a database access error occurs or
883      * this method is called on a closed <code>PreparedStatement</code>
884      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
885      *
886      * @since 1.6
887      */
888      void setNClob(int parameterIndex, Reader reader, long length)
889        throws SQLException;
890 
891      /**
892       * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object.
893       * The driver converts this to an
894       * SQL <code>XML</code> value when it sends it to the database.
895       * <p>
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 }