0001 /*
0002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
0003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0004 *
0005 * This code is free software; you can redistribute it and/or modify it
0006 * under the terms of the GNU General Public License version 2 only, as
0007 * published by the Free Software Foundation. Sun designates this
0008 * particular file as subject to the "Classpath" exception as provided
0009 * by Sun in the LICENSE file that accompanied this code.
0010 *
0011 * This code is distributed in the hope that it will be useful, but WITHOUT
0012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0014 * version 2 for more details (a copy is included in the LICENSE file that
0015 * accompanied this code).
0016 *
0017 * You should have received a copy of the GNU General Public License version
0018 * 2 along with this work; if not, write to the Free Software Foundation,
0019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0020 *
0021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0022 * CA 95054 USA or visit www.sun.com if you need additional information or
0023 * have any questions.
0024 */
0025
0026 package java.sql;
0027
0028 import java.math.BigDecimal;
0029 import java.util.Calendar;
0030 import java.io.Reader;
0031 import java.io.InputStream;
0032
0033 /**
0034 * The interface used to execute SQL stored procedures. The JDBC API
0035 * provides a stored procedure SQL escape syntax that allows stored procedures
0036 * to be called in a standard way for all RDBMSs. This escape syntax has one
0037 * form that includes a result parameter and one that does not. If used, the result
0038 * parameter must be registered as an OUT parameter. The other parameters
0039 * can be used for input, output or both. Parameters are referred to
0040 * sequentially, by number, with the first parameter being 1.
0041 * <PRE>
0042 * {?= call <procedure-name>[(<arg1>,<arg2>, ...)]}
0043 * {call <procedure-name>[(<arg1>,<arg2>, ...)]}
0044 * </PRE>
0045 * <P>
0046 * IN parameter values are set using the <code>set</code> methods inherited from
0047 * {@link PreparedStatement}. The type of all OUT parameters must be
0048 * registered prior to executing the stored procedure; their values
0049 * are retrieved after execution via the <code>get</code> methods provided here.
0050 * <P>
0051 * A <code>CallableStatement</code> can return one {@link ResultSet} object or
0052 * multiple <code>ResultSet</code> objects. Multiple
0053 * <code>ResultSet</code> objects are handled using operations
0054 * inherited from {@link Statement}.
0055 * <P>
0056 * For maximum portability, a call's <code>ResultSet</code> objects and
0057 * update counts should be processed prior to getting the values of output
0058 * parameters.
0059 * <P>
0060 *
0061 * @see Connection#prepareCall
0062 * @see ResultSet
0063 */
0064
0065 public interface CallableStatement extends PreparedStatement {
0066
0067 /**
0068 * Registers the OUT parameter in ordinal position
0069 * <code>parameterIndex</code> to the JDBC type
0070 * <code>sqlType</code>. All OUT parameters must be registered
0071 * before a stored procedure is executed.
0072 * <p>
0073 * The JDBC type specified by <code>sqlType</code> for an OUT
0074 * parameter determines the Java type that must be used
0075 * in the <code>get</code> method to read the value of that parameter.
0076 * <p>
0077 * If the JDBC type expected to be returned to this output parameter
0078 * is specific to this particular database, <code>sqlType</code>
0079 * should be <code>java.sql.Types.OTHER</code>. The method
0080 * {@link #getObject} retrieves the value.
0081 *
0082 * @param parameterIndex the first parameter is 1, the second is 2,
0083 * and so on
0084 * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
0085 * If the parameter is of JDBC type <code>NUMERIC</code>
0086 * or <code>DECIMAL</code>, the version of
0087 * <code>registerOutParameter</code> that accepts a scale value
0088 * should be used.
0089 *
0090 * @exception SQLException if the parameterIndex is not valid;
0091 * if a database access error occurs or
0092 * this method is called on a closed <code>CallableStatement</code>
0093 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0094 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0095 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0096 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0097 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0098 * or <code>STRUCT</code> data type and the JDBC driver does not support
0099 * this data type
0100 * @see Types
0101 */
0102 void registerOutParameter(int parameterIndex, int sqlType)
0103 throws SQLException;
0104
0105 /**
0106 * Registers the parameter in ordinal position
0107 * <code>parameterIndex</code> to be of JDBC type
0108 * <code>sqlType</code>. All OUT parameters must be registered
0109 * before a stored procedure is executed.
0110 * <p>
0111 * The JDBC type specified by <code>sqlType</code> for an OUT
0112 * parameter determines the Java type that must be used
0113 * in the <code>get</code> method to read the value of that parameter.
0114 * <p>
0115 * This version of <code>registerOutParameter</code> should be
0116 * used when the parameter is of JDBC type <code>NUMERIC</code>
0117 * or <code>DECIMAL</code>.
0118 *
0119 * @param parameterIndex the first parameter is 1, the second is 2,
0120 * and so on
0121 * @param sqlType the SQL type code defined by <code>java.sql.Types</code>.
0122 * @param scale the desired number of digits to the right of the
0123 * decimal point. It must be greater than or equal to zero.
0124 * @exception SQLException if the parameterIndex is not valid;
0125 * if a database access error occurs or
0126 * this method is called on a closed <code>CallableStatement</code>
0127 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0128 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0129 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0130 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0131 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0132 * or <code>STRUCT</code> data type and the JDBC driver does not support
0133 * this data type
0134 * @see Types
0135 */
0136 void registerOutParameter(int parameterIndex, int sqlType, int scale)
0137 throws SQLException;
0138
0139 /**
0140 * Retrieves whether the last OUT parameter read had the value of
0141 * SQL <code>NULL</code>. Note that this method should be called only after
0142 * calling a getter method; otherwise, there is no value to use in
0143 * determining whether it is <code>null</code> or not.
0144 *
0145 * @return <code>true</code> if the last parameter read was SQL
0146 * <code>NULL</code>; <code>false</code> otherwise
0147 * @exception SQLException if a database access error occurs or
0148 * this method is called on a closed <code>CallableStatement</code>
0149 */
0150 boolean wasNull() throws SQLException;
0151
0152 /**
0153 * Retrieves the value of the designated JDBC <code>CHAR</code>,
0154 * <code>VARCHAR</code>, or <code>LONGVARCHAR</code> parameter as a
0155 * <code>String</code> in the Java programming language.
0156 * <p>
0157 * For the fixed-length type JDBC <code>CHAR</code>,
0158 * the <code>String</code> object
0159 * returned has exactly the same value the SQL
0160 * <code>CHAR</code> value had in the
0161 * database, including any padding added by the database.
0162 *
0163 * @param parameterIndex the first parameter is 1, the second is 2,
0164 * and so on
0165 * @return the parameter value. If the value is SQL <code>NULL</code>,
0166 * the result
0167 * is <code>null</code>.
0168 * @exception SQLException if the parameterIndex is not valid;
0169 * if a database access error occurs or
0170 * this method is called on a closed <code>CallableStatement</code>
0171 * @see #setString
0172 */
0173 String getString(int parameterIndex) throws SQLException;
0174
0175 /**
0176 * Retrieves the value of the designated JDBC <code>BIT</code>
0177 * or <code>BOOLEAN</code> parameter as a
0178 * <code>boolean</code> in the Java programming language.
0179 *
0180 * @param parameterIndex the first parameter is 1, the second is 2,
0181 * and so on
0182 * @return the parameter value. If the value is SQL <code>NULL</code>,
0183 * the result is <code>false</code>.
0184 * @exception SQLException if the parameterIndex is not valid;
0185 * if a database access error occurs or
0186 * this method is called on a closed <code>CallableStatement</code>
0187 * @see #setBoolean
0188 */
0189 boolean getBoolean(int parameterIndex) throws SQLException;
0190
0191 /**
0192 * Retrieves the value of the designated JDBC <code>TINYINT</code> parameter
0193 * as a <code>byte</code> in the Java programming language.
0194 *
0195 * @param parameterIndex the first parameter is 1, the second is 2,
0196 * and so on
0197 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0198 * is <code>0</code>.
0199 * @exception SQLException if the parameterIndex is not valid;
0200 * if a database access error occurs or
0201 * this method is called on a closed <code>CallableStatement</code>
0202 * @see #setByte
0203 */
0204 byte getByte(int parameterIndex) throws SQLException;
0205
0206 /**
0207 * Retrieves the value of the designated JDBC <code>SMALLINT</code> parameter
0208 * as a <code>short</code> in the Java programming language.
0209 *
0210 * @param parameterIndex the first parameter is 1, the second is 2,
0211 * and so on
0212 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0213 * is <code>0</code>.
0214 * @exception SQLException if the parameterIndex is not valid;
0215 * if a database access error occurs or
0216 * this method is called on a closed <code>CallableStatement</code>
0217 * @see #setShort
0218 */
0219 short getShort(int parameterIndex) throws SQLException;
0220
0221 /**
0222 * Retrieves the value of the designated JDBC <code>INTEGER</code> parameter
0223 * as an <code>int</code> in the Java programming language.
0224 *
0225 * @param parameterIndex the first parameter is 1, the second is 2,
0226 * and so on
0227 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0228 * is <code>0</code>.
0229 * @exception SQLException if the parameterIndex is not valid;
0230 * if a database access error occurs or
0231 * this method is called on a closed <code>CallableStatement</code>
0232 * @see #setInt
0233 */
0234 int getInt(int parameterIndex) throws SQLException;
0235
0236 /**
0237 * Retrieves the value of the designated JDBC <code>BIGINT</code> parameter
0238 * as a <code>long</code> in the Java programming language.
0239 *
0240 * @param parameterIndex the first parameter is 1, the second is 2,
0241 * and so on
0242 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0243 * is <code>0</code>.
0244 * @exception SQLException if the parameterIndex is not valid;
0245 * if a database access error occurs or
0246 * this method is called on a closed <code>CallableStatement</code>
0247 * @see #setLong
0248 */
0249 long getLong(int parameterIndex) throws SQLException;
0250
0251 /**
0252 * Retrieves the value of the designated JDBC <code>FLOAT</code> parameter
0253 * as a <code>float</code> in the Java programming language.
0254 *
0255 * @param parameterIndex the first parameter is 1, the second is 2,
0256 * and so on
0257 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0258 * is <code>0</code>.
0259 * @exception SQLException if the parameterIndex is not valid;
0260 * if a database access error occurs or
0261 * this method is called on a closed <code>CallableStatement</code>
0262 * @see #setFloat
0263 */
0264 float getFloat(int parameterIndex) throws SQLException;
0265
0266 /**
0267 * Retrieves the value of the designated JDBC <code>DOUBLE</code> parameter as a <code>double</code>
0268 * in the Java programming language.
0269 * @param parameterIndex the first parameter is 1, the second is 2,
0270 * and so on
0271 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0272 * is <code>0</code>.
0273 * @exception SQLException if the parameterIndex is not valid;
0274 * if a database access error occurs or
0275 * this method is called on a closed <code>CallableStatement</code>
0276 * @see #setDouble
0277 */
0278 double getDouble(int parameterIndex) throws SQLException;
0279
0280 /**
0281 * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
0282 * <code>java.math.BigDecimal</code> object with <i>scale</i> digits to
0283 * the right of the decimal point.
0284 * @param parameterIndex the first parameter is 1, the second is 2,
0285 * and so on
0286 * @param scale the number of digits to the right of the decimal point
0287 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0288 * is <code>null</code>.
0289 * @exception SQLException if the parameterIndex is not valid;
0290 * if a database access error occurs or
0291 * this method is called on a closed <code>CallableStatement</code>
0292 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0293 * this method
0294 * @deprecated use <code>getBigDecimal(int parameterIndex)</code>
0295 * or <code>getBigDecimal(String parameterName)</code>
0296 * @see #setBigDecimal
0297 */
0298 BigDecimal getBigDecimal(int parameterIndex, int scale)
0299 throws SQLException;
0300
0301 /**
0302 * Retrieves the value of the designated JDBC <code>BINARY</code> or
0303 * <code>VARBINARY</code> parameter as an array of <code>byte</code>
0304 * values in the Java programming language.
0305 * @param parameterIndex the first parameter is 1, the second is 2,
0306 * and so on
0307 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0308 * is <code>null</code>.
0309 * @exception SQLException if the parameterIndex is not valid;
0310 * if a database access error occurs or
0311 * this method is called on a closed <code>CallableStatement</code>
0312 * @see #setBytes
0313 */
0314 byte[] getBytes(int parameterIndex) throws SQLException;
0315
0316 /**
0317 * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
0318 * <code>java.sql.Date</code> object.
0319 * @param parameterIndex the first parameter is 1, the second is 2,
0320 * and so on
0321 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0322 * is <code>null</code>.
0323 * @exception SQLException if the parameterIndex is not valid;
0324 * if a database access error occurs or
0325 * this method is called on a closed <code>CallableStatement</code>
0326 * @see #setDate
0327 */
0328 java.sql.Date getDate(int parameterIndex) throws SQLException;
0329
0330 /**
0331 * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
0332 * <code>java.sql.Time</code> object.
0333 *
0334 * @param parameterIndex the first parameter is 1, the second is 2,
0335 * and so on
0336 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0337 * is <code>null</code>.
0338 * @exception SQLException if the parameterIndex is not valid;
0339 * if a database access error occurs or
0340 * this method is called on a closed <code>CallableStatement</code>
0341 * @see #setTime
0342 */
0343 java.sql.Time getTime(int parameterIndex) throws SQLException;
0344
0345 /**
0346 * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
0347 * <code>java.sql.Timestamp</code> object.
0348 *
0349 * @param parameterIndex the first parameter is 1, the second is 2,
0350 * and so on
0351 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0352 * is <code>null</code>.
0353 * @exception SQLException if the parameterIndex is not valid;
0354 * if a database access error occurs or
0355 * this method is called on a closed <code>CallableStatement</code>
0356 * @see #setTimestamp
0357 */
0358 java.sql.Timestamp getTimestamp(int parameterIndex)
0359 throws SQLException;
0360
0361 //----------------------------------------------------------------------
0362 // Advanced features:
0363
0364 /**
0365 * Retrieves the value of the designated parameter as an <code>Object</code>
0366 * in the Java programming language. If the value is an SQL <code>NULL</code>,
0367 * the driver returns a Java <code>null</code>.
0368 * <p>
0369 * This method returns a Java object whose type corresponds to the JDBC
0370 * type that was registered for this parameter using the method
0371 * <code>registerOutParameter</code>. By registering the target JDBC
0372 * type as <code>java.sql.Types.OTHER</code>, this method can be used
0373 * to read database-specific abstract data types.
0374 *
0375 * @param parameterIndex the first parameter is 1, the second is 2,
0376 * and so on
0377 * @return A <code>java.lang.Object</code> holding the OUT parameter value
0378 * @exception SQLException if the parameterIndex is not valid;
0379 * if a database access error occurs or
0380 * this method is called on a closed <code>CallableStatement</code>
0381 * @see Types
0382 * @see #setObject
0383 */
0384 Object getObject(int parameterIndex) throws SQLException;
0385
0386 //--------------------------JDBC 2.0-----------------------------
0387
0388 /**
0389 * Retrieves the value of the designated JDBC <code>NUMERIC</code> parameter as a
0390 * <code>java.math.BigDecimal</code> object with as many digits to the
0391 * right of the decimal point as the value contains.
0392 * @param parameterIndex the first parameter is 1, the second is 2,
0393 * and so on
0394 * @return the parameter value in full precision. If the value is
0395 * SQL <code>NULL</code>, the result is <code>null</code>.
0396 * @exception SQLException if the parameterIndex is not valid;
0397 * if a database access error occurs or
0398 * this method is called on a closed <code>CallableStatement</code>
0399 * @see #setBigDecimal
0400 * @since 1.2
0401 */
0402 BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
0403
0404 /**
0405 * Returns an object representing the value of OUT parameter
0406 * <code>parameterIndex</code> and uses <code>map</code> for the custom
0407 * mapping of the parameter value.
0408 * <p>
0409 * This method returns a Java object whose type corresponds to the
0410 * JDBC type that was registered for this parameter using the method
0411 * <code>registerOutParameter</code>. By registering the target
0412 * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
0413 * be used to read database-specific abstract data types.
0414 * @param parameterIndex the first parameter is 1, the second is 2, and so on
0415 * @param map the mapping from SQL type names to Java classes
0416 * @return a <code>java.lang.Object</code> holding the OUT parameter value
0417 * @exception SQLException if the parameterIndex is not valid;
0418 * if a database access error occurs or
0419 * this method is called on a closed <code>CallableStatement</code>
0420 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0421 * this method
0422 * @see #setObject
0423 * @since 1.2
0424 */
0425 Object getObject(int parameterIndex,
0426 java.util.Map<String, Class<?>> map) throws SQLException;
0427
0428 /**
0429 * Retrieves the value of the designated JDBC <code>REF(<structured-type>)</code>
0430 * parameter as a {@link java.sql.Ref} object in the Java programming language.
0431 * @param parameterIndex the first parameter is 1, the second is 2,
0432 * and so on
0433 * @return the parameter value as a <code>Ref</code> object in the
0434 * Java programming language. If the value was SQL <code>NULL</code>, the value
0435 * <code>null</code> is returned.
0436 * @exception SQLException if the parameterIndex is not valid;
0437 * if a database access error occurs or
0438 * this method is called on a closed <code>CallableStatement</code>
0439 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0440 * this method
0441 * @since 1.2
0442 */
0443 Ref getRef(int parameterIndex) throws SQLException;
0444
0445 /**
0446 * Retrieves the value of the designated JDBC <code>BLOB</code> parameter as a
0447 * {@link java.sql.Blob} object in the Java programming language.
0448 * @param parameterIndex the first parameter is 1, the second is 2, and so on
0449 * @return the parameter value as a <code>Blob</code> object in the
0450 * Java programming language. If the value was SQL <code>NULL</code>, the value
0451 * <code>null</code> is returned.
0452 * @exception SQLException if the parameterIndex is not valid;
0453 * if a database access error occurs or
0454 * this method is called on a closed <code>CallableStatement</code>
0455 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0456 * this method
0457 * @since 1.2
0458 */
0459 Blob getBlob(int parameterIndex) throws SQLException;
0460
0461 /**
0462 * Retrieves the value of the designated JDBC <code>CLOB</code> parameter as a
0463 * <code>java.sql.Clob</code> object in the Java programming language.
0464 * @param parameterIndex the first parameter is 1, the second is 2, and
0465 * so on
0466 * @return the parameter value as a <code>Clob</code> object in the
0467 * Java programming language. If the value was SQL <code>NULL</code>, the
0468 * value <code>null</code> is returned.
0469 * @exception SQLException if the parameterIndex is not valid;
0470 * if a database access error occurs or
0471 * this method is called on a closed <code>CallableStatement</code>
0472 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0473 * this method
0474 * @since 1.2
0475 */
0476 Clob getClob(int parameterIndex) throws SQLException;
0477
0478 /**
0479 *
0480 * Retrieves the value of the designated JDBC <code>ARRAY</code> parameter as an
0481 * {@link java.sql.Array} object in the Java programming language.
0482 * @param parameterIndex the first parameter is 1, the second is 2, and
0483 * so on
0484 * @return the parameter value as an <code>Array</code> object in
0485 * the Java programming language. If the value was SQL <code>NULL</code>, the
0486 * value <code>null</code> is returned.
0487 * @exception SQLException if the parameterIndex is not valid;
0488 * if a database access error occurs or
0489 * this method is called on a closed <code>CallableStatement</code>
0490 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0491 * this method
0492 * @since 1.2
0493 */
0494 Array getArray(int parameterIndex) throws SQLException;
0495
0496 /**
0497 * Retrieves the value of the designated JDBC <code>DATE</code> parameter as a
0498 * <code>java.sql.Date</code> object, using
0499 * the given <code>Calendar</code> object
0500 * to construct the date.
0501 * With a <code>Calendar</code> object, the driver
0502 * can calculate the date taking into account a custom timezone and locale.
0503 * If no <code>Calendar</code> object is specified, the driver uses the
0504 * default timezone and locale.
0505 *
0506 * @param parameterIndex the first parameter is 1, the second is 2,
0507 * and so on
0508 * @param cal the <code>Calendar</code> object the driver will use
0509 * to construct the date
0510 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0511 * is <code>null</code>.
0512 * @exception SQLException if the parameterIndex is not valid;
0513 * if a database access error occurs or
0514 * this method is called on a closed <code>CallableStatement</code>
0515 * @see #setDate
0516 * @since 1.2
0517 */
0518 java.sql.Date getDate(int parameterIndex, Calendar cal)
0519 throws SQLException;
0520
0521 /**
0522 * Retrieves the value of the designated JDBC <code>TIME</code> parameter as a
0523 * <code>java.sql.Time</code> object, using
0524 * the given <code>Calendar</code> object
0525 * to construct the time.
0526 * With a <code>Calendar</code> object, the driver
0527 * can calculate the time taking into account a custom timezone and locale.
0528 * If no <code>Calendar</code> object is specified, the driver uses the
0529 * default timezone and locale.
0530 *
0531 * @param parameterIndex the first parameter is 1, the second is 2,
0532 * and so on
0533 * @param cal the <code>Calendar</code> object the driver will use
0534 * to construct the time
0535 * @return the parameter value; if the value is SQL <code>NULL</code>, the result
0536 * is <code>null</code>.
0537 * @exception SQLException if the parameterIndex is not valid;
0538 * if a database access error occurs or
0539 * this method is called on a closed <code>CallableStatement</code>
0540 * @see #setTime
0541 * @since 1.2
0542 */
0543 java.sql.Time getTime(int parameterIndex, Calendar cal)
0544 throws SQLException;
0545
0546 /**
0547 * Retrieves the value of the designated JDBC <code>TIMESTAMP</code> parameter as a
0548 * <code>java.sql.Timestamp</code> object, using
0549 * the given <code>Calendar</code> object to construct
0550 * the <code>Timestamp</code> object.
0551 * With a <code>Calendar</code> object, the driver
0552 * can calculate the timestamp taking into account a custom timezone and locale.
0553 * If no <code>Calendar</code> object is specified, the driver uses the
0554 * default timezone and locale.
0555 *
0556 *
0557 * @param parameterIndex the first parameter is 1, the second is 2,
0558 * and so on
0559 * @param cal the <code>Calendar</code> object the driver will use
0560 * to construct the timestamp
0561 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
0562 * is <code>null</code>.
0563 * @exception SQLException if the parameterIndex is not valid;
0564 * if a database access error occurs or
0565 * this method is called on a closed <code>CallableStatement</code>
0566 * @see #setTimestamp
0567 * @since 1.2
0568 */
0569 java.sql.Timestamp getTimestamp(int parameterIndex, Calendar cal)
0570 throws SQLException;
0571
0572 /**
0573 * Registers the designated output parameter.
0574 * This version of
0575 * the method <code>registerOutParameter</code>
0576 * should be used for a user-defined or <code>REF</code> output parameter. Examples
0577 * of user-defined types include: <code>STRUCT</code>, <code>DISTINCT</code>,
0578 * <code>JAVA_OBJECT</code>, and named array types.
0579 *<p>
0580 * All OUT parameters must be registered
0581 * before a stored procedure is executed.
0582 * <p> For a user-defined parameter, the fully-qualified SQL
0583 * type name of the parameter should also be given, while a <code>REF</code>
0584 * parameter requires that the fully-qualified type name of the
0585 * referenced type be given. A JDBC driver that does not need the
0586 * type code and type name information may ignore it. To be portable,
0587 * however, applications should always provide these values for
0588 * user-defined and <code>REF</code> parameters.
0589 *
0590 * Although it is intended for user-defined and <code>REF</code> parameters,
0591 * this method may be used to register a parameter of any JDBC type.
0592 * If the parameter does not have a user-defined or <code>REF</code> type, the
0593 * <i>typeName</i> parameter is ignored.
0594 *
0595 * <P><B>Note:</B> When reading the value of an out parameter, you
0596 * must use the getter method whose Java type corresponds to the
0597 * parameter's registered SQL type.
0598 *
0599 * @param parameterIndex the first parameter is 1, the second is 2,...
0600 * @param sqlType a value from {@link java.sql.Types}
0601 * @param typeName the fully-qualified name of an SQL structured type
0602 * @exception SQLException if the parameterIndex is not valid;
0603 * if a database access error occurs or
0604 * this method is called on a closed <code>CallableStatement</code>
0605 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0606 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0607 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0608 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0609 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0610 * or <code>STRUCT</code> data type and the JDBC driver does not support
0611 * this data type
0612 * @see Types
0613 * @since 1.2
0614 */
0615 void registerOutParameter(int parameterIndex, int sqlType,
0616 String typeName) throws SQLException;
0617
0618 //--------------------------JDBC 3.0-----------------------------
0619
0620 /**
0621 * Registers the OUT parameter named
0622 * <code>parameterName</code> to the JDBC type
0623 * <code>sqlType</code>. All OUT parameters must be registered
0624 * before a stored procedure is executed.
0625 * <p>
0626 * The JDBC type specified by <code>sqlType</code> for an OUT
0627 * parameter determines the Java type that must be used
0628 * in the <code>get</code> method to read the value of that parameter.
0629 * <p>
0630 * If the JDBC type expected to be returned to this output parameter
0631 * is specific to this particular database, <code>sqlType</code>
0632 * should be <code>java.sql.Types.OTHER</code>. The method
0633 * {@link #getObject} retrieves the value.
0634 * @param parameterName the name of the parameter
0635 * @param sqlType the JDBC type code defined by <code>java.sql.Types</code>.
0636 * If the parameter is of JDBC type <code>NUMERIC</code>
0637 * or <code>DECIMAL</code>, the version of
0638 * <code>registerOutParameter</code> that accepts a scale value
0639 * should be used.
0640 * @exception SQLException if parameterName does not correspond to a named
0641 * parameter; if a database access error occurs or
0642 * this method is called on a closed <code>CallableStatement</code>
0643 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0644 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0645 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0646 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0647 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0648 * or <code>STRUCT</code> data type and the JDBC driver does not support
0649 * this data type or if the JDBC driver does not support
0650 * this method
0651 * @since 1.4
0652 * @see Types
0653 */
0654 void registerOutParameter(String parameterName, int sqlType)
0655 throws SQLException;
0656
0657 /**
0658 * Registers the parameter named
0659 * <code>parameterName</code> to be of JDBC type
0660 * <code>sqlType</code>. All OUT parameters must be registered
0661 * before a stored procedure is executed.
0662 * <p>
0663 * The JDBC type specified by <code>sqlType</code> for an OUT
0664 * parameter determines the Java type that must be used
0665 * in the <code>get</code> method to read the value of that parameter.
0666 * <p>
0667 * This version of <code>registerOutParameter</code> should be
0668 * used when the parameter is of JDBC type <code>NUMERIC</code>
0669 * or <code>DECIMAL</code>.
0670 *
0671 * @param parameterName the name of the parameter
0672 * @param sqlType SQL type code defined by <code>java.sql.Types</code>.
0673 * @param scale the desired number of digits to the right of the
0674 * decimal point. It must be greater than or equal to zero.
0675 * @exception SQLException if parameterName does not correspond to a named
0676 * parameter; if a database access error occurs or
0677 * this method is called on a closed <code>CallableStatement</code>
0678 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0679 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0680 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0681 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0682 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0683 * or <code>STRUCT</code> data type and the JDBC driver does not support
0684 * this data type or if the JDBC driver does not support
0685 * this method
0686 * @since 1.4
0687 * @see Types
0688 */
0689 void registerOutParameter(String parameterName, int sqlType,
0690 int scale) throws SQLException;
0691
0692 /**
0693 * Registers the designated output parameter. This version of
0694 * the method <code>registerOutParameter</code>
0695 * should be used for a user-named or REF output parameter. Examples
0696 * of user-named types include: STRUCT, DISTINCT, JAVA_OBJECT, and
0697 * named array types.
0698 *<p>
0699 * All OUT parameters must be registered
0700 * before a stored procedure is executed.
0701 * <p>
0702 * For a user-named parameter the fully-qualified SQL
0703 * type name of the parameter should also be given, while a REF
0704 * parameter requires that the fully-qualified type name of the
0705 * referenced type be given. A JDBC driver that does not need the
0706 * type code and type name information may ignore it. To be portable,
0707 * however, applications should always provide these values for
0708 * user-named and REF parameters.
0709 *
0710 * Although it is intended for user-named and REF parameters,
0711 * this method may be used to register a parameter of any JDBC type.
0712 * If the parameter does not have a user-named or REF type, the
0713 * typeName parameter is ignored.
0714 *
0715 * <P><B>Note:</B> When reading the value of an out parameter, you
0716 * must use the <code>getXXX</code> method whose Java type XXX corresponds to the
0717 * parameter's registered SQL type.
0718 *
0719 * @param parameterName the name of the parameter
0720 * @param sqlType a value from {@link java.sql.Types}
0721 * @param typeName the fully-qualified name of an SQL structured type
0722 * @exception SQLException if parameterName does not correspond to a named
0723 * parameter; if a database access error occurs or
0724 * this method is called on a closed <code>CallableStatement</code>
0725 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0726 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0727 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0728 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0729 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0730 * or <code>STRUCT</code> data type and the JDBC driver does not support
0731 * this data type or if the JDBC driver does not support
0732 * this method
0733 * @see Types
0734 * @since 1.4
0735 */
0736 void registerOutParameter(String parameterName, int sqlType,
0737 String typeName) throws SQLException;
0738
0739 /**
0740 * Retrieves the value of the designated JDBC <code>DATALINK</code> parameter as a
0741 * <code>java.net.URL</code> object.
0742 *
0743 * @param parameterIndex the first parameter is 1, the second is 2,...
0744 * @return a <code>java.net.URL</code> object that represents the
0745 * JDBC <code>DATALINK</code> value used as the designated
0746 * parameter
0747 * @exception SQLException if the parameterIndex is not valid;
0748 * if a database access error occurs,
0749 * this method is called on a closed <code>CallableStatement</code>,
0750 * or if the URL being returned is
0751 * not a valid URL on the Java platform
0752 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0753 * this method
0754 * @see #setURL
0755 * @since 1.4
0756 */
0757 java.net.URL getURL(int parameterIndex) throws SQLException;
0758
0759 /**
0760 * Sets the designated parameter to the given <code>java.net.URL</code> object.
0761 * The driver converts this to an SQL <code>DATALINK</code> value when
0762 * it sends it to the database.
0763 *
0764 * @param parameterName the name of the parameter
0765 * @param val the parameter value
0766 * @exception SQLException if parameterName does not correspond to a named
0767 * parameter; if a database access error occurs;
0768 * this method is called on a closed <code>CallableStatement</code>
0769 * or if a URL is malformed
0770 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0771 * this method
0772 * @see #getURL
0773 * @since 1.4
0774 */
0775 void setURL(String parameterName, java.net.URL val)
0776 throws SQLException;
0777
0778 /**
0779 * Sets the designated parameter to SQL <code>NULL</code>.
0780 *
0781 * <P><B>Note:</B> You must specify the parameter's SQL type.
0782 *
0783 * @param parameterName the name of the parameter
0784 * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
0785 * @exception SQLException if parameterName does not correspond to a named
0786 * parameter; if a database access error occurs or
0787 * this method is called on a closed <code>CallableStatement</code>
0788 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0789 * this method
0790 * @since 1.4
0791 */
0792 void setNull(String parameterName, int sqlType) throws SQLException;
0793
0794 /**
0795 * Sets the designated parameter to the given Java <code>boolean</code> value.
0796 * The driver converts this
0797 * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
0798 *
0799 * @param parameterName the name of the parameter
0800 * @param x the parameter value
0801 * @exception SQLException if parameterName does not correspond to a named
0802 * parameter; if a database access error occurs or
0803 * this method is called on a closed <code>CallableStatement</code>
0804 * @see #getBoolean
0805 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0806 * this method
0807 * @since 1.4
0808 */
0809 void setBoolean(String parameterName, boolean x)
0810 throws SQLException;
0811
0812 /**
0813 * Sets the designated parameter to the given Java <code>byte</code> value.
0814 * The driver converts this
0815 * to an SQL <code>TINYINT</code> value when it sends it to the database.
0816 *
0817 * @param parameterName the name of the parameter
0818 * @param x the parameter value
0819 * @exception SQLException if parameterName does not correspond to a named
0820 * parameter; if a database access error occurs or
0821 * this method is called on a closed <code>CallableStatement</code>
0822 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0823 * this method
0824 * @see #getByte
0825 * @since 1.4
0826 */
0827 void setByte(String parameterName, byte x) throws SQLException;
0828
0829 /**
0830 * Sets the designated parameter to the given Java <code>short</code> value.
0831 * The driver converts this
0832 * to an SQL <code>SMALLINT</code> value when it sends it to the database.
0833 *
0834 * @param parameterName the name of the parameter
0835 * @param x the parameter value
0836 * @exception SQLException if parameterName does not correspond to a named
0837 * parameter; if a database access error occurs or
0838 * this method is called on a closed <code>CallableStatement</code>
0839 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0840 * this method
0841 * @see #getShort
0842 * @since 1.4
0843 */
0844 void setShort(String parameterName, short x) throws SQLException;
0845
0846 /**
0847 * Sets the designated parameter to the given Java <code>int</code> value.
0848 * The driver converts this
0849 * to an SQL <code>INTEGER</code> value when it sends it to the database.
0850 *
0851 * @param parameterName the name of the parameter
0852 * @param x the parameter value
0853 * @exception SQLException if parameterName does not correspond to a named
0854 * parameter; if a database access error occurs or
0855 * this method is called on a closed <code>CallableStatement</code>
0856 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0857 * this method
0858 * @see #getInt
0859 * @since 1.4
0860 */
0861 void setInt(String parameterName, int x) throws SQLException;
0862
0863 /**
0864 * Sets the designated parameter to the given Java <code>long</code> value.
0865 * The driver converts this
0866 * to an SQL <code>BIGINT</code> value when it sends it to the database.
0867 *
0868 * @param parameterName the name of the parameter
0869 * @param x the parameter value
0870 * @exception SQLException if parameterName does not correspond to a named
0871 * parameter; if a database access error occurs or
0872 * this method is called on a closed <code>CallableStatement</code>
0873 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0874 * this method
0875 * @see #getLong
0876 * @since 1.4
0877 */
0878 void setLong(String parameterName, long x) throws SQLException;
0879
0880 /**
0881 * Sets the designated parameter to the given Java <code>float</code> value.
0882 * The driver converts this
0883 * to an SQL <code>FLOAT</code> value when it sends it to the database.
0884 *
0885 * @param parameterName the name of the parameter
0886 * @param x the parameter value
0887 * @exception SQLException if parameterName does not correspond to a named
0888 * parameter; if a database access error occurs or
0889 * this method is called on a closed <code>CallableStatement</code>
0890 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0891 * this method
0892 * @see #getFloat
0893 * @since 1.4
0894 */
0895 void setFloat(String parameterName, float x) throws SQLException;
0896
0897 /**
0898 * Sets the designated parameter to the given Java <code>double</code> value.
0899 * The driver converts this
0900 * to an SQL <code>DOUBLE</code> value when it sends it to the database.
0901 *
0902 * @param parameterName the name of the parameter
0903 * @param x the parameter value
0904 * @exception SQLException if parameterName does not correspond to a named
0905 * parameter; if a database access error occurs or
0906 * this method is called on a closed <code>CallableStatement</code>
0907 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0908 * this method
0909 * @see #getDouble
0910 * @since 1.4
0911 */
0912 void setDouble(String parameterName, double x) throws SQLException;
0913
0914 /**
0915 * Sets the designated parameter to the given
0916 * <code>java.math.BigDecimal</code> value.
0917 * The driver converts this to an SQL <code>NUMERIC</code> value when
0918 * it sends it to the database.
0919 *
0920 * @param parameterName the name of the parameter
0921 * @param x the parameter value
0922 * @exception SQLException if parameterName does not correspond to a named
0923 * parameter; if a database access error occurs or
0924 * this method is called on a closed <code>CallableStatement</code>
0925 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0926 * this method
0927 * @see #getBigDecimal
0928 * @since 1.4
0929 */
0930 void setBigDecimal(String parameterName, BigDecimal x)
0931 throws SQLException;
0932
0933 /**
0934 * Sets the designated parameter to the given Java <code>String</code> value.
0935 * The driver converts this
0936 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
0937 * (depending on the argument's
0938 * size relative to the driver's limits on <code>VARCHAR</code> values)
0939 * when it sends it to the database.
0940 *
0941 * @param parameterName the name of the parameter
0942 * @param x the parameter value
0943 * @exception SQLException if parameterName does not correspond to a named
0944 * parameter; if a database access error occurs or
0945 * this method is called on a closed <code>CallableStatement</code>
0946 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0947 * this method
0948 * @see #getString
0949 * @since 1.4
0950 */
0951 void setString(String parameterName, String x) throws SQLException;
0952
0953 /**
0954 * Sets the designated parameter to the given Java array of bytes.
0955 * The driver converts this to an SQL <code>VARBINARY</code> or
0956 * <code>LONGVARBINARY</code> (depending on the argument's size relative
0957 * to the driver's limits on <code>VARBINARY</code> values) when it sends
0958 * it to the database.
0959 *
0960 * @param parameterName the name of the parameter
0961 * @param x the parameter value
0962 * @exception SQLException if parameterName does not correspond to a named
0963 * parameter; if a database access error occurs or
0964 * this method is called on a closed <code>CallableStatement</code>
0965 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0966 * this method
0967 * @see #getBytes
0968 * @since 1.4
0969 */
0970 void setBytes(String parameterName, byte x[]) throws SQLException;
0971
0972 /**
0973 * Sets the designated parameter to the given <code>java.sql.Date</code> value
0974 * using the default time zone of the virtual machine that is running
0975 * the application.
0976 * The driver converts this
0977 * to an SQL <code>DATE</code> value when it sends it to the database.
0978 *
0979 * @param parameterName the name of the parameter
0980 * @param x the parameter value
0981 * @exception SQLException if parameterName does not correspond to a named
0982 * parameter; if a database access error occurs or
0983 * this method is called on a closed <code>CallableStatement</code>
0984 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0985 * this method
0986 * @see #getDate
0987 * @since 1.4
0988 */
0989 void setDate(String parameterName, java.sql.Date x)
0990 throws SQLException;
0991
0992 /**
0993 * Sets the designated parameter to the given <code>java.sql.Time</code> value.
0994 * The driver converts this
0995 * to an SQL <code>TIME</code> value when it sends it to the database.
0996 *
0997 * @param parameterName the name of the parameter
0998 * @param x the parameter value
0999 * @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,
1053 int length) 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,
1123 int scale) 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 * Sets the designated parameter to the given <code>Reader</code>
1196 * object, which is the given number of characters long.
1197 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1198 * parameter, it may be more practical to send it via a
1199 * <code>java.io.Reader</code> object. The data will be read from the stream
1200 * as needed until end-of-file is reached. The JDBC driver will
1201 * do any necessary conversion from UNICODE to the database char format.
1202 *
1203 * <P><B>Note:</B> This stream object can either be a standard
1204 * Java stream object or your own subclass that implements the
1205 * standard interface.
1206 *
1207 * @param parameterName the name of the parameter
1208 * @param reader the <code>java.io.Reader</code> object that
1209 * contains the UNICODE data used as the designated parameter
1210 * @param length the number of characters in the stream
1211 * @exception SQLException if parameterName does not correspond to a named
1212 * parameter; if a database access error occurs or
1213 * this method is called on a closed <code>CallableStatement</code>
1214 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1215 * this method
1216 * @since 1.4
1217 */
1218 void setCharacterStream(String parameterName,
1219 java.io.Reader reader, int length) throws SQLException;
1220
1221 /**
1222 * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1223 * using the given <code>Calendar</code> object. The driver uses
1224 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1225 * which the driver then sends to the database. With a
1226 * a <code>Calendar</code> object, the driver can calculate the date
1227 * taking into account a custom timezone. If no
1228 * <code>Calendar</code> object is specified, the driver uses the default
1229 * timezone, which is that of the virtual machine running the application.
1230 *
1231 * @param parameterName the name of the parameter
1232 * @param x the parameter value
1233 * @param cal the <code>Calendar</code> object the driver will use
1234 * to construct the date
1235 * @exception SQLException if parameterName does not correspond to a named
1236 * parameter; if a database access error occurs or
1237 * this method is called on a closed <code>CallableStatement</code>
1238 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1239 * this method
1240 * @see #getDate
1241 * @since 1.4
1242 */
1243 void setDate(String parameterName, java.sql.Date x, Calendar cal)
1244 throws SQLException;
1245
1246 /**
1247 * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1248 * using the given <code>Calendar</code> object. The driver uses
1249 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1250 * which the driver then sends to the database. With a
1251 * a <code>Calendar</code> object, the driver can calculate the time
1252 * taking into account a custom timezone. If no
1253 * <code>Calendar</code> object is specified, the driver uses the default
1254 * timezone, which is that of the virtual machine running the application.
1255 *
1256 * @param parameterName the name of the parameter
1257 * @param x the parameter value
1258 * @param cal the <code>Calendar</code> object the driver will use
1259 * to construct the time
1260 * @exception SQLException if parameterName does not correspond to a named
1261 * parameter; if a database access error occurs or
1262 * this method is called on a closed <code>CallableStatement</code>
1263 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1264 * this method
1265 * @see #getTime
1266 * @since 1.4
1267 */
1268 void setTime(String parameterName, java.sql.Time x, Calendar cal)
1269 throws SQLException;
1270
1271 /**
1272 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1273 * using the given <code>Calendar</code> object. The driver uses
1274 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1275 * which the driver then sends to the database. With a
1276 * a <code>Calendar</code> object, the driver can calculate the timestamp
1277 * taking into account a custom timezone. If no
1278 * <code>Calendar</code> object is specified, the driver uses the default
1279 * timezone, which is that of the virtual machine running the application.
1280 *
1281 * @param parameterName the name of the parameter
1282 * @param x the parameter value
1283 * @param cal the <code>Calendar</code> object the driver will use
1284 * to construct the timestamp
1285 * @exception SQLException if parameterName does not correspond to a named
1286 * parameter; if a database access error occurs or
1287 * this method is called on a closed <code>CallableStatement</code>
1288 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1289 * this method
1290 * @see #getTimestamp
1291 * @since 1.4
1292 */
1293 void setTimestamp(String parameterName, java.sql.Timestamp x,
1294 Calendar cal) throws SQLException;
1295
1296 /**
1297 * Sets the designated parameter to SQL <code>NULL</code>.
1298 * This version of the method <code>setNull</code> should
1299 * be used for user-defined types and REF type parameters. Examples
1300 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
1301 * named array types.
1302 *
1303 * <P><B>Note:</B> To be portable, applications must give the
1304 * SQL type code and the fully-qualified SQL type name when specifying
1305 * a NULL user-defined or REF parameter. In the case of a user-defined type
1306 * the name is the type name of the parameter itself. For a REF
1307 * parameter, the name is the type name of the referenced type.
1308 * <p>
1309 * Although it is intended for user-defined and Ref parameters,
1310 * this method may be used to set a null parameter of any JDBC type.
1311 * If the parameter does not have a user-defined or REF type, the given
1312 * typeName is ignored.
1313 *
1314 *
1315 * @param parameterName the name of the parameter
1316 * @param sqlType a value from <code>java.sql.Types</code>
1317 * @param typeName the fully-qualified name of an SQL user-defined type;
1318 * ignored if the parameter is not a user-defined type or
1319 * SQL <code>REF</code> value
1320 * @exception SQLException if parameterName does not correspond to a named
1321 * parameter; if a database access error occurs or
1322 * this method is called on a closed <code>CallableStatement</code>
1323 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1324 * this method
1325 * @since 1.4
1326 */
1327 void setNull(String parameterName, int sqlType, String typeName)
1328 throws SQLException;
1329
1330 /**
1331 * Retrieves the value of a JDBC <code>CHAR</code>, <code>VARCHAR</code>,
1332 * or <code>LONGVARCHAR</code> parameter as a <code>String</code> in
1333 * the Java programming language.
1334 * <p>
1335 * For the fixed-length type JDBC <code>CHAR</code>,
1336 * the <code>String</code> object
1337 * returned has exactly the same value the SQL
1338 * <code>CHAR</code> value had in the
1339 * database, including any padding added by the database.
1340 * @param parameterName the name of the parameter
1341 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1342 * is <code>null</code>.
1343 * @exception SQLException if parameterName does not correspond to a named
1344 * parameter; if a database access error occurs or
1345 * this method is called on a closed <code>CallableStatement</code>
1346 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1347 * this method
1348 * @see #setString
1349 * @since 1.4
1350 */
1351 String getString(String parameterName) throws SQLException;
1352
1353 /**
1354 * Retrieves the value of a JDBC <code>BIT</code> or <code>BOOLEAN</code>
1355 * parameter as a
1356 * <code>boolean</code> in the Java programming language.
1357 * @param parameterName the name of the parameter
1358 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1359 * is <code>false</code>.
1360 * @exception SQLException if parameterName does not correspond to a named
1361 * parameter; if a database access error occurs or
1362 * this method is called on a closed <code>CallableStatement</code>
1363 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1364 * this method
1365 * @see #setBoolean
1366 * @since 1.4
1367 */
1368 boolean getBoolean(String parameterName) throws SQLException;
1369
1370 /**
1371 * Retrieves the value of a JDBC <code>TINYINT</code> parameter as a <code>byte</code>
1372 * in the Java programming language.
1373 * @param parameterName the name of the parameter
1374 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1375 * is <code>0</code>.
1376 * @exception SQLException if parameterName does not correspond to a named
1377 * parameter; if a database access error occurs or
1378 * this method is called on a closed <code>CallableStatement</code>
1379 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1380 * this method
1381 * @see #setByte
1382 * @since 1.4
1383 */
1384 byte getByte(String parameterName) throws SQLException;
1385
1386 /**
1387 * Retrieves the value of a JDBC <code>SMALLINT</code> parameter as a <code>short</code>
1388 * in the Java programming language.
1389 * @param parameterName the name of the parameter
1390 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1391 * is <code>0</code>.
1392 * @exception SQLException if parameterName does not correspond to a named
1393 * parameter; if a database access error occurs or
1394 * this method is called on a closed <code>CallableStatement</code>
1395 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1396 * this method
1397 * @see #setShort
1398 * @since 1.4
1399 */
1400 short getShort(String parameterName) throws SQLException;
1401
1402 /**
1403 * Retrieves the value of a JDBC <code>INTEGER</code> parameter as an <code>int</code>
1404 * in the Java programming language.
1405 *
1406 * @param parameterName the name of the parameter
1407 * @return the parameter value. If the value is SQL <code>NULL</code>,
1408 * the result is <code>0</code>.
1409 * @exception SQLException if parameterName does not correspond to a named
1410 * parameter; if a database access error occurs or
1411 * this method is called on a closed <code>CallableStatement</code>
1412 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1413 * this method
1414 * @see #setInt
1415 * @since 1.4
1416 */
1417 int getInt(String parameterName) throws SQLException;
1418
1419 /**
1420 * Retrieves the value of a JDBC <code>BIGINT</code> parameter as a <code>long</code>
1421 * in the Java programming language.
1422 *
1423 * @param parameterName the name of the parameter
1424 * @return the parameter value. If the value is SQL <code>NULL</code>,
1425 * the result is <code>0</code>.
1426 * @exception SQLException if parameterName does not correspond to a named
1427 * parameter; if a database access error occurs or
1428 * this method is called on a closed <code>CallableStatement</code>
1429 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1430 * this method
1431 * @see #setLong
1432 * @since 1.4
1433 */
1434 long getLong(String parameterName) throws SQLException;
1435
1436 /**
1437 * Retrieves the value of a JDBC <code>FLOAT</code> parameter as a <code>float</code>
1438 * in the Java programming language.
1439 * @param parameterName the name of the parameter
1440 * @return the parameter value. If the value is SQL <code>NULL</code>,
1441 * the result is <code>0</code>.
1442 * @exception SQLException if parameterName does not correspond to a named
1443 * parameter; if a database access error occurs or
1444 * this method is called on a closed <code>CallableStatement</code>
1445 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1446 * this method
1447 * @see #setFloat
1448 * @since 1.4
1449 */
1450 float getFloat(String parameterName) throws SQLException;
1451
1452 /**
1453 * Retrieves the value of a JDBC <code>DOUBLE</code> parameter as a <code>double</code>
1454 * in the Java programming language.
1455 * @param parameterName the name of the parameter
1456 * @return the parameter value. If the value is SQL <code>NULL</code>,
1457 * the result is <code>0</code>.
1458 * @exception SQLException if parameterName does not correspond to a named
1459 * parameter; if a database access error occurs or
1460 * this method is called on a closed <code>CallableStatement</code>
1461 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1462 * this method
1463 * @see #setDouble
1464 * @since 1.4
1465 */
1466 double getDouble(String parameterName) throws SQLException;
1467
1468 /**
1469 * Retrieves the value of a JDBC <code>BINARY</code> or <code>VARBINARY</code>
1470 * parameter as an array of <code>byte</code> values in the Java
1471 * programming language.
1472 * @param parameterName the name of the parameter
1473 * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1474 * <code>null</code>.
1475 * @exception SQLException if parameterName does not correspond to a named
1476 * parameter; if a database access error occurs or
1477 * this method is called on a closed <code>CallableStatement</code>
1478 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1479 * this method
1480 * @see #setBytes
1481 * @since 1.4
1482 */
1483 byte[] getBytes(String parameterName) throws SQLException;
1484
1485 /**
1486 * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1487 * <code>java.sql.Date</code> object.
1488 * @param parameterName the name of the parameter
1489 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1490 * is <code>null</code>.
1491 * @exception SQLException if parameterName does not correspond to a named
1492 * parameter; if a database access error occurs or
1493 * this method is called on a closed <code>CallableStatement</code>
1494 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1495 * this method
1496 * @see #setDate
1497 * @since 1.4
1498 */
1499 java.sql.Date getDate(String parameterName) throws SQLException;
1500
1501 /**
1502 * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1503 * <code>java.sql.Time</code> object.
1504 * @param parameterName the name of the parameter
1505 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1506 * is <code>null</code>.
1507 * @exception SQLException if parameterName does not correspond to a named
1508 * parameter; if a database access error occurs or
1509 * this method is called on a closed <code>CallableStatement</code>
1510 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1511 * this method
1512 * @see #setTime
1513 * @since 1.4
1514 */
1515 java.sql.Time getTime(String parameterName) throws SQLException;
1516
1517 /**
1518 * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1519 * <code>java.sql.Timestamp</code> object.
1520 * @param parameterName the name of the parameter
1521 * @return the parameter value. If the value is SQL <code>NULL</code>, the result
1522 * is <code>null</code>.
1523 * @exception SQLException if parameterName does not correspond to a named
1524 * parameter; if a database access error occurs or
1525 * this method is called on a closed <code>CallableStatement</code>
1526 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1527 * this method
1528 * @see #setTimestamp
1529 * @since 1.4
1530 */
1531 java.sql.Timestamp getTimestamp(String parameterName)
1532 throws SQLException;
1533
1534 /**
1535 * Retrieves the value of a parameter as an <code>Object</code> in the Java
1536 * programming language. If the value is an SQL <code>NULL</code>, the
1537 * driver returns a Java <code>null</code>.
1538 * <p>
1539 * This method returns a Java object whose type corresponds to the JDBC
1540 * type that was registered for this parameter using the method
1541 * <code>registerOutParameter</code>. By registering the target JDBC
1542 * type as <code>java.sql.Types.OTHER</code>, this method can be used
1543 * to read database-specific abstract data types.
1544 * @param parameterName the name of the parameter
1545 * @return A <code>java.lang.Object</code> holding the OUT parameter value.
1546 * @exception SQLException if parameterName does not correspond to a named
1547 * parameter; if a database access error occurs or
1548 * this method is called on a closed <code>CallableStatement</code>
1549 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1550 * this method
1551 * @see Types
1552 * @see #setObject
1553 * @since 1.4
1554 */
1555 Object getObject(String parameterName) throws SQLException;
1556
1557 /**
1558 * Retrieves the value of a JDBC <code>NUMERIC</code> parameter as a
1559 * <code>java.math.BigDecimal</code> object with as many digits to the
1560 * right of the decimal point as the value contains.
1561 * @param parameterName the name of the parameter
1562 * @return the parameter value in full precision. If the value is
1563 * SQL <code>NULL</code>, the result is <code>null</code>.
1564 * @exception SQLExceptionif parameterName does not correspond to a named
1565 * parameter; if a database access error occurs or
1566 * this method is called on a closed <code>CallableStatement</code>
1567 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1568 * this method
1569 * @see #setBigDecimal
1570 * @since 1.4
1571 */
1572 BigDecimal getBigDecimal(String parameterName) throws SQLException;
1573
1574 /**
1575 * Returns an object representing the value of OUT parameter
1576 * <code>parameterName</code> and uses <code>map</code> for the custom
1577 * mapping of the parameter value.
1578 * <p>
1579 * This method returns a Java object whose type corresponds to the
1580 * JDBC type that was registered for this parameter using the method
1581 * <code>registerOutParameter</code>. By registering the target
1582 * JDBC type as <code>java.sql.Types.OTHER</code>, this method can
1583 * be used to read database-specific abstract data types.
1584 * @param parameterName the name of the parameter
1585 * @param map the mapping from SQL type names to Java classes
1586 * @return a <code>java.lang.Object</code> holding the OUT parameter value
1587 * @exception SQLException if parameterName does not correspond to a named
1588 * parameter; if a database access error occurs or
1589 * this method is called on a closed <code>CallableStatement</code>
1590 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1591 * this method
1592 * @see #setObject
1593 * @since 1.4
1594 */
1595 Object getObject(String parameterName,
1596 java.util.Map<String, Class<?>> map) throws SQLException;
1597
1598 /**
1599 * Retrieves the value of a JDBC <code>REF(<structured-type>)</code>
1600 * parameter as a {@link java.sql.Ref} object in the Java programming language.
1601 *
1602 * @param parameterName the name of the parameter
1603 * @return the parameter value as a <code>Ref</code> object in the
1604 * Java programming language. If the value was SQL <code>NULL</code>,
1605 * the value <code>null</code> is returned.
1606 * @exception SQLException if parameterName does not correspond to a named
1607 * parameter; if a database access error occurs or
1608 * this method is called on a closed <code>CallableStatement</code>
1609 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1610 * this method
1611 * @since 1.4
1612 */
1613 Ref getRef(String parameterName) throws SQLException;
1614
1615 /**
1616 * Retrieves the value of a JDBC <code>BLOB</code> parameter as a
1617 * {@link java.sql.Blob} object in the Java programming language.
1618 *
1619 * @param parameterName the name of the parameter
1620 * @return the parameter value as a <code>Blob</code> object in the
1621 * Java programming language. If the value was SQL <code>NULL</code>,
1622 * the value <code>null</code> is returned.
1623 * @exception SQLException if parameterName does not correspond to a named
1624 * parameter; if a database access error occurs or
1625 * this method is called on a closed <code>CallableStatement</code>
1626 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1627 * this method
1628 * @since 1.4
1629 */
1630 Blob getBlob(String parameterName) throws SQLException;
1631
1632 /**
1633 * Retrieves the value of a JDBC <code>CLOB</code> parameter as a
1634 * <code>java.sql.Clob</code> object in the Java programming language.
1635 * @param parameterName the name of the parameter
1636 * @return the parameter value as a <code>Clob</code> object in the
1637 * Java programming language. If the value was SQL <code>NULL</code>,
1638 * the value <code>null</code> is returned.
1639 * @exception SQLException if parameterName does not correspond to a named
1640 * parameter; if a database access error occurs or
1641 * this method is called on a closed <code>CallableStatement</code>
1642 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1643 * this method
1644 * @since 1.4
1645 */
1646 Clob getClob(String parameterName) throws SQLException;
1647
1648 /**
1649 * Retrieves the value of a JDBC <code>ARRAY</code> parameter as an
1650 * {@link java.sql.Array} object in the Java programming language.
1651 *
1652 * @param parameterName the name of the parameter
1653 * @return the parameter value as an <code>Array</code> object in
1654 * Java programming language. If the value was SQL <code>NULL</code>,
1655 * the value <code>null</code> is returned.
1656 * @exception SQLException if parameterName does not correspond to a named
1657 * parameter; if a database access error occurs or
1658 * this method is called on a closed <code>CallableStatement</code>
1659 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1660 * this method
1661 * @since 1.4
1662 */
1663 Array getArray(String parameterName) throws SQLException;
1664
1665 /**
1666 * Retrieves the value of a JDBC <code>DATE</code> parameter as a
1667 * <code>java.sql.Date</code> object, using
1668 * the given <code>Calendar</code> object
1669 * to construct the date.
1670 * With a <code>Calendar</code> object, the driver
1671 * can calculate the date taking into account a custom timezone and locale.
1672 * If no <code>Calendar</code> object is specified, the driver uses the
1673 * default timezone and locale.
1674 *
1675 * @param parameterName the name of the parameter
1676 * @param cal the <code>Calendar</code> object the driver will use
1677 * to construct the date
1678 * @return the parameter value. If the value is SQL <code>NULL</code>,
1679 * the result is <code>null</code>.
1680 * @exception SQLException if parameterName does not correspond to a named
1681 * parameter; if a database access error occurs or
1682 * this method is called on a closed <code>CallableStatement</code>
1683 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1684 * this method
1685 * @see #setDate
1686 * @since 1.4
1687 */
1688 java.sql.Date getDate(String parameterName, Calendar cal)
1689 throws SQLException;
1690
1691 /**
1692 * Retrieves the value of a JDBC <code>TIME</code> parameter as a
1693 * <code>java.sql.Time</code> object, using
1694 * the given <code>Calendar</code> object
1695 * to construct the time.
1696 * With a <code>Calendar</code> object, the driver
1697 * can calculate the time taking into account a custom timezone and locale.
1698 * If no <code>Calendar</code> object is specified, the driver uses the
1699 * default timezone and locale.
1700 *
1701 * @param parameterName the name of the parameter
1702 * @param cal the <code>Calendar</code> object the driver will use
1703 * to construct the time
1704 * @return the parameter value; if the value is SQL <code>NULL</code>, the result is
1705 * <code>null</code>.
1706 * @exception SQLException if parameterName does not correspond to a named
1707 * parameter; if a database access error occurs or
1708 * this method is called on a closed <code>CallableStatement</code>
1709 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1710 * this method
1711 * @see #setTime
1712 * @since 1.4
1713 */
1714 java.sql.Time getTime(String parameterName, Calendar cal)
1715 throws SQLException;
1716
1717 /**
1718 * Retrieves the value of a JDBC <code>TIMESTAMP</code> parameter as a
1719 * <code>java.sql.Timestamp</code> object, using
1720 * the given <code>Calendar</code> object to construct
1721 * the <code>Timestamp</code> object.
1722 * With a <code>Calendar</code> object, the driver
1723 * can calculate the timestamp taking into account a custom timezone and locale.
1724 * If no <code>Calendar</code> object is specified, the driver uses the
1725 * default timezone and locale.
1726 *
1727 *
1728 * @param parameterName the name of the parameter
1729 * @param cal the <code>Calendar</code> object the driver will use
1730 * to construct the timestamp
1731 * @return the parameter value. If the value is SQL <code>NULL</code>, the result is
1732 * <code>null</code>.
1733 * @exception SQLException if parameterName does not correspond to a named
1734 * parameter; if a database access error occurs or
1735 * this method is called on a closed <code>CallableStatement</code>
1736 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1737 * this method
1738 * @see #setTimestamp
1739 * @since 1.4
1740 */
1741 java.sql.Timestamp getTimestamp(String parameterName, Calendar cal)
1742 throws SQLException;
1743
1744 /**
1745 * Retrieves the value of a JDBC <code>DATALINK</code> parameter as a
1746 * <code>java.net.URL</code> object.
1747 *
1748 * @param parameterName the name of the parameter
1749 * @return the parameter value as a <code>java.net.URL</code> object in the
1750 * Java programming language. If the value was SQL <code>NULL</code>, the
1751 * value <code>null</code> is returned.
1752 * @exception SQLException if parameterName does not correspond to a named
1753 * parameter; if a database access error occurs,
1754 * this method is called on a closed <code>CallableStatement</code>,
1755 * or if there is a problem with the URL
1756 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1757 * this method
1758 * @see #setURL
1759 * @since 1.4
1760 */
1761 java.net.URL getURL(String parameterName) throws SQLException;
1762
1763 //------------------------- JDBC 4.0 -----------------------------------
1764
1765 /**
1766 * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1767 * <code>java.sql.RowId</code> object.
1768 *
1769 * @param parameterIndex the first parameter is 1, the second is 2,...
1770 * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1771 * value is used as the designated parameter. If the parameter contains
1772 * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1773 * @throws SQLException if the parameterIndex is not valid;
1774 * if a database access error occurs or
1775 * this method is called on a closed <code>CallableStatement</code>
1776 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1777 * this method
1778 * @since 1.6
1779 */
1780 RowId getRowId(int parameterIndex) throws SQLException;
1781
1782 /**
1783 * Retrieves the value of the designated JDBC <code>ROWID</code> parameter as a
1784 * <code>java.sql.RowId</code> object.
1785 *
1786 * @param parameterName the name of the parameter
1787 * @return a <code>RowId</code> object that represents the JDBC <code>ROWID</code>
1788 * value is used as the designated parameter. If the parameter contains
1789 * a SQL <code>NULL</code>, then a <code>null</code> value is returned.
1790 * @throws SQLException if parameterName does not correspond to a named
1791 * parameter; if a database access error occurs or
1792 * this method is called on a closed <code>CallableStatement</code>
1793 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1794 * this method
1795 * @since 1.6
1796 */
1797 RowId getRowId(String parameterName) throws SQLException;
1798
1799 /**
1800 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1801 * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1802 * database.
1803 *
1804 * @param parameterName the name of the parameter
1805 * @param x the parameter value
1806 * @throws SQLException if parameterName does not correspond to a named
1807 * parameter; if a database access error occurs or
1808 * this method is called on a closed <code>CallableStatement</code>
1809 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1810 * this method
1811 * @since 1.6
1812 */
1813 void setRowId(String parameterName, RowId x) throws SQLException;
1814
1815 /**
1816 * Sets the designated parameter to the given <code>String</code> object.
1817 * The driver converts this to a SQL <code>NCHAR</code> or
1818 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1819 * @param parameterName the name of the parameter to be set
1820 * @param value the parameter value
1821 * @throws SQLException if parameterName does not correspond to a named
1822 * parameter; if the driver does not support national
1823 * character sets; if the driver can detect that a data conversion
1824 * error could occur; if a database access error occurs or
1825 * this method is called on a closed <code>CallableStatement</code>
1826 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1827 * this method
1828 * @since 1.6
1829 */
1830 void setNString(String parameterName, String value)
1831 throws SQLException;
1832
1833 /**
1834 * Sets the designated parameter to a <code>Reader</code> object. The
1835 * <code>Reader</code> reads the data till end-of-file is reached. The
1836 * driver does the necessary conversion from Java character format to
1837 * the national character set in the database.
1838 * @param parameterName the name of the parameter to be set
1839 * @param value the parameter value
1840 * @param length the number of characters in the parameter data.
1841 * @throws SQLException if parameterName does not correspond to a named
1842 * parameter; if the driver does not support national
1843 * character sets; if the driver can detect that a data conversion
1844 * error could occur; if a database access error occurs or
1845 * this method is called on a closed <code>CallableStatement</code>
1846 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1847 * this method
1848 * @since 1.6
1849 */
1850 void setNCharacterStream(String parameterName, Reader value,
1851 long length) throws SQLException;
1852
1853 /**
1854 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
1855 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
1856 * object maps to a SQL <code>NCLOB</code>.
1857 * @param parameterName the name of the parameter to be set
1858 * @param value the parameter value
1859 * @throws SQLException if parameterName does not correspond to a named
1860 * parameter; if the driver does not support national
1861 * character sets; if the driver can detect that a data conversion
1862 * error could occur; if a database access error occurs or
1863 * this method is called on a closed <code>CallableStatement</code>
1864 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1865 * this method
1866 * @since 1.6
1867 */
1868 void setNClob(String parameterName, NClob value)
1869 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,
1922 long length) throws SQLException;
1923
1924 /**
1925 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1926 * of characters specified by length otherwise a <code>SQLException</code> will be
1927 * generated when the <code>CallableStatement</code> is executed.
1928 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1929 * because it informs the driver that the parameter value should be sent to
1930 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
1931 * driver may have to do extra work to determine whether the parameter
1932 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
1933 *
1934 * @param parameterName the name of the parameter to be set
1935 * @param reader An object that contains the data to set the parameter value to.
1936 * @param length the number of characters in the parameter data.
1937 * @throws SQLException if parameterName does not correspond to a named
1938 * parameter; if the length specified is less than zero;
1939 * if the driver does not support national
1940 * character sets; if the driver can detect that a data conversion
1941 * error could occur; if a database access error occurs or
1942 * this method is called on a closed <code>CallableStatement</code>
1943 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1944 * this method
1945 * @since 1.6
1946 */
1947 void setNClob(String parameterName, Reader reader, long length)
1948 throws SQLException;
1949
1950 /**
1951 * Retrieves the value of the designated JDBC <code>NCLOB</code> parameter as a
1952 * <code>java.sql.NClob</code> object in the Java programming language.
1953 *
1954 * @param parameterIndex the first parameter is 1, the second is 2, and
1955 * so on
1956 * @return the parameter value as a <code>NClob</code> object in the
1957 * Java programming language. If the value was SQL <code>NULL</code>, the
1958 * value <code>null</code> is returned.
1959 * @exception SQLException if the parameterIndex is not valid;
1960 * if the driver does not support national
1961 * character sets; if the driver can detect that a data conversion
1962 * error could occur; if a database access error occurs or
1963 * this method is called on a closed <code>CallableStatement</code>
1964 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1965 * this method
1966 * @since 1.6
1967 */
1968 NClob getNClob(int parameterIndex) throws SQLException;
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)
2005 throws SQLException;
2006
2007 /**
2008 * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2009 * <code>java.sql.SQLXML</code> object in the Java programming language.
2010 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2011 * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2012 * @throws SQLException if the parameterIndex is not valid;
2013 * if a database access error occurs or
2014 * this method is called on a closed <code>CallableStatement</code>
2015 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2016 * this method
2017 * @since 1.6
2018 */
2019 SQLXML getSQLXML(int parameterIndex) throws SQLException;
2020
2021 /**
2022 * Retrieves the value of the designated <code>SQL XML</code> parameter as a
2023 * <code>java.sql.SQLXML</code> object in the Java programming language.
2024 * @param parameterName the name of the parameter
2025 * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
2026 * @throws SQLException if parameterName does not correspond to a named
2027 * parameter; if a database access error occurs or
2028 * this method is called on a closed <code>CallableStatement</code>
2029 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2030 * this method
2031 * @since 1.6
2032 */
2033 SQLXML getSQLXML(String parameterName) throws SQLException;
2034
2035 /**
2036 * Retrieves the value of the designated <code>NCHAR</code>,
2037 * <code>NVARCHAR</code>
2038 * or <code>LONGNVARCHAR</code> parameter as
2039 * a <code>String</code> in the Java programming language.
2040 * <p>
2041 * For the fixed-length type JDBC <code>NCHAR</code>,
2042 * the <code>String</code> object
2043 * returned has exactly the same value the SQL
2044 * <code>NCHAR</code> value had in the
2045 * database, including any padding added by the database.
2046 *
2047 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2048 * @return a <code>String</code> object that maps an
2049 * <code>NCHAR</code>, <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
2050 * @exception SQLException if the parameterIndex is not valid;
2051 * if a database access error occurs or
2052 * this method is called on a closed <code>CallableStatement</code>
2053 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2054 * this method
2055 * @since 1.6
2056 * @see #setNString
2057 */
2058 String getNString(int parameterIndex) throws SQLException;
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)
2105 throws SQLException;
2106
2107 /**
2108 * Retrieves the value of the designated parameter as a
2109 * <code>java.io.Reader</code> object in the Java programming language.
2110 * It is intended for use when
2111 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
2112 * and <code>LONGNVARCHAR</code> parameters.
2113 *
2114 * @param parameterName the name of the parameter
2115 * @return a <code>java.io.Reader</code> object that contains the parameter
2116 * value; if the value is SQL <code>NULL</code>, the value returned is
2117 * <code>null</code> in the Java programming language
2118 * @exception SQLException if parameterName does not correspond to a named
2119 * parameter; if a database access error occurs or
2120 * this method is called on a closed <code>CallableStatement</code>
2121 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2122 * this method
2123 * @since 1.6
2124 */
2125 java.io.Reader getNCharacterStream(String parameterName)
2126 throws SQLException;
2127
2128 /**
2129 * Retrieves the value of the designated parameter as a
2130 * <code>java.io.Reader</code> object in the Java programming language.
2131 *
2132 * @return a <code>java.io.Reader</code> object that contains the parameter
2133 * value; if the value is SQL <code>NULL</code>, the value returned is
2134 * <code>null</code> in the Java programming language.
2135 * @param parameterIndex the first parameter is 1, the second is 2, ...
2136 * @exception SQLException if the parameterIndex is not valid; if a database access error occurs or
2137 * this method is called on a closed <code>CallableStatement</code>
2138 * @since 1.6
2139 */
2140 java.io.Reader getCharacterStream(int parameterIndex)
2141 throws SQLException;
2142
2143 /**
2144 * Retrieves the value of the designated parameter as a
2145 * <code>java.io.Reader</code> object in the Java programming language.
2146 *
2147 * @param parameterName the name of the parameter
2148 * @return a <code>java.io.Reader</code> object that contains the parameter
2149 * value; if the value is SQL <code>NULL</code>, the value returned is
2150 * <code>null</code> in the Java programming language
2151 * @exception SQLException if parameterName does not correspond to a named
2152 * parameter; if a database access error occurs or
2153 * this method is called on a closed <code>CallableStatement</code>
2154 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2155 * this method
2156 * @since 1.6
2157 */
2158 java.io.Reader getCharacterStream(String parameterName)
2159 throws SQLException;
2160
2161 /**
2162 * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
2163 * The driver converts this to an SQL <code>BLOB</code> value when it
2164 * sends it to the database.
2165 *
2166 * @param parameterName the name of the parameter
2167 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
2168 * @exception SQLException if parameterName does not correspond to a named
2169 * parameter; if a database access error occurs or
2170 * this method is called on a closed <code>CallableStatement</code>
2171 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2172 * this method
2173 * @since 1.6
2174 */
2175 void setBlob(String parameterName, Blob x) throws SQLException;
2176
2177 /**
2178 * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
2179 * The driver converts this to an SQL <code>CLOB</code> value when it
2180 * sends it to the database.
2181 *
2182 * @param parameterName the name of the parameter
2183 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
2184 * @exception SQLException if parameterName does not correspond to a named
2185 * parameter; if a database access error occurs or
2186 * this method is called on a closed <code>CallableStatement</code>
2187 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2188 * this method
2189 * @since 1.6
2190 */
2191 void setClob(String parameterName, Clob x) throws SQLException;
2192
2193 /**
2194 * Sets the designated parameter to the given input stream, which will have
2195 * the specified number of bytes.
2196 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2197 * parameter, it may be more practical to send it via a
2198 * <code>java.io.InputStream</code>. Data will be read from the stream
2199 * as needed until end-of-file is reached. The JDBC driver will
2200 * do any necessary conversion from ASCII to the database char format.
2201 *
2202 * <P><B>Note:</B> This stream object can either be a standard
2203 * Java stream object or your own subclass that implements the
2204 * standard interface.
2205 *
2206 * @param parameterName the name of the parameter
2207 * @param x the Java input stream that contains the ASCII parameter value
2208 * @param length the number of bytes in the stream
2209 * @exception SQLException if parameterName does not correspond to a named
2210 * parameter; if a database access error occurs or
2211 * this method is called on a closed <code>CallableStatement</code>
2212 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2213 * this method
2214 * @since 1.6
2215 */
2216 void setAsciiStream(String parameterName, java.io.InputStream x,
2217 long length) throws SQLException;
2218
2219 /**
2220 * Sets the designated parameter to the given input stream, which will have
2221 * the specified number of bytes.
2222 * When a very large binary value is input to a <code>LONGVARBINARY</code>
2223 * parameter, it may be more practical to send it via a
2224 * <code>java.io.InputStream</code> object. The data will be read from the stream
2225 * as needed until end-of-file is reached.
2226 *
2227 * <P><B>Note:</B> This stream object can either be a standard
2228 * Java stream object or your own subclass that implements the
2229 * standard interface.
2230 *
2231 * @param parameterName the name of the parameter
2232 * @param x the java input stream which contains the binary parameter value
2233 * @param length the number of bytes in the stream
2234 * @exception SQLException if parameterName does not correspond to a named
2235 * parameter; if a database access error occurs or
2236 * this method is called on a closed <code>CallableStatement</code>
2237 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2238 * this method
2239 * @since 1.6
2240 */
2241 void setBinaryStream(String parameterName, java.io.InputStream x,
2242 long length) throws SQLException;
2243
2244 /**
2245 * Sets the designated parameter to the given <code>Reader</code>
2246 * object, which is the given number of characters long.
2247 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2248 * parameter, it may be more practical to send it via a
2249 * <code>java.io.Reader</code> object. The data will be read from the stream
2250 * as needed until end-of-file is reached. The JDBC driver will
2251 * do any necessary conversion from UNICODE to the database char format.
2252 *
2253 * <P><B>Note:</B> This stream object can either be a standard
2254 * Java stream object or your own subclass that implements the
2255 * standard interface.
2256 *
2257 * @param parameterName the name of the parameter
2258 * @param reader the <code>java.io.Reader</code> object that
2259 * contains the UNICODE data used as the designated parameter
2260 * @param length the number of characters in the stream
2261 * @exception SQLException if parameterName does not correspond to a named
2262 * parameter; if a database access error occurs or
2263 * this method is called on a closed <code>CallableStatement</code>
2264 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2265 * this method
2266 * @since 1.6
2267 */
2268 void setCharacterStream(String parameterName,
2269 java.io.Reader reader, long length) throws SQLException;
2270
2271 //--
2272 /**
2273 * Sets the designated parameter to the given input stream.
2274 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
2275 * parameter, it may be more practical to send it via a
2276 * <code>java.io.InputStream</code>. Data will be read from the stream
2277 * as needed until end-of-file is reached. The JDBC driver will
2278 * do any necessary conversion from ASCII to the database char format.
2279 *
2280 * <P><B>Note:</B> This stream object can either be a standard
2281 * Java stream object or your own subclass that implements the
2282 * standard interface.
2283 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2284 * it might be more efficient to use a version of
2285 * <code>setAsciiStream</code> which takes a length parameter.
2286 *
2287 * @param parameterName the name of the parameter
2288 * @param x the Java input stream that contains the ASCII parameter value
2289 * @exception SQLException if parameterName does not correspond to a named
2290 * parameter; if a database access error occurs or
2291 * this method is called on a closed <code>CallableStatement</code>
2292 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2293 * @since 1.6
2294 */
2295 void setAsciiStream(String parameterName, java.io.InputStream x)
2296 throws SQLException;
2297
2298 /**
2299 * Sets the designated parameter to the given input stream.
2300 * When a very large binary value is input to a <code>LONGVARBINARY</code>
2301 * parameter, it may be more practical to send it via a
2302 * <code>java.io.InputStream</code> object. The data will be read from the
2303 * stream as needed until end-of-file is reached.
2304 *
2305 * <P><B>Note:</B> This stream object can either be a standard
2306 * Java stream object or your own subclass that implements the
2307 * standard interface.
2308 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2309 * it might be more efficient to use a version of
2310 * <code>setBinaryStream</code> which takes a length parameter.
2311 *
2312 * @param parameterName the name of the parameter
2313 * @param x the java input stream which contains the binary parameter value
2314 * @exception SQLException if parameterName does not correspond to a named
2315 * parameter; if a database access error occurs or
2316 * this method is called on a closed <code>CallableStatement</code>
2317 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2318 * @since 1.6
2319 */
2320 void setBinaryStream(String parameterName, java.io.InputStream x)
2321 throws SQLException;
2322
2323 /**
2324 * Sets the designated parameter to the given <code>Reader</code>
2325 * object.
2326 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
2327 * parameter, it may be more practical to send it via a
2328 * <code>java.io.Reader</code> object. The data will be read from the stream
2329 * as needed until end-of-file is reached. The JDBC driver will
2330 * do any necessary conversion from UNICODE to the database char format.
2331 *
2332 * <P><B>Note:</B> This stream object can either be a standard
2333 * Java stream object or your own subclass that implements the
2334 * standard interface.
2335 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2336 * it might be more efficient to use a version of
2337 * <code>setCharacterStream</code> which takes a length parameter.
2338 *
2339 * @param parameterName the name of the parameter
2340 * @param reader the <code>java.io.Reader</code> object that contains the
2341 * Unicode data
2342 * @exception SQLException if parameterName does not correspond to a named
2343 * parameter; if a database access error occurs or
2344 * this method is called on a closed <code>CallableStatement</code>
2345 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2346 * @since 1.6
2347 */
2348 void setCharacterStream(String parameterName, java.io.Reader reader)
2349 throws SQLException;
2350
2351 /**
2352 * Sets the designated parameter to a <code>Reader</code> object. The
2353 * <code>Reader</code> reads the data till end-of-file is reached. The
2354 * driver does the necessary conversion from Java character format to
2355 * the national character set in the database.
2356
2357 * <P><B>Note:</B> This stream object can either be a standard
2358 * Java stream object or your own subclass that implements the
2359 * standard interface.
2360 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2361 * it might be more efficient to use a version of
2362 * <code>setNCharacterStream</code> which takes a length parameter.
2363 *
2364 * @param parameterName the name of the parameter
2365 * @param value the parameter value
2366 * @throws SQLException if parameterName does not correspond to a named
2367 * parameter; if the driver does not support national
2368 * character sets; if the driver can detect that a data conversion
2369 * error could occur; if a database access error occurs; or
2370 * this method is called on a closed <code>CallableStatement</code>
2371 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2372 * @since 1.6
2373 */
2374 void setNCharacterStream(String parameterName, Reader value)
2375 throws SQLException;
2376
2377 /**
2378 * Sets the designated parameter to a <code>Reader</code> object.
2379 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2380 * because it informs the driver that the parameter value should be sent to
2381 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
2382 * driver may have to do extra work to determine whether the parameter
2383 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
2384 *
2385 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2386 * it might be more efficient to use a version of
2387 * <code>setClob</code> which takes a length parameter.
2388 *
2389 * @param parameterName the name of the parameter
2390 * @param reader An object that contains the data to set the parameter value to.
2391 * @throws SQLException if parameterName does not correspond to a named
2392 * parameter; if a database access error occurs or this method is called on
2393 * a closed <code>CallableStatement</code>
2394 *
2395 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2396 * @since 1.6
2397 */
2398 void setClob(String parameterName, Reader reader)
2399 throws SQLException;
2400
2401 /**
2402 * Sets the designated parameter to a <code>InputStream</code> object.
2403 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
2404 * method because it informs the driver that the parameter value should be
2405 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
2406 * the driver may have to do extra work to determine whether the parameter
2407 * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
2408 *
2409 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2410 * it might be more efficient to use a version of
2411 * <code>setBlob</code> which takes a length parameter.
2412 *
2413 * @param parameterName the name of the parameter
2414 * @param inputStream An object that contains the data to set the parameter
2415 * value to.
2416 * @throws SQLException if parameterName does not correspond to a named
2417 * parameter; if a database access error occurs or
2418 * this method is called on a closed <code>CallableStatement</code>
2419 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2420 *
2421 * @since 1.6
2422 */
2423 void setBlob(String parameterName, InputStream inputStream)
2424 throws SQLException;
2425
2426 /**
2427 * Sets the designated parameter to a <code>Reader</code> object.
2428 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2429 * because it informs the driver that the parameter value should be sent to
2430 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2431 * driver may have to do extra work to determine whether the parameter
2432 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2433 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2434 * it might be more efficient to use a version of
2435 * <code>setNClob</code> which takes a length parameter.
2436 *
2437 * @param parameterName the name of the parameter
2438 * @param reader An object that contains the data to set the parameter value to.
2439 * @throws SQLException if parameterName does not correspond to a named
2440 * parameter; if the driver does not support national character sets;
2441 * if the driver can detect that a data conversion
2442 * error could occur; if a database access error occurs or
2443 * this method is called on a closed <code>CallableStatement</code>
2444 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2445 *
2446 * @since 1.6
2447 */
2448 void setNClob(String parameterName, Reader reader)
2449 throws SQLException;
2450 }
|