1 /*

     2  * Copyright (c) 1996, 2016, 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  * @since 1.1

    60  */

    61 

    62 public interface PreparedStatement extends Statement {

    63 

    64     /**

    65      * Executes the SQL query in this <code>PreparedStatement</code> object

    66      * and returns the <code>ResultSet</code> object generated by the query.

    67      *

    68      * @return a <code>ResultSet</code> object that contains the data produced by the

    69      *         query; never <code>null</code>

    70      * @exception SQLException if a database access error occurs;

    71      * this method is called on a closed  <code>PreparedStatement</code> or the SQL

    72      *            statement does not return a <code>ResultSet</code> object

    73      * @throws SQLTimeoutException when the driver has determined that the

    74      * timeout value that was specified by the {@code setQueryTimeout}

    75      * method has been exceeded and has at least attempted to cancel

    76      * the currently running {@code Statement}

    77      */

    78     ResultSet executeQuery() throws SQLException;

    79 

    80     /**

    81      * Executes the SQL statement in this <code>PreparedStatement</code> object,

    82      * which must be an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or

    83      * <code>DELETE</code>; or an SQL statement that returns nothing,

    84      * such as a DDL statement.

    85      *

    86      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements

    87      *         or (2) 0 for SQL statements that return nothing

    88      * @exception SQLException if a database access error occurs;

    89      * this method is called on a closed  <code>PreparedStatement</code>

    90      * or the SQL statement returns a <code>ResultSet</code> object

    91      * @throws SQLTimeoutException when the driver has determined that the

    92      * timeout value that was specified by the {@code setQueryTimeout}

    93      * method has been exceeded and has at least attempted to cancel

    94      * the currently running {@code Statement}

    95      */

    96     int executeUpdate() throws SQLException;

    97 

    98     /**

    99      * Sets the designated parameter to SQL <code>NULL</code>.

   100      *

   101      * <P><B>Note:</B> You must specify the parameter's SQL type.

   102      *

   103      * @param parameterIndex the first parameter is 1, the second is 2, ...

   104      * @param sqlType the SQL type code defined in <code>java.sql.Types</code>

   105      * @exception SQLException if parameterIndex does not correspond to a parameter

   106      * marker in the SQL statement; if a database access error occurs or

   107      * this method is called on a closed <code>PreparedStatement</code>

   108      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is

   109      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,

   110      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,

   111      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,

   112      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>

   113      * or  <code>STRUCT</code> data type and the JDBC driver does not support

   114      * this data type

   115      */

   116     void setNull(int parameterIndex, int sqlType) throws SQLException;

   117 

   118     /**

   119      * Sets the designated parameter to the given Java <code>boolean</code> value.

   120      * The driver converts this

   121      * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.

   122      *

   123      * @param parameterIndex the first parameter is 1, the second is 2, ...

   124      * @param x the parameter value

   125      * @exception SQLException if parameterIndex does not correspond to a parameter

   126      * marker in the SQL statement;

   127      * if a database access error occurs or

   128      * this method is called on a closed <code>PreparedStatement</code>

   129      */

   130     void setBoolean(int parameterIndex, boolean x) throws SQLException;

   131 

   132     /**

   133      * Sets the designated parameter to the given Java <code>byte</code> value.

   134      * The driver converts this

   135      * to an SQL <code>TINYINT</code> value when it sends it to the database.

   136      *

   137      * @param parameterIndex the first parameter is 1, the second is 2, ...

   138      * @param x the parameter value

   139      * @exception SQLException if parameterIndex does not correspond to a parameter

   140      * marker in the SQL statement; if a database access error occurs or

   141      * this method is called on a closed <code>PreparedStatement</code>

   142      */

   143     void setByte(int parameterIndex, byte x) throws SQLException;

   144 

   145     /**

   146      * Sets the designated parameter to the given Java <code>short</code> value.

   147      * The driver converts this

   148      * to an SQL <code>SMALLINT</code> value when it sends it to the database.

   149      *

   150      * @param parameterIndex the first parameter is 1, the second is 2, ...

   151      * @param x the parameter value

   152      * @exception SQLException if parameterIndex does not correspond to a parameter

   153      * marker in the SQL statement; if a database access error occurs or

   154      * this method is called on a closed <code>PreparedStatement</code>

   155      */

   156     void setShort(int parameterIndex, short x) throws SQLException;

   157 

   158     /**

   159      * Sets the designated parameter to the given Java <code>int</code> value.

   160      * The driver converts this

   161      * to an SQL <code>INTEGER</code> value when it sends it to the database.

   162      *

   163      * @param parameterIndex the first parameter is 1, the second is 2, ...

   164      * @param x the parameter value

   165      * @exception SQLException if parameterIndex does not correspond to a parameter

   166      * marker in the SQL statement; if a database access error occurs or

   167      * this method is called on a closed <code>PreparedStatement</code>

   168      */

   169     void setInt(int parameterIndex, int x) throws SQLException;

   170 

   171     /**

   172      * Sets the designated parameter to the given Java <code>long</code> value.

   173      * The driver converts this

   174      * to an SQL <code>BIGINT</code> value when it sends it to the database.

   175      *

   176      * @param parameterIndex the first parameter is 1, the second is 2, ...

   177      * @param x the parameter value

   178      * @exception SQLException if parameterIndex does not correspond to a parameter

   179      * marker in the SQL statement; if a database access error occurs or

   180      * this method is called on a closed <code>PreparedStatement</code>

   181      */

   182     void setLong(int parameterIndex, long x) throws SQLException;

   183 

   184     /**

   185      * Sets the designated parameter to the given Java <code>float</code> value.

   186      * The driver converts this

   187      * to an SQL <code>REAL</code> value when it sends it to the database.

   188      *

   189      * @param parameterIndex the first parameter is 1, the second is 2, ...

   190      * @param x the parameter value

   191      * @exception SQLException if parameterIndex does not correspond to a parameter

   192      * marker in the SQL statement; if a database access error occurs or

   193      * this method is called on a closed <code>PreparedStatement</code>

   194      */

   195     void setFloat(int parameterIndex, float x) throws SQLException;

   196 

   197     /**

   198      * Sets the designated parameter to the given Java <code>double</code> value.

   199      * The driver converts this

   200      * to an SQL <code>DOUBLE</code> value when it sends it to the database.

   201      *

   202      * @param parameterIndex the first parameter is 1, the second is 2, ...

   203      * @param x the parameter value

   204      * @exception SQLException if parameterIndex does not correspond to a parameter

   205      * marker in the SQL statement; if a database access error occurs or

   206      * this method is called on a closed <code>PreparedStatement</code>

   207      */

   208     void setDouble(int parameterIndex, double x) throws SQLException;

   209 

   210     /**

   211      * Sets the designated parameter to the given <code>java.math.BigDecimal</code> value.

   212      * The driver converts this to an SQL <code>NUMERIC</code> value when

   213      * it sends it to the database.

   214      *

   215      * @param parameterIndex the first parameter is 1, the second is 2, ...

   216      * @param x the parameter value

   217      * @exception SQLException if parameterIndex does not correspond to a parameter

   218      * marker in the SQL statement; if a database access error occurs or

   219      * this method is called on a closed <code>PreparedStatement</code>

   220      */

   221     void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException;

   222 

   223     /**

   224      * Sets the designated parameter to the given Java <code>String</code> value.

   225      * The driver converts this

   226      * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value

   227      * (depending on the argument's

   228      * size relative to the driver's limits on <code>VARCHAR</code> values)

   229      * when it sends it to the database.

   230      *

   231      * @param parameterIndex the first parameter is 1, the second is 2, ...

   232      * @param x the parameter value

   233      * @exception SQLException if parameterIndex does not correspond to a parameter

   234      * marker in the SQL statement; if a database access error occurs or

   235      * this method is called on a closed <code>PreparedStatement</code>

   236      */

   237     void setString(int parameterIndex, String x) throws SQLException;

   238 

   239     /**

   240      * Sets the designated parameter to the given Java array of bytes.  The driver converts

   241      * this to an SQL <code>VARBINARY</code> or <code>LONGVARBINARY</code>

   242      * (depending on the argument's size relative to the driver's limits on

   243      * <code>VARBINARY</code> values) when it sends it to the database.

   244      *

   245      * @param parameterIndex the first parameter is 1, the second is 2, ...

   246      * @param x the parameter value

   247      * @exception SQLException if parameterIndex does not correspond to a parameter

   248      * marker in the SQL statement; if a database access error occurs or

   249      * this method is called on a closed <code>PreparedStatement</code>

   250      */

   251     void setBytes(int parameterIndex, byte x[]) throws SQLException;

   252 

   253     /**

   254      * Sets the designated parameter to the given <code>java.sql.Date</code> value

   255      * using the default time zone of the virtual machine that is running

   256      * the application.

   257      * The driver converts this

   258      * to an SQL <code>DATE</code> value when it sends it to the database.

   259      *

   260      * @param parameterIndex the first parameter is 1, the second is 2, ...

   261      * @param x the parameter value

   262      * @exception SQLException if parameterIndex does not correspond to a parameter

   263      * marker in the SQL statement; if a database access error occurs or

   264      * this method is called on a closed <code>PreparedStatement</code>

   265      */

   266     void setDate(int parameterIndex, java.sql.Date x)

   267             throws SQLException;

   268 

   269     /**

   270      * Sets the designated parameter to the given <code>java.sql.Time</code> value.

   271      * The driver converts this

   272      * to an SQL <code>TIME</code> value when it sends it to the database.

   273      *

   274      * @param parameterIndex the first parameter is 1, the second is 2, ...

   275      * @param x the parameter value

   276      * @exception SQLException if parameterIndex does not correspond to a parameter

   277      * marker in the SQL statement; if a database access error occurs or

   278      * this method is called on a closed <code>PreparedStatement</code>

   279      */

   280     void setTime(int parameterIndex, java.sql.Time x)

   281             throws SQLException;

   282 

   283     /**

   284      * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.

   285      * The driver

   286      * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the

   287      * database.

   288      *

   289      * @param parameterIndex the first parameter is 1, the second is 2, ...

   290      * @param x the parameter value

   291      * @exception SQLException if parameterIndex does not correspond to a parameter

   292      * marker in the SQL statement; if a database access error occurs or

   293      * this method is called on a closed <code>PreparedStatement</code>     */

   294     void setTimestamp(int parameterIndex, java.sql.Timestamp x)

   295             throws SQLException;

   296 

   297     /**

   298      * Sets the designated parameter to the given input stream, which will have

   299      * the specified number of bytes.

   300      * When a very large ASCII value is input to a <code>LONGVARCHAR</code>

   301      * parameter, it may be more practical to send it via a

   302      * <code>java.io.InputStream</code>. Data will be read from the stream

   303      * as needed until end-of-file is reached.  The JDBC driver will

   304      * do any necessary conversion from ASCII to the database char format.

   305      *

   306      * <P><B>Note:</B> This stream object can either be a standard

   307      * Java stream object or your own subclass that implements the

   308      * standard interface.

   309      *

   310      * @param parameterIndex the first parameter is 1, the second is 2, ...

   311      * @param x the Java input stream that contains the ASCII parameter value

   312      * @param length the number of bytes in the stream

   313      * @exception SQLException if parameterIndex does not correspond to a parameter

   314      * marker in the SQL statement; if a database access error occurs or

   315      * this method is called on a closed <code>PreparedStatement</code>

   316      */

   317     void setAsciiStream(int parameterIndex, java.io.InputStream x, int length)

   318             throws SQLException;

   319 

   320     /**

   321      * Sets the designated parameter to the given input stream, which

   322      * will have the specified number of bytes.

   323      *

   324      * When a very large Unicode value is input to a <code>LONGVARCHAR</code>

   325      * parameter, it may be more practical to send it via a

   326      * <code>java.io.InputStream</code> object. The data will be read from the

   327      * stream as needed until end-of-file is reached.  The JDBC driver will

   328      * do any necessary conversion from Unicode to the database char format.

   329      *

   330      *The byte format of the Unicode stream must be a Java UTF-8, as defined in the

   331      *Java Virtual Machine Specification.

   332      *

   333      * <P><B>Note:</B> This stream object can either be a standard

   334      * Java stream object or your own subclass that implements the

   335      * standard interface.

   336      *

   337      * @param parameterIndex the first parameter is 1, the second is 2, ...

   338      * @param x a <code>java.io.InputStream</code> object that contains the

   339      *        Unicode parameter value

   340      * @param length the number of bytes in the stream

   341      * @exception SQLException if parameterIndex does not correspond to a parameter

   342      * marker in the SQL statement; if a database access error occurs or

   343      * this method is called on a closed <code>PreparedStatement</code>

   344      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   345      * this method

   346      * @deprecated Use {@code setCharacterStream}

   347      */

   348     @Deprecated(since="1.2")

   349     void setUnicodeStream(int parameterIndex, java.io.InputStream x,

   350                           int length) throws SQLException;

   351 

   352     /**

   353      * Sets the designated parameter to the given input stream, which will have

   354      * the specified number of bytes.

   355      * When a very large binary value is input to a <code>LONGVARBINARY</code>

   356      * parameter, it may be more practical to send it via a

   357      * <code>java.io.InputStream</code> object. The data will be read from the

   358      * stream as needed until end-of-file is reached.

   359      *

   360      * <P><B>Note:</B> This stream object can either be a standard

   361      * Java stream object or your own subclass that implements the

   362      * standard interface.

   363      *

   364      * @param parameterIndex the first parameter is 1, the second is 2, ...

   365      * @param x the java input stream which contains the binary parameter value

   366      * @param length the number of bytes in the stream

   367      * @exception SQLException if parameterIndex does not correspond to a parameter

   368      * marker in the SQL statement; if a database access error occurs or

   369      * this method is called on a closed <code>PreparedStatement</code>

   370      */

   371     void setBinaryStream(int parameterIndex, java.io.InputStream x,

   372                          int length) throws SQLException;

   373 

   374     /**

   375      * Clears the current parameter values immediately.

   376      * <P>In general, parameter values remain in force for repeated use of a

   377      * statement. Setting a parameter value automatically clears its

   378      * previous value.  However, in some cases it is useful to immediately

   379      * release the resources used by the current parameter values; this can

   380      * be done by calling the method <code>clearParameters</code>.

   381      *

   382      * @exception SQLException if a database access error occurs or

   383      * this method is called on a closed <code>PreparedStatement</code>

   384      */

   385     void clearParameters() throws SQLException;

   386 

   387     //----------------------------------------------------------------------

   388     // Advanced features:

   389 

   390    /**

   391     * Sets the value of the designated parameter with the given object.

   392     *

   393     * This method is similar to {@link #setObject(int parameterIndex,

   394     * Object x, int targetSqlType, int scaleOrLength)},

   395     * except that it assumes a scale of zero.

   396     *

   397     * @param parameterIndex the first parameter is 1, the second is 2, ...

   398     * @param x the object containing the input parameter value

   399     * @param targetSqlType the SQL type (as defined in java.sql.Types) to be

   400     *                      sent to the database

   401     * @exception SQLException if parameterIndex does not correspond to a parameter

   402     * marker in the SQL statement; if a database access error occurs or this

   403     * method is called on a closed PreparedStatement

   404     * @exception SQLFeatureNotSupportedException if

   405     * the JDBC driver does not support the specified targetSqlType

   406     * @see Types

   407     */

   408     void setObject(int parameterIndex, Object x, int targetSqlType)

   409       throws SQLException;

   410 

   411     /**

   412      * <p>Sets the value of the designated parameter using the given object.

   413      *

   414      * <p>The JDBC specification specifies a standard mapping from

   415      * Java <code>Object</code> types to SQL types.  The given argument

   416      * will be converted to the corresponding SQL type before being

   417      * sent to the database.

   418      *

   419      * <p>Note that this method may be used to pass database-

   420      * specific abstract data types, by using a driver-specific Java

   421      * type.

   422      *

   423      * If the object is of a class implementing the interface <code>SQLData</code>,

   424      * the JDBC driver should call the method <code>SQLData.writeSQL</code>

   425      * to write it to the SQL data stream.

   426      * If, on the other hand, the object is of a class implementing

   427      * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,  <code>NClob</code>,

   428      *  <code>Struct</code>, <code>java.net.URL</code>, <code>RowId</code>, <code>SQLXML</code>

   429      * or <code>Array</code>, the driver should pass it to the database as a

   430      * value of the corresponding SQL type.

   431      * <P>

   432      *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to

   433      * the backend. For maximum portability, the <code>setNull</code> or the

   434      * <code>setObject(int parameterIndex, Object x, int sqlType)</code>

   435      * method should be used

   436      * instead of <code>setObject(int parameterIndex, Object x)</code>.

   437      *<p>

   438      * <b>Note:</b> This method throws an exception if there is an ambiguity, for example, if the

   439      * object is of a class implementing more than one of the interfaces named above.

   440      *

   441      * @param parameterIndex the first parameter is 1, the second is 2, ...

   442      * @param x the object containing the input parameter value

   443      * @exception SQLException if parameterIndex does not correspond to a parameter

   444      * marker in the SQL statement; if a database access error occurs;

   445      *  this method is called on a closed <code>PreparedStatement</code>

   446      * or the type of the given object is ambiguous

   447      */

   448     void setObject(int parameterIndex, Object x) throws SQLException;

   449 

   450     /**

   451      * Executes the SQL statement in this <code>PreparedStatement</code> object,

   452      * which may be any kind of SQL statement.

   453      * Some prepared statements return multiple results; the <code>execute</code>

   454      * method handles these complex statements as well as the simpler

   455      * form of statements handled by the methods <code>executeQuery</code>

   456      * and <code>executeUpdate</code>.

   457      * <P>

   458      * The <code>execute</code> method returns a <code>boolean</code> to

   459      * indicate the form of the first result.  You must call either the method

   460      * <code>getResultSet</code> or <code>getUpdateCount</code>

   461      * to retrieve the result; you must call <code>getMoreResults</code> to

   462      * move to any subsequent result(s).

   463      *

   464      * @return <code>true</code> if the first result is a <code>ResultSet</code>

   465      *         object; <code>false</code> if the first result is an update

   466      *         count or there is no result

   467      * @exception SQLException if a database access error occurs;

   468      * this method is called on a closed <code>PreparedStatement</code>

   469      * or an argument is supplied to this method

   470      * @throws SQLTimeoutException when the driver has determined that the

   471      * timeout value that was specified by the {@code setQueryTimeout}

   472      * method has been exceeded and has at least attempted to cancel

   473      * the currently running {@code Statement}

   474      * @see Statement#execute

   475      * @see Statement#getResultSet

   476      * @see Statement#getUpdateCount

   477      * @see Statement#getMoreResults

   478 

   479      */

   480     boolean execute() throws SQLException;

   481 

   482     //--------------------------JDBC 2.0-----------------------------

   483 

   484     /**

   485      * Adds a set of parameters to this <code>PreparedStatement</code>

   486      * object's batch of commands.

   487      *

   488      * @exception SQLException if a database access error occurs or

   489      * this method is called on a closed <code>PreparedStatement</code>

   490      * @see Statement#addBatch

   491      * @since 1.2

   492      */

   493     void addBatch() throws SQLException;

   494 

   495     /**

   496      * Sets the designated parameter to the given <code>Reader</code>

   497      * object, which is the given number of characters long.

   498      * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>

   499      * parameter, it may be more practical to send it via a

   500      * <code>java.io.Reader</code> object. The data will be read from the stream

   501      * as needed until end-of-file is reached.  The JDBC driver will

   502      * do any necessary conversion from UNICODE to the database char format.

   503      *

   504      * <P><B>Note:</B> This stream object can either be a standard

   505      * Java stream object or your own subclass that implements the

   506      * standard interface.

   507      *

   508      * @param parameterIndex the first parameter is 1, the second is 2, ...

   509      * @param reader the <code>java.io.Reader</code> object that contains the

   510      *        Unicode data

   511      * @param length the number of characters in the stream

   512      * @exception SQLException if parameterIndex does not correspond to a parameter

   513      * marker in the SQL statement; if a database access error occurs or

   514      * this method is called on a closed <code>PreparedStatement</code>

   515      * @since 1.2

   516      */

   517     void setCharacterStream(int parameterIndex,

   518                           java.io.Reader reader,

   519                           int length) throws SQLException;

   520 

   521     /**

   522      * Sets the designated parameter to the given

   523      *  <code>REF(&lt;structured-type&gt;)</code> value.

   524      * The driver converts this to an SQL <code>REF</code> value when it

   525      * sends it to the database.

   526      *

   527      * @param parameterIndex the first parameter is 1, the second is 2, ...

   528      * @param x an SQL <code>REF</code> value

   529      * @exception SQLException if parameterIndex does not correspond to a parameter

   530      * marker in the SQL statement; if a database access error occurs or

   531      * this method is called on a closed <code>PreparedStatement</code>

   532      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   533      * @since 1.2

   534      */

   535     void setRef (int parameterIndex, Ref x) throws SQLException;

   536 

   537     /**

   538      * Sets the designated parameter to the given <code>java.sql.Blob</code> object.

   539      * The driver converts this to an SQL <code>BLOB</code> value when it

   540      * sends it to the database.

   541      *

   542      * @param parameterIndex the first parameter is 1, the second is 2, ...

   543      * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value

   544      * @exception SQLException if parameterIndex does not correspond to a parameter

   545      * marker in the SQL statement; if a database access error occurs or

   546      * this method is called on a closed <code>PreparedStatement</code>

   547      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   548      * @since 1.2

   549      */

   550     void setBlob (int parameterIndex, Blob x) throws SQLException;

   551 

   552     /**

   553      * Sets the designated parameter to the given <code>java.sql.Clob</code> object.

   554      * The driver converts this to an SQL <code>CLOB</code> value when it

   555      * sends it to the database.

   556      *

   557      * @param parameterIndex the first parameter is 1, the second is 2, ...

   558      * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value

   559      * @exception SQLException if parameterIndex does not correspond to a parameter

   560      * marker in the SQL statement; if a database access error occurs or

   561      * this method is called on a closed <code>PreparedStatement</code>

   562      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   563      * @since 1.2

   564      */

   565     void setClob (int parameterIndex, Clob x) throws SQLException;

   566 

   567     /**

   568      * Sets the designated parameter to the given <code>java.sql.Array</code> object.

   569      * The driver converts this to an SQL <code>ARRAY</code> value when it

   570      * sends it to the database.

   571      *

   572      * @param parameterIndex the first parameter is 1, the second is 2, ...

   573      * @param x an <code>Array</code> object that maps an SQL <code>ARRAY</code> value

   574      * @exception SQLException if parameterIndex does not correspond to a parameter

   575      * marker in the SQL statement; if a database access error occurs or

   576      * this method is called on a closed <code>PreparedStatement</code>

   577      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   578      * @since 1.2

   579      */

   580     void setArray (int parameterIndex, Array x) throws SQLException;

   581 

   582     /**

   583      * Retrieves a <code>ResultSetMetaData</code> object that contains

   584      * information about the columns of the <code>ResultSet</code> object

   585      * that will be returned when this <code>PreparedStatement</code> object

   586      * is executed.

   587      * <P>

   588      * Because a <code>PreparedStatement</code> object is precompiled, it is

   589      * possible to know about the <code>ResultSet</code> object that it will

   590      * return without having to execute it.  Consequently, it is possible

   591      * to invoke the method <code>getMetaData</code> on a

   592      * <code>PreparedStatement</code> object rather than waiting to execute

   593      * it and then invoking the <code>ResultSet.getMetaData</code> method

   594      * on the <code>ResultSet</code> object that is returned.

   595      * <P>

   596      * <B>NOTE:</B> Using this method may be expensive for some drivers due

   597      * to the lack of underlying DBMS support.

   598      *

   599      * @return the description of a <code>ResultSet</code> object's columns or

   600      *         <code>null</code> if the driver cannot return a

   601      *         <code>ResultSetMetaData</code> object

   602      * @exception SQLException if a database access error occurs or

   603      * this method is called on a closed <code>PreparedStatement</code>

   604      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   605      * this method

   606      * @since 1.2

   607      */

   608     ResultSetMetaData getMetaData() throws SQLException;

   609 

   610     /**

   611      * Sets the designated parameter to the given <code>java.sql.Date</code> value,

   612      * using the given <code>Calendar</code> object.  The driver uses

   613      * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,

   614      * which the driver then sends to the database.  With

   615      * a <code>Calendar</code> object, the driver can calculate the date

   616      * taking into account a custom timezone.  If no

   617      * <code>Calendar</code> object is specified, the driver uses the default

   618      * timezone, which is that of the virtual machine running the application.

   619      *

   620      * @param parameterIndex the first parameter is 1, the second is 2, ...

   621      * @param x the parameter value

   622      * @param cal the <code>Calendar</code> object the driver will use

   623      *            to construct the date

   624      * @exception SQLException if parameterIndex does not correspond to a parameter

   625      * marker in the SQL statement; if a database access error occurs or

   626      * this method is called on a closed <code>PreparedStatement</code>

   627      * @since 1.2

   628      */

   629     void setDate(int parameterIndex, java.sql.Date x, Calendar cal)

   630             throws SQLException;

   631 

   632     /**

   633      * Sets the designated parameter to the given <code>java.sql.Time</code> value,

   634      * using the given <code>Calendar</code> object.  The driver uses

   635      * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,

   636      * which the driver then sends to the database.  With

   637      * a <code>Calendar</code> object, the driver can calculate the time

   638      * taking into account a custom timezone.  If no

   639      * <code>Calendar</code> object is specified, the driver uses the default

   640      * timezone, which is that of the virtual machine running the application.

   641      *

   642      * @param parameterIndex the first parameter is 1, the second is 2, ...

   643      * @param x the parameter value

   644      * @param cal the <code>Calendar</code> object the driver will use

   645      *            to construct the time

   646      * @exception SQLException if parameterIndex does not correspond to a parameter

   647      * marker in the SQL statement; if a database access error occurs or

   648      * this method is called on a closed <code>PreparedStatement</code>

   649      * @since 1.2

   650      */

   651     void setTime(int parameterIndex, java.sql.Time x, Calendar cal)

   652             throws SQLException;

   653 

   654     /**

   655      * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,

   656      * using the given <code>Calendar</code> object.  The driver uses

   657      * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,

   658      * which the driver then sends to the database.  With a

   659      *  <code>Calendar</code> object, the driver can calculate the timestamp

   660      * taking into account a custom timezone.  If no

   661      * <code>Calendar</code> object is specified, the driver uses the default

   662      * timezone, which is that of the virtual machine running the application.

   663      *

   664      * @param parameterIndex the first parameter is 1, the second is 2, ...

   665      * @param x the parameter value

   666      * @param cal the <code>Calendar</code> object the driver will use

   667      *            to construct the timestamp

   668      * @exception SQLException if parameterIndex does not correspond to a parameter

   669      * marker in the SQL statement; if a database access error occurs or

   670      * this method is called on a closed <code>PreparedStatement</code>

   671      * @since 1.2

   672      */

   673     void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal)

   674             throws SQLException;

   675 

   676     /**

   677      * Sets the designated parameter to SQL <code>NULL</code>.

   678      * This version of the method <code>setNull</code> should

   679      * be used for user-defined types and REF type parameters.  Examples

   680      * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and

   681      * named array types.

   682      *

   683      * <P><B>Note:</B> To be portable, applications must give the

   684      * SQL type code and the fully-qualified SQL type name when specifying

   685      * a NULL user-defined or REF parameter.  In the case of a user-defined type

   686      * the name is the type name of the parameter itself.  For a REF

   687      * parameter, the name is the type name of the referenced type.  If

   688      * a JDBC driver does not need the type code or type name information,

   689      * it may ignore it.

   690      *

   691      * Although it is intended for user-defined and Ref parameters,

   692      * this method may be used to set a null parameter of any JDBC type.

   693      * If the parameter does not have a user-defined or REF type, the given

   694      * typeName is ignored.

   695      *

   696      *

   697      * @param parameterIndex the first parameter is 1, the second is 2, ...

   698      * @param sqlType a value from <code>java.sql.Types</code>

   699      * @param typeName the fully-qualified name of an SQL user-defined type;

   700      *  ignored if the parameter is not a user-defined type or REF

   701      * @exception SQLException if parameterIndex does not correspond to a parameter

   702      * marker in the SQL statement; if a database access error occurs or

   703      * this method is called on a closed <code>PreparedStatement</code>

   704      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is

   705      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,

   706      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,

   707      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,

   708      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>

   709      * or  <code>STRUCT</code> data type and the JDBC driver does not support

   710      * this data type or if the JDBC driver does not support this method

   711      * @since 1.2

   712      */

   713   void setNull (int parameterIndex, int sqlType, String typeName)

   714     throws SQLException;

   715 

   716     //------------------------- JDBC 3.0 -----------------------------------

   717 

   718     /**

   719      * Sets the designated parameter to the given <code>java.net.URL</code> value.

   720      * The driver converts this to an SQL <code>DATALINK</code> value

   721      * when it sends it to the database.

   722      *

   723      * @param parameterIndex the first parameter is 1, the second is 2, ...

   724      * @param x the <code>java.net.URL</code> object to be set

   725      * @exception SQLException if parameterIndex does not correspond to a parameter

   726      * marker in the SQL statement; if a database access error occurs or

   727      * this method is called on a closed <code>PreparedStatement</code>

   728      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   729      * @since 1.4

   730      */

   731     void setURL(int parameterIndex, java.net.URL x) throws SQLException;

   732 

   733     /**

   734      * Retrieves the number, types and properties of this

   735      * <code>PreparedStatement</code> object's parameters.

   736      *

   737      * @return a <code>ParameterMetaData</code> object that contains information

   738      *         about the number, types and properties for each

   739      *  parameter marker of this <code>PreparedStatement</code> object

   740      * @exception SQLException if a database access error occurs or

   741      * this method is called on a closed <code>PreparedStatement</code>

   742      * @see ParameterMetaData

   743      * @since 1.4

   744      */

   745     ParameterMetaData getParameterMetaData() throws SQLException;

   746 

   747     //------------------------- JDBC 4.0 -----------------------------------

   748 

   749     /**

   750      * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The

   751      * driver converts this to a SQL <code>ROWID</code> value when it sends it

   752      * to the database

   753      *

   754      * @param parameterIndex the first parameter is 1, the second is 2, ...

   755      * @param x the parameter value

   756      * @throws SQLException if parameterIndex does not correspond to a parameter

   757      * marker in the SQL statement; if a database access error occurs or

   758      * this method is called on a closed <code>PreparedStatement</code>

   759      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   760      *

   761      * @since 1.6

   762      */

   763     void setRowId(int parameterIndex, RowId x) throws SQLException;

   764 

   765 

   766     /**

   767      * Sets the designated parameter to the given <code>String</code> object.

   768      * The driver converts this to a SQL <code>NCHAR</code> or

   769      * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value

   770      * (depending on the argument's

   771      * size relative to the driver's limits on <code>NVARCHAR</code> values)

   772      * when it sends it to the database.

   773      *

   774      * @param parameterIndex of the first parameter is 1, the second is 2, ...

   775      * @param value the parameter value

   776      * @throws SQLException if parameterIndex does not correspond to a parameter

   777      * marker in the SQL statement; if the driver does not support national

   778      *         character sets;  if the driver can detect that a data conversion

   779      *  error could occur; if a database access error occurs; or

   780      * this method is called on a closed <code>PreparedStatement</code>

   781      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   782      * @since 1.6

   783      */

   784      void setNString(int parameterIndex, String value) throws SQLException;

   785 

   786     /**

   787      * Sets the designated parameter to a <code>Reader</code> object. The

   788      * <code>Reader</code> reads the data till end-of-file is reached. The

   789      * driver does the necessary conversion from Java character format to

   790      * the national character set in the database.

   791      * @param parameterIndex of the first parameter is 1, the second is 2, ...

   792      * @param value the parameter value

   793      * @param length the number of characters in the parameter data.

   794      * @throws SQLException if parameterIndex does not correspond to a parameter

   795      * marker in the SQL statement; if the driver does not support national

   796      *         character sets;  if the driver can detect that a data conversion

   797      *  error could occur; if a database access error occurs; or

   798      * this method is called on a closed <code>PreparedStatement</code>

   799      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   800      * @since 1.6

   801      */

   802      void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException;

   803 

   804     /**

   805      * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a

   806      * SQL <code>NCLOB</code> value when it sends it to the database.

   807      * @param parameterIndex of the first parameter is 1, the second is 2, ...

   808      * @param value the parameter value

   809      * @throws SQLException if parameterIndex does not correspond to a parameter

   810      * marker in the SQL statement; if the driver does not support national

   811      *         character sets;  if the driver can detect that a data conversion

   812      *  error could occur; if a database access error occurs; or

   813      * this method is called on a closed <code>PreparedStatement</code>

   814      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   815      * @since 1.6

   816      */

   817      void setNClob(int parameterIndex, NClob value) throws SQLException;

   818 

   819     /**

   820      * Sets the designated parameter to a <code>Reader</code> object.  The reader must contain  the number

   821      * of characters specified by length otherwise a <code>SQLException</code> will be

   822      * generated when the <code>PreparedStatement</code> is executed.

   823      *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method

   824      * because it informs the driver that the parameter value should be sent to

   825      * the server as a <code>CLOB</code>.  When the <code>setCharacterStream</code> method is used, the

   826      * driver may have to do extra work to determine whether the parameter

   827      * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>

   828      * @param parameterIndex index of the first parameter is 1, the second is 2, ...

   829      * @param reader An object that contains the data to set the parameter value to.

   830      * @param length the number of characters in the parameter data.

   831      * @throws SQLException if parameterIndex does not correspond to a parameter

   832      * marker in the SQL statement; if a database access error occurs; this method is called on

   833      * a closed <code>PreparedStatement</code> or if the length specified is less than zero.

   834      *

   835      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   836      * @since 1.6

   837      */

   838      void setClob(int parameterIndex, Reader reader, long length)

   839        throws SQLException;

   840 

   841     /**

   842      * Sets the designated parameter to a <code>InputStream</code> object.

   843      * The {@code Inputstream} must contain  the number

   844      * of characters specified by length otherwise a <code>SQLException</code> will be

   845      * generated when the <code>PreparedStatement</code> is executed.

   846      * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>

   847      * method because it informs the driver that the parameter value should be

   848      * sent to the server as a <code>BLOB</code>.  When the <code>setBinaryStream</code> method is used,

   849      * the driver may have to do extra work to determine whether the parameter

   850      * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>

   851      * @param parameterIndex index of the first parameter is 1,

   852      * the second is 2, ...

   853      * @param inputStream An object that contains the data to set the parameter

   854      * value to.

   855      * @param length the number of bytes in the parameter data.

   856      * @throws SQLException if parameterIndex does not correspond to a parameter

   857      * marker in the SQL statement; if a database access error occurs;

   858      * this method is called on a closed <code>PreparedStatement</code>;

   859      * if the length specified

   860      * is less than zero or if the number of bytes in the {@code InputStream} does not match

   861      * the specified length.

   862      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   863      *

   864      * @since 1.6

   865      */

   866      void setBlob(int parameterIndex, InputStream inputStream, long length)

   867         throws SQLException;

   868     /**

   869      * Sets the designated parameter to a <code>Reader</code> object.  The reader must contain  the number

   870      * of characters specified by length otherwise a <code>SQLException</code> will be

   871      * generated when the <code>PreparedStatement</code> is executed.

   872      * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method

   873      * because it informs the driver that the parameter value should be sent to

   874      * the server as a <code>NCLOB</code>.  When the <code>setCharacterStream</code> method is used, the

   875      * driver may have to do extra work to determine whether the parameter

   876      * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>

   877      * @param parameterIndex index of the first parameter is 1, the second is 2, ...

   878      * @param reader An object that contains the data to set the parameter value to.

   879      * @param length the number of characters in the parameter data.

   880      * @throws SQLException if parameterIndex does not correspond to a parameter

   881      * marker in the SQL statement; if the length specified is less than zero;

   882      * if the driver does not support national character sets;

   883      * if the driver can detect that a data conversion

   884      *  error could occur;  if a database access error occurs or

   885      * this method is called on a closed <code>PreparedStatement</code>

   886      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   887      *

   888      * @since 1.6

   889      */

   890      void setNClob(int parameterIndex, Reader reader, long length)

   891        throws SQLException;

   892 

   893      /**

   894       * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object.

   895       * The driver converts this to an

   896       * SQL <code>XML</code> value when it sends it to the database.

   897       *

   898       * @param parameterIndex index of the first parameter is 1, the second is 2, ...

   899       * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value

   900       * @throws SQLException if parameterIndex does not correspond to a parameter

   901      * marker in the SQL statement; if a database access error occurs;

   902       *  this method is called on a closed <code>PreparedStatement</code>

   903       * or the <code>java.xml.transform.Result</code>,

   904       *  <code>Writer</code> or <code>OutputStream</code> has not been closed for

   905       * the <code>SQLXML</code> object

   906       * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   907       *

   908       * @since 1.6

   909       */

   910      void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException;

   911 

   912     /**

   913      * <p>Sets the value of the designated parameter with the given object.

   914      *

   915      * If the second argument is an <code>InputStream</code> then the stream must contain

   916      * the number of bytes specified by scaleOrLength.  If the second argument is a

   917      * <code>Reader</code> then the reader must contain the number of characters specified

   918      * by scaleOrLength. If these conditions are not true the driver will generate a

   919      * <code>SQLException</code> when the prepared statement is executed.

   920      *

   921      * <p>The given Java object will be converted to the given targetSqlType

   922      * before being sent to the database.

   923      *

   924      * If the object has a custom mapping (is of a class implementing the

   925      * interface <code>SQLData</code>),

   926      * the JDBC driver should call the method <code>SQLData.writeSQL</code> to

   927      * write it to the SQL data stream.

   928      * If, on the other hand, the object is of a class implementing

   929      * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,  <code>NClob</code>,

   930      *  <code>Struct</code>, <code>java.net.URL</code>,

   931      * or <code>Array</code>, the driver should pass it to the database as a

   932      * value of the corresponding SQL type.

   933      *

   934      * <p>Note that this method may be used to pass database-specific

   935      * abstract data types.

   936      *

   937      * @param parameterIndex the first parameter is 1, the second is 2, ...

   938      * @param x the object containing the input parameter value

   939      * @param targetSqlType the SQL type (as defined in java.sql.Types) to be

   940      * sent to the database. The scale argument may further qualify this type.

   941      * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code>

   942      *          or <code>java.sql.Types.NUMERIC types</code>,

   943      *          this is the number of digits after the decimal point. For

   944      *          Java Object types <code>InputStream</code> and <code>Reader</code>,

   945      *          this is the length

   946      *          of the data in the stream or reader.  For all other types,

   947      *          this value will be ignored.

   948      * @exception SQLException if parameterIndex does not correspond to a parameter

   949      * marker in the SQL statement; if a database access error occurs;

   950      * this method is called on a closed <code>PreparedStatement</code> or

   951      *            if the Java Object specified by x is an InputStream

   952      *            or Reader object and the value of the scale parameter is less

   953      *            than zero

   954      * @exception SQLFeatureNotSupportedException if

   955      * the JDBC driver does not support the specified targetSqlType

   956      * @see Types

   957      *

   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.