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 * An object that represents a precompiled SQL statement.
0035 * <P>A SQL statement is precompiled and stored in a
0036 * <code>PreparedStatement</code> object. This object can then be used to
0037 * efficiently execute this statement multiple times.
0038 *
0039 * <P><B>Note:</B> The setter methods (<code>setShort</code>, <code>setString</code>,
0040 * and so on) for setting IN parameter values
0041 * must specify types that are compatible with the defined SQL type of
0042 * the input parameter. For instance, if the IN parameter has SQL type
0043 * <code>INTEGER</code>, then the method <code>setInt</code> should be used.
0044 *
0045 * <p>If arbitrary parameter type conversions are required, the method
0046 * <code>setObject</code> should be used with a target SQL type.
0047 * <P>
0048 * In the following example of setting a parameter, <code>con</code> represents
0049 * an active connection:
0050 * <PRE>
0051 * PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES
0052 * SET SALARY = ? WHERE ID = ?");
0053 * pstmt.setBigDecimal(1, 153833.00)
0054 * pstmt.setInt(2, 110592)
0055 * </PRE>
0056 *
0057 * @see Connection#prepareStatement
0058 * @see ResultSet
0059 */
0060
0061 public interface PreparedStatement extends Statement {
0062
0063 /**
0064 * Executes the SQL query in this <code>PreparedStatement</code> object
0065 * and returns the <code>ResultSet</code> object generated by the query.
0066 *
0067 * @return a <code>ResultSet</code> object that contains the data produced by the
0068 * query; never <code>null</code>
0069 * @exception SQLException if a database access error occurs;
0070 * this method is called on a closed <code>PreparedStatement</code> or the SQL
0071 * statement does not return a <code>ResultSet</code> object
0072 */
0073 ResultSet executeQuery() throws SQLException;
0074
0075 /**
0076 * Executes the SQL statement in this <code>PreparedStatement</code> object,
0077 * which must be an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
0078 * <code>DELETE</code>; or an SQL statement that returns nothing,
0079 * such as a DDL statement.
0080 *
0081 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
0082 * or (2) 0 for SQL statements that return nothing
0083 * @exception SQLException if a database access error occurs;
0084 * this method is called on a closed <code>PreparedStatement</code>
0085 * or the SQL
0086 * statement returns a <code>ResultSet</code> object
0087 */
0088 int executeUpdate() throws SQLException;
0089
0090 /**
0091 * Sets the designated parameter to SQL <code>NULL</code>.
0092 *
0093 * <P><B>Note:</B> You must specify the parameter's SQL type.
0094 *
0095 * @param parameterIndex the first parameter is 1, the second is 2, ...
0096 * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
0097 * @exception SQLException if parameterIndex does not correspond to a parameter
0098 * marker in the SQL statement; if a database access error occurs or
0099 * this method is called on a closed <code>PreparedStatement</code>
0100 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0101 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0102 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0103 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0104 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0105 * or <code>STRUCT</code> data type and the JDBC driver does not support
0106 * this data type
0107 */
0108 void setNull(int parameterIndex, int sqlType) throws SQLException;
0109
0110 /**
0111 * Sets the designated parameter to the given Java <code>boolean</code> value.
0112 * The driver converts this
0113 * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
0114 *
0115 * @param parameterIndex the first parameter is 1, the second is 2, ...
0116 * @param x the parameter value
0117 * @exception SQLException if parameterIndex does not correspond to a parameter
0118 * marker in the SQL statement;
0119 * if a database access error occurs or
0120 * this method is called on a closed <code>PreparedStatement</code>
0121 */
0122 void setBoolean(int parameterIndex, boolean x) throws SQLException;
0123
0124 /**
0125 * Sets the designated parameter to the given Java <code>byte</code> value.
0126 * The driver converts this
0127 * to an SQL <code>TINYINT</code> value when it sends it to the database.
0128 *
0129 * @param parameterIndex the first parameter is 1, the second is 2, ...
0130 * @param x the parameter value
0131 * @exception SQLException if parameterIndex does not correspond to a parameter
0132 * marker in the SQL statement; if a database access error occurs or
0133 * this method is called on a closed <code>PreparedStatement</code>
0134 */
0135 void setByte(int parameterIndex, byte x) throws SQLException;
0136
0137 /**
0138 * Sets the designated parameter to the given Java <code>short</code> value.
0139 * The driver converts this
0140 * to an SQL <code>SMALLINT</code> value when it sends it to the database.
0141 *
0142 * @param parameterIndex the first parameter is 1, the second is 2, ...
0143 * @param x the parameter value
0144 * @exception SQLException if parameterIndex does not correspond to a parameter
0145 * marker in the SQL statement; if a database access error occurs or
0146 * this method is called on a closed <code>PreparedStatement</code>
0147 */
0148 void setShort(int parameterIndex, short x) throws SQLException;
0149
0150 /**
0151 * Sets the designated parameter to the given Java <code>int</code> value.
0152 * The driver converts this
0153 * to an SQL <code>INTEGER</code> value when it sends it to the database.
0154 *
0155 * @param parameterIndex the first parameter is 1, the second is 2, ...
0156 * @param x the parameter value
0157 * @exception SQLException if parameterIndex does not correspond to a parameter
0158 * marker in the SQL statement; if a database access error occurs or
0159 * this method is called on a closed <code>PreparedStatement</code>
0160 */
0161 void setInt(int parameterIndex, int x) throws SQLException;
0162
0163 /**
0164 * Sets the designated parameter to the given Java <code>long</code> value.
0165 * The driver converts this
0166 * to an SQL <code>BIGINT</code> value when it sends it to the database.
0167 *
0168 * @param parameterIndex the first parameter is 1, the second is 2, ...
0169 * @param x the parameter value
0170 * @exception SQLException if parameterIndex does not correspond to a parameter
0171 * marker in the SQL statement; if a database access error occurs or
0172 * this method is called on a closed <code>PreparedStatement</code>
0173 */
0174 void setLong(int parameterIndex, long x) throws SQLException;
0175
0176 /**
0177 * Sets the designated parameter to the given Java <code>float</code> value.
0178 * The driver converts this
0179 * to an SQL <code>REAL</code> value when it sends it to the database.
0180 *
0181 * @param parameterIndex the first parameter is 1, the second is 2, ...
0182 * @param x the parameter value
0183 * @exception SQLException if parameterIndex does not correspond to a parameter
0184 * marker in the SQL statement; if a database access error occurs or
0185 * this method is called on a closed <code>PreparedStatement</code>
0186 */
0187 void setFloat(int parameterIndex, float x) throws SQLException;
0188
0189 /**
0190 * Sets the designated parameter to the given Java <code>double</code> value.
0191 * The driver converts this
0192 * to an SQL <code>DOUBLE</code> value when it sends it to the database.
0193 *
0194 * @param parameterIndex the first parameter is 1, the second is 2, ...
0195 * @param x the parameter value
0196 * @exception SQLException if parameterIndex does not correspond to a parameter
0197 * marker in the SQL statement; if a database access error occurs or
0198 * this method is called on a closed <code>PreparedStatement</code>
0199 */
0200 void setDouble(int parameterIndex, double x) throws SQLException;
0201
0202 /**
0203 * Sets the designated parameter to the given <code>java.math.BigDecimal</code> value.
0204 * The driver converts this to an SQL <code>NUMERIC</code> value when
0205 * it sends it to the database.
0206 *
0207 * @param parameterIndex the first parameter is 1, the second is 2, ...
0208 * @param x the parameter value
0209 * @exception SQLException if parameterIndex does not correspond to a parameter
0210 * marker in the SQL statement; if a database access error occurs or
0211 * this method is called on a closed <code>PreparedStatement</code>
0212 */
0213 void setBigDecimal(int parameterIndex, BigDecimal x)
0214 throws SQLException;
0215
0216 /**
0217 * Sets the designated parameter to the given Java <code>String</code> value.
0218 * The driver converts this
0219 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
0220 * (depending on the argument's
0221 * size relative to the driver's limits on <code>VARCHAR</code> values)
0222 * when it sends it to the database.
0223 *
0224 * @param parameterIndex the first parameter is 1, the second is 2, ...
0225 * @param x the parameter value
0226 * @exception SQLException if parameterIndex does not correspond to a parameter
0227 * marker in the SQL statement; if a database access error occurs or
0228 * this method is called on a closed <code>PreparedStatement</code>
0229 */
0230 void setString(int parameterIndex, String x) throws SQLException;
0231
0232 /**
0233 * Sets the designated parameter to the given Java array of bytes. The driver converts
0234 * this to an SQL <code>VARBINARY</code> or <code>LONGVARBINARY</code>
0235 * (depending on the argument's size relative to the driver's limits on
0236 * <code>VARBINARY</code> values) when it sends it to the database.
0237 *
0238 * @param parameterIndex the first parameter is 1, the second is 2, ...
0239 * @param x the parameter value
0240 * @exception SQLException if parameterIndex does not correspond to a parameter
0241 * marker in the SQL statement; if a database access error occurs or
0242 * this method is called on a closed <code>PreparedStatement</code>
0243 */
0244 void setBytes(int parameterIndex, byte x[]) throws SQLException;
0245
0246 /**
0247 * Sets the designated parameter to the given <code>java.sql.Date</code> value
0248 * using the default time zone of the virtual machine that is running
0249 * the application.
0250 * The driver converts this
0251 * to an SQL <code>DATE</code> value when it sends it to the database.
0252 *
0253 * @param parameterIndex the first parameter is 1, the second is 2, ...
0254 * @param x the parameter value
0255 * @exception SQLException if parameterIndex does not correspond to a parameter
0256 * marker in the SQL statement; if a database access error occurs or
0257 * this method is called on a closed <code>PreparedStatement</code>
0258 */
0259 void setDate(int parameterIndex, java.sql.Date x)
0260 throws SQLException;
0261
0262 /**
0263 * Sets the designated parameter to the given <code>java.sql.Time</code> value.
0264 * The driver converts this
0265 * to an SQL <code>TIME</code> value when it sends it to the database.
0266 *
0267 * @param parameterIndex the first parameter is 1, the second is 2, ...
0268 * @param x the parameter value
0269 * @exception SQLException if parameterIndex does not correspond to a parameter
0270 * marker in the SQL statement; if a database access error occurs or
0271 * this method is called on a closed <code>PreparedStatement</code>
0272 */
0273 void setTime(int parameterIndex, java.sql.Time x)
0274 throws SQLException;
0275
0276 /**
0277 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
0278 * The driver
0279 * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
0280 * database.
0281 *
0282 * @param parameterIndex the first parameter is 1, the second is 2, ...
0283 * @param x the parameter value
0284 * @exception SQLException if parameterIndex does not correspond to a parameter
0285 * marker in the SQL statement; if a database access error occurs or
0286 * this method is called on a closed <code>PreparedStatement</code> */
0287 void setTimestamp(int parameterIndex, java.sql.Timestamp x)
0288 throws SQLException;
0289
0290 /**
0291 * Sets the designated parameter to the given input stream, which will have
0292 * the specified number of bytes.
0293 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
0294 * parameter, it may be more practical to send it via a
0295 * <code>java.io.InputStream</code>. Data will be read from the stream
0296 * as needed until end-of-file is reached. The JDBC driver will
0297 * do any necessary conversion from ASCII to the database char format.
0298 *
0299 * <P><B>Note:</B> This stream object can either be a standard
0300 * Java stream object or your own subclass that implements the
0301 * standard interface.
0302 *
0303 * @param parameterIndex the first parameter is 1, the second is 2, ...
0304 * @param x the Java input stream that contains the ASCII parameter value
0305 * @param length the number of bytes in the stream
0306 * @exception SQLException if parameterIndex does not correspond to a parameter
0307 * marker in the SQL statement; if a database access error occurs or
0308 * this method is called on a closed <code>PreparedStatement</code>
0309 */
0310 void setAsciiStream(int parameterIndex, java.io.InputStream x,
0311 int length) throws SQLException;
0312
0313 /**
0314 * Sets the designated parameter to the given input stream, which
0315 * will have the specified number of bytes.
0316 *
0317 * When a very large Unicode value is input to a <code>LONGVARCHAR</code>
0318 * parameter, it may be more practical to send it via a
0319 * <code>java.io.InputStream</code> object. The data will be read from the
0320 * stream as needed until end-of-file is reached. The JDBC driver will
0321 * do any necessary conversion from Unicode to the database char format.
0322 *
0323 *The byte format of the Unicode stream must be a Java UTF-8, as defined in the
0324 *Java Virtual Machine Specification.
0325 *
0326 * <P><B>Note:</B> This stream object can either be a standard
0327 * Java stream object or your own subclass that implements the
0328 * standard interface.
0329 *
0330 * @param parameterIndex the first parameter is 1, the second is 2, ...
0331 * @param x a <code>java.io.InputStream</code> object that contains the
0332 * Unicode parameter value
0333 * @param length the number of bytes in the stream
0334 * @exception SQLException if parameterIndex does not correspond to a parameter
0335 * marker in the SQL statement; if a database access error occurs or
0336 * this method is called on a closed <code>PreparedStatement</code>
0337 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0338 * this method
0339 * @deprecated
0340 */
0341 void setUnicodeStream(int parameterIndex, java.io.InputStream x,
0342 int length) throws SQLException;
0343
0344 /**
0345 * Sets the designated parameter to the given input stream, which will have
0346 * the specified number of bytes.
0347 * When a very large binary value is input to a <code>LONGVARBINARY</code>
0348 * parameter, it may be more practical to send it via a
0349 * <code>java.io.InputStream</code> object. The data will be read from the
0350 * stream as needed until end-of-file is reached.
0351 *
0352 * <P><B>Note:</B> This stream object can either be a standard
0353 * Java stream object or your own subclass that implements the
0354 * standard interface.
0355 *
0356 * @param parameterIndex the first parameter is 1, the second is 2, ...
0357 * @param x the java input stream which contains the binary parameter value
0358 * @param length the number of bytes in the stream
0359 * @exception SQLException if parameterIndex does not correspond to a parameter
0360 * marker in the SQL statement; if a database access error occurs or
0361 * this method is called on a closed <code>PreparedStatement</code>
0362 */
0363 void setBinaryStream(int parameterIndex, java.io.InputStream x,
0364 int length) throws SQLException;
0365
0366 /**
0367 * Clears the current parameter values immediately.
0368 * <P>In general, parameter values remain in force for repeated use of a
0369 * statement. Setting a parameter value automatically clears its
0370 * previous value. However, in some cases it is useful to immediately
0371 * release the resources used by the current parameter values; this can
0372 * be done by calling the method <code>clearParameters</code>.
0373 *
0374 * @exception SQLException if a database access error occurs or
0375 * this method is called on a closed <code>PreparedStatement</code>
0376 */
0377 void clearParameters() throws SQLException;
0378
0379 //----------------------------------------------------------------------
0380 // Advanced features:
0381
0382 /**
0383 * Sets the value of the designated parameter with the given object.
0384 * This method is like the method <code>setObject</code>
0385 * above, except that it assumes a scale of zero.
0386 *
0387 * @param parameterIndex the first parameter is 1, the second is 2, ...
0388 * @param x the object containing the input parameter value
0389 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
0390 * sent to the database
0391 * @exception SQLException if parameterIndex does not correspond to a parameter
0392 * marker in the SQL statement; if a database access error occurs or
0393 * this method is called on a closed <code>PreparedStatement</code>
0394 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
0395 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0396 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0397 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0398 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0399 * or <code>STRUCT</code> data type and the JDBC driver does not support
0400 * this data type
0401 * @see Types
0402 */
0403 void setObject(int parameterIndex, Object x, int targetSqlType)
0404 throws SQLException;
0405
0406 /**
0407 * <p>Sets the value of the designated parameter using the given object.
0408 * The second parameter must be of type <code>Object</code>; therefore, the
0409 * <code>java.lang</code> equivalent objects should be used for built-in types.
0410 *
0411 * <p>The JDBC specification specifies a standard mapping from
0412 * Java <code>Object</code> types to SQL types. The given argument
0413 * will be converted to the corresponding SQL type before being
0414 * sent to the database.
0415 *
0416 * <p>Note that this method may be used to pass datatabase-
0417 * specific abstract data types, by using a driver-specific Java
0418 * type.
0419 *
0420 * If the object is of a class implementing the interface <code>SQLData</code>,
0421 * the JDBC driver should call the method <code>SQLData.writeSQL</code>
0422 * to write it to the SQL data stream.
0423 * If, on the other hand, the object is of a class implementing
0424 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
0425 * <code>Struct</code>, <code>java.net.URL</code>, <code>RowId</code>, <code>SQLXML</code>
0426 * or <code>Array</code>, the driver should pass it to the database as a
0427 * value of the corresponding SQL type.
0428 * <P>
0429 *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to
0430 * the backend. For maximum portability, the <code>setNull</code> or the
0431 * <code>setObject(int parameterIndex, Object x, int sqlType)</code>
0432 * method should be used
0433 * instead of <code>setObject(int parameterIndex, Object x)</code>.
0434 *<p>
0435 * <b>Note:</b> This method throws an exception if there is an ambiguity, for example, if the
0436 * object is of a class implementing more than one of the interfaces named above.
0437 *
0438 * @param parameterIndex the first parameter is 1, the second is 2, ...
0439 * @param x the object containing the input parameter value
0440 * @exception SQLException if parameterIndex does not correspond to a parameter
0441 * marker in the SQL statement; if a database access error occurs;
0442 * this method is called on a closed <code>PreparedStatement</code>
0443 * or the type of the given object is ambiguous
0444 */
0445 void setObject(int parameterIndex, Object x) throws SQLException;
0446
0447 /**
0448 * Executes the SQL statement in this <code>PreparedStatement</code> object,
0449 * which may be any kind of SQL statement.
0450 * Some prepared statements return multiple results; the <code>execute</code>
0451 * method handles these complex statements as well as the simpler
0452 * form of statements handled by the methods <code>executeQuery</code>
0453 * and <code>executeUpdate</code>.
0454 * <P>
0455 * The <code>execute</code> method returns a <code>boolean</code> to
0456 * indicate the form of the first result. You must call either the method
0457 * <code>getResultSet</code> or <code>getUpdateCount</code>
0458 * to retrieve the result; you must call <code>getMoreResults</code> to
0459 * move to any subsequent result(s).
0460 *
0461 * @return <code>true</code> if the first result is a <code>ResultSet</code>
0462 * object; <code>false</code> if the first result is an update
0463 * count or there is no result
0464 * @exception SQLException if a database access error occurs;
0465 * this method is called on a closed <code>PreparedStatement</code>
0466 * or an argument is supplied to this method
0467 * @see Statement#execute
0468 * @see Statement#getResultSet
0469 * @see Statement#getUpdateCount
0470 * @see Statement#getMoreResults
0471
0472 */
0473 boolean execute() throws SQLException;
0474
0475 //--------------------------JDBC 2.0-----------------------------
0476
0477 /**
0478 * Adds a set of parameters to this <code>PreparedStatement</code>
0479 * object's batch of commands.
0480 *
0481 * @exception SQLException if a database access error occurs or
0482 * this method is called on a closed <code>PreparedStatement</code>
0483 * @see Statement#addBatch
0484 * @since 1.2
0485 */
0486 void addBatch() throws SQLException;
0487
0488 /**
0489 * Sets the designated parameter to the given <code>Reader</code>
0490 * object, which is the given number of characters long.
0491 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
0492 * parameter, it may be more practical to send it via a
0493 * <code>java.io.Reader</code> object. The data will be read from the stream
0494 * as needed until end-of-file is reached. The JDBC driver will
0495 * do any necessary conversion from UNICODE to the database char format.
0496 *
0497 * <P><B>Note:</B> This stream object can either be a standard
0498 * Java stream object or your own subclass that implements the
0499 * standard interface.
0500 *
0501 * @param parameterIndex the first parameter is 1, the second is 2, ...
0502 * @param reader the <code>java.io.Reader</code> object that contains the
0503 * Unicode data
0504 * @param length the number of characters in the stream
0505 * @exception SQLException if parameterIndex does not correspond to a parameter
0506 * marker in the SQL statement; if a database access error occurs or
0507 * this method is called on a closed <code>PreparedStatement</code>
0508 * @since 1.2
0509 */
0510 void setCharacterStream(int parameterIndex, java.io.Reader reader,
0511 int length) throws SQLException;
0512
0513 /**
0514 * Sets the designated parameter to the given
0515 * <code>REF(<structured-type>)</code> value.
0516 * The driver converts this to an SQL <code>REF</code> value when it
0517 * sends it to the database.
0518 *
0519 * @param parameterIndex the first parameter is 1, the second is 2, ...
0520 * @param x an SQL <code>REF</code> value
0521 * @exception SQLException if parameterIndex does not correspond to a parameter
0522 * marker in the SQL statement; if a database access error occurs or
0523 * this method is called on a closed <code>PreparedStatement</code>
0524 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0525 * @since 1.2
0526 */
0527 void setRef(int parameterIndex, Ref x) throws SQLException;
0528
0529 /**
0530 * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
0531 * The driver converts this to an SQL <code>BLOB</code> value when it
0532 * sends it to the database.
0533 *
0534 * @param parameterIndex the first parameter is 1, the second is 2, ...
0535 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
0536 * @exception SQLException if parameterIndex does not correspond to a parameter
0537 * marker in the SQL statement; if a database access error occurs or
0538 * this method is called on a closed <code>PreparedStatement</code>
0539 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0540 * @since 1.2
0541 */
0542 void setBlob(int parameterIndex, Blob x) throws SQLException;
0543
0544 /**
0545 * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
0546 * The driver converts this to an SQL <code>CLOB</code> value when it
0547 * sends it to the database.
0548 *
0549 * @param parameterIndex the first parameter is 1, the second is 2, ...
0550 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
0551 * @exception SQLException if parameterIndex does not correspond to a parameter
0552 * marker in the SQL statement; if a database access error occurs or
0553 * this method is called on a closed <code>PreparedStatement</code>
0554 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0555 * @since 1.2
0556 */
0557 void setClob(int parameterIndex, Clob x) throws SQLException;
0558
0559 /**
0560 * Sets the designated parameter to the given <code>java.sql.Array</code> object.
0561 * The driver converts this to an SQL <code>ARRAY</code> value when it
0562 * sends it to the database.
0563 *
0564 * @param parameterIndex the first parameter is 1, the second is 2, ...
0565 * @param x an <code>Array</code> object that maps an SQL <code>ARRAY</code> value
0566 * @exception SQLException if parameterIndex does not correspond to a parameter
0567 * marker in the SQL statement; if a database access error occurs or
0568 * this method is called on a closed <code>PreparedStatement</code>
0569 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0570 * @since 1.2
0571 */
0572 void setArray(int parameterIndex, Array x) throws SQLException;
0573
0574 /**
0575 * Retrieves a <code>ResultSetMetaData</code> object that contains
0576 * information about the columns of the <code>ResultSet</code> object
0577 * that will be returned when this <code>PreparedStatement</code> object
0578 * is executed.
0579 * <P>
0580 * Because a <code>PreparedStatement</code> object is precompiled, it is
0581 * possible to know about the <code>ResultSet</code> object that it will
0582 * return without having to execute it. Consequently, it is possible
0583 * to invoke the method <code>getMetaData</code> on a
0584 * <code>PreparedStatement</code> object rather than waiting to execute
0585 * it and then invoking the <code>ResultSet.getMetaData</code> method
0586 * on the <code>ResultSet</code> object that is returned.
0587 * <P>
0588 * <B>NOTE:</B> Using this method may be expensive for some drivers due
0589 * to the lack of underlying DBMS support.
0590 *
0591 * @return the description of a <code>ResultSet</code> object's columns or
0592 * <code>null</code> if the driver cannot return a
0593 * <code>ResultSetMetaData</code> object
0594 * @exception SQLException if a database access error occurs or
0595 * this method is called on a closed <code>PreparedStatement</code>
0596 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0597 * this method
0598 * @since 1.2
0599 */
0600 ResultSetMetaData getMetaData() throws SQLException;
0601
0602 /**
0603 * Sets the designated parameter to the given <code>java.sql.Date</code> value,
0604 * using the given <code>Calendar</code> object. The driver uses
0605 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
0606 * which the driver then sends to the database. With
0607 * a <code>Calendar</code> object, the driver can calculate the date
0608 * taking into account a custom timezone. If no
0609 * <code>Calendar</code> object is specified, the driver uses the default
0610 * timezone, which is that of the virtual machine running the application.
0611 *
0612 * @param parameterIndex the first parameter is 1, the second is 2, ...
0613 * @param x the parameter value
0614 * @param cal the <code>Calendar</code> object the driver will use
0615 * to construct the date
0616 * @exception SQLException if parameterIndex does not correspond to a parameter
0617 * marker in the SQL statement; if a database access error occurs or
0618 * this method is called on a closed <code>PreparedStatement</code>
0619 * @since 1.2
0620 */
0621 void setDate(int parameterIndex, java.sql.Date x, Calendar cal)
0622 throws SQLException;
0623
0624 /**
0625 * Sets the designated parameter to the given <code>java.sql.Time</code> value,
0626 * using the given <code>Calendar</code> object. The driver uses
0627 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
0628 * which the driver then sends to the database. With
0629 * a <code>Calendar</code> object, the driver can calculate the time
0630 * taking into account a custom timezone. If no
0631 * <code>Calendar</code> object is specified, the driver uses the default
0632 * timezone, which is that of the virtual machine running the application.
0633 *
0634 * @param parameterIndex the first parameter is 1, the second is 2, ...
0635 * @param x the parameter value
0636 * @param cal the <code>Calendar</code> object the driver will use
0637 * to construct the time
0638 * @exception SQLException if parameterIndex does not correspond to a parameter
0639 * marker in the SQL statement; if a database access error occurs or
0640 * this method is called on a closed <code>PreparedStatement</code>
0641 * @since 1.2
0642 */
0643 void setTime(int parameterIndex, java.sql.Time x, Calendar cal)
0644 throws SQLException;
0645
0646 /**
0647 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
0648 * using the given <code>Calendar</code> object. The driver uses
0649 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
0650 * which the driver then sends to the database. With a
0651 * <code>Calendar</code> object, the driver can calculate the timestamp
0652 * taking into account a custom timezone. If no
0653 * <code>Calendar</code> object is specified, the driver uses the default
0654 * timezone, which is that of the virtual machine running the application.
0655 *
0656 * @param parameterIndex the first parameter is 1, the second is 2, ...
0657 * @param x the parameter value
0658 * @param cal the <code>Calendar</code> object the driver will use
0659 * to construct the timestamp
0660 * @exception SQLException if parameterIndex does not correspond to a parameter
0661 * marker in the SQL statement; if a database access error occurs or
0662 * this method is called on a closed <code>PreparedStatement</code>
0663 * @since 1.2
0664 */
0665 void setTimestamp(int parameterIndex, java.sql.Timestamp x,
0666 Calendar cal) throws SQLException;
0667
0668 /**
0669 * Sets the designated parameter to SQL <code>NULL</code>.
0670 * This version of the method <code>setNull</code> should
0671 * be used for user-defined types and REF type parameters. Examples
0672 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
0673 * named array types.
0674 *
0675 * <P><B>Note:</B> To be portable, applications must give the
0676 * SQL type code and the fully-qualified SQL type name when specifying
0677 * a NULL user-defined or REF parameter. In the case of a user-defined type
0678 * the name is the type name of the parameter itself. For a REF
0679 * parameter, the name is the type name of the referenced type. If
0680 * a JDBC driver does not need the type code or type name information,
0681 * it may ignore it.
0682 *
0683 * Although it is intended for user-defined and Ref parameters,
0684 * this method may be used to set a null parameter of any JDBC type.
0685 * If the parameter does not have a user-defined or REF type, the given
0686 * typeName is ignored.
0687 *
0688 *
0689 * @param parameterIndex the first parameter is 1, the second is 2, ...
0690 * @param sqlType a value from <code>java.sql.Types</code>
0691 * @param typeName the fully-qualified name of an SQL user-defined type;
0692 * ignored if the parameter is not a user-defined type or REF
0693 * @exception SQLException if parameterIndex does not correspond to a parameter
0694 * marker in the SQL statement; if a database access error occurs or
0695 * this method is called on a closed <code>PreparedStatement</code>
0696 * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is
0697 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0698 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0699 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0700 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0701 * or <code>STRUCT</code> data type and the JDBC driver does not support
0702 * this data type or if the JDBC driver does not support this method
0703 * @since 1.2
0704 */
0705 void setNull(int parameterIndex, int sqlType, String typeName)
0706 throws SQLException;
0707
0708 //------------------------- JDBC 3.0 -----------------------------------
0709
0710 /**
0711 * Sets the designated parameter to the given <code>java.net.URL</code> value.
0712 * The driver converts this to an SQL <code>DATALINK</code> value
0713 * when it sends it to the database.
0714 *
0715 * @param parameterIndex the first parameter is 1, the second is 2, ...
0716 * @param x the <code>java.net.URL</code> object to be set
0717 * @exception SQLException if parameterIndex does not correspond to a parameter
0718 * marker in the SQL statement; if a database access error occurs or
0719 * this method is called on a closed <code>PreparedStatement</code>
0720 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0721 * @since 1.4
0722 */
0723 void setURL(int parameterIndex, java.net.URL x) throws SQLException;
0724
0725 /**
0726 * Retrieves the number, types and properties of this
0727 * <code>PreparedStatement</code> object's parameters.
0728 *
0729 * @return a <code>ParameterMetaData</code> object that contains information
0730 * about the number, types and properties for each
0731 * parameter marker of this <code>PreparedStatement</code> object
0732 * @exception SQLException if a database access error occurs or
0733 * this method is called on a closed <code>PreparedStatement</code>
0734 * @see ParameterMetaData
0735 * @since 1.4
0736 */
0737 ParameterMetaData getParameterMetaData() throws SQLException;
0738
0739 //------------------------- JDBC 4.0 -----------------------------------
0740
0741 /**
0742 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
0743 * driver converts this to a SQL <code>ROWID</code> value when it sends it
0744 * to the database
0745 *
0746 * @param parameterIndex the first parameter is 1, the second is 2, ...
0747 * @param x the parameter value
0748 * @throws SQLException if parameterIndex does not correspond to a parameter
0749 * marker in the SQL statement; if a database access error occurs or
0750 * this method is called on a closed <code>PreparedStatement</code>
0751 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0752 *
0753 * @since 1.6
0754 */
0755 void setRowId(int parameterIndex, RowId x) throws SQLException;
0756
0757 /**
0758 * Sets the designated paramter to the given <code>String</code> object.
0759 * The driver converts this to a SQL <code>NCHAR</code> or
0760 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
0761 * (depending on the argument's
0762 * size relative to the driver's limits on <code>NVARCHAR</code> values)
0763 * when it sends it to the database.
0764 *
0765 * @param parameterIndex of the first parameter is 1, the second is 2, ...
0766 * @param value the parameter value
0767 * @throws SQLException if parameterIndex does not correspond to a parameter
0768 * marker in the SQL statement; if the driver does not support national
0769 * character sets; if the driver can detect that a data conversion
0770 * error could occur; if a database access error occurs; or
0771 * this method is called on a closed <code>PreparedStatement</code>
0772 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0773 * @since 1.6
0774 */
0775 void setNString(int parameterIndex, String value)
0776 throws SQLException;
0777
0778 /**
0779 * Sets the designated parameter to a <code>Reader</code> object. The
0780 * <code>Reader</code> reads the data till end-of-file is reached. The
0781 * driver does the necessary conversion from Java character format to
0782 * the national character set in the database.
0783 * @param parameterIndex of the first parameter is 1, the second is 2, ...
0784 * @param value the parameter value
0785 * @param length the number of characters in the parameter data.
0786 * @throws SQLException if parameterIndex does not correspond to a parameter
0787 * marker in the SQL statement; if the driver does not support national
0788 * character sets; if the driver can detect that a data conversion
0789 * error could occur; if a database access error occurs; or
0790 * this method is called on a closed <code>PreparedStatement</code>
0791 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0792 * @since 1.6
0793 */
0794 void setNCharacterStream(int parameterIndex, Reader value,
0795 long length) throws SQLException;
0796
0797 /**
0798 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a
0799 * SQL <code>NCLOB</code> value when it sends it to the database.
0800 * @param parameterIndex of the first parameter is 1, the second is 2, ...
0801 * @param value the parameter value
0802 * @throws SQLException if parameterIndex does not correspond to a parameter
0803 * marker in the SQL statement; if the driver does not support national
0804 * character sets; if the driver can detect that a data conversion
0805 * error could occur; if a database access error occurs; or
0806 * this method is called on a closed <code>PreparedStatement</code>
0807 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0808 * @since 1.6
0809 */
0810 void setNClob(int parameterIndex, NClob value) throws SQLException;
0811
0812 /**
0813 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
0814 * of characters specified by length otherwise a <code>SQLException</code> will be
0815 * generated when the <code>PreparedStatement</code> is executed.
0816 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
0817 * because it informs the driver that the parameter value should be sent to
0818 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
0819 * driver may have to do extra work to determine whether the parameter
0820 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
0821 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
0822 * @param reader An object that contains the data to set the parameter value to.
0823 * @param length the number of characters in the parameter data.
0824 * @throws SQLException if parameterIndex does not correspond to a parameter
0825 * marker in the SQL statement; if a database access error occurs; this method is called on
0826 * a closed <code>PreparedStatement</code> or if the length specified is less than zero.
0827 *
0828 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0829 * @since 1.6
0830 */
0831 void setClob(int parameterIndex, Reader reader, long length)
0832 throws SQLException;
0833
0834 /**
0835 * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number
0836 * of characters specified by length otherwise a <code>SQLException</code> will be
0837 * generated when the <code>PreparedStatement</code> is executed.
0838 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
0839 * method because it informs the driver that the parameter value should be
0840 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
0841 * the driver may have to do extra work to determine whether the parameter
0842 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
0843 * @param parameterIndex index of the first parameter is 1,
0844 * the second is 2, ...
0845 * @param inputStream An object that contains the data to set the parameter
0846 * value to.
0847 * @param length the number of bytes in the parameter data.
0848 * @throws SQLException if parameterIndex does not correspond to a parameter
0849 * marker in the SQL statement; if a database access error occurs;
0850 * this method is called on a closed <code>PreparedStatement</code>;
0851 * if the length specified
0852 * is less than zero or if the number of bytes in the inputstream does not match
0853 * the specfied length.
0854 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0855 *
0856 * @since 1.6
0857 */
0858 void setBlob(int parameterIndex, InputStream inputStream,
0859 long length) throws SQLException;
0860
0861 /**
0862 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
0863 * of characters specified by length otherwise a <code>SQLException</code> will be
0864 * generated when the <code>PreparedStatement</code> is executed.
0865 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
0866 * because it informs the driver that the parameter value should be sent to
0867 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
0868 * driver may have to do extra work to determine whether the parameter
0869 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
0870 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
0871 * @param reader An object that contains the data to set the parameter value to.
0872 * @param length the number of characters in the parameter data.
0873 * @throws SQLException if parameterIndex does not correspond to a parameter
0874 * marker in the SQL statement; if the length specified is less than zero;
0875 * if the driver does not support national character sets;
0876 * if the driver can detect that a data conversion
0877 * error could occur; if a database access error occurs or
0878 * this method is called on a closed <code>PreparedStatement</code>
0879 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0880 *
0881 * @since 1.6
0882 */
0883 void setNClob(int parameterIndex, Reader reader, long length)
0884 throws SQLException;
0885
0886 /**
0887 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object.
0888 * The driver converts this to an
0889 * SQL <code>XML</code> value when it sends it to the database.
0890 * <p>
0891 *
0892 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
0893 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value
0894 * @throws SQLException if parameterIndex does not correspond to a parameter
0895 * marker in the SQL statement; if a database access error occurs;
0896 * this method is called on a closed <code>PreparedStatement</code>
0897 * or the <code>java.xml.transform.Result</code>,
0898 * <code>Writer</code> or <code>OutputStream</code> has not been closed for
0899 * the <code>SQLXML</code> object
0900 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
0901 *
0902 * @since 1.6
0903 */
0904 void setSQLXML(int parameterIndex, SQLXML xmlObject)
0905 throws SQLException;
0906
0907 /**
0908 * <p>Sets the value of the designated parameter with the given object. The second
0909 * argument must be an object type; for integral values, the
0910 * <code>java.lang</code> equivalent objects should be used.
0911 *
0912 * If the second argument is an <code>InputStream</code> then the stream must contain
0913 * the number of bytes specified by scaleOrLength. If the second argument is a
0914 * <code>Reader</code> then the reader must contain the number of characters specified
0915 * by scaleOrLength. If these conditions are not true the driver will generate a
0916 * <code>SQLException</code> when the prepared statement is executed.
0917 *
0918 * <p>The given Java object will be converted to the given targetSqlType
0919 * before being sent to the database.
0920 *
0921 * If the object has a custom mapping (is of a class implementing the
0922 * interface <code>SQLData</code>),
0923 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to
0924 * write it to the SQL data stream.
0925 * If, on the other hand, the object is of a class implementing
0926 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
0927 * <code>Struct</code>, <code>java.net.URL</code>,
0928 * or <code>Array</code>, the driver should pass it to the database as a
0929 * value of the corresponding SQL type.
0930 *
0931 * <p>Note that this method may be used to pass database-specific
0932 * abstract data types.
0933 *
0934 * @param parameterIndex the first parameter is 1, the second is 2, ...
0935 * @param x the object containing the input parameter value
0936 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
0937 * sent to the database. The scale argument may further qualify this type.
0938 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code>
0939 * or <code>java.sql.Types.NUMERIC types</code>,
0940 * this is the number of digits after the decimal point. For
0941 * Java Object types <code>InputStream</code> and <code>Reader</code>,
0942 * this is the length
0943 * of the data in the stream or reader. For all other types,
0944 * this value will be ignored.
0945 * @exception SQLException if parameterIndex does not correspond to a parameter
0946 * marker in the SQL statement; if a database access error occurs;
0947 * this method is called on a closed <code>PreparedStatement</code> or
0948 * if the Java Object specified by x is an InputStream
0949 * or Reader object and the value of the scale parameter is less
0950 * than zero
0951 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
0952 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
0953 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
0954 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
0955 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
0956 * or <code>STRUCT</code> data type and the JDBC driver does not support
0957 * this data type
0958 * @see Types
0959 *
0960 * @since 1.6
0961 */
0962 void setObject(int parameterIndex, Object x, int targetSqlType,
0963 int scaleOrLength) throws SQLException;
0964
0965 /**
0966 * Sets the designated parameter to the given input stream, which will have
0967 * the specified number of bytes.
0968 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
0969 * parameter, it may be more practical to send it via a
0970 * <code>java.io.InputStream</code>. Data will be read from the stream
0971 * as needed until end-of-file is reached. The JDBC driver will
0972 * do any necessary conversion from ASCII to the database char format.
0973 *
0974 * <P><B>Note:</B> This stream object can either be a standard
0975 * Java stream object or your own subclass that implements the
0976 * standard interface.
0977 *
0978 * @param parameterIndex the first parameter is 1, the second is 2, ...
0979 * @param x the Java input stream that contains the ASCII parameter value
0980 * @param length the number of bytes in the stream
0981 * @exception SQLException if parameterIndex does not correspond to a parameter
0982 * marker in the SQL statement; if a database access error occurs or
0983 * this method is called on a closed <code>PreparedStatement</code>
0984 * @since 1.6
0985 */
0986 void setAsciiStream(int parameterIndex, java.io.InputStream x,
0987 long length) throws SQLException;
0988
0989 /**
0990 * Sets the designated parameter to the given input stream, which will have
0991 * the specified number of bytes.
0992 * When a very large binary value is input to a <code>LONGVARBINARY</code>
0993 * parameter, it may be more practical to send it via a
0994 * <code>java.io.InputStream</code> object. The data will be read from the
0995 * stream as needed until end-of-file is reached.
0996 *
0997 * <P><B>Note:</B> This stream object can either be a standard
0998 * Java stream object or your own subclass that implements the
0999 * standard interface.
1000 *
1001 * @param parameterIndex the first parameter is 1, the second is 2, ...
1002 * @param x the java input stream which contains the binary parameter value
1003 * @param length the number of bytes in the stream
1004 * @exception SQLException if parameterIndex does not correspond to a parameter
1005 * marker in the SQL statement; if a database access error occurs or
1006 * this method is called on a closed <code>PreparedStatement</code>
1007 * @since 1.6
1008 */
1009 void setBinaryStream(int parameterIndex, java.io.InputStream x,
1010 long length) throws SQLException;
1011
1012 /**
1013 * Sets the designated parameter to the given <code>Reader</code>
1014 * object, which is the given number of characters long.
1015 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1016 * parameter, it may be more practical to send it via a
1017 * <code>java.io.Reader</code> object. The data will be read from the stream
1018 * as needed until end-of-file is reached. The JDBC driver will
1019 * do any necessary conversion from UNICODE to the database char format.
1020 *
1021 * <P><B>Note:</B> This stream object can either be a standard
1022 * Java stream object or your own subclass that implements the
1023 * standard interface.
1024 *
1025 * @param parameterIndex the first parameter is 1, the second is 2, ...
1026 * @param reader the <code>java.io.Reader</code> object that contains the
1027 * Unicode data
1028 * @param length the number of characters in the stream
1029 * @exception SQLException if parameterIndex does not correspond to a parameter
1030 * marker in the SQL statement; if a database access error occurs or
1031 * this method is called on a closed <code>PreparedStatement</code>
1032 * @since 1.6
1033 */
1034 void setCharacterStream(int parameterIndex, java.io.Reader reader,
1035 long length) throws SQLException;
1036
1037 //-----
1038 /**
1039 * Sets the designated parameter to the given input stream.
1040 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1041 * parameter, it may be more practical to send it via a
1042 * <code>java.io.InputStream</code>. Data will be read from the stream
1043 * as needed until end-of-file is reached. The JDBC driver will
1044 * do any necessary conversion from ASCII to the database char format.
1045 *
1046 * <P><B>Note:</B> This stream object can either be a standard
1047 * Java stream object or your own subclass that implements the
1048 * standard interface.
1049 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1050 * it might be more efficient to use a version of
1051 * <code>setAsciiStream</code> which takes a length parameter.
1052 *
1053 * @param parameterIndex the first parameter is 1, the second is 2, ...
1054 * @param x the Java input stream that contains the ASCII parameter value
1055 * @exception SQLException if parameterIndex does not correspond to a parameter
1056 * marker in the SQL statement; if a database access error occurs or
1057 * this method is called on a closed <code>PreparedStatement</code>
1058 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1059 * @since 1.6
1060 */
1061 void setAsciiStream(int parameterIndex, java.io.InputStream x)
1062 throws SQLException;
1063
1064 /**
1065 * Sets the designated parameter to the given input stream.
1066 * When a very large binary value is input to a <code>LONGVARBINARY</code>
1067 * parameter, it may be more practical to send it via a
1068 * <code>java.io.InputStream</code> object. The data will be read from the
1069 * stream as needed until end-of-file is reached.
1070 *
1071 * <P><B>Note:</B> This stream object can either be a standard
1072 * Java stream object or your own subclass that implements the
1073 * standard interface.
1074 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1075 * it might be more efficient to use a version of
1076 * <code>setBinaryStream</code> which takes a length parameter.
1077 *
1078 * @param parameterIndex the first parameter is 1, the second is 2, ...
1079 * @param x the java input stream which contains the binary parameter value
1080 * @exception SQLException if parameterIndex does not correspond to a parameter
1081 * marker in the SQL statement; if a database access error occurs or
1082 * this method is called on a closed <code>PreparedStatement</code>
1083 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1084 * @since 1.6
1085 */
1086 void setBinaryStream(int parameterIndex, java.io.InputStream x)
1087 throws SQLException;
1088
1089 /**
1090 * Sets the designated parameter to the given <code>Reader</code>
1091 * object.
1092 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1093 * parameter, it may be more practical to send it via a
1094 * <code>java.io.Reader</code> object. The data will be read from the stream
1095 * as needed until end-of-file is reached. The JDBC driver will
1096 * do any necessary conversion from UNICODE to the database char format.
1097 *
1098 * <P><B>Note:</B> This stream object can either be a standard
1099 * Java stream object or your own subclass that implements the
1100 * standard interface.
1101 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1102 * it might be more efficient to use a version of
1103 * <code>setCharacterStream</code> which takes a length parameter.
1104 *
1105 * @param parameterIndex the first parameter is 1, the second is 2, ...
1106 * @param reader the <code>java.io.Reader</code> object that contains the
1107 * Unicode data
1108 * @exception SQLException if parameterIndex does not correspond to a parameter
1109 * marker in the SQL statement; if a database access error occurs or
1110 * this method is called on a closed <code>PreparedStatement</code>
1111 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1112 * @since 1.6
1113 */
1114 void setCharacterStream(int parameterIndex, java.io.Reader reader)
1115 throws SQLException;
1116
1117 /**
1118 * Sets the designated parameter to a <code>Reader</code> object. The
1119 * <code>Reader</code> reads the data till end-of-file is reached. The
1120 * driver does the necessary conversion from Java character format to
1121 * the national character set in the database.
1122
1123 * <P><B>Note:</B> This stream object can either be a standard
1124 * Java stream object or your own subclass that implements the
1125 * standard interface.
1126 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1127 * it might be more efficient to use a version of
1128 * <code>setNCharacterStream</code> which takes a length parameter.
1129 *
1130 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1131 * @param value the parameter value
1132 * @throws SQLException if parameterIndex does not correspond to a parameter
1133 * marker in the SQL statement; if the driver does not support national
1134 * character sets; if the driver can detect that a data conversion
1135 * error could occur; if a database access error occurs; or
1136 * this method is called on a closed <code>PreparedStatement</code>
1137 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1138 * @since 1.6
1139 */
1140 void setNCharacterStream(int parameterIndex, Reader value)
1141 throws SQLException;
1142
1143 /**
1144 * Sets the designated parameter to a <code>Reader</code> object.
1145 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1146 * because it informs the driver that the parameter value should be sent to
1147 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1148 * driver may have to do extra work to determine whether the parameter
1149 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1150 *
1151 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1152 * it might be more efficient to use a version of
1153 * <code>setClob</code> which takes a length parameter.
1154 *
1155 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1156 * @param reader An object that contains the data to set the parameter value to.
1157 * @throws SQLException if parameterIndex does not correspond to a parameter
1158 * marker in the SQL statement; if a database access error occurs; this method is called on
1159 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter
1160 * marker in the SQL statement
1161 *
1162 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1163 * @since 1.6
1164 */
1165 void setClob(int parameterIndex, Reader reader) throws SQLException;
1166
1167 /**
1168 * Sets the designated parameter to a <code>InputStream</code> object.
1169 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1170 * method because it informs the driver that the parameter value should be
1171 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1172 * the driver may have to do extra work to determine whether the parameter
1173 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1174 *
1175 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1176 * it might be more efficient to use a version of
1177 * <code>setBlob</code> which takes a length parameter.
1178 *
1179 * @param parameterIndex index of the first parameter is 1,
1180 * the second is 2, ...
1181 * @param inputStream An object that contains the data to set the parameter
1182 * value to.
1183 * @throws SQLException if parameterIndex does not correspond to a parameter
1184 * marker in the SQL statement; if a database access error occurs;
1185 * this method is called on a closed <code>PreparedStatement</code> or
1186 * if parameterIndex does not correspond
1187 * to a parameter marker in the SQL statement,
1188 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1189 *
1190 * @since 1.6
1191 */
1192 void setBlob(int parameterIndex, InputStream inputStream)
1193 throws SQLException;
1194
1195 /**
1196 * Sets the designated parameter to a <code>Reader</code> object.
1197 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1198 * because it informs the driver that the parameter value should be sent to
1199 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
1200 * driver may have to do extra work to determine whether the parameter
1201 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
1202 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1203 * it might be more efficient to use a version of
1204 * <code>setNClob</code> which takes a length parameter.
1205 *
1206 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1207 * @param reader An object that contains the data to set the parameter value to.
1208 * @throws SQLException if parameterIndex does not correspond to a parameter
1209 * marker in the SQL statement;
1210 * if the driver does not support national character sets;
1211 * if the driver can detect that a data conversion
1212 * error could occur; if a database access error occurs or
1213 * this method is called on a closed <code>PreparedStatement</code>
1214 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1215 *
1216 * @since 1.6
1217 */
1218 void setNClob(int parameterIndex, Reader reader)
1219 throws SQLException;
1220
1221 }
|