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  * The interface used to execute SQL stored procedures.  The JDBC API
  35  * provides a stored procedure SQL escape syntax that allows stored procedures
  36  * to be called in a standard way for all RDBMSs. This escape syntax has one
  37  * form that includes a result parameter and one that does not. If used, the result
  38  * parameter must be registered as an OUT parameter. The other parameters
  39  * can be used for input, output or both. Parameters are referred to
  40  * sequentially, by number, with the first parameter being 1.
  41  * <PRE>
  42  *   {?= call &lt;procedure-name&gt;[(&lt;arg1&gt;,&lt;arg2&gt;, ...)]}
  43  *   {call &lt;procedure-name&gt;[(&lt;arg1&gt;,&lt;arg2&gt;, ...)]}
  44  * </PRE>
  45  * <P>
  46  * IN parameter values are set using the <code>set</code> methods inherited from
  47  * {@link PreparedStatement}.  The type of all OUT parameters must be
  48  * registered prior to executing the stored procedure; their values
  49  * are retrieved after execution via the <code>get</code> methods provided here.
  50  * <P>
  51  * A <code>CallableStatement</code> can return one {@link ResultSet} object or
  52  * multiple <code>ResultSet</code> objects.  Multiple
  53  * <code>ResultSet</code> objects are handled using operations
  54  * inherited from {@link Statement}.
  55  * <P>
  56  * For maximum portability, a call's <code>ResultSet</code> objects and
  57  * update counts should be processed prior to getting the values of output
  58  * parameters.
  59  * <P>
  60  *
  61  * @see Connection#prepareCall
  62  * @see ResultSet
  63  */
  64 
  65 public interface CallableStatement extends PreparedStatement {
  66 
  67     /**
  68      * Registers the OUT parameter in ordinal position
  69      * <code>parameterIndex</code> to the JDBC type
  70      * <code>sqlType</code>.  All OUT parameters must be registered
  71      * before a stored procedure is executed.
  72      * <p>
  73      * The JDBC type specified by <code>sqlType</code> for an OUT
  74      * parameter determines the Java type that must be used
  75      * in the <code>get</code> method to read the value of that parameter.
  76      * <p>
  77      * If the JDBC type expected to be returned to this output parameter
  78      * is specific to this particular database, <code>sqlType</code>
  79      * should be <code>java.sql.Types.OTHER</code>.  The method
  80      * {@link #getObject} retrieves the value.
  81      *
  82      * @param parameterIndex the first parameter is 1, the second is 2,
  83      *        and so on
  84      * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
  85      *        If the parameter is of JDBC type <code>NUMERIC</code>
  86      *        or <code>DECIMAL</code>, the version of
  87      *        <code>registerOutParameter</code> that accepts a scale value
  88      *        should be used.
  89      *
  90      * @exception SQLException if the parameterIndex is not valid;
  91      * if a database access error occurs or
  92      * this method is called on a closed <code>CallableStatement</code>
  93      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
  94      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
  95      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
  96      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
  97      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
  98      * or  <code>STRUCT</code> data type and the JDBC driver does not support
  99      * this data type
 100      * @see Types
 101      */
 102     void registerOutParameter(int parameterIndex, int sqlType)
 103         throws SQLException;
 104 
 105     /**
 106      * Registers the parameter in ordinal position
 107      * <code>parameterIndex</code> to be of JDBC type
 108      * <code>sqlType</code>. All OUT parameters must be registered
 109      * before a stored procedure is executed.
 110      * <p>
 111      * The JDBC type specified by <code>sqlType</code> for an OUT
 112      * parameter determines the Java type that must be used
 113      * in the <code>get</code> method to read the value of that parameter.
 114      * <p>
 115      * This version of <code>registerOutParameter</code> should be
 116      * used when the parameter is of JDBC type <code>NUMERIC</code>
 117      * or <code>DECIMAL</code>.
 118      *
 119      * @param parameterIndex the first parameter is 1, the second is 2,
 120      * and so on
 121      * @param sqlType the SQL type code defined by <code>java.sql.Types</code>.
 122      * @param scale the desired number of digits to the right of the
 123      * decimal point.  It must be greater than or equal to zero.
 124      * @exception SQLException if the parameterIndex is not valid;
 125      * if a database access error occurs or
 126      * this method is called on a closed <code>CallableStatement</code>
 127      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
 128      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
 129      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
 130      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
 131      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
 132      * or  <code>STRUCT</code> data type and the JDBC driver does not support
 133      * this data type
 134      * @see Types
 135      */
 136     void registerOutParameter(int parameterIndex, int sqlType, int scale)
 137         throws SQLException;
 138 
 139     /**
 140      * Retrieves whether the last OUT parameter read had the value of
 141      * SQL <code>NULL</code>.  Note that this method should be called only after
 142      * calling a getter method; otherwise, there is no value to use in
 143      * determining whether it is <code>null</code> or not.
 144      *
 145      * @return <code>true</code> if the last parameter read was SQL
 146      * <code>NULL</code>; <code>false</code> otherwise
 147      * @exception SQLException if a database access error occurs or
 148      * this method is called on a closed <code>CallableStatement</code>
 149      */
 150     boolean wasNull() throws SQLException;
 151 
 152     /**
 153      * Retrieves the value of the designated JDBC <code>CHAR</code>,
 154      * <code>VARCHAR</code>, or <code>LONGVARCHAR</code> parameter as a
 155      * <code>String</code> in the Java programming language.
 156      * <p>
 157      * For the fixed-length type JDBC <code>CHAR</code>,
 158      * the <code>String</code> object
 159      * returned has exactly the same value the SQL
 160      * <code>CHAR</code> value had in the
 161      * database, including any padding added by the database.
 162      *
 163      * @param parameterIndex the first parameter is 1, the second is 2,
 164      * and so on
 165      * @return the parameter value. If the value is SQL <code>NULL</code>,
 166      *         the result
 167      *         is <code>null</code>.
 168      * @exception SQLException if the parameterIndex is not valid;
 169      * if a database access error occurs or
 170      * this method is called on a closed <code>CallableStatement</code>
 171      * @see #setString
 172      */
 173     String getString(int parameterIndex) throws SQLException;
 174 
 175     /**
 176      * Retrieves the value of the designated JDBC <code>BIT</code>
 177      * or <code>BOOLEAN</code> parameter as a
 178      * <code>boolean</code> in the Java programming language.
 179      *
 180      * @param parameterIndex the first parameter is 1, the second is 2,
 181      *        and so on
 182      * @return the parameter value.  If the value is SQL <code>NULL</code>,
 183      *         the result is <code>false</code>.
 184      * @exception SQLException if the parameterIndex is not valid;
 185      * if a database access error occurs or
 186      * this method is called on a closed <code>CallableStatement</code>
 187      * @see #setBoolean
 188      */
 189     boolean getBoolean(int parameterIndex) throws SQLException;
 190 
 191     /**
 192      * Retrieves the value of the designated JDBC <code>TINYINT</code> parameter
 193      * as a <code>byte</code> in the Java programming language.
 194      *
 195      * @param parameterIndex the first parameter is 1, the second is 2,
 196      * and so on
 197      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 198      * is <code>0</code>.
 199      * @exception SQLException if the parameterIndex is not valid;
 200      * if a database access error occurs or
 201      * this method is called on a closed <code>CallableStatement</code>
 202      * @see #setByte
 203      */
 204     byte getByte(int parameterIndex) throws SQLException;
 205 
 206     /**
 207      * Retrieves the value of the designated JDBC <code>SMALLINT</code> parameter
 208      * as a <code>short</code> in the Java programming language.
 209      *
 210      * @param parameterIndex the first parameter is 1, the second is 2,
 211      * and so on
 212      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 213      * is <code>0</code>.
 214      * @exception SQLException if the parameterIndex is not valid;
 215      * if a database access error occurs or
 216      * this method is called on a closed <code>CallableStatement</code>
 217      * @see #setShort
 218      */
 219     short getShort(int parameterIndex) throws SQLException;
 220 
 221     /**
 222      * Retrieves the value of the designated JDBC <code>INTEGER</code> parameter
 223      * as an <code>int</code> in the Java programming language.
 224      *
 225      * @param parameterIndex the first parameter is 1, the second is 2,
 226      * and so on
 227      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 228      * is <code>0</code>.
 229      * @exception SQLException if the parameterIndex is not valid;
 230      * if a database access error occurs or
 231      * this method is called on a closed <code>CallableStatement</code>
 232      * @see #setInt
 233      */
 234     int getInt(int parameterIndex) throws SQLException;
 235 
 236     /**
 237      * Retrieves the value of the designated JDBC <code>BIGINT</code> parameter
 238      * as a <code>long</code> in the Java programming language.
 239      *
 240      * @param parameterIndex the first parameter is 1, the second is 2,
 241      * and so on
 242      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 243      * is <code>0</code>.
 244      * @exception SQLException if the parameterIndex is not valid;
 245      * if a database access error occurs or
 246      * this method is called on a closed <code>CallableStatement</code>
 247      * @see #setLong
 248      */
 249     long getLong(int parameterIndex) throws SQLException;
 250 
 251     /**
 252      * Retrieves the value of the designated JDBC <code>FLOAT</code> parameter
 253      * as a <code>float</code> in the Java programming language.
 254      *
 255      * @param parameterIndex the first parameter is 1, the second is 2,
 256      *        and so on
 257      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 258      *         is <code>0</code>.
 259      * @exception SQLException if the parameterIndex is not valid;
 260      * if a database access error occurs or
 261      * this method is called on a closed <code>CallableStatement</code>
 262      * @see #setFloat
 263      */
 264     float getFloat(int parameterIndex) throws SQLException;
 265 
 266     /**
 267      * Retrieves the value of the designated JDBC <code>DOUBLE</code> parameter as a <code>double</code>
 268      * in the Java programming language.
 269      * @param parameterIndex the first parameter is 1, the second is 2,
 270      *        and so on
 271      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 272      *         is <code>0</code>.
 273      * @exception SQLException if the parameterIndex is not valid;
 274      * if a database access error occurs or
 275      * this method is called on a closed <code>CallableStatement</code>
 276      * @see #setDouble
 277      */
 278     double getDouble(int parameterIndex) throws SQLException;
 279 
 280     /**
 281      * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
 282      * <code>java.math.BigDecimal</code> object with <i>scale</i> digits to
 283      * the right of the decimal point.
 284      * @param parameterIndex the first parameter is 1, the second is 2,
 285      *        and so on
 286      * @param scale the number of digits to the right of the decimal point
 287      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 288      *         is <code>null</code>.
 289      * @exception SQLException if the parameterIndex is not valid;
 290      * if a database access error occurs or
 291      * this method is called on a closed <code>CallableStatement</code>
 292      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 293      * this method
 294      * @deprecated use <code>getBigDecimal(int parameterIndex)</code>
 295      *             or <code>getBigDecimal(String parameterName)</code>
 296      * @see #setBigDecimal
 297      */
 298     BigDecimal getBigDecimal(int parameterIndex, int scale)
 299         throws SQLException;
 300 
 301     /**
 302      * Retrieves the value of the designated JDBC <code>BINARY</code> or
 303      * <code>VARBINARY</code> parameter as an array of <code>byte</code>
 304      * values in the Java programming language.
 305      * @param parameterIndex the first parameter is 1, the second is 2,
 306      *        and so on
 307      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 308      *         is <code>null</code>.
 309      * @exception SQLException if the parameterIndex is not valid;
 310      * if a database access error occurs or
 311      * this method is called on a closed <code>CallableStatement</code>
 312      * @see #setBytes
 313      */
 314     byte[] getBytes(int parameterIndex) throws SQLException;
 315 
 316     /**
 317      * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
 318      * <code>java.sql.Date</code> object.
 319      * @param parameterIndex the first parameter is 1, the second is 2,
 320      *        and so on
 321      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 322      *         is <code>null</code>.
 323      * @exception SQLException if the parameterIndex is not valid;
 324      * if a database access error occurs or
 325      * this method is called on a closed <code>CallableStatement</code>
 326      * @see #setDate
 327      */
 328     java.sql.Date getDate(int parameterIndex) throws SQLException;
 329 
 330     /**
 331      * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
 332      * <code>java.sql.Time</code> object.
 333      *
 334      * @param parameterIndex the first parameter is 1, the second is 2,
 335      *        and so on
 336      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 337      *         is <code>null</code>.
 338      * @exception SQLException if the parameterIndex is not valid;
 339      * if a database access error occurs or
 340      * this method is called on a closed <code>CallableStatement</code>
 341      * @see #setTime
 342      */
 343     java.sql.Time getTime(int parameterIndex) throws SQLException;
 344 
 345     /**
 346      * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
 347      * <code>java.sql.Timestamp</code> object.
 348      *
 349      * @param parameterIndex the first parameter is 1, the second is 2,
 350      *        and so on
 351      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 352      *         is <code>null</code>.
 353      * @exception SQLException if the parameterIndex is not valid;
 354      * if a database access error occurs or
 355      * this method is called on a closed <code>CallableStatement</code>
 356      * @see #setTimestamp
 357      */
 358     java.sql.Timestamp getTimestamp(int parameterIndex)
 359         throws SQLException;
 360 
 361     //----------------------------------------------------------------------
 362     // Advanced features:
 363 
 364 
 365     /**
 366      * Retrieves the value of the designated parameter as an <code>Object</code>
 367      * in the Java programming language. If the value is an SQL <code>NULL</code>,
 368      * the driver returns a Java <code>null</code>.
 369      * <p>
 370      * This method returns a Java object whose type corresponds to the JDBC
 371      * type that was registered for this parameter using the method
 372      * <code>registerOutParameter</code>.  By registering the target JDBC
 373      * type as <code>java.sql.Types.OTHER</code>, this method can be used
 374      * to read database-specific abstract data types.
 375      *
 376      * @param parameterIndex the first parameter is 1, the second is 2,
 377      *        and so on
 378      * @return A <code>java.lang.Object</code> holding the OUT parameter value
 379      * @exception SQLException if the parameterIndex is not valid;
 380      * if a database access error occurs or
 381      * this method is called on a closed <code>CallableStatement</code>
 382      * @see Types
 383      * @see #setObject
 384      */
 385     Object getObject(int parameterIndex) throws SQLException;
 386 
 387 
 388     //--------------------------JDBC 2.0-----------------------------
 389 
 390     /**
 391      * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
 392      * <code>java.math.BigDecimal</code> object with as many digits to the
 393      * right of the decimal point as the value contains.
 394      * @param parameterIndex the first parameter is 1, the second is 2,
 395      * and so on
 396      * @return the parameter value in full precision.  If the value is
 397      * SQL <code>NULL</code>, the result is <code>null</code>.
 398      * @exception SQLException if the parameterIndex is not valid;
 399      * if a database access error occurs or
 400      * this method is called on a closed <code>CallableStatement</code>
 401      * @see #setBigDecimal
 402      * @since 1.2
 403      */
 404     BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
 405 
 406     /**
 407      * Returns an object representing the value of OUT parameter
 408      * <code>parameterIndex</code> and uses <code>map</code> for the custom
 409      * mapping of the parameter value.
 410      * <p>
 411      * This method returns a Java object whose type corresponds to the
 412      * JDBC type that was registered for this parameter using the method
 413      * <code>registerOutParameter</code>.  By registering the target
 414      * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
 415      * be used to read database-specific abstract data types.
 416      * @param parameterIndex the first parameter is 1, the second is 2, and so on
 417      * @param map the mapping from SQL type names to Java classes
 418      * @return a <code>java.lang.Object</code> holding the OUT parameter value
 419      * @exception SQLException if the parameterIndex is not valid;
 420      * if a database access error occurs or
 421      * this method is called on a closed <code>CallableStatement</code>
 422      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 423      * this method
 424      * @see #setObject
 425      * @since 1.2
 426      */
 427     Object getObject(int parameterIndex, java.util.Map<String,Class<?>> map)
 428         throws SQLException;
 429 
 430     /**
 431      * Retrieves the value of the designated JDBC <code>REF(&lt;structured-type&gt;)</code>
 432      * parameter as a {@link java.sql.Ref} object in the Java programming language.
 433      * @param parameterIndex the first parameter is 1, the second is 2,
 434      * and so on
 435      * @return the parameter value as a <code>Ref</code> object in the
 436      * Java programming language.  If the value was SQL <code>NULL</code>, the value
 437      * <code>null</code> is returned.
 438      * @exception SQLException if the parameterIndex is not valid;
 439      * if a database access error occurs or
 440      * this method is called on a closed <code>CallableStatement</code>
 441      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 442      * this method
 443      * @since 1.2
 444      */
 445     Ref getRef (int parameterIndex) throws SQLException;
 446 
 447     /**
 448      * Retrieves the value of the designated JDBC <code>BLOB</code> parameter as a
 449      * {@link java.sql.Blob} object in the Java programming language.
 450      * @param parameterIndex the first parameter is 1, the second is 2, and so on
 451      * @return the parameter value as a <code>Blob</code> object in the
 452      * Java programming language.  If the value was SQL <code>NULL</code>, the value
 453      * <code>null</code> is returned.
 454      * @exception SQLException if the parameterIndex is not valid;
 455      * if a database access error occurs or
 456      * this method is called on a closed <code>CallableStatement</code>
 457      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 458      * this method
 459      * @since 1.2
 460      */
 461     Blob getBlob (int parameterIndex) throws SQLException;
 462 
 463     /**
 464      * Retrieves the value of the designated JDBC <code>CLOB</code> parameter as a
 465      * <code>java.sql.Clob</code> object in the Java programming language.
 466      * @param parameterIndex the first parameter is 1, the second is 2, and
 467      * so on
 468      * @return the parameter value as a <code>Clob</code> object in the
 469      * Java programming language.  If the value was SQL <code>NULL</code>, the
 470      * value <code>null</code> is returned.
 471      * @exception SQLException if the parameterIndex is not valid;
 472      * if a database access error occurs or
 473      * this method is called on a closed <code>CallableStatement</code>
 474      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 475      * this method
 476      * @since 1.2
 477      */
 478     Clob getClob (int parameterIndex) throws SQLException;
 479 
 480     /**
 481      *
 482      * Retrieves the value of the designated JDBC <code>ARRAY</code> parameter as an
 483      * {@link java.sql.Array} object in the Java programming language.
 484      * @param parameterIndex the first parameter is 1, the second is 2, and
 485      * so on
 486      * @return the parameter value as an <code>Array</code> object in
 487      * the Java programming language.  If the value was SQL <code>NULL</code>, the
 488      * value <code>null</code> is returned.
 489      * @exception SQLException if the parameterIndex is not valid;
 490      * if a database access error occurs or
 491      * this method is called on a closed <code>CallableStatement</code>
 492      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 493      * this method
 494      * @since 1.2
 495      */
 496     Array getArray (int parameterIndex) throws SQLException;
 497 
 498     /**
 499      * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
 500      * <code>java.sql.Date</code> object, using
 501      * the given <code>Calendar</code> object
 502      * to construct the date.
 503      * With a <code>Calendar</code> object, the driver
 504      * can calculate the date taking into account a custom timezone and locale.
 505      * If no <code>Calendar</code> object is specified, the driver uses the
 506      * default timezone and locale.
 507      *
 508      * @param parameterIndex the first parameter is 1, the second is 2,
 509      * and so on
 510      * @param cal the <code>Calendar</code> object the driver will use
 511      *            to construct the date
 512      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 513      *         is <code>null</code>.
 514      * @exception SQLException if the parameterIndex is not valid;
 515      * if a database access error occurs or
 516      * this method is called on a closed <code>CallableStatement</code>
 517      * @see #setDate
 518      * @since 1.2
 519      */
 520     java.sql.Date getDate(int parameterIndex, Calendar cal)
 521         throws SQLException;
 522 
 523     /**
 524      * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
 525      * <code>java.sql.Time</code> object, using
 526      * the given <code>Calendar</code> object
 527      * to construct the time.
 528      * With a <code>Calendar</code> object, the driver
 529      * can calculate the time taking into account a custom timezone and locale.
 530      * If no <code>Calendar</code> object is specified, the driver uses the
 531      * default timezone and locale.
 532      *
 533      * @param parameterIndex the first parameter is 1, the second is 2,
 534      * and so on
 535      * @param cal the <code>Calendar</code> object the driver will use
 536      *            to construct the time
 537      * @return the parameter value; if the value is SQL <code>NULL</code>, the result
 538      *         is <code>null</code>.
 539      * @exception SQLException if the parameterIndex is not valid;
 540      * if a database access error occurs or
 541      * this method is called on a closed <code>CallableStatement</code>
 542      * @see #setTime
 543      * @since 1.2
 544      */
 545     java.sql.Time getTime(int parameterIndex, Calendar cal)
 546         throws SQLException;
 547 
 548     /**
 549      * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
 550      * <code>java.sql.Timestamp</code> object, using
 551      * the given <code>Calendar</code> object to construct
 552      * the <code>Timestamp</code> object.
 553      * With a <code>Calendar</code> object, the driver
 554      * can calculate the timestamp taking into account a custom timezone and locale.
 555      * If no <code>Calendar</code> object is specified, the driver uses the
 556      * default timezone and locale.
 557      *
 558      *
 559      * @param parameterIndex the first parameter is 1, the second is 2,
 560      * and so on
 561      * @param cal the <code>Calendar</code> object the driver will use
 562      *            to construct the timestamp
 563      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
 564      *         is <code>null</code>.
 565      * @exception SQLException if the parameterIndex is not valid;
 566      * if a database access error occurs or
 567      * this method is called on a closed <code>CallableStatement</code>
 568      * @see #setTimestamp
 569      * @since 1.2
 570      */
 571     java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal)
 572         throws SQLException;
 573 
 574 
 575     /**
 576      * Registers the designated output parameter.
 577      * This version of
 578      * the method <code>registerOutParameter</code>
 579      * should be used for a user-defined or <code>REF</code> output parameter.  Examples
 580      * of user-defined types include: <code>STRUCT</code>, <code>DISTINCT</code>,
 581      * <code>JAVA_OBJECT</code>, and named array types.
 582      *<p>
 583      * All OUT parameters must be registered
 584      * before a stored procedure is executed.
 585      * <p>  For a user-defined parameter, the fully-qualified SQL
 586      * type name of the parameter should also be given, while a <code>REF</code>
 587      * parameter requires that the fully-qualified type name of the
 588      * referenced type be given.  A JDBC driver that does not need the
 589      * type code and type name information may ignore it.   To be portable,
 590      * however, applications should always provide these values for
 591      * user-defined and <code>REF</code> parameters.
 592      *
 593      * Although it is intended for user-defined and <code>REF</code> parameters,
 594      * this method may be used to register a parameter of any JDBC type.
 595      * If the parameter does not have a user-defined or <code>REF</code> type, the
 596      * <i>typeName</i> parameter is ignored.
 597      *
 598      * <P><B>Note:</B> When reading the value of an out parameter, you
 599      * must use the getter method whose Java type corresponds to the
 600      * parameter's registered SQL type.
 601      *
 602      * @param parameterIndex the first parameter is 1, the second is 2,...
 603      * @param sqlType a value from {@link java.sql.Types}
 604      * @param typeName the fully-qualified name of an SQL structured type
 605      * @exception SQLException if the parameterIndex is not valid;
 606      * if a database access error occurs or
 607      * this method is called on a closed <code>CallableStatement</code>
 608      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
 609      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
 610      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
 611      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
 612      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
 613      * or  <code>STRUCT</code> data type and the JDBC driver does not support
 614      * this data type
 615      * @see Types
 616      * @since 1.2
 617      */
 618     void registerOutParameter (int parameterIndex, int sqlType, String typeName)
 619         throws SQLException;
 620 
 621   //--------------------------JDBC 3.0-----------------------------
 622 
 623     /**
 624      * Registers the OUT parameter named
 625      * <code>parameterName</code> to the JDBC type
 626      * <code>sqlType</code>.  All OUT parameters must be registered
 627      * before a stored procedure is executed.
 628      * <p>
 629      * The JDBC type specified by <code>sqlType</code> for an OUT
 630      * parameter determines the Java type that must be used
 631      * in the <code>get</code> method to read the value of that parameter.
 632      * <p>
 633      * If the JDBC type expected to be returned to this output parameter
 634      * is specific to this particular database, <code>sqlType</code>
 635      * should be <code>java.sql.Types.OTHER</code>.  The method
 636      * {@link #getObject} retrieves the value.
 637      * @param parameterName the name of the parameter
 638      * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
 639      * If the parameter is of JDBC type <code>NUMERIC</code>
 640      * or <code>DECIMAL</code>, the version of
 641      * <code>registerOutParameter</code> that accepts a scale value
 642      * should be used.
 643      * @exception SQLException if parameterName does not correspond to a named
 644      * parameter; if a database access error occurs or
 645      * this method is called on a closed <code>CallableStatement</code>
 646      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
 647      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
 648      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
 649      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
 650      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
 651      * or  <code>STRUCT</code> data type and the JDBC driver does not support
 652      * this data type or if the JDBC driver does not support
 653      * this method
 654      * @since 1.4
 655      * @see Types
 656      */
 657     void registerOutParameter(String parameterName, int sqlType)
 658         throws SQLException;
 659 
 660     /**
 661      * Registers the parameter named
 662      * <code>parameterName</code> to be of JDBC type
 663      * <code>sqlType</code>.  All OUT parameters must be registered
 664      * before a stored procedure is executed.
 665      * <p>
 666      * The JDBC type specified by <code>sqlType</code> for an OUT
 667      * parameter determines the Java type that must be used
 668      * in the <code>get</code> method to read the value of that parameter.
 669      * <p>
 670      * This version of <code>registerOutParameter</code> should be
 671      * used when the parameter is of JDBC type <code>NUMERIC</code>
 672      * or <code>DECIMAL</code>.
 673      *
 674      * @param parameterName the name of the parameter
 675      * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
 676      * @param scale the desired number of digits to the right of the
 677      * decimal point.  It must be greater than or equal to zero.
 678      * @exception SQLException if parameterName does not correspond to a named
 679      * parameter; if a database access error occurs or
 680      * this method is called on a closed <code>CallableStatement</code>
 681      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
 682      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
 683      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
 684      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
 685      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
 686      * or  <code>STRUCT</code> data type and the JDBC driver does not support
 687      * this data type or if the JDBC driver does not support
 688      * this method
 689      * @since 1.4
 690      * @see Types
 691      */
 692     void registerOutParameter(String parameterName, int sqlType, int scale)
 693         throws SQLException;
 694 
 695     /**
 696      * Registers the designated output parameter.  This version of
 697      * the method <code>registerOutParameter</code>
 698      * should be used for a user-named or REF output parameter.  Examples
 699      * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
 700      * named array types.
 701      *<p>
 702      * All OUT parameters must be registered
 703      * before a stored procedure is executed.
 704      * <p>
 705      * For a user-named parameter the fully-qualified SQL
 706      * type name of the parameter should also be given, while a REF
 707      * parameter requires that the fully-qualified type name of the
 708      * referenced type be given.  A JDBC driver that does not need the
 709      * type code and type name information may ignore it.   To be portable,
 710      * however, applications should always provide these values for
 711      * user-named and REF parameters.
 712      *
 713      * Although it is intended for user-named and REF parameters,
 714      * this method may be used to register a parameter of any JDBC type.
 715      * If the parameter does not have a user-named or REF type, the
 716      * typeName parameter is ignored.
 717      *
 718      * <P><B>Note:</B> When reading the value of an out parameter, you
 719      * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
 720      * parameter's registered SQL type.
 721      *
 722      * @param parameterName the name of the parameter
 723      * @param sqlType a value from {@link java.sql.Types}
 724      * @param typeName the fully-qualified name of an SQL structured type
 725      * @exception SQLException if parameterName does not correspond to a named
 726      * parameter; if a database access error occurs or
 727      * this method is called on a closed <code>CallableStatement</code>
 728      * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
 729      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
 730      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
 731      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
 732      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
 733      * or  <code>STRUCT</code> data type and the JDBC driver does not support
 734      * this data type or if the JDBC driver does not support
 735      * this method
 736      * @see Types
 737      * @since 1.4
 738      */
 739     void registerOutParameter (String parameterName, int sqlType, String typeName)
 740         throws SQLException;
 741 
 742     /**
 743      * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
 744      * <code>java.net.URL</code> object.
 745      *
 746      * @param parameterIndex the first parameter is 1, the second is 2,...
 747      * @return a <code>java.net.URL</code> object that represents the
 748      *         JDBC <code>DATALINK</code> value used as the designated
 749      *         parameter
 750      * @exception SQLException if the parameterIndex is not valid;
 751      * if a database access error occurs,
 752      * this method is called on a closed <code>CallableStatement</code>,
 753      *            or if the URL being returned is
 754      *            not a valid URL on the Java platform
 755      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 756      * this method
 757      * @see #setURL
 758      * @since 1.4
 759      */
 760     java.net.URL getURL(int parameterIndex) throws SQLException;
 761 
 762     /**
 763      * Sets the designated parameter to the given <code>java.net.URL</code> object.
 764      * The driver converts this to an SQL <code>DATALINK</code> value when
 765      * it sends it to the database.
 766      *
 767      * @param parameterName the name of the parameter
 768      * @param val the parameter value
 769      * @exception SQLException if parameterName does not correspond to a named
 770      * parameter; if a database access error occurs;
 771      * this method is called on a closed <code>CallableStatement</code>
 772      *            or if a URL is malformed
 773      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 774      * this method
 775      * @see #getURL
 776      * @since 1.4
 777      */
 778     void setURL(String parameterName, java.net.URL val) throws SQLException;
 779 
 780     /**
 781      * Sets the designated parameter to SQL <code>NULL</code>.
 782      *
 783      * <P><B>Note:</B> You must specify the parameter's SQL type.
 784      *
 785      * @param parameterName the name of the parameter
 786      * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
 787      * @exception SQLException if parameterName does not correspond to a named
 788      * parameter; if a database access error occurs or
 789      * this method is called on a closed <code>CallableStatement</code>
 790      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 791      * this method
 792      * @since 1.4
 793      */
 794     void setNull(String parameterName, int sqlType) throws SQLException;
 795 
 796     /**
 797      * Sets the designated parameter to the given Java <code>boolean</code> value.
 798      * The driver converts this
 799      * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
 800      *
 801      * @param parameterName the name of the parameter
 802      * @param x the parameter value
 803      * @exception SQLException if parameterName does not correspond to a named
 804      * parameter; if a database access error occurs or
 805      * this method is called on a closed <code>CallableStatement</code>
 806      * @see #getBoolean
 807      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 808      * this method
 809      * @since 1.4
 810      */
 811     void setBoolean(String parameterName, boolean x) throws SQLException;
 812 
 813     /**
 814      * Sets the designated parameter to the given Java <code>byte</code> value.
 815      * The driver converts this
 816      * to an SQL <code>TINYINT</code> value when it sends it to the database.
 817      *
 818      * @param parameterName the name of the parameter
 819      * @param x the parameter value
 820      * @exception SQLException if parameterName does not correspond to a named
 821      * parameter; if a database access error occurs or
 822      * this method is called on a closed <code>CallableStatement</code>
 823      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 824      * this method
 825      * @see #getByte
 826      * @since 1.4
 827      */
 828     void setByte(String parameterName, byte x) throws SQLException;
 829 
 830     /**
 831      * Sets the designated parameter to the given Java <code>short</code> value.
 832      * The driver converts this
 833      * to an SQL <code>SMALLINT</code> value when it sends it to the database.
 834      *
 835      * @param parameterName the name of the parameter
 836      * @param x the parameter value
 837      * @exception SQLException if parameterName does not correspond to a named
 838      * parameter; if a database access error occurs or
 839      * this method is called on a closed <code>CallableStatement</code>
 840      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 841      * this method
 842      * @see #getShort
 843      * @since 1.4
 844      */
 845     void setShort(String parameterName, short x) throws SQLException;
 846 
 847     /**
 848      * Sets the designated parameter to the given Java <code>int</code> value.
 849      * The driver converts this
 850      * to an SQL <code>INTEGER</code> value when it sends it to the database.
 851      *
 852      * @param parameterName the name of the parameter
 853      * @param x the parameter value
 854      * @exception SQLException if parameterName does not correspond to a named
 855      * parameter; if a database access error occurs or
 856      * this method is called on a closed <code>CallableStatement</code>
 857      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 858      * this method
 859      * @see #getInt
 860      * @since 1.4
 861      */
 862     void setInt(String parameterName, int x) throws SQLException;
 863 
 864     /**
 865      * Sets the designated parameter to the given Java <code>long</code> value.
 866      * The driver converts this
 867      * to an SQL <code>BIGINT</code> value when it sends it to the database.
 868      *
 869      * @param parameterName the name of the parameter
 870      * @param x the parameter value
 871      * @exception SQLException if parameterName does not correspond to a named
 872      * parameter; if a database access error occurs or
 873      * this method is called on a closed <code>CallableStatement</code>
 874      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 875      * this method
 876      * @see #getLong
 877      * @since 1.4
 878      */
 879     void setLong(String parameterName, long x) throws SQLException;
 880 
 881     /**
 882      * Sets the designated parameter to the given Java <code>float</code> value.
 883      * The driver converts this
 884      * to an SQL <code>FLOAT</code> value when it sends it to the database.
 885      *
 886      * @param parameterName the name of the parameter
 887      * @param x the parameter value
 888      * @exception SQLException if parameterName does not correspond to a named
 889      * parameter; if a database access error occurs or
 890      * this method is called on a closed <code>CallableStatement</code>
 891      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 892      * this method
 893      * @see #getFloat
 894      * @since 1.4
 895      */
 896     void setFloat(String parameterName, float x) throws SQLException;
 897 
 898     /**
 899      * Sets the designated parameter to the given Java <code>double</code> value.
 900      * The driver converts this
 901      * to an SQL <code>DOUBLE</code> value when it sends it to the database.
 902      *
 903      * @param parameterName the name of the parameter
 904      * @param x the parameter value
 905      * @exception SQLException if parameterName does not correspond to a named
 906      * parameter; if a database access error occurs or
 907      * this method is called on a closed <code>CallableStatement</code>
 908      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 909      * this method
 910      * @see #getDouble
 911      * @since 1.4
 912      */
 913     void setDouble(String parameterName, double x) throws SQLException;
 914 
 915     /**
 916      * Sets the designated parameter to the given
 917      * <code>java.math.BigDecimal</code> value.
 918      * The driver converts this to an SQL <code>NUMERIC</code> value when
 919      * it sends it to the database.
 920      *
 921      * @param parameterName the name of the parameter
 922      * @param x the parameter value
 923      * @exception SQLException if parameterName does not correspond to a named
 924      * parameter; if a database access error occurs or
 925      * this method is called on a closed <code>CallableStatement</code>
 926      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 927      * this method
 928      * @see #getBigDecimal
 929      * @since 1.4
 930      */
 931     void setBigDecimal(String parameterName, BigDecimal x) throws SQLException;
 932 
 933     /**
 934      * Sets the designated parameter to the given Java <code>String</code> value.
 935      * The driver converts this
 936      * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
 937      * (depending on the argument's
 938      * size relative to the driver's limits on <code>VARCHAR</code> values)
 939      * when it sends it to the database.
 940      *
 941      * @param parameterName the name of the parameter
 942      * @param x the parameter value
 943      * @exception SQLException if parameterName does not correspond to a named
 944      * parameter; if a database access error occurs or
 945      * this method is called on a closed <code>CallableStatement</code>
 946      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 947      * this method
 948      * @see #getString
 949      * @since 1.4
 950      */
 951     void setString(String parameterName, String x) throws SQLException;
 952 
 953     /**
 954      * Sets the designated parameter to the given Java array of bytes.
 955      * The driver converts this to an SQL <code>VARBINARY</code> or
 956      * <code>LONGVARBINARY</code> (depending on the argument's size relative
 957      * to the driver's limits on <code>VARBINARY</code> values) when it sends
 958      * it to the database.
 959      *
 960      * @param parameterName the name of the parameter
 961      * @param x the parameter value
 962      * @exception SQLException if parameterName does not correspond to a named
 963      * parameter; if a database access error occurs or
 964      * this method is called on a closed <code>CallableStatement</code>
 965      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 966      * this method
 967      * @see #getBytes
 968      * @since 1.4
 969      */
 970     void setBytes(String parameterName, byte x[]) throws SQLException;
 971 
 972     /**
 973      * Sets the designated parameter to the given <code>java.sql.Date</code> value
 974      * using the default time zone of the virtual machine that is running
 975      * the application.
 976      * The driver converts this
 977      * to an SQL <code>DATE</code> value when it sends it to the database.
 978      *
 979      * @param parameterName the name of the parameter
 980      * @param x the parameter value
 981      * @exception SQLException if parameterName does not correspond to a named
 982      * parameter; if a database access error occurs or
 983      * this method is called on a closed <code>CallableStatement</code>
 984      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
 985      * this method
 986      * @see #getDate
 987      * @since 1.4
 988      */
 989     void setDate(String parameterName, java.sql.Date x)
 990         throws SQLException;
 991 
 992     /**
 993      * Sets the designated parameter to the given <code>java.sql.Time</code> value.
 994      * The driver converts this
 995      * to an SQL <code>TIME</code> value when it sends it to the database.
 996      *
 997      * @param parameterName the name of the parameter
 998      * @param x the parameter value
 999      * @exception SQLException if parameterName does not correspond to a named
1000      * parameter; if a database access error occurs or
1001      * this method is called on a closed <code>CallableStatement</code>
1002      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1003      * this method
1004      * @see #getTime
1005      * @since 1.4
1006      */
1007     void setTime(String parameterName, java.sql.Time x)
1008         throws SQLException;
1009 
1010     /**
1011      * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
1012      * The driver
1013      * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
1014      * database.
1015      *
1016      * @param parameterName the name of the parameter
1017      * @param x the parameter value
1018      * @exception SQLException if parameterName does not correspond to a named
1019      * parameter; if a database access error occurs or
1020      * this method is called on a closed <code>CallableStatement</code>
1021      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1022      * this method
1023      * @see #getTimestamp
1024      * @since 1.4
1025      */
1026     void setTimestamp(String parameterName, java.sql.Timestamp x)
1027         throws SQLException;
1028 
1029     /**
1030      * Sets the designated parameter to the given input stream, which will have
1031      * the specified number of bytes.
1032      * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1033      * parameter, it may be more practical to send it via a
1034      * <code>java.io.InputStream</code>. Data will be read from the stream
1035      * as needed until end-of-file is reached.  The JDBC driver will
1036      * do any necessary conversion from ASCII to the database char format.
1037      *
1038      * <P><B>Note:</B> This stream object can either be a standard
1039      * Java stream object or your own subclass that implements the
1040      * standard interface.
1041      *
1042      * @param parameterName the name of the parameter
1043      * @param x the Java input stream that contains the ASCII parameter value
1044      * @param length the number of bytes in the stream
1045      * @exception SQLException if parameterName does not correspond to a named
1046      * parameter; if a database access error occurs or
1047      * this method is called on a closed <code>CallableStatement</code>
1048      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1049      * this method
1050      * @since 1.4
1051      */
1052     void setAsciiStream(String parameterName, java.io.InputStream x, int length)
1053         throws SQLException;
1054 
1055     /**
1056      * Sets the designated parameter to the given input stream, which will have
1057      * the specified number of bytes.
1058      * When a very large binary value is input to a <code>LONGVARBINARY</code>
1059      * parameter, it may be more practical to send it via a
1060      * <code>java.io.InputStream</code> object. The data will be read from the stream
1061      * as needed until end-of-file is reached.
1062      *
1063      * <P><B>Note:</B> This stream object can either be a standard
1064      * Java stream object or your own subclass that implements the
1065      * standard interface.
1066      *
1067      * @param parameterName the name of the parameter
1068      * @param x the java input stream which contains the binary parameter value
1069      * @param length the number of bytes in the stream
1070      * @exception SQLException if parameterName does not correspond to a named
1071      * parameter; if a database access error occurs or
1072      * this method is called on a closed <code>CallableStatement</code>
1073      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1074      * this method
1075      * @since 1.4
1076      */
1077     void setBinaryStream(String parameterName, java.io.InputStream x,
1078                          int length) throws SQLException;
1079 
1080     /**
1081      * Sets the value of the designated parameter with the given object. The second
1082      * argument must be an object type; for integral values, the
1083      * <code>java.lang</code> equivalent objects should be used.
1084      *
1085      * <p>The given Java object will be converted to the given targetSqlType
1086      * before being sent to the database.
1087      *
1088      * If the object has a custom mapping (is of a class implementing the
1089      * interface <code>SQLData</code>),
1090      * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1091      * to the SQL data stream.
1092      * If, on the other hand, the object is of a class implementing
1093      * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,  <code>NClob</code>,
1094      *  <code>Struct</code>, <code>java.net.URL</code>,
1095      * or <code>Array</code>, the driver should pass it to the database as a
1096      * value of the corresponding SQL type.
1097      * <P>
1098      * Note that this method may be used to pass datatabase-
1099      * specific abstract data types.
1100      *
1101      * @param parameterName the name of the parameter
1102      * @param x the object containing the input parameter value
1103      * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1104      * sent to the database. The scale argument may further qualify this type.
1105      * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1106      *          this is the number of digits after the decimal point.  For all other
1107      *          types, this value will be ignored.
1108      * @exception SQLException if parameterName does not correspond to a named
1109      * parameter; if a database access error occurs or
1110      * this method is called on a closed <code>CallableStatement</code>
1111      * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1112      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1113      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1114      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1115      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1116      * or  <code>STRUCT</code> data type and the JDBC driver does not support
1117      * this data type
1118      * @see Types
1119      * @see #getObject
1120      * @since 1.4
1121      */
1122     void setObject(String parameterName, Object x, int targetSqlType, int scale)
1123         throws SQLException;
1124 
1125     /**
1126      * Sets the value of the designated parameter with the given object.
1127      * This method is like the method <code>setObject</code>
1128      * above, except that it assumes a scale of zero.
1129      *
1130      * @param parameterName the name of the parameter
1131      * @param x the object containing the input parameter value
1132      * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1133      *                      sent to the database
1134      * @exception SQLException if parameterName does not correspond to a named
1135      * parameter; if a database access error occurs or
1136      * this method is called on a closed <code>CallableStatement</code>
1137      * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1138      * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1139      * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1140      * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1141      *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1142      * or  <code>STRUCT</code> data type and the JDBC driver does not support
1143      * this data type
1144      * @see #getObject
1145      * @since 1.4
1146      */
1147     void setObject(String parameterName, Object x, int targetSqlType)
1148         throws SQLException;
1149 
1150     /**
1151      * Sets the value of the designated parameter with the given object.
1152      * The second parameter must be of type <code>Object</code>; therefore, the
1153      * <code>java.lang</code> equivalent objects should be used for built-in types.
1154      *
1155      * <p>The JDBC specification specifies a standard mapping from
1156      * Java <code>Object</code> types to SQL types.  The given argument
1157      * will be converted to the corresponding SQL type before being
1158      * sent to the database.
1159      * <p>Note that this method may be used to pass datatabase-
1160      * specific abstract data types, by using a driver-specific Java
1161      * type.
1162      *
1163      * If the object is of a class implementing the interface <code>SQLData</code>,
1164      * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1165      * to write it to the SQL data stream.
1166      * If, on the other hand, the object is of a class implementing
1167      * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,  <code>NClob</code>,
1168      *  <code>Struct</code>, <code>java.net.URL</code>,
1169      * or <code>Array</code>, the driver should pass it to the database as a
1170      * value of the corresponding SQL type.
1171      * <P>
1172      * This method throws an exception if there is an ambiguity, for example, if the
1173      * object is of a class implementing more than one of the interfaces named above.
1174      *<p>
1175      *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to
1176      * the backend. For maximum portability, the <code>setNull</code> or the
1177      * <code>setObject(String parameterName, Object x, int sqlType)</code>
1178      * method should be used
1179      * instead of <code>setObject(String parameterName, Object x)</code>.
1180      *<p>
1181      * @param parameterName the name of the parameter
1182      * @param x the object containing the input parameter value
1183      * @exception SQLException if parameterName does not correspond to a named
1184      * parameter; if a database access error occurs,
1185      * this method is called on a closed <code>CallableStatement</code> or if the given
1186      *            <code>Object</code> parameter is ambiguous
1187      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1188      * this method
1189      * @see #getObject
1190      * @since 1.4
1191      */
1192     void setObject(String parameterName, Object x) throws SQLException;
1193 
1194 
1195     /**
1196      * Sets the designated parameter to the given <code>Reader</code>
1197      * object, which is the given number of characters long.
1198      * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1199      * parameter, it may be more practical to send it via a
1200      * <code>java.io.Reader</code> object. The data will be read from the stream
1201      * as needed until end-of-file is reached.  The JDBC driver will
1202      * do any necessary conversion from UNICODE to the database char format.
1203      *
1204      * <P><B>Note:</B> This stream object can either be a standard
1205      * Java stream object or your own subclass that implements the
1206      * standard interface.
1207      *
1208      * @param parameterName the name of the parameter
1209      * @param reader the <code>java.io.Reader</code> object that
1210      *        contains the UNICODE data used as the designated parameter
1211      * @param length the number of characters in the stream
1212      * @exception SQLException if parameterName does not correspond to a named
1213      * parameter; if a database access error occurs or
1214      * this method is called on a closed <code>CallableStatement</code>
1215      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1216      * this method
1217      * @since 1.4
1218      */
1219     void setCharacterStream(String parameterName,
1220                             java.io.Reader reader,
1221                             int length) throws SQLException;
1222 
1223     /**
1224      * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1225      * using the given <code>Calendar</code> object.  The driver uses
1226      * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1227      * which the driver then sends to the database.  With a
1228      * a <code>Calendar</code> object, the driver can calculate the date
1229      * taking into account a custom timezone.  If no
1230      * <code>Calendar</code> object is specified, the driver uses the default
1231      * timezone, which is that of the virtual machine running the application.
1232      *
1233      * @param parameterName the name of the parameter
1234      * @param x the parameter value
1235      * @param cal the <code>Calendar</code> object the driver will use
1236      *            to construct the date
1237      * @exception SQLException if parameterName does not correspond to a named
1238      * parameter; if a database access error occurs or
1239      * this method is called on a closed <code>CallableStatement</code>
1240      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1241      * this method
1242      * @see #getDate
1243      * @since 1.4
1244      */
1245     void setDate(String parameterName, java.sql.Date x, Calendar cal)
1246         throws SQLException;
1247 
1248     /**
1249      * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1250      * using the given <code>Calendar</code> object.  The driver uses
1251      * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1252      * which the driver then sends to the database.  With a
1253      * a <code>Calendar</code> object, the driver can calculate the time
1254      * taking into account a custom timezone.  If no
1255      * <code>Calendar</code> object is specified, the driver uses the default
1256      * timezone, which is that of the virtual machine running the application.
1257      *
1258      * @param parameterName the name of the parameter
1259      * @param x the parameter value
1260      * @param cal the <code>Calendar</code> object the driver will use
1261      *            to construct the time
1262      * @exception SQLException if parameterName does not correspond to a named
1263      * parameter; if a database access error occurs or
1264      * this method is called on a closed <code>CallableStatement</code>
1265      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1266      * this method
1267      * @see #getTime
1268      * @since 1.4
1269      */
1270     void setTime(String parameterName, java.sql.Time x, Calendar cal)
1271         throws SQLException;
1272 
1273     /**
1274      * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1275      * using the given <code>Calendar</code> object.  The driver uses
1276      * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1277      * which the driver then sends to the database.  With a
1278      * a <code>Calendar</code> object, the driver can calculate the timestamp
1279      * taking into account a custom timezone.  If no
1280      * <code>Calendar</code> object is specified, the driver uses the default
1281      * timezone, which is that of the virtual machine running the application.
1282      *
1283      * @param parameterName the name of the parameter
1284      * @param x the parameter value
1285      * @param cal the <code>Calendar</code> object the driver will use
1286      *            to construct the timestamp
1287      * @exception SQLException if parameterName does not correspond to a named
1288      * parameter; if a database access error occurs or
1289      * this method is called on a closed <code>CallableStatement</code>
1290      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1291      * this method
1292      * @see #getTimestamp
1293      * @since 1.4
1294      */
1295     void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal)
1296         throws SQLException;
1297 
1298     /**
1299      * Sets the designated parameter to SQL <code>NULL</code>.
1300      * This version of the method <code>setNull</code> should
1301      * be used for user-defined types and REF type parameters.  Examples
1302      * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
1303      * named array types.
1304      *
1305      * <P><B>Note:</B> To be portable, applications must give the
1306      * SQL type code and the fully-qualified SQL type name when specifying
1307      * a NULL user-defined or REF parameter.  In the case of a user-defined type
1308      * the name is the type name of the parameter itself.  For a REF
1309      * parameter, the name is the type name of the referenced type.
1310      * <p>
1311      * Although it is intended for user-defined and Ref parameters,
1312      * this method may be used to set a null parameter of any JDBC type.
1313      * If the parameter does not have a user-defined or REF type, the given
1314      * typeName is ignored.
1315      *
1316      *
1317      * @param parameterName the name of the parameter
1318      * @param sqlType a value from <code>java.sql.Types</code>
1319      * @param typeName the fully-qualified name of an SQL user-defined type;
1320      *        ignored if the parameter is not a user-defined type or
1321      *        SQL <code>REF</code> value
1322      * @exception SQLException if parameterName does not correspond to a named
1323      * parameter; if a database access error occurs or
1324      * this method is called on a closed <code>CallableStatement</code>
1325      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1326      * this method
1327      * @since 1.4
1328      */
1329     void setNull (String parameterName, int sqlType, String typeName)
1330         throws SQLException;
1331 
1332     /**
1333      * Retrieves the value of a JDBC <code>CHAR</code>, <code>VARCHAR</code>,
1334      * or <code>LONGVARCHAR</code> parameter as a <code>String</code> in
1335      * the Java programming language.
1336      * <p>
1337      * For the fixed-length type JDBC <code>CHAR</code>,
1338      * the <code>String</code> object
1339      * returned has exactly the same value the SQL
1340      * <code>CHAR</code> value had in the
1341      * database, including any padding added by the database.
1342      * @param parameterName the name of the parameter
1343      * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1344      * is <code>null</code>.
1345      * @exception SQLException if parameterName does not correspond to a named
1346      * parameter; if a database access error occurs or
1347      * this method is called on a closed <code>CallableStatement</code>
1348      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1349      * this method
1350      * @see #setString
1351      * @since 1.4
1352      */
1353     String getString(String parameterName) throws SQLException;
1354 
1355     /**
1356      * Retrieves the value of a JDBC <code>BIT</code> or <code>BOOLEAN</code>
1357      * parameter as a
1358      * <code>boolean</code> in the Java programming language.
1359      * @param parameterName the name of the parameter
1360      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
1361      * is <code>false</code>.
1362      * @exception SQLException if parameterName does not correspond to a named
1363      * parameter; if a database access error occurs or
1364      * this method is called on a closed <code>CallableStatement</code>
1365      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1366      * this method
1367      * @see #setBoolean
1368      * @since 1.4
1369      */
1370     boolean getBoolean(String parameterName) throws SQLException;
1371 
1372     /**
1373      * Retrieves the value of a JDBC <code>TINYINT</code> parameter as a <code>byte</code>
1374      * in the Java programming language.
1375      * @param parameterName the name of the parameter
1376      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
1377      * is <code>0</code>.
1378      * @exception SQLException if parameterName does not correspond to a named
1379      * parameter; if a database access error occurs or
1380      * this method is called on a closed <code>CallableStatement</code>
1381      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1382      * this method
1383      * @see #setByte
1384      * @since 1.4
1385      */
1386     byte getByte(String parameterName) throws SQLException;
1387 
1388     /**
1389      * Retrieves the value of a JDBC <code>SMALLINT</code> parameter as a <code>short</code>
1390      * in the Java programming language.
1391      * @param parameterName the name of the parameter
1392      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
1393      * is <code>0</code>.
1394      * @exception SQLException if parameterName does not correspond to a named
1395      * parameter; if a database access error occurs or
1396      * this method is called on a closed <code>CallableStatement</code>
1397      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1398      * this method
1399      * @see #setShort
1400      * @since 1.4
1401      */
1402     short getShort(String parameterName) throws SQLException;
1403 
1404     /**
1405      * Retrieves the value of a JDBC <code>INTEGER</code> parameter as an <code>int</code>
1406      * in the Java programming language.
1407      *
1408      * @param parameterName the name of the parameter
1409      * @return the parameter value.  If the value is SQL <code>NULL</code>,
1410      *         the result is <code>0</code>.
1411      * @exception SQLException if parameterName does not correspond to a named
1412      * parameter; if a database access error occurs or
1413      * this method is called on a closed <code>CallableStatement</code>
1414      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1415      * this method
1416      * @see #setInt
1417      * @since 1.4
1418      */
1419     int getInt(String parameterName) throws SQLException;
1420 
1421     /**
1422      * Retrieves the value of a JDBC <code>BIGINT</code> parameter as a <code>long</code>
1423      * in the Java programming language.
1424      *
1425      * @param parameterName the name of the parameter
1426      * @return the parameter value.  If the value is SQL <code>NULL</code>,
1427      *         the result is <code>0</code>.
1428      * @exception SQLException if parameterName does not correspond to a named
1429      * parameter; if a database access error occurs or
1430      * this method is called on a closed <code>CallableStatement</code>
1431      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1432      * this method
1433      * @see #setLong
1434      * @since 1.4
1435      */
1436     long getLong(String parameterName) throws SQLException;
1437 
1438     /**
1439      * Retrieves the value of a JDBC <code>FLOAT</code> parameter as a <code>float</code>
1440      * in the Java programming language.
1441      * @param parameterName the name of the parameter
1442      * @return the parameter value.  If the value is SQL <code>NULL</code>,
1443      *         the result is <code>0</code>.
1444      * @exception SQLException if parameterName does not correspond to a named
1445      * parameter; if a database access error occurs or
1446      * this method is called on a closed <code>CallableStatement</code>
1447      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1448      * this method
1449      * @see #setFloat
1450      * @since 1.4
1451      */
1452     float getFloat(String parameterName) throws SQLException;
1453 
1454     /**
1455      * Retrieves the value of a JDBC <code>DOUBLE</code> parameter as a <code>double</code>
1456      * in the Java programming language.
1457      * @param parameterName the name of the parameter
1458      * @return the parameter value.  If the value is SQL <code>NULL</code>,
1459      *         the result is <code>0</code>.
1460      * @exception SQLException if parameterName does not correspond to a named
1461      * parameter; if a database access error occurs or
1462      * this method is called on a closed <code>CallableStatement</code>
1463      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1464      * this method
1465      * @see #setDouble
1466      * @since 1.4
1467      */
1468     double getDouble(String parameterName) throws SQLException;
1469 
1470     /**
1471      * Retrieves the value of a JDBC <code>BINARY</code> or <code>VARBINARY</code>
1472      * parameter as an array of <code>byte</code> values in the Java
1473      * programming language.
1474      * @param parameterName the name of the parameter
1475      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result is
1476      *  <code>null</code>.
1477      * @exception SQLException if parameterName does not correspond to a named
1478      * parameter; if a database access error occurs or
1479      * this method is called on a closed <code>CallableStatement</code>
1480      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1481      * this method
1482      * @see #setBytes
1483      * @since 1.4
1484      */
1485     byte[] getBytes(String parameterName) throws SQLException;
1486 
1487     /**
1488      * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1489      * <code>java.sql.Date</code> object.
1490      * @param parameterName the name of the parameter
1491      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
1492      * is <code>null</code>.
1493      * @exception SQLException if parameterName does not correspond to a named
1494      * parameter; if a database access error occurs or
1495      * this method is called on a closed <code>CallableStatement</code>
1496      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1497      * this method
1498      * @see #setDate
1499      * @since 1.4
1500      */
1501     java.sql.Date getDate(String parameterName) throws SQLException;
1502 
1503     /**
1504      * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1505      * <code>java.sql.Time</code> object.
1506      * @param parameterName the name of the parameter
1507      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
1508      * is <code>null</code>.
1509      * @exception SQLException if parameterName does not correspond to a named
1510      * parameter; if a database access error occurs or
1511      * this method is called on a closed <code>CallableStatement</code>
1512      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1513      * this method
1514      * @see #setTime
1515      * @since 1.4
1516      */
1517     java.sql.Time getTime(String parameterName) throws SQLException;
1518 
1519     /**
1520      * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1521      * <code>java.sql.Timestamp</code> object.
1522      * @param parameterName the name of the parameter
1523      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result
1524      * is <code>null</code>.
1525      * @exception SQLException if parameterName does not correspond to a named
1526      * parameter; if a database access error occurs or
1527      * this method is called on a closed <code>CallableStatement</code>
1528      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1529      * this method
1530      * @see #setTimestamp
1531      * @since 1.4
1532      */
1533     java.sql.Timestamp getTimestamp(String parameterName) throws SQLException;
1534 
1535     /**
1536      * Retrieves the value of a parameter as an <code>Object</code> in the Java
1537      * programming language. If the value is an SQL <code>NULL</code>, the
1538      * driver returns a Java <code>null</code>.
1539      * <p>
1540      * This method returns a Java object whose type corresponds to the JDBC
1541      * type that was registered for this parameter using the method
1542      * <code>registerOutParameter</code>.  By registering the target JDBC
1543      * type as <code>java.sql.Types.OTHER</code>, this method can be used
1544      * to read database-specific abstract data types.
1545      * @param parameterName the name of the parameter
1546      * @return A <code>java.lang.Object</code> holding the OUT parameter value.
1547      * @exception SQLException if parameterName does not correspond to a named
1548      * parameter; if a database access error occurs or
1549      * this method is called on a closed <code>CallableStatement</code>
1550      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1551      * this method
1552      * @see Types
1553      * @see #setObject
1554      * @since 1.4
1555      */
1556     Object getObject(String parameterName) throws SQLException;
1557 
1558     /**
1559      * Retrieves the value of a JDBC <code>NUMERIC</code> parameter as a
1560      * <code>java.math.BigDecimal</code> object with as many digits to the
1561      * right of the decimal point as the value contains.
1562      * @param parameterName the name of the parameter
1563      * @return the parameter value in full precision.  If the value is
1564      * SQL <code>NULL</code>, the result is <code>null</code>.
1565      * @exception SQLExceptionif parameterName does not correspond to a named
1566      * parameter;  if a database access error occurs or
1567      * this method is called on a closed <code>CallableStatement</code>
1568      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1569      * this method
1570      * @see #setBigDecimal
1571      * @since 1.4
1572      */
1573     BigDecimal getBigDecimal(String parameterName) throws SQLException;
1574 
1575     /**
1576      * Returns an object representing the value of OUT parameter
1577      * <code>parameterName</code> and uses <code>map</code> for the custom
1578      * mapping of the parameter value.
1579      * <p>
1580      * This method returns a Java object whose type corresponds to the
1581      * JDBC type that was registered for this parameter using the method
1582      * <code>registerOutParameter</code>.  By registering the target
1583      * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
1584      * be used to read database-specific abstract data types.
1585      * @param parameterName the name of the parameter
1586      * @param map the mapping from SQL type names to Java classes
1587      * @return a <code>java.lang.Object</code> holding the OUT parameter value
1588      * @exception SQLException if parameterName does not correspond to a named
1589      * parameter; if a database access error occurs or
1590      * this method is called on a closed <code>CallableStatement</code>
1591      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1592      * this method
1593      * @see #setObject
1594      * @since 1.4
1595      */
1596     Object getObject(String parameterName, java.util.Map<String,Class<?>> map)
1597       throws SQLException;
1598 
1599     /**
1600      * Retrieves the value of a JDBC <code>REF(&lt;structured-type&gt;)</code>
1601      * parameter as a {@link java.sql.Ref} object in the Java programming language.
1602      *
1603      * @param parameterName the name of the parameter
1604      * @return the parameter value as a <code>Ref</code> object in the
1605      *         Java programming language.  If the value was SQL <code>NULL</code>,
1606      *         the value <code>null</code> is returned.
1607      * @exception SQLException if parameterName does not correspond to a named
1608      * parameter; if a database access error occurs or
1609      * this method is called on a closed <code>CallableStatement</code>
1610      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1611      * this method
1612      * @since 1.4
1613      */
1614     Ref getRef (String parameterName) throws SQLException;
1615 
1616     /**
1617      * Retrieves the value of a JDBC <code>BLOB</code> parameter as a
1618      * {@link java.sql.Blob} object in the Java programming language.
1619      *
1620      * @param parameterName the name of the parameter
1621      * @return the parameter value as a <code>Blob</code> object in the
1622      *         Java programming language.  If the value was SQL <code>NULL</code>,
1623      *         the value <code>null</code> is returned.
1624      * @exception SQLException if parameterName does not correspond to a named
1625      * parameter; if a database access error occurs or
1626      * this method is called on a closed <code>CallableStatement</code>
1627      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1628      * this method
1629      * @since 1.4
1630      */
1631     Blob getBlob (String parameterName) throws SQLException;
1632 
1633     /**
1634      * Retrieves the value of a JDBC <code>CLOB</code> parameter as a
1635      * <code>java.sql.Clob</code> object in the Java programming language.
1636      * @param parameterName the name of the parameter
1637      * @return the parameter value as a <code>Clob</code> object in the
1638      *         Java programming language.  If the value was SQL <code>NULL</code>,
1639      *         the value <code>null</code> is returned.
1640      * @exception SQLException if parameterName does not correspond to a named
1641      * parameter; if a database access error occurs or
1642      * this method is called on a closed <code>CallableStatement</code>
1643      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1644      * this method
1645      * @since 1.4
1646      */
1647     Clob getClob (String parameterName) throws SQLException;
1648 
1649     /**
1650      * Retrieves the value of a JDBC <code>ARRAY</code> parameter as an
1651      * {@link java.sql.Array} object in the Java programming language.
1652      *
1653      * @param parameterName the name of the parameter
1654      * @return the parameter value as an <code>Array</code> object in
1655      *         Java programming language.  If the value was SQL <code>NULL</code>,
1656      *         the value <code>null</code> is returned.
1657      * @exception SQLException if parameterName does not correspond to a named
1658      * parameter; if a database access error occurs or
1659      * this method is called on a closed <code>CallableStatement</code>
1660      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1661      * this method
1662      * @since 1.4
1663      */
1664     Array getArray (String parameterName) throws SQLException;
1665 
1666     /**
1667      * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1668      * <code>java.sql.Date</code> object, using
1669      * the given <code>Calendar</code> object
1670      * to construct the date.
1671      * With a <code>Calendar</code> object, the driver
1672      * can calculate the date taking into account a custom timezone and locale.
1673      * If no <code>Calendar</code> object is specified, the driver uses the
1674      * default timezone and locale.
1675      *
1676      * @param parameterName the name of the parameter
1677      * @param cal the <code>Calendar</code> object the driver will use
1678      *            to construct the date
1679      * @return the parameter value.  If the value is SQL <code>NULL</code>,
1680      * the result is <code>null</code>.
1681      * @exception SQLException if parameterName does not correspond to a named
1682      * parameter; if a database access error occurs or
1683      * this method is called on a closed <code>CallableStatement</code>
1684      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1685      * this method
1686      * @see #setDate
1687      * @since 1.4
1688      */
1689     java.sql.Date getDate(String parameterName, Calendar cal)
1690         throws SQLException;
1691 
1692     /**
1693      * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1694      * <code>java.sql.Time</code> object, using
1695      * the given <code>Calendar</code> object
1696      * to construct the time.
1697      * With a <code>Calendar</code> object, the driver
1698      * can calculate the time taking into account a custom timezone and locale.
1699      * If no <code>Calendar</code> object is specified, the driver uses the
1700      * default timezone and locale.
1701      *
1702      * @param parameterName the name of the parameter
1703      * @param cal the <code>Calendar</code> object the driver will use
1704      *            to construct the time
1705      * @return the parameter value; if the value is SQL <code>NULL</code>, the result is
1706      * <code>null</code>.
1707      * @exception SQLException if parameterName does not correspond to a named
1708      * parameter; if a database access error occurs or
1709      * this method is called on a closed <code>CallableStatement</code>
1710      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1711      * this method
1712      * @see #setTime
1713      * @since 1.4
1714      */
1715     java.sql.Time getTime(String parameterName, Calendar cal)
1716         throws SQLException;
1717 
1718     /**
1719      * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1720      * <code>java.sql.Timestamp</code> object, using
1721      * the given <code>Calendar</code> object to construct
1722      * the <code>Timestamp</code> object.
1723      * With a <code>Calendar</code> object, the driver
1724      * can calculate the timestamp taking into account a custom timezone and locale.
1725      * If no <code>Calendar</code> object is specified, the driver uses the
1726      * default timezone and locale.
1727      *
1728      *
1729      * @param parameterName the name of the parameter
1730      * @param cal the <code>Calendar</code> object the driver will use
1731      *            to construct the timestamp
1732      * @return the parameter value.  If the value is SQL <code>NULL</code>, the result is
1733      * <code>null</code>.
1734      * @exception SQLException if parameterName does not correspond to a named
1735      * parameter; if a database access error occurs or
1736      * this method is called on a closed <code>CallableStatement</code>
1737      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1738      * this method
1739      * @see #setTimestamp
1740      * @since 1.4
1741      */
1742     java.sql.Timestamp getTimestamp(String parameterName, Calendar cal)
1743         throws SQLException;
1744 
1745     /**
1746      * Retrieves the value of a JDBC <code>DATALINK</code> parameter as a
1747      * <code>java.net.URL</code> object.
1748      *
1749      * @param parameterName the name of the parameter
1750      * @return the parameter value as a <code>java.net.URL</code> object in the
1751      * Java programming language.  If the value was SQL <code>NULL</code>, the
1752      * value <code>null</code> is returned.
1753      * @exception SQLException if parameterName does not correspond to a named
1754      * parameter; if a database access error occurs,
1755      * this method is called on a closed <code>CallableStatement</code>,
1756      *            or if there is a problem with the URL
1757      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1758      * this method
1759      * @see #setURL
1760      * @since 1.4
1761      */
1762     java.net.URL getURL(String parameterName) throws SQLException;
1763 
1764     //------------------------- JDBC 4.0 -----------------------------------
1765 
1766     /**
1767      * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1768      * <code>java.sql.RowId</code> object.
1769      *
1770      * @param parameterIndex the first parameter is 1, the second is 2,...
1771      * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1772      *     value is used as the designated parameter. If the parameter contains
1773      * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1774      * @throws SQLException if the parameterIndex is not valid;
1775      * if a database access error occurs or
1776      * this method is called on a closed <code>CallableStatement</code>
1777      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1778      * this method
1779      * @since 1.6
1780      */
1781     RowId getRowId(int parameterIndex) throws SQLException;
1782 
1783     /**
1784      * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1785      * <code>java.sql.RowId</code> object.
1786      *
1787      * @param parameterName the name of the parameter
1788      * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1789      *     value is used as the designated parameter. If the parameter contains
1790      * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1791      * @throws SQLException if parameterName does not correspond to a named
1792      * parameter; if a database access error occurs or
1793      * this method is called on a closed <code>CallableStatement</code>
1794      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1795      * this method
1796      * @since 1.6
1797      */
1798     RowId getRowId(String parameterName) throws SQLException;
1799 
1800      /**
1801      * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1802      * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1803      * database.
1804      *
1805      * @param parameterName the name of the parameter
1806      * @param x the parameter value
1807      * @throws SQLException if parameterName does not correspond to a named
1808      * parameter; if a database access error occurs or
1809      * this method is called on a closed <code>CallableStatement</code>
1810      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1811      * this method
1812      * @since 1.6
1813      */
1814     void setRowId(String parameterName, RowId x) throws SQLException;
1815 
1816     /**
1817      * Sets the designated parameter to the given <code>String</code> object.
1818      * The driver converts this to a SQL <code>NCHAR</code> or
1819      * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1820      * @param parameterName the name of the parameter to be set
1821      * @param value the parameter value
1822      * @throws SQLException if parameterName does not correspond to a named
1823      * parameter; if the driver does not support national
1824      *         character sets;  if the driver can detect that a data conversion
1825      *  error could occur; if a database access error occurs or
1826      * this method is called on a closed <code>CallableStatement</code>
1827      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1828      * this method
1829      * @since 1.6
1830      */
1831     void setNString(String parameterName, String value)
1832             throws SQLException;
1833 
1834     /**
1835      * Sets the designated parameter to a <code>Reader</code> object. The
1836      * <code>Reader</code> reads the data till end-of-file is reached. The
1837      * driver does the necessary conversion from Java character format to
1838      * the national character set in the database.
1839      * @param parameterName the name of the parameter to be set
1840      * @param value the parameter value
1841      * @param length the number of characters in the parameter data.
1842      * @throws SQLException if parameterName does not correspond to a named
1843      * parameter; if the driver does not support national
1844      *         character sets;  if the driver can detect that a data conversion
1845      *  error could occur; if a database access error occurs or
1846      * this method is called on a closed <code>CallableStatement</code>
1847      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1848      * this method
1849      * @since 1.6
1850      */
1851     void setNCharacterStream(String parameterName, Reader value, long length)
1852             throws SQLException;
1853 
1854      /**
1855      * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
1856      * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
1857      * object maps to a SQL <code>NCLOB</code>.
1858      * @param parameterName the name of the parameter to be set
1859      * @param value the parameter value
1860      * @throws SQLException if parameterName does not correspond to a named
1861      * parameter; if the driver does not support national
1862      *         character sets;  if the driver can detect that a data conversion
1863      *  error could occur; if a database access error occurs or
1864      * this method is called on a closed <code>CallableStatement</code>
1865      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1866      * this method
1867      * @since 1.6
1868      */
1869      void setNClob(String parameterName, NClob value) throws SQLException;
1870 
1871     /**
1872      * Sets the designated parameter to a <code>Reader</code> object.  The <code>reader</code> must contain  the number
1873      * of characters specified by length otherwise a <code>SQLException</code> will be
1874      * generated when the <code>CallableStatement</code> is executed.
1875      * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1876      * because it informs the driver that the parameter value should be sent to
1877      * the server as a <code>CLOB</code>.  When the <code>setCharacterStream</code> method is used, the
1878      * driver may have to do extra work to determine whether the parameter
1879      * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1880      * @param parameterName the name of the parameter to be set
1881      * @param reader An object that contains the data to set the parameter value to.
1882      * @param length the number of characters in the parameter data.
1883      * @throws SQLException if parameterName does not correspond to a named
1884      * parameter; if the length specified is less than zero;
1885      * a database access error occurs or
1886      * this method is called on a closed <code>CallableStatement</code>
1887      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1888      * this method
1889      *
1890      * @since 1.6
1891      */
1892      void setClob(String parameterName, Reader reader, long length)
1893        throws SQLException;
1894 
1895     /**
1896      * Sets the designated parameter to a <code>InputStream</code> object.  The <code>inputstream</code> must contain  the number
1897      * of characters specified by length, otherwise a <code>SQLException</code> will be
1898      * generated when the <code>CallableStatement</code> is executed.
1899      * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1900      * method because it informs the driver that the parameter value should be
1901      * sent to the server as a <code>BLOB</code>.  When the <code>setBinaryStream</code> method is used,
1902      * the driver may have to do extra work to determine whether the parameter
1903      * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1904      *
1905      * @param parameterName the name of the parameter to be set
1906      * the second is 2, ...
1907      *
1908      * @param inputStream An object that contains the data to set the parameter
1909      * value to.
1910      * @param length the number of bytes in the parameter data.
1911      * @throws SQLException  if parameterName does not correspond to a named
1912      * parameter; if the length specified
1913      * is less than zero; if the number of bytes in the inputstream does not match
1914      * the specfied length; if a database access error occurs or
1915      * this method is called on a closed <code>CallableStatement</code>
1916      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1917      * this method
1918      *
1919      * @since 1.6
1920      */
1921      void setBlob(String parameterName, InputStream inputStream, long length)
1922         throws SQLException;
1923     /**
1924      * Sets the designated parameter to a <code>Reader</code> object.  The <code>reader</code> must contain  the number
1925      * of characters specified by length otherwise a <code>SQLException</code> will be
1926      * generated when the <code>CallableStatement</code> is executed.
1927      * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1928      * because it informs the driver that the parameter value should be sent to
1929      * the server as a <code>NCLOB</code>.  When the <code>setCharacterStream</code> method is used, the
1930      * driver may have to do extra work to determine whether the parameter
1931      * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
1932      *
1933      * @param parameterName the name of the parameter to be set
1934      * @param reader An object that contains the data to set the parameter value to.
1935      * @param length the number of characters in the parameter data.
1936      * @throws SQLException if parameterName does not correspond to a named
1937      * parameter; if the length specified is less than zero;
1938      * if the driver does not support national
1939      *         character sets;  if the driver can detect that a data conversion
1940      *  error could occur; if a database access error occurs or
1941      * this method is called on a closed <code>CallableStatement</code>
1942      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1943      * this method
1944      * @since 1.6
1945      */
1946      void setNClob(String parameterName, Reader reader, long length)
1947        throws SQLException;
1948 
1949     /**
1950      * Retrieves the value of the designated JDBC <code>NCLOB</code> parameter as a
1951      * <code>java.sql.NClob</code> object in the Java programming language.
1952      *
1953      * @param parameterIndex the first parameter is 1, the second is 2, and
1954      * so on
1955      * @return the parameter value as a <code>NClob</code> object in the
1956      * Java programming language.  If the value was SQL <code>NULL</code>, the
1957      * value <code>null</code> is returned.
1958      * @exception SQLException if the parameterIndex is not valid;
1959      * if the driver does not support national
1960      *         character sets;  if the driver can detect that a data conversion
1961      *  error could occur; if a database access error occurs or
1962      * this method is called on a closed <code>CallableStatement</code>
1963      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1964      * this method
1965      * @since 1.6
1966      */
1967     NClob getNClob (int parameterIndex) throws SQLException;
1968 
1969 
1970     /**
1971      * Retrieves the value of a JDBC <code>NCLOB</code> parameter as a
1972      * <code>java.sql.NClob</code> object in the Java programming language.
1973      * @param parameterName the name of the parameter
1974      * @return the parameter value as a <code>NClob</code> object in the
1975      *         Java programming language.  If the value was SQL <code>NULL</code>,
1976      *         the value <code>null</code> is returned.
1977      * @exception SQLException if parameterName does not correspond to a named
1978      * parameter; if the driver does not support national
1979      *         character sets;  if the driver can detect that a data conversion
1980      *  error could occur; if a database access error occurs or
1981      * this method is called on a closed <code>CallableStatement</code>
1982      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1983      * this method
1984      * @since 1.6
1985      */
1986     NClob getNClob (String parameterName) throws SQLException;
1987 
1988     /**
1989      * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1990      * <code>SQL XML</code> value when it sends it to the database.
1991      *
1992      * @param parameterName the name of the parameter
1993      * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
1994      * @throws SQLException if parameterName does not correspond to a named
1995      * parameter; if a database access error occurs;
1996      * this method is called on a closed <code>CallableStatement</code> or
1997      * the <code>java.xml.transform.Result</code>,
1998    *  <code>Writer</code> or <code>OutputStream</code> has not been closed for the <code>SQLXML</code> object
1999      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2000      * this method
2001      *
2002      * @since 1.6
2003      */
2004     void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException;
2005 
2006     /**
2007      * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2008      * <code>java.sql.SQLXML</code> object in the Java programming language.
2009      * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2010      * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2011      * @throws SQLException if the parameterIndex is not valid;
2012      * if a database access error occurs or
2013      * this method is called on a closed <code>CallableStatement</code>
2014      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2015      * this method
2016      * @since 1.6
2017      */
2018     SQLXML getSQLXML(int parameterIndex) throws SQLException;
2019 
2020     /**
2021      * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2022      * <code>java.sql.SQLXML</code> object in the Java programming language.
2023      * @param parameterName the name of the parameter
2024      * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2025      * @throws SQLException if parameterName does not correspond to a named
2026      * parameter; if a database access error occurs or
2027      * this method is called on a closed <code>CallableStatement</code>
2028      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2029      * this method
2030      * @since 1.6
2031      */
2032     SQLXML getSQLXML(String parameterName) throws SQLException;
2033 
2034     /**
2035      * Retrieves the value of the designated <code>NCHAR</code>,
2036      * <code>NVARCHAR</code>
2037      * or <code>LONGNVARCHAR</code> parameter as
2038      * a <code>String</code> in the Java programming language.
2039      *  <p>
2040      * For the fixed-length type JDBC <code>NCHAR</code>,
2041      * the <code>String</code> object
2042      * returned has exactly the same value the SQL
2043      * <code>NCHAR</code> value had in the
2044      * database, including any padding added by the database.
2045      *
2046      * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2047      * @return a <code>String</code> object that maps an
2048      * <code>NCHAR</code>, <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
2049      * @exception SQLException if the parameterIndex is not valid;
2050      * if a database access error occurs or
2051      * this method is called on a closed <code>CallableStatement</code>
2052      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2053      * this method
2054      * @since 1.6
2055      * @see #setNString
2056      */
2057     String getNString(int parameterIndex) throws SQLException;
2058 
2059 
2060     /**
2061      *  Retrieves the value of the designated <code>NCHAR</code>,
2062      * <code>NVARCHAR</code>
2063      * or <code>LONGNVARCHAR</code> parameter as
2064      * a <code>String</code> in the Java programming language.
2065      * <p>
2066      * For the fixed-length type JDBC <code>NCHAR</code>,
2067      * the <code>String</code> object
2068      * returned has exactly the same value the SQL
2069      * <code>NCHAR</code> value had in the
2070      * database, including any padding added by the database.
2071      *
2072      * @param parameterName the name of the parameter
2073      * @return a <code>String</code> object that maps an
2074      * <code>NCHAR</code>, <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
2075      * @exception SQLException if parameterName does not correspond to a named
2076      * parameter;
2077      * if a database access error occurs or
2078      * this method is called on a closed <code>CallableStatement</code>
2079      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2080      * this method
2081      * @since 1.6
2082      * @see #setNString
2083      */
2084     String getNString(String parameterName) throws SQLException;
2085 
2086     /**
2087      * Retrieves the value of the designated parameter as a
2088      * <code>java.io.Reader</code> object in the Java programming language.
2089      * It is intended for use when
2090      * accessing  <code>NCHAR</code>,<code>NVARCHAR</code>
2091      * and <code>LONGNVARCHAR</code> parameters.
2092      *
2093      * @return a <code>java.io.Reader</code> object that contains the parameter
2094      * value; if the value is SQL <code>NULL</code>, the value returned is
2095      * <code>null</code> in the Java programming language.
2096      * @param parameterIndex the first parameter is 1, the second is 2, ...
2097      * @exception SQLException if the parameterIndex is not valid;
2098      * if a database access error occurs or
2099      * this method is called on a closed <code>CallableStatement</code>
2100      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2101      * this method
2102      * @since 1.6
2103      */
2104     java.io.Reader getNCharacterStream(int parameterIndex) throws SQLException;
2105 
2106     /**
2107      * Retrieves the value of the designated parameter as a
2108      * <code>java.io.Reader</code> object in the Java programming language.
2109      * It is intended for use when
2110      * accessing  <code>NCHAR</code>,<code>NVARCHAR</code>
2111      * and <code>LONGNVARCHAR</code> parameters.
2112      *
2113      * @param parameterName the name of the parameter
2114      * @return a <code>java.io.Reader</code> object that contains the parameter
2115      * value; if the value is SQL <code>NULL</code>, the value returned is
2116      * <code>null</code> in the Java programming language
2117      * @exception SQLException if parameterName does not correspond to a named
2118      * parameter; if a database access error occurs or
2119      * this method is called on a closed <code>CallableStatement</code>
2120      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2121      * this method
2122      * @since 1.6
2123      */
2124     java.io.Reader getNCharacterStream(String parameterName) throws SQLException;
2125 
2126     /**
2127      * Retrieves the value of the designated parameter as a
2128      * <code>java.io.Reader</code> object in the Java programming language.
2129      *
2130      * @return a <code>java.io.Reader</code> object that contains the parameter
2131      * value; if the value is SQL <code>NULL</code>, the value returned is
2132      * <code>null</code> in the Java programming language.
2133      * @param parameterIndex the first parameter is 1, the second is 2, ...
2134      * @exception SQLException if the parameterIndex is not valid; if a database access error occurs or
2135      * this method is called on a closed <code>CallableStatement</code>
2136      * @since 1.6
2137      */
2138     java.io.Reader getCharacterStream(int parameterIndex) throws SQLException;
2139 
2140     /**
2141      * Retrieves the value of the designated parameter as a
2142      * <code>java.io.Reader</code> object in the Java programming language.
2143      *
2144      * @param parameterName the name of the parameter
2145      * @return a <code>java.io.Reader</code> object that contains the parameter
2146      * value; if the value is SQL <code>NULL</code>, the value returned is
2147      * <code>null</code> in the Java programming language
2148      * @exception SQLException if parameterName does not correspond to a named
2149      * parameter; if a database access error occurs or
2150      * this method is called on a closed <code>CallableStatement</code>
2151      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2152      * this method
2153      * @since 1.6
2154      */
2155     java.io.Reader getCharacterStream(String parameterName) throws SQLException;
2156 
2157     /**
2158      * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
2159      * The driver converts this to an SQL <code>BLOB</code> value when it
2160      * sends it to the database.
2161      *
2162      * @param parameterName the name of the parameter
2163      * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
2164      * @exception SQLException if parameterName does not correspond to a named
2165      * parameter; if a database access error occurs or
2166      * this method is called on a closed <code>CallableStatement</code>
2167      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2168      * this method
2169      * @since 1.6
2170      */
2171     void setBlob (String parameterName, Blob x) throws SQLException;
2172 
2173     /**
2174      * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
2175      * The driver converts this to an SQL <code>CLOB</code> value when it
2176      * sends it to the database.
2177      *
2178      * @param parameterName the name of the parameter
2179      * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
2180      * @exception SQLException if parameterName does not correspond to a named
2181      * parameter; if a database access error occurs or
2182      * this method is called on a closed <code>CallableStatement</code>
2183      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2184      * this method
2185      * @since 1.6
2186      */
2187     void setClob (String parameterName, Clob x) throws SQLException;
2188     /**
2189      * Sets the designated parameter to the given input stream, which will have
2190      * the specified number of bytes.
2191      * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2192      * parameter, it may be more practical to send it via a
2193      * <code>java.io.InputStream</code>. Data will be read from the stream
2194      * as needed until end-of-file is reached.  The JDBC driver will
2195      * do any necessary conversion from ASCII to the database char format.
2196      *
2197      * <P><B>Note:</B> This stream object can either be a standard
2198      * Java stream object or your own subclass that implements the
2199      * standard interface.
2200      *
2201      * @param parameterName the name of the parameter
2202      * @param x the Java input stream that contains the ASCII parameter value
2203      * @param length the number of bytes in the stream
2204      * @exception SQLException if parameterName does not correspond to a named
2205      * parameter; if a database access error occurs or
2206      * this method is called on a closed <code>CallableStatement</code>
2207      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2208      * this method
2209      * @since 1.6
2210      */
2211     void setAsciiStream(String parameterName, java.io.InputStream x, long length)
2212         throws SQLException;
2213 
2214     /**
2215      * Sets the designated parameter to the given input stream, which will have
2216      * the specified number of bytes.
2217      * When a very large binary value is input to a <code>LONGVARBINARY</code>
2218      * parameter, it may be more practical to send it via a
2219      * <code>java.io.InputStream</code> object. The data will be read from the stream
2220      * as needed until end-of-file is reached.
2221      *
2222      * <P><B>Note:</B> This stream object can either be a standard
2223      * Java stream object or your own subclass that implements the
2224      * standard interface.
2225      *
2226      * @param parameterName the name of the parameter
2227      * @param x the java input stream which contains the binary parameter value
2228      * @param length the number of bytes in the stream
2229      * @exception SQLException if parameterName does not correspond to a named
2230      * parameter; if a database access error occurs or
2231      * this method is called on a closed <code>CallableStatement</code>
2232      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2233      * this method
2234      * @since 1.6
2235      */
2236     void setBinaryStream(String parameterName, java.io.InputStream x,
2237                          long length) throws SQLException;
2238         /**
2239      * Sets the designated parameter to the given <code>Reader</code>
2240      * object, which is the given number of characters long.
2241      * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2242      * parameter, it may be more practical to send it via a
2243      * <code>java.io.Reader</code> object. The data will be read from the stream
2244      * as needed until end-of-file is reached.  The JDBC driver will
2245      * do any necessary conversion from UNICODE to the database char format.
2246      *
2247      * <P><B>Note:</B> This stream object can either be a standard
2248      * Java stream object or your own subclass that implements the
2249      * standard interface.
2250      *
2251      * @param parameterName the name of the parameter
2252      * @param reader the <code>java.io.Reader</code> object that
2253      *        contains the UNICODE data used as the designated parameter
2254      * @param length the number of characters in the stream
2255      * @exception SQLException if parameterName does not correspond to a named
2256      * parameter; if a database access error occurs or
2257      * this method is called on a closed <code>CallableStatement</code>
2258      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2259      * this method
2260      * @since 1.6
2261      */
2262     void setCharacterStream(String parameterName,
2263                             java.io.Reader reader,
2264                             long length) throws SQLException;
2265      //--
2266     /**
2267      * Sets the designated parameter to the given input stream.
2268      * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2269      * parameter, it may be more practical to send it via a
2270      * <code>java.io.InputStream</code>. Data will be read from the stream
2271      * as needed until end-of-file is reached.  The JDBC driver will
2272      * do any necessary conversion from ASCII to the database char format.
2273      *
2274      * <P><B>Note:</B> This stream object can either be a standard
2275      * Java stream object or your own subclass that implements the
2276      * standard interface.
2277      * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2278      * it might be more efficient to use a version of
2279      * <code>setAsciiStream</code> which takes a length parameter.
2280      *
2281      * @param parameterName the name of the parameter
2282      * @param x the Java input stream that contains the ASCII parameter value
2283      * @exception SQLException if parameterName does not correspond to a named
2284      * parameter; if a database access error occurs or
2285      * this method is called on a closed <code>CallableStatement</code>
2286      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
2287        * @since 1.6
2288     */
2289     void setAsciiStream(String parameterName, java.io.InputStream x)
2290             throws SQLException;
2291     /**
2292      * Sets the designated parameter to the given input stream.
2293      * When a very large binary value is input to a <code>LONGVARBINARY</code>
2294      * parameter, it may be more practical to send it via a
2295      * <code>java.io.InputStream</code> object. The data will be read from the
2296      * stream as needed until end-of-file is reached.
2297      *
2298      * <P><B>Note:</B> This stream object can either be a standard
2299      * Java stream object or your own subclass that implements the
2300      * standard interface.
2301      * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2302      * it might be more efficient to use a version of
2303      * <code>setBinaryStream</code> which takes a length parameter.
2304      *
2305      * @param parameterName the name of the parameter
2306      * @param x the java input stream which contains the binary parameter value
2307      * @exception SQLException if parameterName does not correspond to a named
2308      * parameter; if a database access error occurs or
2309      * this method is called on a closed <code>CallableStatement</code>
2310      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
2311      * @since 1.6
2312      */
2313     void setBinaryStream(String parameterName, java.io.InputStream x)
2314     throws SQLException;
2315     /**
2316      * Sets the designated parameter to the given <code>Reader</code>
2317      * object.
2318      * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2319      * parameter, it may be more practical to send it via a
2320      * <code>java.io.Reader</code> object. The data will be read from the stream
2321      * as needed until end-of-file is reached.  The JDBC driver will
2322      * do any necessary conversion from UNICODE to the database char format.
2323      *
2324      * <P><B>Note:</B> This stream object can either be a standard
2325      * Java stream object or your own subclass that implements the
2326      * standard interface.
2327      * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2328      * it might be more efficient to use a version of
2329      * <code>setCharacterStream</code> which takes a length parameter.
2330      *
2331      * @param parameterName the name of the parameter
2332      * @param reader the <code>java.io.Reader</code> object that contains the
2333      *        Unicode data
2334      * @exception SQLException if parameterName does not correspond to a named
2335      * parameter; if a database access error occurs or
2336      * this method is called on a closed <code>CallableStatement</code>
2337      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
2338      * @since 1.6
2339      */
2340     void setCharacterStream(String parameterName,
2341                           java.io.Reader reader) throws SQLException;
2342   /**
2343      * Sets the designated parameter to a <code>Reader</code> object. The
2344      * <code>Reader</code> reads the data till end-of-file is reached. The
2345      * driver does the necessary conversion from Java character format to
2346      * the national character set in the database.
2347 
2348      * <P><B>Note:</B> This stream object can either be a standard
2349      * Java stream object or your own subclass that implements the
2350      * standard interface.
2351      * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2352      * it might be more efficient to use a version of
2353      * <code>setNCharacterStream</code> which takes a length parameter.
2354      *
2355      * @param parameterName the name of the parameter
2356      * @param value the parameter value
2357      * @throws SQLException if parameterName does not correspond to a named
2358      * parameter; if the driver does not support national
2359      *         character sets;  if the driver can detect that a data conversion
2360      *  error could occur; if a database access error occurs; or
2361      * this method is called on a closed <code>CallableStatement</code>
2362      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
2363      * @since 1.6
2364      */
2365      void setNCharacterStream(String parameterName, Reader value) throws SQLException;
2366 
2367     /**
2368      * Sets the designated parameter to a <code>Reader</code> object.
2369      * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2370      * because it informs the driver that the parameter value should be sent to
2371      * the server as a <code>CLOB</code>.  When the <code>setCharacterStream</code> method is used, the
2372      * driver may have to do extra work to determine whether the parameter
2373      * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
2374      *
2375      * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2376      * it might be more efficient to use a version of
2377      * <code>setClob</code> which takes a length parameter.
2378      *
2379      * @param parameterName the name of the parameter
2380      * @param reader An object that contains the data to set the parameter value to.
2381      * @throws SQLException if parameterName does not correspond to a named
2382      * parameter; if a database access error occurs or this method is called on
2383      * a closed <code>CallableStatement</code>
2384      *
2385      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
2386      * @since 1.6
2387      */
2388      void setClob(String parameterName, Reader reader)
2389        throws SQLException;
2390 
2391     /**
2392      * Sets the designated parameter to a <code>InputStream</code> object.
2393      * This method differs from the <code>setBinaryStream (int, InputStream)</code>
2394      * method because it informs the driver that the parameter value should be
2395      * sent to the server as a <code>BLOB</code>.  When the <code>setBinaryStream</code> method is used,
2396      * the driver may have to do extra work to determine whether the parameter
2397      * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
2398      *
2399      * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2400      * it might be more efficient to use a version of
2401      * <code>setBlob</code> which takes a length parameter.
2402      *
2403      * @param parameterName the name of the parameter
2404      * @param inputStream An object that contains the data to set the parameter
2405      * value to.
2406      * @throws SQLException if parameterName does not correspond to a named
2407      * parameter; if a database access error occurs or
2408      * this method is called on a closed <code>CallableStatement</code>
2409      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
2410      *
2411      * @since 1.6
2412      */
2413      void setBlob(String parameterName, InputStream inputStream)
2414         throws SQLException;
2415     /**
2416      * Sets the designated parameter to a <code>Reader</code> object.
2417      * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2418      * because it informs the driver that the parameter value should be sent to
2419      * the server as a <code>NCLOB</code>.  When the <code>setCharacterStream</code> method is used, the
2420      * driver may have to do extra work to determine whether the parameter
2421      * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2422      * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2423      * it might be more efficient to use a version of
2424      * <code>setNClob</code> which takes a length parameter.
2425      *
2426      * @param parameterName the name of the parameter
2427      * @param reader An object that contains the data to set the parameter value to.
2428      * @throws SQLException if parameterName does not correspond to a named
2429      * parameter; if the driver does not support national character sets;
2430      * if the driver can detect that a data conversion
2431      *  error could occur;  if a database access error occurs or
2432      * this method is called on a closed <code>CallableStatement</code>
2433      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
2434      *
2435      * @since 1.6
2436      */
2437      void setNClob(String parameterName, Reader reader)
2438        throws SQLException;
2439 
2440     //------------------------- JDBC 4.1 -----------------------------------
2441 
2442 
2443     /**
2444      *<p>Returns an object representing the value of OUT parameter
2445      * {@code parameterIndex} and will convert from the
2446      * SQL type of the parameter to the requested Java data type, if the
2447      * conversion is supported. If the conversion is not
2448      * supported or null is specified for the type, a
2449      * <code>SQLException</code> is thrown.
2450      *<p>
2451      * At a minimum, an implementation must support the conversions defined in
2452      * Appendix B, Table B-3 and conversion of appropriate user defined SQL
2453      * types to a Java type which implements {@code SQLData}, or {@code Struct}.
2454      * Additional conversions may be supported and are vendor defined.
2455      *
2456      * @param parameterIndex the first parameter is 1, the second is 2, and so on
2457      * @param type Class representing the Java data type to convert the
2458      * designated parameter to.
2459      * @return an instance of {@code type} holding the OUT parameter value
2460      * @throws SQLException if conversion is not supported, type is null or
2461      *         another error occurs. The getCause() method of the
2462      * exception may provide a more detailed exception, for example, if
2463      * a conversion error occurs
2464      * @throws SQLFeatureNotSupportedException if the JDBC driver does not support
2465      * this method
2466      * @since 1.7
2467      */
2468      public <T> T getObject(int parameterIndex, Class<T> type) throws SQLException;
2469 
2470 
2471     /**
2472      *<p>Returns an object representing the value of OUT parameter
2473      * {@code parameterName} and will convert from the
2474      * SQL type of the parameter to the requested Java data type, if the
2475      * conversion is supported. If the conversion is not
2476      * supported  or null is specified for the type, a
2477      * <code>SQLException</code> is thrown.
2478      *<p>
2479      * At a minimum, an implementation must support the conversions defined in
2480      * Appendix B, Table B-3 and conversion of appropriate user defined SQL
2481      * types to a Java type which implements {@code SQLData}, or {@code Struct}.
2482      * Additional conversions may be supported and are vendor defined.
2483      *
2484      * @param parameterName the name of the parameter
2485      * @param type Class representing the Java data type to convert
2486      * the designated parameter to.
2487      * @return an instance of {@code type} holding the OUT parameter
2488      * value
2489      * @throws SQLException if conversion is not supported, type is null or
2490      *         another error occurs. The getCause() method of the
2491      * exception may provide a more detailed exception, for example, if
2492      * a conversion error occurs
2493      * @throws SQLFeatureNotSupportedException if the JDBC driver does not support
2494      * this method
2495      * @since 1.7
2496      */
2497      public <T> T getObject(String parameterName, Class<T> type) throws SQLException;
2498 
2499 }