Home » openjdk-7 » java » sql » [javadoc | source]

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

Home » openjdk-7 » java » sql » [javadoc | source]