0001 /*
0002 * Copyright 2000-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 javax.sql;
0027
0028 import java.sql.*;
0029 import java.io.*;
0030 import java.math.*;
0031 import java.util.*;
0032
0033 /**
0034 * The interface that adds support to the JDBC API for the
0035 * JavaBeans<sup><font size=-2>TM</font></sup> component model.
0036 * A rowset, which can be used as a JavaBeans component in
0037 * a visual Bean development environment, can be created and
0038 * configured at design time and executed at run time.
0039 * <P>
0040 * The <code>RowSet</code>
0041 * interface provides a set of JavaBeans properties that allow a <code>RowSet</code>
0042 * instance to be configured to connect to a JDBC data source and read
0043 * some data from the data source. A group of setter methods (<code>setInt</code>,
0044 * <code>setBytes</code>, <code>setString</code>, and so on)
0045 * provide a way to pass input parameters to a rowset's command property.
0046 * This command is the SQL query the rowset uses when it gets its data from
0047 * a relational database, which is generally the case.
0048 * <P>
0049 * The <code>RowSet</code>
0050 * interface supports JavaBeans events, allowing other components in an
0051 * application to be notified when an event occurs on a rowset,
0052 * such as a change in its value.
0053 *
0054 * <P>The <code>RowSet</code> interface is unique in that it is intended to be
0055 * implemented using the rest of the JDBC API. In other words, a
0056 * <code>RowSet</code> implementation is a layer of software that executes "on top"
0057 * of a JDBC driver. Implementations of the <code>RowSet</code> interface can
0058 * be provided by anyone, including JDBC driver vendors who want to
0059 * provide a <code>RowSet</code> implementation as part of their JDBC products.
0060 * <P>
0061 * A <code>RowSet</code> object may make a connection with a data source and
0062 * maintain that connection throughout its life cycle, in which case it is
0063 * called a <i>connected</i> rowset. A rowset may also make a connection with
0064 * a data source, get data from it, and then close the connection. Such a rowset
0065 * is called a <i>disconnected</i> rowset. A disconnected rowset may make
0066 * changes to its data while it is disconnected and then send the changes back
0067 * to the original source of the data, but it must reestablish a connection to do so.
0068 * <P>
0069 * A disconnected rowset may have a reader (a <code>RowSetReader</code> object)
0070 * and a writer (a <code>RowSetWriter</code> object) associated with it.
0071 * The reader may be implemented in many different ways to populate a rowset
0072 * with data, including getting data from a non-relational data source. The
0073 * writer can also be implemented in many different ways to propagate changes
0074 * made to the rowset's data back to the underlying data source.
0075 * <P>
0076 * Rowsets are easy to use. The <code>RowSet</code> interface extends the standard
0077 * <code>java.sql.ResultSet</code> interface. The <code>RowSetMetaData</code>
0078 * interface extends the <code>java.sql.ResultSetMetaData</code> interface.
0079 * Thus, developers familiar
0080 * with the JDBC API will have to learn a minimal number of new APIs to
0081 * use rowsets. In addition, third-party software tools that work with
0082 * JDBC <code>ResultSet</code> objects will also easily be made to work with rowsets.
0083 *
0084 * @since 1.4
0085 */
0086
0087 public interface RowSet extends ResultSet {
0088
0089 //-----------------------------------------------------------------------
0090 // Properties
0091 //-----------------------------------------------------------------------
0092
0093 //-----------------------------------------------------------------------
0094 // The following properties may be used to create a Connection.
0095 //-----------------------------------------------------------------------
0096
0097 /**
0098 * Retrieves the url property this <code>RowSet</code> object will use to
0099 * create a connection if it uses the <code>DriverManager</code>
0100 * instead of a <code>DataSource</code> object to establish the connection.
0101 * The default value is <code>null</code>.
0102 *
0103 * @return a string url
0104 * @exception SQLException if a database access error occurs
0105 * @see #setUrl
0106 */
0107 String getUrl() throws SQLException;
0108
0109 /**
0110 * Sets the URL this <code>RowSet</code> object will use when it uses the
0111 * <code>DriverManager</code> to create a connection.
0112 *
0113 * Setting this property is optional. If a URL is used, a JDBC driver
0114 * that accepts the URL must be loaded before the
0115 * rowset is used to connect to a database. The rowset will use the URL
0116 * internally to create a database connection when reading or writing
0117 * data. Either a URL or a data source name is used to create a
0118 * connection, whichever was set to non null value most recently.
0119 *
0120 * @param url a string value; may be <code>null</code>
0121 * @exception SQLException if a database access error occurs
0122 * @see #getUrl
0123 */
0124 void setUrl(String url) throws SQLException;
0125
0126 /**
0127 * Retrieves the logical name that identifies the data source for this
0128 * <code>RowSet</code> object.
0129 *
0130 * @return a data source name
0131 * @see #setDataSourceName
0132 * @see #setUrl
0133 */
0134 String getDataSourceName();
0135
0136 /**
0137 * Sets the data source name property for this <code>RowSet</code> object to the
0138 * given <code>String</code>.
0139 * <P>
0140 * The value of the data source name property can be used to do a lookup of
0141 * a <code>DataSource</code> object that has been registered with a naming
0142 * service. After being retrieved, the <code>DataSource</code> object can be
0143 * used to create a connection to the data source that it represents.
0144 *
0145 * @param name the logical name of the data source for this <code>RowSet</code>
0146 * object; may be <code>null</code>
0147 * @exception SQLException if a database access error occurs
0148 * @see #getDataSourceName
0149 */
0150 void setDataSourceName(String name) throws SQLException;
0151
0152 /**
0153 * Retrieves the username used to create a database connection for this
0154 * <code>RowSet</code> object.
0155 * The username property is set at run time before calling the method
0156 * <code>execute</code>. It is
0157 * not usually part of the serialized state of a <code>RowSet</code> object.
0158 *
0159 * @return the username property
0160 * @see #setUsername
0161 */
0162 String getUsername();
0163
0164 /**
0165 * Sets the username property for this <code>RowSet</code> object to the
0166 * given <code>String</code>.
0167 *
0168 * @param name a user name
0169 * @exception SQLException if a database access error occurs
0170 * @see #getUsername
0171 */
0172 void setUsername(String name) throws SQLException;
0173
0174 /**
0175 * Retrieves the password used to create a database connection.
0176 * The password property is set at run time before calling the method
0177 * <code>execute</code>. It is not usually part of the serialized state
0178 * of a <code>RowSet</code> object.
0179 *
0180 * @return the password for making a database connection
0181 * @see #setPassword
0182 */
0183 String getPassword();
0184
0185 /**
0186 * Sets the database password for this <code>RowSet</code> object to
0187 * the given <code>String</code>.
0188 *
0189 * @param password the password string
0190 * @exception SQLException if a database access error occurs
0191 * @see #getPassword
0192 */
0193 void setPassword(String password) throws SQLException;
0194
0195 /**
0196 * Retrieves the transaction isolation level set for this
0197 * <code>RowSet</code> object.
0198 *
0199 * @return the transaction isolation level; one of
0200 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
0201 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
0202 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
0203 * <code>Connection.TRANSACTION_SERIALIZABLE</code>
0204 * @see #setTransactionIsolation
0205 */
0206 int getTransactionIsolation();
0207
0208 /**
0209 * Sets the transaction isolation level for this <code>RowSet</code> obejct.
0210 *
0211 * @param level the transaction isolation level; one of
0212 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>,
0213 * <code>Connection.TRANSACTION_READ_COMMITTED</code>,
0214 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or
0215 * <code>Connection.TRANSACTION_SERIALIZABLE</code>
0216 * @exception SQLException if a database access error occurs
0217 * @see #getTransactionIsolation
0218 */
0219 void setTransactionIsolation(int level) throws SQLException;
0220
0221 /**
0222 * Retrieves the <code>Map</code> object associated with this
0223 * <code>RowSet</code> object, which specifies the custom mapping
0224 * of SQL user-defined types, if any. The default is for the
0225 * type map to be empty.
0226 *
0227 * @return a <code>java.util.Map</code> object containing the names of
0228 * SQL user-defined types and the Java classes to which they are
0229 * to be mapped
0230 *
0231 * @exception SQLException if a database access error occurs
0232 * @see #setTypeMap
0233 */
0234 java.util.Map<String, Class<?>> getTypeMap() throws SQLException;
0235
0236 /**
0237 * Installs the given <code>java.util.Map</code> object as the default
0238 * type map for this <code>RowSet</code> object. This type map will be
0239 * used unless another type map is supplied as a method parameter.
0240 *
0241 * @param map a <code>java.util.Map</code> object containing the names of
0242 * SQL user-defined types and the Java classes to which they are
0243 * to be mapped
0244 * @exception SQLException if a database access error occurs
0245 * @see #getTypeMap
0246 */
0247 void setTypeMap(java.util.Map<String, Class<?>> map)
0248 throws SQLException;
0249
0250 //-----------------------------------------------------------------------
0251 // The following properties may be used to create a Statement.
0252 //-----------------------------------------------------------------------
0253
0254 /**
0255 * Retrieves this <code>RowSet</code> object's command property.
0256 *
0257 * The command property contains a command string, which must be an SQL
0258 * query, that can be executed to fill the rowset with data.
0259 * The default value is <code>null</code>.
0260 *
0261 * @return the command string; may be <code>null</code>
0262 * @see #setCommand
0263 */
0264 String getCommand();
0265
0266 /**
0267 * Sets this <code>RowSet</code> object's command property to the given
0268 * SQL query.
0269 *
0270 * This property is optional
0271 * when a rowset gets its data from a data source that does not support
0272 * commands, such as a spreadsheet.
0273 *
0274 * @param cmd the SQL query that will be used to get the data for this
0275 * <code>RowSet</code> object; may be <code>null</code>
0276 * @exception SQLException if a database access error occurs
0277 * @see #getCommand
0278 */
0279 void setCommand(String cmd) throws SQLException;
0280
0281 /**
0282 * Retrieves whether this <code>RowSet</code> object is read-only.
0283 * If updates are possible, the default is for a rowset to be
0284 * updatable.
0285 * <P>
0286 * Attempts to update a read-only rowset will result in an
0287 * <code>SQLException</code> being thrown.
0288 *
0289 * @return <code>true</code> if this <code>RowSet</code> object is
0290 * read-only; <code>false</code> if it is updatable
0291 * @see #setReadOnly
0292 */
0293 boolean isReadOnly();
0294
0295 /**
0296 * Sets whether this <code>RowSet</code> object is read-only to the
0297 * given <code>boolean</code>.
0298 *
0299 * @param value <code>true</code> if read-only; <code>false</code> if
0300 * updatable
0301 * @exception SQLException if a database access error occurs
0302 * @see #isReadOnly
0303 */
0304 void setReadOnly(boolean value) throws SQLException;
0305
0306 /**
0307 * Retrieves the maximum number of bytes that may be returned
0308 * for certain column values.
0309 * This limit applies only to <code>BINARY</code>,
0310 * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
0311 * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>
0312 * and <code>NVARCHAR</code> columns.
0313 * If the limit is exceeded, the excess data is silently discarded.
0314 *
0315 * @return the current maximum column size limit; zero means that there
0316 * is no limit
0317 * @exception SQLException if a database access error occurs
0318 * @see #setMaxFieldSize
0319 */
0320 int getMaxFieldSize() throws SQLException;
0321
0322 /**
0323 * Sets the maximum number of bytes that can be returned for a column
0324 * value to the given number of bytes.
0325 * This limit applies only to <code>BINARY</code>,
0326 * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>,
0327 * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code>
0328 * and <code>NVARCHAR</code> columns.
0329 * If the limit is exceeded, the excess data is silently discarded.
0330 * For maximum portability, use values greater than 256.
0331 *
0332 * @param max the new max column size limit in bytes; zero means unlimited
0333 * @exception SQLException if a database access error occurs
0334 * @see #getMaxFieldSize
0335 */
0336 void setMaxFieldSize(int max) throws SQLException;
0337
0338 /**
0339 * Retrieves the maximum number of rows that this <code>RowSet</code>
0340 * object can contain.
0341 * If the limit is exceeded, the excess rows are silently dropped.
0342 *
0343 * @return the current maximum number of rows that this <code>RowSet</code>
0344 * object can contain; zero means unlimited
0345 * @exception SQLException if a database access error occurs
0346 * @see #setMaxRows
0347 */
0348 int getMaxRows() throws SQLException;
0349
0350 /**
0351 * Sets the maximum number of rows that this <code>RowSet</code>
0352 * object can contain to the specified number.
0353 * If the limit is exceeded, the excess rows are silently dropped.
0354 *
0355 * @param max the new maximum number of rows; zero means unlimited
0356 * @exception SQLException if a database access error occurs
0357 * @see #getMaxRows
0358 */
0359 void setMaxRows(int max) throws SQLException;
0360
0361 /**
0362 * Retrieves whether escape processing is enabled for this
0363 * <code>RowSet</code> object.
0364 * If escape scanning is enabled, which is the default, the driver will do
0365 * escape substitution before sending an SQL statement to the database.
0366 *
0367 * @return <code>true</code> if escape processing is enabled;
0368 * <code>false</code> if it is disabled
0369 * @exception SQLException if a database access error occurs
0370 * @see #setEscapeProcessing
0371 */
0372 boolean getEscapeProcessing() throws SQLException;
0373
0374 /**
0375 * Sets escape processing for this <code>RowSet</code> object on or
0376 * off. If escape scanning is on (the default), the driver will do
0377 * escape substitution before sending an SQL statement to the database.
0378 *
0379 * @param enable <code>true</code> to enable escape processing;
0380 * <code>false</code> to disable it
0381 * @exception SQLException if a database access error occurs
0382 * @see #getEscapeProcessing
0383 */
0384 void setEscapeProcessing(boolean enable) throws SQLException;
0385
0386 /**
0387 * Retrieves the maximum number of seconds the driver will wait for
0388 * a statement to execute.
0389 * If this limit is exceeded, an <code>SQLException</code> is thrown.
0390 *
0391 * @return the current query timeout limit in seconds; zero means
0392 * unlimited
0393 * @exception SQLException if a database access error occurs
0394 * @see #setQueryTimeout
0395 */
0396 int getQueryTimeout() throws SQLException;
0397
0398 /**
0399 * Sets the maximum time the driver will wait for
0400 * a statement to execute to the given number of seconds.
0401 * If this limit is exceeded, an <code>SQLException</code> is thrown.
0402 *
0403 * @param seconds the new query timeout limit in seconds; zero means
0404 * that there is no limit
0405 * @exception SQLException if a database access error occurs
0406 * @see #getQueryTimeout
0407 */
0408 void setQueryTimeout(int seconds) throws SQLException;
0409
0410 /**
0411 * Sets the type of this <code>RowSet</code> object to the given type.
0412 * This method is used to change the type of a rowset, which is by
0413 * default read-only and non-scrollable.
0414 *
0415 * @param type one of the <code>ResultSet</code> constants specifying a type:
0416 * <code>ResultSet.TYPE_FORWARD_ONLY</code>,
0417 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
0418 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
0419 * @exception SQLException if a database access error occurs
0420 * @see java.sql.ResultSet#getType
0421 */
0422 void setType(int type) throws SQLException;
0423
0424 /**
0425 * Sets the concurrency of this <code>RowSet</code> object to the given
0426 * concurrency level. This method is used to change the concurrency level
0427 * of a rowset, which is by default <code>ResultSet.CONCUR_READ_ONLY</code>
0428 *
0429 * @param concurrency one of the <code>ResultSet</code> constants specifying a
0430 * concurrency level: <code>ResultSet.CONCUR_READ_ONLY</code> or
0431 * <code>ResultSet.CONCUR_UPDATABLE</code>
0432 * @exception SQLException if a database access error occurs
0433 * @see ResultSet#getConcurrency
0434 */
0435 void setConcurrency(int concurrency) throws SQLException;
0436
0437 //-----------------------------------------------------------------------
0438 // Parameters
0439 //-----------------------------------------------------------------------
0440
0441 /**
0442 * The <code>RowSet</code> setter methods are used to set any input parameters
0443 * needed by the <code>RowSet</code> object's command.
0444 * Parameters are set at run time, as opposed to design time.
0445 */
0446
0447 /**
0448 * Sets the designated parameter in this <code>RowSet</code> object's SQL
0449 * command to SQL <code>NULL</code>.
0450 *
0451 * <P><B>Note:</B> You must specify the parameter's SQL type.
0452 *
0453 * @param parameterIndex the first parameter is 1, the second is 2, ...
0454 * @param sqlType a SQL type code defined by <code>java.sql.Types</code>
0455 * @exception SQLException if a database access error occurs
0456 */
0457 void setNull(int parameterIndex, int sqlType) throws SQLException;
0458
0459 /**
0460 * Sets the designated parameter to SQL <code>NULL</code>.
0461 *
0462 * <P><B>Note:</B> You must specify the parameter's SQL type.
0463 *
0464 * @param parameterName the name of the parameter
0465 * @param sqlType the SQL type code defined in <code>java.sql.Types</code>
0466 * @exception SQLException if a database access error occurs or
0467 * this method is called on a closed <code>CallableStatement</code>
0468 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0469 * this method
0470 * @since 1.4
0471 */
0472 void setNull(String parameterName, int sqlType) throws SQLException;
0473
0474 /**
0475 * Sets the designated parameter in this <code>RowSet</code> object's SQL
0476 * command to SQL <code>NULL</code>. This version of the method <code>setNull</code>
0477 * should be used for SQL user-defined types (UDTs) and <code>REF</code> type
0478 * parameters. Examples of UDTs include: <code>STRUCT</code>, <code>DISTINCT</code>,
0479 * <code>JAVA_OBJECT</code>, and named array types.
0480 *
0481 * <P><B>Note:</B> To be portable, applications must give the
0482 * SQL type code and the fully qualified SQL type name when specifying
0483 * a NULL UDT or <code>REF</code> parameter. In the case of a UDT,
0484 * the name is the type name of the parameter itself. For a <code>REF</code>
0485 * parameter, the name is the type name of the referenced type. If
0486 * a JDBC driver does not need the type code or type name information,
0487 * it may ignore it.
0488 *
0489 * Although it is intended for UDT and <code>REF</code> parameters,
0490 * this method may be used to set a null parameter of any JDBC type.
0491 * If the parameter does not have a user-defined or <code>REF</code> type,
0492 * the typeName parameter is ignored.
0493 *
0494 *
0495 * @param paramIndex the first parameter is 1, the second is 2, ...
0496 * @param sqlType a value from <code>java.sql.Types</code>
0497 * @param typeName the fully qualified name of an SQL UDT or the type
0498 * name of the SQL structured type being referenced by a <code>REF</code>
0499 * type; ignored if the parameter is not a UDT or <code>REF</code> type
0500 * @exception SQLException if a database access error occurs
0501 */
0502 void setNull(int paramIndex, int sqlType, String typeName)
0503 throws SQLException;
0504
0505 /**
0506 * Sets the designated parameter to SQL <code>NULL</code>.
0507 * This version of the method <code>setNull</code> should
0508 * be used for user-defined types and REF type parameters. Examples
0509 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and
0510 * named array types.
0511 *
0512 * <P><B>Note:</B> To be portable, applications must give the
0513 * SQL type code and the fully-qualified SQL type name when specifying
0514 * a NULL user-defined or REF parameter. In the case of a user-defined type
0515 * the name is the type name of the parameter itself. For a REF
0516 * parameter, the name is the type name of the referenced type. If
0517 * a JDBC driver does not need the type code or type name information,
0518 * it may ignore it.
0519 *
0520 * Although it is intended for user-defined and Ref parameters,
0521 * this method may be used to set a null parameter of any JDBC type.
0522 * If the parameter does not have a user-defined or REF type, the given
0523 * typeName is ignored.
0524 *
0525 *
0526 * @param parameterName the name of the parameter
0527 * @param sqlType a value from <code>java.sql.Types</code>
0528 * @param typeName the fully-qualified name of an SQL user-defined type;
0529 * ignored if the parameter is not a user-defined type or
0530 * SQL <code>REF</code> value
0531 * @exception SQLException if a database access error occurs or
0532 * this method is called on a closed <code>CallableStatement</code>
0533 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0534 * this method
0535 * @since 1.4
0536 */
0537 void setNull(String parameterName, int sqlType, String typeName)
0538 throws SQLException;
0539
0540 /**
0541 * Sets the designated parameter in this <code>RowSet</code> object's command
0542 * to the given Java <code>boolean</code> value. The driver converts this to
0543 * an SQL <code>BIT</code> value before sending it to the database.
0544 *
0545 * @param parameterIndex the first parameter is 1, the second is 2, ...
0546 * @param x the parameter value
0547 * @exception SQLException if a database access error occurs
0548 */
0549 void setBoolean(int parameterIndex, boolean x) throws SQLException;
0550
0551 /**
0552 * Sets the designated parameter to the given Java <code>boolean</code> value.
0553 * The driver converts this
0554 * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.
0555 *
0556 * @param parameterName the name of the parameter
0557 * @param x the parameter value
0558 * @exception SQLException if a database access error occurs or
0559 * this method is called on a closed <code>CallableStatement</code>
0560 * @see #getBoolean
0561 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0562 * this method
0563 * @since 1.4
0564 */
0565 void setBoolean(String parameterName, boolean x)
0566 throws SQLException;
0567
0568 /**
0569 * Sets the designated parameter in this <code>RowSet</code> object's command
0570 * to the given Java <code>byte</code> value. The driver converts this to
0571 * an SQL <code>TINYINT</code> value before sending it to the database.
0572 *
0573 * @param parameterIndex the first parameter is 1, the second is 2, ...
0574 * @param x the parameter value
0575 * @exception SQLException if a database access error occurs
0576 */
0577 void setByte(int parameterIndex, byte x) throws SQLException;
0578
0579 /**
0580 * Sets the designated parameter to the given Java <code>byte</code> value.
0581 * The driver converts this
0582 * to an SQL <code>TINYINT</code> value when it sends it to the database.
0583 *
0584 * @param parameterName the name of the parameter
0585 * @param x the parameter value
0586 * @exception SQLException if a database access error occurs or
0587 * this method is called on a closed <code>CallableStatement</code>
0588 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0589 * this method
0590 * @see #getByte
0591 * @since 1.4
0592 */
0593 void setByte(String parameterName, byte x) throws SQLException;
0594
0595 /**
0596 * Sets the designated parameter in this <code>RowSet</code> object's command
0597 * to the given Java <code>short</code> value. The driver converts this to
0598 * an SQL <code>SMALLINT</code> value before sending it to the database.
0599 *
0600 * @param parameterIndex the first parameter is 1, the second is 2, ...
0601 * @param x the parameter value
0602 * @exception SQLException if a database access error occurs
0603 */
0604 void setShort(int parameterIndex, short x) throws SQLException;
0605
0606 /**
0607 * Sets the designated parameter to the given Java <code>short</code> value.
0608 * The driver converts this
0609 * to an SQL <code>SMALLINT</code> value when it sends it to the database.
0610 *
0611 * @param parameterName the name of the parameter
0612 * @param x the parameter value
0613 * @exception SQLException if a database access error occurs or
0614 * this method is called on a closed <code>CallableStatement</code>
0615 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0616 * this method
0617 * @see #getShort
0618 * @since 1.4
0619 */
0620 void setShort(String parameterName, short x) throws SQLException;
0621
0622 /**
0623 * Sets the designated parameter in this <code>RowSet</code> object's command
0624 * to the given Java <code>int</code> value. The driver converts this to
0625 * an SQL <code>INTEGER</code> value before sending it to the database.
0626 *
0627 * @param parameterIndex the first parameter is 1, the second is 2, ...
0628 * @param x the parameter value
0629 * @exception SQLException if a database access error occurs
0630 */
0631 void setInt(int parameterIndex, int x) throws SQLException;
0632
0633 /**
0634 * Sets the designated parameter to the given Java <code>int</code> value.
0635 * The driver converts this
0636 * to an SQL <code>INTEGER</code> value when it sends it to the database.
0637 *
0638 * @param parameterName the name of the parameter
0639 * @param x the parameter value
0640 * @exception SQLException if a database access error occurs or
0641 * this method is called on a closed <code>CallableStatement</code>
0642 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0643 * this method
0644 * @see #getInt
0645 * @since 1.4
0646 */
0647 void setInt(String parameterName, int x) throws SQLException;
0648
0649 /**
0650 * Sets the designated parameter in this <code>RowSet</code> object's command
0651 * to the given Java <code>long</code> value. The driver converts this to
0652 * an SQL <code>BIGINT</code> value before sending it to the database.
0653 *
0654 * @param parameterIndex the first parameter is 1, the second is 2, ...
0655 * @param x the parameter value
0656 * @exception SQLException if a database access error occurs
0657 */
0658 void setLong(int parameterIndex, long x) throws SQLException;
0659
0660 /**
0661 * Sets the designated parameter to the given Java <code>long</code> value.
0662 * The driver converts this
0663 * to an SQL <code>BIGINT</code> value when it sends it to the database.
0664 *
0665 * @param parameterName the name of the parameter
0666 * @param x the parameter value
0667 * @exception SQLException if a database access error occurs or
0668 * this method is called on a closed <code>CallableStatement</code>
0669 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0670 * this method
0671 * @see #getLong
0672 * @since 1.4
0673 */
0674 void setLong(String parameterName, long x) throws SQLException;
0675
0676 /**
0677 * Sets the designated parameter in this <code>RowSet</code> object's command
0678 * to the given Java <code>float</code> value. The driver converts this to
0679 * an SQL <code>REAL</code> value before sending it to the database.
0680 *
0681 * @param parameterIndex the first parameter is 1, the second is 2, ...
0682 * @param x the parameter value
0683 * @exception SQLException if a database access error occurs
0684 */
0685 void setFloat(int parameterIndex, float x) throws SQLException;
0686
0687 /**
0688 * Sets the designated parameter to the given Java <code>float</code> value.
0689 * The driver converts this
0690 * to an SQL <code>FLOAT</code> value when it sends it to the database.
0691 *
0692 * @param parameterName the name of the parameter
0693 * @param x the parameter value
0694 * @exception SQLException if a database access error occurs or
0695 * this method is called on a closed <code>CallableStatement</code>
0696 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0697 * this method
0698 * @see #getFloat
0699 * @since 1.4
0700 */
0701 void setFloat(String parameterName, float x) throws SQLException;
0702
0703 /**
0704 * Sets the designated parameter in this <code>RowSet</code> object's command
0705 * to the given Java <code>double</code> value. The driver converts this to
0706 * an SQL <code>DOUBLE</code> value before sending it to the database.
0707 *
0708 * @param parameterIndex the first parameter is 1, the second is 2, ...
0709 * @param x the parameter value
0710 * @exception SQLException if a database access error occurs
0711 */
0712 void setDouble(int parameterIndex, double x) throws SQLException;
0713
0714 /**
0715 * Sets the designated parameter to the given Java <code>double</code> value.
0716 * The driver converts this
0717 * to an SQL <code>DOUBLE</code> value when it sends it to the database.
0718 *
0719 * @param parameterName the name of the parameter
0720 * @param x the parameter value
0721 * @exception SQLException if a database access error occurs or
0722 * this method is called on a closed <code>CallableStatement</code>
0723 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0724 * this method
0725 * @see #getDouble
0726 * @since 1.4
0727 */
0728 void setDouble(String parameterName, double x) throws SQLException;
0729
0730 /**
0731 * Sets the designated parameter in this <code>RowSet</code> object's command
0732 * to the given <code>java.math.BigDeciaml</code> value.
0733 * The driver converts this to
0734 * an SQL <code>NUMERIC</code> value before sending it to the database.
0735 *
0736 * @param parameterIndex the first parameter is 1, the second is 2, ...
0737 * @param x the parameter value
0738 * @exception SQLException if a database access error occurs
0739 */
0740 void setBigDecimal(int parameterIndex, BigDecimal x)
0741 throws SQLException;
0742
0743 /**
0744 * Sets the designated parameter to the given
0745 * <code>java.math.BigDecimal</code> value.
0746 * The driver converts this to an SQL <code>NUMERIC</code> value when
0747 * it sends it to the database.
0748 *
0749 * @param parameterName the name of the parameter
0750 * @param x the parameter value
0751 * @exception SQLException if a database access error occurs or
0752 * this method is called on a closed <code>CallableStatement</code>
0753 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0754 * this method
0755 * @see #getBigDecimal
0756 * @since 1.4
0757 */
0758 void setBigDecimal(String parameterName, BigDecimal x)
0759 throws SQLException;
0760
0761 /**
0762 * Sets the designated parameter in this <code>RowSet</code> object's command
0763 * to the given Java <code>String</code> value. Before sending it to the
0764 * database, the driver converts this to an SQL <code>VARCHAR</code> or
0765 * <code>LONGVARCHAR</code> value, depending on the argument's size relative
0766 * to the driver's limits on <code>VARCHAR</code> values.
0767 *
0768 * @param parameterIndex the first parameter is 1, the second is 2, ...
0769 * @param x the parameter value
0770 * @exception SQLException if a database access error occurs
0771 */
0772 void setString(int parameterIndex, String x) throws SQLException;
0773
0774 /**
0775 * Sets the designated parameter to the given Java <code>String</code> value.
0776 * The driver converts this
0777 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value
0778 * (depending on the argument's
0779 * size relative to the driver's limits on <code>VARCHAR</code> values)
0780 * when it sends it to the database.
0781 *
0782 * @param parameterName the name of the parameter
0783 * @param x the parameter value
0784 * @exception SQLException if a database access error occurs or
0785 * this method is called on a closed <code>CallableStatement</code>
0786 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0787 * this method
0788 * @see #getString
0789 * @since 1.4
0790 */
0791 void setString(String parameterName, String x) throws SQLException;
0792
0793 /**
0794 * Sets the designated parameter in this <code>RowSet</code> object's command
0795 * to the given Java array of <code>byte</code> values. Before sending it to the
0796 * database, the driver converts this to an SQL <code>VARBINARY</code> or
0797 * <code>LONGVARBINARY</code> value, depending on the argument's size relative
0798 * to the driver's limits on <code>VARBINARY</code> values.
0799 *
0800 * @param parameterIndex the first parameter is 1, the second is 2, ...
0801 * @param x the parameter value
0802 * @exception SQLException if a database access error occurs
0803 */
0804 void setBytes(int parameterIndex, byte x[]) throws SQLException;
0805
0806 /**
0807 * Sets the designated parameter to the given Java array of bytes.
0808 * The driver converts this to an SQL <code>VARBINARY</code> or
0809 * <code>LONGVARBINARY</code> (depending on the argument's size relative
0810 * to the driver's limits on <code>VARBINARY</code> values) when it sends
0811 * it to the database.
0812 *
0813 * @param parameterName the name of the parameter
0814 * @param x the parameter value
0815 * @exception SQLException if a database access error occurs or
0816 * this method is called on a closed <code>CallableStatement</code>
0817 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0818 * this method
0819 * @see #getBytes
0820 * @since 1.4
0821 */
0822 void setBytes(String parameterName, byte x[]) throws SQLException;
0823
0824 /**
0825 * Sets the designated parameter in this <code>RowSet</code> object's command
0826 * to the given <code>java.sql.Date</code> value. The driver converts this to
0827 * an SQL <code>DATE</code> value before sending it to the database, using the
0828 * default <code>java.util.Calendar</code> to calculate the date.
0829 *
0830 * @param parameterIndex the first parameter is 1, the second is 2, ...
0831 * @param x the parameter value
0832 * @exception SQLException if a database access error occurs
0833 */
0834 void setDate(int parameterIndex, java.sql.Date x)
0835 throws SQLException;
0836
0837 /**
0838 * Sets the designated parameter in this <code>RowSet</code> object's command
0839 * to the given <code>java.sql.Time</code> value. The driver converts this to
0840 * an SQL <code>TIME</code> value before sending it to the database, using the
0841 * default <code>java.util.Calendar</code> to calculate it.
0842 *
0843 * @param parameterIndex the first parameter is 1, the second is 2, ...
0844 * @param x the parameter value
0845 * @exception SQLException if a database access error occurs
0846 */
0847 void setTime(int parameterIndex, java.sql.Time x)
0848 throws SQLException;
0849
0850 /**
0851 * Sets the designated parameter in this <code>RowSet</code> object's command
0852 * to the given <code>java.sql.Timestamp</code> value. The driver converts this to
0853 * an SQL <code>TIMESTAMP</code> value before sending it to the database, using the
0854 * default <code>java.util.Calendar</code> to calculate it.
0855 *
0856 * @param parameterIndex the first parameter is 1, the second is 2, ...
0857 * @param x the parameter value
0858 * @exception SQLException if a database access error occurs
0859 */
0860 void setTimestamp(int parameterIndex, java.sql.Timestamp x)
0861 throws SQLException;
0862
0863 /**
0864 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.
0865 * The driver
0866 * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the
0867 * database.
0868 *
0869 * @param parameterName the name of the parameter
0870 * @param x the parameter value
0871 * @exception SQLException 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 #getTimestamp
0876 * @since 1.4
0877 */
0878 void setTimestamp(String parameterName, java.sql.Timestamp x)
0879 throws SQLException;
0880
0881 /**
0882 * Sets the designated parameter in this <code>RowSet</code> object's command
0883 * to the given <code>java.io.InputStream</code> value.
0884 * It may be more practical to send a very large ASCII value via a
0885 * <code>java.io.InputStream</code> rather than as a <code>LONGVARCHAR</code>
0886 * parameter. The driver will read the data from the stream
0887 * as needed until it reaches end-of-file.
0888 *
0889 * <P><B>Note:</B> This stream object can either be a standard
0890 * Java stream object or your own subclass that implements the
0891 * standard interface.
0892 *
0893 * @param parameterIndex the first parameter is 1, the second is 2, ...
0894 * @param x the Java input stream that contains the ASCII parameter value
0895 * @param length the number of bytes in the stream
0896 * @exception SQLException if a database access error occurs
0897 */
0898 void setAsciiStream(int parameterIndex, java.io.InputStream x,
0899 int length) throws SQLException;
0900
0901 /**
0902 * Sets the designated parameter to the given input stream, which will have
0903 * the specified number of bytes.
0904 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
0905 * parameter, it may be more practical to send it via a
0906 * <code>java.io.InputStream</code>. Data will be read from the stream
0907 * as needed until end-of-file is reached. The JDBC driver will
0908 * do any necessary conversion from ASCII to the database char format.
0909 *
0910 * <P><B>Note:</B> This stream object can either be a standard
0911 * Java stream object or your own subclass that implements the
0912 * standard interface.
0913 *
0914 * @param parameterName the name of the parameter
0915 * @param x the Java input stream that contains the ASCII parameter value
0916 * @param length the number of bytes in the stream
0917 * @exception SQLException if a database access error occurs or
0918 * this method is called on a closed <code>CallableStatement</code>
0919 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0920 * this method
0921 * @since 1.4
0922 */
0923 void setAsciiStream(String parameterName, java.io.InputStream x,
0924 int length) throws SQLException;
0925
0926 /**
0927 * Sets the designated parameter in this <code>RowSet</code> object's command
0928 * to the given <code>java.io.InputStream</code> value.
0929 * It may be more practical to send a very large binary value via a
0930 * <code>java.io.InputStream</code> rather than as a <code>LONGVARBINARY</code>
0931 * parameter. The driver will read the data from the stream
0932 * as needed until it reaches end-of-file.
0933 *
0934 * <P><B>Note:</B> This stream object can either be a standard
0935 * Java stream object or your own subclass that implements the
0936 * standard interface.
0937 *
0938 * @param parameterIndex the first parameter is 1, the second is 2, ...
0939 * @param x the java input stream which contains the binary parameter value
0940 * @param length the number of bytes in the stream
0941 * @exception SQLException if a database access error occurs
0942 */
0943 void setBinaryStream(int parameterIndex, java.io.InputStream x,
0944 int length) throws SQLException;
0945
0946 /**
0947 * Sets the designated parameter to the given input stream, which will have
0948 * the specified number of bytes.
0949 * When a very large binary value is input to a <code>LONGVARBINARY</code>
0950 * parameter, it may be more practical to send it via a
0951 * <code>java.io.InputStream</code> object. The data will be read from the stream
0952 * as needed until end-of-file is reached.
0953 *
0954 * <P><B>Note:</B> This stream object can either be a standard
0955 * Java stream object or your own subclass that implements the
0956 * standard interface.
0957 *
0958 * @param parameterName the name of the parameter
0959 * @param x the java input stream which contains the binary parameter value
0960 * @param length the number of bytes in the stream
0961 * @exception SQLException if a database access error occurs or
0962 * this method is called on a closed <code>CallableStatement</code>
0963 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
0964 * this method
0965 * @since 1.4
0966 */
0967 void setBinaryStream(String parameterName, java.io.InputStream x,
0968 int length) throws SQLException;
0969
0970 /**
0971 * Sets the designated parameter in this <code>RowSet</code> object's command
0972 * to the given <code>java.io.Reader</code> value.
0973 * It may be more practical to send a very large UNICODE value via a
0974 * <code>java.io.Reader</code> rather than as a <code>LONGVARCHAR</code>
0975 * parameter. The driver will read the data from the stream
0976 * as needed until it reaches end-of-file.
0977 *
0978 * <P><B>Note:</B> This stream object can either be a standard
0979 * Java stream object or your own subclass that implements the
0980 * standard interface.
0981 *
0982 * @param parameterIndex the first parameter is 1, the second is 2, ...
0983 * @param reader the <code>Reader</code> object that contains the UNICODE data
0984 * to be set
0985 * @param length the number of characters in the stream
0986 * @exception SQLException if a database access error occurs
0987 */
0988 void setCharacterStream(int parameterIndex, Reader reader,
0989 int length) throws SQLException;
0990
0991 /**
0992 * Sets the designated parameter to the given <code>Reader</code>
0993 * object, which is the given number of characters long.
0994 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
0995 * parameter, it may be more practical to send it via a
0996 * <code>java.io.Reader</code> object. The data will be read from the stream
0997 * as needed until end-of-file is reached. The JDBC driver will
0998 * do any necessary conversion from UNICODE to the database char format.
0999 *
1000 * <P><B>Note:</B> This stream object can either be a standard
1001 * Java stream object or your own subclass that implements the
1002 * standard interface.
1003 *
1004 * @param parameterName the name of the parameter
1005 * @param reader the <code>java.io.Reader</code> object that
1006 * contains the UNICODE data used as the designated parameter
1007 * @param length the number of characters in the stream
1008 * @exception SQLException if a database access error occurs or
1009 * this method is called on a closed <code>CallableStatement</code>
1010 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1011 * this method
1012 * @since 1.4
1013 */
1014 void setCharacterStream(String parameterName,
1015 java.io.Reader reader, int length) throws SQLException;
1016
1017 /**
1018 * Sets the designated parameter in this <code>RowSet</code> object's command
1019 * to the given input stream.
1020 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1021 * parameter, it may be more practical to send it via a
1022 * <code>java.io.InputStream</code>. Data will be read from the stream
1023 * as needed until end-of-file is reached. The JDBC driver will
1024 * do any necessary conversion from ASCII to the database char format.
1025 *
1026 * <P><B>Note:</B> This stream object can either be a standard
1027 * Java stream object or your own subclass that implements the
1028 * standard interface.
1029 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1030 * it might be more efficient to use a version of
1031 * <code>setAsciiStream</code> which takes a length parameter.
1032 *
1033 * @param parameterIndex the first parameter is 1, the second is 2, ...
1034 * @param x the Java input stream that contains the ASCII parameter value
1035 * @exception SQLException if a database access error occurs or
1036 * this method is called on a closed <code>PreparedStatement</code>
1037 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1038 * @since 1.6
1039 */
1040 void setAsciiStream(int parameterIndex, java.io.InputStream x)
1041 throws SQLException;
1042
1043 /**
1044 * Sets the designated parameter to the given input stream.
1045 * When a very large ASCII value is input to a <code>LONGVARCHAR</code>
1046 * parameter, it may be more practical to send it via a
1047 * <code>java.io.InputStream</code>. Data will be read from the stream
1048 * as needed until end-of-file is reached. The JDBC driver will
1049 * do any necessary conversion from ASCII to the database char format.
1050 *
1051 * <P><B>Note:</B> This stream object can either be a standard
1052 * Java stream object or your own subclass that implements the
1053 * standard interface.
1054 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1055 * it might be more efficient to use a version of
1056 * <code>setAsciiStream</code> which takes a length parameter.
1057 *
1058 * @param parameterName the name of the parameter
1059 * @param x the Java input stream that contains the ASCII parameter value
1060 * @exception SQLException if a database access error occurs or
1061 * this method is called on a closed <code>CallableStatement</code>
1062 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1063 * @since 1.6
1064 */
1065 void setAsciiStream(String parameterName, java.io.InputStream x)
1066 throws SQLException;
1067
1068 /**
1069 * Sets the designated parameter in this <code>RowSet</code> object's command
1070 * to the given input stream.
1071 * When a very large binary value is input to a <code>LONGVARBINARY</code>
1072 * parameter, it may be more practical to send it via a
1073 * <code>java.io.InputStream</code> object. The data will be read from the
1074 * stream as needed until end-of-file is reached.
1075 *
1076 * <P><B>Note:</B> This stream object can either be a standard
1077 * Java stream object or your own subclass that implements the
1078 * standard interface.
1079 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1080 * it might be more efficient to use a version of
1081 * <code>setBinaryStream</code> which takes a length parameter.
1082 *
1083 * @param parameterIndex the first parameter is 1, the second is 2, ...
1084 * @param x the java input stream which contains the binary parameter value
1085 * @exception SQLException if a database access error occurs or
1086 * this method is called on a closed <code>PreparedStatement</code>
1087 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1088 * @since 1.6
1089 */
1090 void setBinaryStream(int parameterIndex, java.io.InputStream x)
1091 throws SQLException;
1092
1093 /**
1094 * Sets the designated parameter to the given input stream.
1095 * When a very large binary value is input to a <code>LONGVARBINARY</code>
1096 * parameter, it may be more practical to send it via a
1097 * <code>java.io.InputStream</code> object. The data will be read from the
1098 * stream as needed until end-of-file is reached.
1099 *
1100 * <P><B>Note:</B> This stream object can either be a standard
1101 * Java stream object or your own subclass that implements the
1102 * standard interface.
1103 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1104 * it might be more efficient to use a version of
1105 * <code>setBinaryStream</code> which takes a length parameter.
1106 *
1107 * @param parameterName the name of the parameter
1108 * @param x the java input stream which contains the binary parameter value
1109 * @exception SQLException if a database access error occurs or
1110 * this method is called on a closed <code>CallableStatement</code>
1111 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1112 * @since 1.6
1113 */
1114 void setBinaryStream(String parameterName, java.io.InputStream x)
1115 throws SQLException;
1116
1117 /**
1118 * Sets the designated parameter in this <code>RowSet</code> object's command
1119 * to the given <code>Reader</code>
1120 * object.
1121 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1122 * parameter, it may be more practical to send it via a
1123 * <code>java.io.Reader</code> object. The data will be read from the stream
1124 * as needed until end-of-file is reached. The JDBC driver will
1125 * do any necessary conversion from UNICODE to the database char format.
1126 *
1127 * <P><B>Note:</B> This stream object can either be a standard
1128 * Java stream object or your own subclass that implements the
1129 * standard interface.
1130 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1131 * it might be more efficient to use a version of
1132 * <code>setCharacterStream</code> which takes a length parameter.
1133 *
1134 * @param parameterIndex the first parameter is 1, the second is 2, ...
1135 * @param reader the <code>java.io.Reader</code> object that contains the
1136 * Unicode data
1137 * @exception SQLException if a database access error occurs or
1138 * this method is called on a closed <code>PreparedStatement</code>
1139 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1140 * @since 1.6
1141 */
1142 void setCharacterStream(int parameterIndex, java.io.Reader reader)
1143 throws SQLException;
1144
1145 /**
1146 * Sets the designated parameter to the given <code>Reader</code>
1147 * object.
1148 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
1149 * parameter, it may be more practical to send it via a
1150 * <code>java.io.Reader</code> object. The data will be read from the stream
1151 * as needed until end-of-file is reached. The JDBC driver will
1152 * do any necessary conversion from UNICODE to the database char format.
1153 *
1154 * <P><B>Note:</B> This stream object can either be a standard
1155 * Java stream object or your own subclass that implements the
1156 * standard interface.
1157 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1158 * it might be more efficient to use a version of
1159 * <code>setCharacterStream</code> which takes a length parameter.
1160 *
1161 * @param parameterName the name of the parameter
1162 * @param reader the <code>java.io.Reader</code> object that contains the
1163 * Unicode data
1164 * @exception SQLException if a database access error occurs or
1165 * this method is called on a closed <code>CallableStatement</code>
1166 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1167 * @since 1.6
1168 */
1169 void setCharacterStream(String parameterName, java.io.Reader reader)
1170 throws SQLException;
1171
1172 /**
1173 * Sets the designated parameter in this <code>RowSet</code> object's command
1174 * to a <code>Reader</code> object. The
1175 * <code>Reader</code> reads the data till end-of-file is reached. The
1176 * driver does the necessary conversion from Java character format to
1177 * the national character set in the database.
1178
1179 * <P><B>Note:</B> This stream object can either be a standard
1180 * Java stream object or your own subclass that implements the
1181 * standard interface.
1182 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1183 * it might be more efficient to use a version of
1184 * <code>setNCharacterStream</code> which takes a length parameter.
1185 *
1186 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1187 * @param value the parameter value
1188 * @throws SQLException if the driver does not support national
1189 * character sets; if the driver can detect that a data conversion
1190 * error could occur ; if a database access error occurs; or
1191 * this method is called on a closed <code>PreparedStatement</code>
1192 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1193 * @since 1.6
1194 */
1195 void setNCharacterStream(int parameterIndex, Reader value)
1196 throws SQLException;
1197
1198 /**
1199 * Sets the designated parameter in this <code>RowSet</code> object's command
1200 * with the given Java <code>Object</code>. For integral values, the
1201 * <code>java.lang</code> equivalent objects should be used (for example,
1202 * an instance of the class <code>Integer</code> for an <code>int</code>).
1203 *
1204 * If the second argument is an <code>InputStream</code> then the stream must contain
1205 * the number of bytes specified by scaleOrLength. If the second argument is a
1206 * <code>Reader</code> then the reader must contain the number of characters specified * by scaleOrLength. If these conditions are not true the driver will generate a
1207 * <code>SQLException</code> when the prepared statement is executed.
1208 *
1209 * <p>The given Java object will be converted to the targetSqlType
1210 * before being sent to the database.
1211 * <P>
1212 * If the object is of a class implementing <code>SQLData</code>,
1213 * the rowset should call the method <code>SQLData.writeSQL</code>
1214 * to write the object to an <code>SQLOutput</code> data stream.
1215 * If, on the other hand, the object is of a class implementing
1216 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1217 * <code>Struct</code>, <code>java.net.URL</code>,
1218 * or <code>Array</code>, the driver should pass it to the database as a
1219 * value of the corresponding SQL type.
1220 * <P>
1221 *
1222 * <p>Note that this method may be used to pass datatabase-specific
1223 * abstract data types.
1224 *
1225 * @param parameterIndex the first parameter is 1, the second is 2, ...
1226 * @param x the object containing the input parameter value
1227 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1228 * to be sent to the database. The scale argument may further qualify this
1229 * type.
1230 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code>
1231 * or <code>java.sql.Types.NUMERIC types</code>,
1232 * this is the number of digits after the decimal point. For
1233 * Java Object types <code>InputStream</code> and <code>Reader</code>,
1234 * this is the length
1235 * of the data in the stream or reader. For all other types,
1236 * this value will be ignored.
1237 * @exception SQLException if a database access error occurs
1238 * @see java.sql.Types
1239 */
1240 void setObject(int parameterIndex, Object x, int targetSqlType,
1241 int scaleOrLength) throws SQLException;
1242
1243 /**
1244 * Sets the value of the designated parameter with the given object. The second
1245 * argument must be an object type; for integral values, the
1246 * <code>java.lang</code> equivalent objects should be used.
1247 *
1248 * <p>The given Java object will be converted to the given targetSqlType
1249 * before being sent to the database.
1250 *
1251 * If the object has a custom mapping (is of a class implementing the
1252 * interface <code>SQLData</code>),
1253 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it
1254 * to the SQL data stream.
1255 * If, on the other hand, the object is of a class implementing
1256 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1257 * <code>Struct</code>, <code>java.net.URL</code>,
1258 * or <code>Array</code>, the driver should pass it to the database as a
1259 * value of the corresponding SQL type.
1260 * <P>
1261 * Note that this method may be used to pass datatabase-
1262 * specific abstract data types.
1263 *
1264 * @param parameterName the name of the parameter
1265 * @param x the object containing the input parameter value
1266 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1267 * sent to the database. The scale argument may further qualify this type.
1268 * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types,
1269 * this is the number of digits after the decimal point. For all other
1270 * types, this value will be ignored.
1271 * @exception SQLException if a database access error occurs or
1272 * this method is called on a closed <code>CallableStatement</code>
1273 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1274 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1275 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1276 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1277 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1278 * or <code>STRUCT</code> data type and the JDBC driver does not support
1279 * this data type
1280 * @see Types
1281 * @see #getObject
1282 * @since 1.4
1283 */
1284 void setObject(String parameterName, Object x, int targetSqlType,
1285 int scale) throws SQLException;
1286
1287 /**
1288 * Sets the designated parameter in this <code>RowSet</code> object's command
1289 * with a Java <code>Object</code>. For integral values, the
1290 * <code>java.lang</code> equivalent objects should be used.
1291 * This method is like <code>setObject</code> above, but the scale used is the scale
1292 * of the second parameter. Scalar values have a scale of zero. Literal
1293 * values have the scale present in the literal.
1294 * <P>
1295 * Even though it is supported, it is not recommended that this method
1296 * be called with floating point input values.
1297 *
1298 * @param parameterIndex the first parameter is 1, the second is 2, ...
1299 * @param x the object containing the input parameter value
1300 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>)
1301 * to be sent to the database
1302 * @exception SQLException if a database access error occurs
1303 */
1304 void setObject(int parameterIndex, Object x, int targetSqlType)
1305 throws SQLException;
1306
1307 /**
1308 * Sets the value of the designated parameter with the given object.
1309 * This method is like the method <code>setObject</code>
1310 * above, except that it assumes a scale of zero.
1311 *
1312 * @param parameterName the name of the parameter
1313 * @param x the object containing the input parameter value
1314 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be
1315 * sent to the database
1316 * @exception SQLException if a database access error occurs or
1317 * this method is called on a closed <code>CallableStatement</code>
1318 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is
1319 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,
1320 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,
1321 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>,
1322 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>
1323 * or <code>STRUCT</code> data type and the JDBC driver does not support
1324 * this data type
1325 * @see #getObject
1326 * @since 1.4
1327 */
1328 void setObject(String parameterName, Object x, int targetSqlType)
1329 throws SQLException;
1330
1331 /**
1332 * Sets the value of the designated parameter with the given object.
1333 * The second parameter must be of type <code>Object</code>; therefore, the
1334 * <code>java.lang</code> equivalent objects should be used for built-in types.
1335 *
1336 * <p>The JDBC specification specifies a standard mapping from
1337 * Java <code>Object</code> types to SQL types. The given argument
1338 * will be converted to the corresponding SQL type before being
1339 * sent to the database.
1340 *
1341 * <p>Note that this method may be used to pass datatabase-
1342 * specific abstract data types, by using a driver-specific Java
1343 * type.
1344 *
1345 * If the object is of a class implementing the interface <code>SQLData</code>,
1346 * the JDBC driver should call the method <code>SQLData.writeSQL</code>
1347 * to write it to the SQL data stream.
1348 * If, on the other hand, the object is of a class implementing
1349 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1350 * <code>Struct</code>, <code>java.net.URL</code>,
1351 * or <code>Array</code>, the driver should pass it to the database as a
1352 * value of the corresponding SQL type.
1353 * <P>
1354 * This method throws an exception if there is an ambiguity, for example, if the
1355 * object is of a class implementing more than one of the interfaces named above.
1356 *
1357 * @param parameterName the name of the parameter
1358 * @param x the object containing the input parameter value
1359 * @exception SQLException if a database access error occurs,
1360 * this method is called on a closed <code>CallableStatement</code> or if the given
1361 * <code>Object</code> parameter is ambiguous
1362 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1363 * this method
1364 * @see #getObject
1365 * @since 1.4
1366 */
1367 void setObject(String parameterName, Object x) throws SQLException;
1368
1369 /**
1370 * Sets the designated parameter in this <code>RowSet</code> object's command
1371 * with a Java <code>Object</code>. For integral values, the
1372 * <code>java.lang</code> equivalent objects should be used.
1373 *
1374 * <p>The JDBC specification provides a standard mapping from
1375 * Java Object types to SQL types. The driver will convert the
1376 * given Java object to its standard SQL mapping before sending it
1377 * to the database.
1378 *
1379 * <p>Note that this method may be used to pass datatabase-specific
1380 * abstract data types by using a driver-specific Java type.
1381 *
1382 * If the object is of a class implementing <code>SQLData</code>,
1383 * the rowset should call the method <code>SQLData.writeSQL</code>
1384 * to write the object to an <code>SQLOutput</code> data stream.
1385 * If, on the other hand, the object is of a class implementing
1386 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>,
1387 * <code>Struct</code>, <code>java.net.URL</code>,
1388 * or <code>Array</code>, the driver should pass it to the database as a
1389 * value of the corresponding SQL type.
1390 * <P>
1391 * <P>
1392 * An exception is thrown if there is an ambiguity, for example, if the
1393 * object is of a class implementing more than one of these interfaces.
1394 *
1395 * @param parameterIndex The first parameter is 1, the second is 2, ...
1396 * @param x The object containing the input parameter value
1397 * @exception SQLException if a database access error occurs
1398 */
1399 void setObject(int parameterIndex, Object x) throws SQLException;
1400
1401 /**
1402 * Sets the designated parameter in this <code>RowSet</code> object's command
1403 * with the given <code>Ref</code> value. The driver will convert this
1404 * to the appropriate <code>REF(<structured-type>)</code> value.
1405 *
1406 * @param i the first parameter is 1, the second is 2, ...
1407 * @param x an object representing data of an SQL <code>REF</code> type
1408 * @exception SQLException if a database access error occurs
1409 */
1410 void setRef(int i, Ref x) throws SQLException;
1411
1412 /**
1413 * Sets the designated parameter in this <code>RowSet</code> object's command
1414 * with the given <code>Blob</code> value. The driver will convert this
1415 * to the <code>BLOB</code> value that the <code>Blob</code> object
1416 * represents before sending it to the database.
1417 *
1418 * @param i the first parameter is 1, the second is 2, ...
1419 * @param x an object representing a BLOB
1420 * @exception SQLException if a database access error occurs
1421 */
1422 void setBlob(int i, Blob x) throws SQLException;
1423
1424 /**
1425 * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number
1426 * of characters specified by length otherwise a <code>SQLException</code> will be
1427 * generated when the <code>PreparedStatement</code> is executed.
1428 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1429 * method because it informs the driver that the parameter value should be
1430 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1431 * the driver may have to do extra work to determine whether the parameter
1432 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1433 * @param parameterIndex index of the first parameter is 1,
1434 * the second is 2, ...
1435 * @param inputStream An object that contains the data to set the parameter
1436 * value to.
1437 * @param length the number of bytes in the parameter data.
1438 * @throws SQLException if a database access error occurs,
1439 * this method is called on a closed <code>PreparedStatement</code>,
1440 * if parameterIndex does not correspond
1441 * to a parameter marker in the SQL statement, if the length specified
1442 * is less than zero or if the number of bytes in the inputstream does not match
1443 * the specfied length.
1444 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1445 *
1446 * @since 1.6
1447 */
1448 void setBlob(int parameterIndex, InputStream inputStream,
1449 long length) throws SQLException;
1450
1451 /**
1452 * Sets the designated parameter to a <code>InputStream</code> object.
1453 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1454 * method because it informs the driver that the parameter value should be
1455 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1456 * the driver may have to do extra work to determine whether the parameter
1457 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1458 *
1459 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1460 * it might be more efficient to use a version of
1461 * <code>setBlob</code> which takes a length parameter.
1462 *
1463 * @param parameterIndex index of the first parameter is 1,
1464 * the second is 2, ...
1465 * @param inputStream An object that contains the data to set the parameter
1466 * value to.
1467 * @throws SQLException if a database access error occurs,
1468 * this method is called on a closed <code>PreparedStatement</code> or
1469 * if parameterIndex does not correspond
1470 * to a parameter marker in the SQL statement,
1471 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1472 *
1473 * @since 1.6
1474 */
1475 void setBlob(int parameterIndex, InputStream inputStream)
1476 throws SQLException;
1477
1478 /**
1479 * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number
1480 * of characters specified by length, otherwise a <code>SQLException</code> will be
1481 * generated when the <code>CallableStatement</code> is executed.
1482 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code>
1483 * method because it informs the driver that the parameter value should be
1484 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1485 * the driver may have to do extra work to determine whether the parameter
1486 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1487 *
1488 * @param parameterName the name of the parameter to be set
1489 * the second is 2, ...
1490 *
1491 * @param inputStream An object that contains the data to set the parameter
1492 * value to.
1493 * @param length the number of bytes in the parameter data.
1494 * @throws SQLException if parameterIndex does not correspond
1495 * to a parameter marker in the SQL statement, or if the length specified
1496 * is less than zero; if the number of bytes in the inputstream does not match
1497 * the specfied length; if a database access error occurs or
1498 * this method is called on a closed <code>CallableStatement</code>
1499 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1500 * this method
1501 *
1502 * @since 1.6
1503 */
1504 void setBlob(String parameterName, InputStream inputStream,
1505 long length) throws SQLException;
1506
1507 /**
1508 * Sets the designated parameter to the given <code>java.sql.Blob</code> object.
1509 * The driver converts this to an SQL <code>BLOB</code> value when it
1510 * sends it to the database.
1511 *
1512 * @param parameterName the name of the parameter
1513 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value
1514 * @exception SQLException if a database access error occurs or
1515 * this method is called on a closed <code>CallableStatement</code>
1516 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1517 * this method
1518 * @since 1.6
1519 */
1520 void setBlob(String parameterName, Blob x) throws SQLException;
1521
1522 /**
1523 * Sets the designated parameter to a <code>InputStream</code> object.
1524 * This method differs from the <code>setBinaryStream (int, InputStream)</code>
1525 * method because it informs the driver that the parameter value should be
1526 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used,
1527 * the driver may have to do extra work to determine whether the parameter
1528 * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code>
1529 *
1530 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1531 * it might be more efficient to use a version of
1532 * <code>setBlob</code> which takes a length parameter.
1533 *
1534 * @param parameterName the name of the parameter
1535 * @param inputStream An object that contains the data to set the parameter
1536 * value to.
1537 * @throws SQLException if a database access error occurs or
1538 * this method is called on a closed <code>CallableStatement</code>
1539 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1540 *
1541 * @since 1.6
1542 */
1543 void setBlob(String parameterName, InputStream inputStream)
1544 throws SQLException;
1545
1546 /**
1547 * Sets the designated parameter in this <code>RowSet</code> object's command
1548 * with the given <code>Clob</code> value. The driver will convert this
1549 * to the <code>CLOB</code> value that the <code>Clob</code> object
1550 * represents before sending it to the database.
1551 *
1552 * @param i the first parameter is 1, the second is 2, ...
1553 * @param x an object representing a CLOB
1554 * @exception SQLException if a database access error occurs
1555 */
1556 void setClob(int i, Clob x) throws SQLException;
1557
1558 /**
1559 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
1560 * of characters specified by length otherwise a <code>SQLException</code> will be
1561 * generated when the <code>PreparedStatement</code> is executed.
1562 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1563 * because it informs the driver that the parameter value should be sent to
1564 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1565 * driver may have to do extra work to determine whether the parameter
1566 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1567 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1568 * @param reader An object that contains the data to set the parameter value to.
1569 * @param length the number of characters in the parameter data.
1570 * @throws SQLException if a database access error occurs, this method is called on
1571 * a closed <code>PreparedStatement</code>, if parameterIndex does not correspond to a parameter
1572 * marker in the SQL statement, or if the length specified is less than zero.
1573 *
1574 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1575 * @since 1.6
1576 */
1577 void setClob(int parameterIndex, Reader reader, long length)
1578 throws SQLException;
1579
1580 /**
1581 * Sets the designated parameter to a <code>Reader</code> object.
1582 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1583 * because it informs the driver that the parameter value should be sent to
1584 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1585 * driver may have to do extra work to determine whether the parameter
1586 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1587 *
1588 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1589 * it might be more efficient to use a version of
1590 * <code>setClob</code> which takes a length parameter.
1591 *
1592 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1593 * @param reader An object that contains the data to set the parameter value to.
1594 * @throws SQLException if a database access error occurs, this method is called on
1595 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter
1596 * marker in the SQL statement
1597 *
1598 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1599 * @since 1.6
1600 */
1601 void setClob(int parameterIndex, Reader reader) throws SQLException;
1602
1603 /**
1604 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
1605 * of characters specified by length otherwise a <code>SQLException</code> will be
1606 * generated when the <code>CallableStatement</code> is executed.
1607 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
1608 * because it informs the driver that the parameter value should be sent to
1609 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1610 * driver may have to do extra work to determine whether the parameter
1611 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1612 * @param parameterName the name of the parameter to be set
1613 * @param reader An object that contains the data to set the parameter value to.
1614 * @param length the number of characters in the parameter data.
1615 * @throws SQLException if parameterIndex does not correspond to a parameter
1616 * marker in the SQL statement; if the length specified is less than zero;
1617 * a database access error occurs or
1618 * this method is called on a closed <code>CallableStatement</code>
1619 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1620 * this method
1621 *
1622 * @since 1.6
1623 */
1624 void setClob(String parameterName, Reader reader, long length)
1625 throws SQLException;
1626
1627 /**
1628 * Sets the designated parameter to the given <code>java.sql.Clob</code> object.
1629 * The driver converts this to an SQL <code>CLOB</code> value when it
1630 * sends it to the database.
1631 *
1632 * @param parameterName the name of the parameter
1633 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value
1634 * @exception SQLException if a database access error occurs or
1635 * this method is called on a closed <code>CallableStatement</code>
1636 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1637 * this method
1638 * @since 1.6
1639 */
1640 void setClob(String parameterName, Clob x) throws SQLException;
1641
1642 /**
1643 * Sets the designated parameter to a <code>Reader</code> object.
1644 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
1645 * because it informs the driver that the parameter value should be sent to
1646 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the
1647 * driver may have to do extra work to determine whether the parameter
1648 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code>
1649 *
1650 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
1651 * it might be more efficient to use a version of
1652 * <code>setClob</code> which takes a length parameter.
1653 *
1654 * @param parameterName the name of the parameter
1655 * @param reader An object that contains the data to set the parameter value to.
1656 * @throws SQLException if a database access error occurs or this method is called on
1657 * a closed <code>CallableStatement</code>
1658 *
1659 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1660 * @since 1.6
1661 */
1662 void setClob(String parameterName, Reader reader)
1663 throws SQLException;
1664
1665 /**
1666 * Sets the designated parameter in this <code>RowSet</code> object's command
1667 * with the given <code>Array</code> value. The driver will convert this
1668 * to the <code>ARRAY</code> value that the <code>Array</code> object
1669 * represents before sending it to the database.
1670 *
1671 * @param i the first parameter is 1, the second is 2, ...
1672 * @param x an object representing an SQL array
1673 * @exception SQLException if a database access error occurs
1674 */
1675 void setArray(int i, Array x) throws SQLException;
1676
1677 /**
1678 * Sets the designated parameter in this <code>RowSet</code> object's command
1679 * with the given <code>java.sql.Date</code> value. The driver will convert this
1680 * to an SQL <code>DATE</code> value, using the given <code>java.util.Calendar</code>
1681 * object to calculate the date.
1682 *
1683 * @param parameterIndex the first parameter is 1, the second is 2, ...
1684 * @param x the parameter value
1685 * @param cal the <code>java.util.Calendar</code> object to use for calculating the date
1686 * @exception SQLException if a database access error occurs
1687 */
1688 void setDate(int parameterIndex, java.sql.Date x, Calendar cal)
1689 throws SQLException;
1690
1691 /**
1692 * Sets the designated parameter to the given <code>java.sql.Date</code> value
1693 * using the default time zone of the virtual machine that is running
1694 * the application.
1695 * The driver converts this
1696 * to an SQL <code>DATE</code> value when it sends it to the database.
1697 *
1698 * @param parameterName the name of the parameter
1699 * @param x the parameter value
1700 * @exception SQLException if a database access error occurs or
1701 * this method is called on a closed <code>CallableStatement</code>
1702 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1703 * this method
1704 * @see #getDate
1705 * @since 1.4
1706 */
1707 void setDate(String parameterName, java.sql.Date x)
1708 throws SQLException;
1709
1710 /**
1711 * Sets the designated parameter to the given <code>java.sql.Date</code> value,
1712 * using the given <code>Calendar</code> object. The driver uses
1713 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value,
1714 * which the driver then sends to the database. With a
1715 * a <code>Calendar</code> object, the driver can calculate the date
1716 * taking into account a custom timezone. If no
1717 * <code>Calendar</code> object is specified, the driver uses the default
1718 * timezone, which is that of the virtual machine running the application.
1719 *
1720 * @param parameterName the name of the parameter
1721 * @param x the parameter value
1722 * @param cal the <code>Calendar</code> object the driver will use
1723 * to construct the date
1724 * @exception SQLException if a database access error occurs or
1725 * this method is called on a closed <code>CallableStatement</code>
1726 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1727 * this method
1728 * @see #getDate
1729 * @since 1.4
1730 */
1731 void setDate(String parameterName, java.sql.Date x, Calendar cal)
1732 throws SQLException;
1733
1734 /**
1735 * Sets the designated parameter in this <code>RowSet</code> object's command
1736 * with the given <code>java.sql.Time</code> value. The driver will convert this
1737 * to an SQL <code>TIME</code> value, using the given <code>java.util.Calendar</code>
1738 * object to calculate it, before sending it to the database.
1739 *
1740 * @param parameterIndex the first parameter is 1, the second is 2, ...
1741 * @param x the parameter value
1742 * @param cal the <code>java.util.Calendar</code> object to use for calculating the time
1743 * @exception SQLException if a database access error occurs
1744 */
1745 void setTime(int parameterIndex, java.sql.Time x, Calendar cal)
1746 throws SQLException;
1747
1748 /**
1749 * Sets the designated parameter to the given <code>java.sql.Time</code> value.
1750 * The driver converts this
1751 * to an SQL <code>TIME</code> value when it sends it to the database.
1752 *
1753 * @param parameterName the name of the parameter
1754 * @param x the parameter value
1755 * @exception SQLException if a database access error occurs or
1756 * this method is called on a closed <code>CallableStatement</code>
1757 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1758 * this method
1759 * @see #getTime
1760 * @since 1.4
1761 */
1762 void setTime(String parameterName, java.sql.Time x)
1763 throws SQLException;
1764
1765 /**
1766 * Sets the designated parameter to the given <code>java.sql.Time</code> value,
1767 * using the given <code>Calendar</code> object. The driver uses
1768 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value,
1769 * which the driver then sends to the database. With a
1770 * a <code>Calendar</code> object, the driver can calculate the time
1771 * taking into account a custom timezone. If no
1772 * <code>Calendar</code> object is specified, the driver uses the default
1773 * timezone, which is that of the virtual machine running the application.
1774 *
1775 * @param parameterName the name of the parameter
1776 * @param x the parameter value
1777 * @param cal the <code>Calendar</code> object the driver will use
1778 * to construct the time
1779 * @exception SQLException if a database access error occurs or
1780 * this method is called on a closed <code>CallableStatement</code>
1781 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1782 * this method
1783 * @see #getTime
1784 * @since 1.4
1785 */
1786 void setTime(String parameterName, java.sql.Time x, Calendar cal)
1787 throws SQLException;
1788
1789 /**
1790 * Sets the designated parameter in this <code>RowSet</code> object's command
1791 * with the given <code>java.sql.Timestamp</code> value. The driver will
1792 * convert this to an SQL <code>TIMESTAMP</code> value, using the given
1793 * <code>java.util.Calendar</code> object to calculate it, before sending it to the
1794 * database.
1795 *
1796 * @param parameterIndex the first parameter is 1, the second is 2, ...
1797 * @param x the parameter value
1798 * @param cal the <code>java.util.Calendar</code> object to use for calculating the
1799 * timestamp
1800 * @exception SQLException if a database access error occurs
1801 */
1802 void setTimestamp(int parameterIndex, java.sql.Timestamp x,
1803 Calendar cal) throws SQLException;
1804
1805 /**
1806 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value,
1807 * using the given <code>Calendar</code> object. The driver uses
1808 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value,
1809 * which the driver then sends to the database. With a
1810 * a <code>Calendar</code> object, the driver can calculate the timestamp
1811 * taking into account a custom timezone. If no
1812 * <code>Calendar</code> object is specified, the driver uses the default
1813 * timezone, which is that of the virtual machine running the application.
1814 *
1815 * @param parameterName the name of the parameter
1816 * @param x the parameter value
1817 * @param cal the <code>Calendar</code> object the driver will use
1818 * to construct the timestamp
1819 * @exception SQLException if a database access error occurs or
1820 * this method is called on a closed <code>CallableStatement</code>
1821 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1822 * this method
1823 * @see #getTimestamp
1824 * @since 1.4
1825 */
1826 void setTimestamp(String parameterName, java.sql.Timestamp x,
1827 Calendar cal) throws SQLException;
1828
1829 /**
1830 * Clears the parameters set for this <code>RowSet</code> object's command.
1831 * <P>In general, parameter values remain in force for repeated use of a
1832 * <code>RowSet</code> object. Setting a parameter value automatically clears its
1833 * previous value. However, in some cases it is useful to immediately
1834 * release the resources used by the current parameter values, which can
1835 * be done by calling the method <code>clearParameters</code>.
1836 *
1837 * @exception SQLException if a database access error occurs
1838 */
1839 void clearParameters() throws SQLException;
1840
1841 //---------------------------------------------------------------------
1842 // Reading and writing data
1843 //---------------------------------------------------------------------
1844
1845 /**
1846 * Fills this <code>RowSet</code> object with data.
1847 * <P>
1848 * The <code>execute</code> method may use the following properties
1849 * to create a connection for reading data: url, data source name,
1850 * user name, password, transaction isolation, and type map.
1851 *
1852 * The <code>execute</code> method may use the following properties
1853 * to create a statement to execute a command:
1854 * command, read only, maximum field size,
1855 * maximum rows, escape processing, and query timeout.
1856 * <P>
1857 * If the required properties have not been set, an exception is
1858 * thrown. If this method is successful, the current contents of the rowset are
1859 * discarded and the rowset's metadata is also (re)set. If there are
1860 * outstanding updates, they are ignored.
1861 * <P>
1862 * If this <code>RowSet</code> object does not maintain a continuous connection
1863 * with its source of data, it may use a reader (a <code>RowSetReader</code>
1864 * object) to fill itself with data. In this case, a reader will have been
1865 * registered with this <code>RowSet</code> object, and the method
1866 * <code>execute</code> will call on the reader's <code>readData</code>
1867 * method as part of its implementation.
1868 *
1869 * @exception SQLException if a database access error occurs or any of the
1870 * properties necessary for making a connection and creating
1871 * a statement have not been set
1872 */
1873 void execute() throws SQLException;
1874
1875 //--------------------------------------------------------------------
1876 // Events
1877 //--------------------------------------------------------------------
1878
1879 /**
1880 * Registers the given listener so that it will be notified of events
1881 * that occur on this <code>RowSet</code> object.
1882 *
1883 * @param listener a component that has implemented the <code>RowSetListener</code>
1884 * interface and wants to be notified when events occur on this
1885 * <code>RowSet</code> object
1886 * @see #removeRowSetListener
1887 */
1888 void addRowSetListener(RowSetListener listener);
1889
1890 /**
1891 * Removes the specified listener from the list of components that will be
1892 * notified when an event occurs on this <code>RowSet</code> object.
1893 *
1894 * @param listener a component that has been registered as a listener for this
1895 * <code>RowSet</code> object
1896 * @see #addRowSetListener
1897 */
1898 void removeRowSetListener(RowSetListener listener);
1899
1900 /**
1901 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1902 * SQL <code>XML</code> value when it sends it to the database.
1903 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
1904 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value
1905 * @throws SQLException if a database access error occurs, this method
1906 * is called on a closed result set,
1907 * the <code>java.xml.transform.Result</code>,
1908 * <code>Writer</code> or <code>OutputStream</code> has not been closed
1909 * for the <code>SQLXML</code> object or
1910 * if there is an error processing the XML value. The <code>getCause</code> method
1911 * of the exception may provide a more detailed exception, for example, if the
1912 * stream does not contain valid XML.
1913 * @since 1.6
1914 */
1915 void setSQLXML(int parameterIndex, SQLXML xmlObject)
1916 throws SQLException;
1917
1918 /**
1919 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an
1920 * <code>SQL XML</code> value when it sends it to the database.
1921 * @param parameterName the name of the parameter
1922 * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
1923 * @throws SQLException if a database access error occurs, this method
1924 * is called on a closed result set,
1925 * the <code>java.xml.transform.Result</code>,
1926 * <code>Writer</code> or <code>OutputStream</code> has not been closed
1927 * for the <code>SQLXML</code> object or
1928 * if there is an error processing the XML value. The <code>getCause</code> method
1929 * of the exception may provide a more detailed exception, for example, if the
1930 * stream does not contain valid XML.
1931 * @since 1.6
1932 */
1933 void setSQLXML(String parameterName, SQLXML xmlObject)
1934 throws SQLException;
1935
1936 /**
1937 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1938 * driver converts this to a SQL <code>ROWID</code> value when it sends it
1939 * to the database
1940 *
1941 * @param parameterIndex the first parameter is 1, the second is 2, ...
1942 * @param x the parameter value
1943 * @throws SQLException if a database access error occurs
1944 *
1945 * @since 1.6
1946 */
1947 void setRowId(int parameterIndex, RowId x) throws SQLException;
1948
1949 /**
1950 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The
1951 * driver converts this to a SQL <code>ROWID</code> when it sends it to the
1952 * database.
1953 *
1954 * @param parameterName the name of the parameter
1955 * @param x the parameter value
1956 * @throws SQLException if a database access error occurs
1957 * @since 1.6
1958 */
1959 void setRowId(String parameterName, RowId x) throws SQLException;
1960
1961 /**
1962 * Sets the designated paramter to the given <code>String</code> object.
1963 * The driver converts this to a SQL <code>NCHAR</code> or
1964 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value
1965 * (depending on the argument's
1966 * size relative to the driver's limits on <code>NVARCHAR</code> values)
1967 * when it sends it to the database.
1968 *
1969 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1970 * @param value the parameter value
1971 * @throws SQLException if the driver does not support national
1972 * character sets; if the driver can detect that a data conversion
1973 * error could occur ; or if a database access error occurs
1974 * @since 1.6
1975 */
1976 void setNString(int parameterIndex, String value)
1977 throws SQLException;
1978
1979 /**
1980 * Sets the designated paramter to the given <code>String</code> object.
1981 * The driver converts this to a SQL <code>NCHAR</code> or
1982 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code>
1983 * @param parameterName the name of the column to be set
1984 * @param value the parameter value
1985 * @throws SQLException if the driver does not support national
1986 * character sets; if the driver can detect that a data conversion
1987 * error could occur; or if a database access error occurs
1988 * @since 1.6
1989 */
1990 public void setNString(String parameterName, String value)
1991 throws SQLException;
1992
1993 /**
1994 * Sets the designated parameter to a <code>Reader</code> object. The
1995 * <code>Reader</code> reads the data till end-of-file is reached. The
1996 * driver does the necessary conversion from Java character format to
1997 * the national character set in the database.
1998 * @param parameterIndex of the first parameter is 1, the second is 2, ...
1999 * @param value the parameter value
2000 * @param length the number of characters in the parameter data.
2001 * @throws SQLException if the driver does not support national
2002 * character sets; if the driver can detect that a data conversion
2003 * error could occur ; or if a database access error occurs
2004 * @since 1.6
2005 */
2006 void setNCharacterStream(int parameterIndex, Reader value,
2007 long length) throws SQLException;
2008
2009 /**
2010 * Sets the designated parameter to a <code>Reader</code> object. The
2011 * <code>Reader</code> reads the data till end-of-file is reached. The
2012 * driver does the necessary conversion from Java character format to
2013 * the national character set in the database.
2014 * @param parameterName the name of the column to be set
2015 * @param value the parameter value
2016 * @param length the number of characters in the parameter data.
2017 * @throws SQLException if the driver does not support national
2018 * character sets; if the driver can detect that a data conversion
2019 * error could occur; or if a database access error occurs
2020 * @since 1.6
2021 */
2022 public void setNCharacterStream(String parameterName, Reader value,
2023 long length) throws SQLException;
2024
2025 /**
2026 * Sets the designated parameter to a <code>Reader</code> object. The
2027 * <code>Reader</code> reads the data till end-of-file is reached. The
2028 * driver does the necessary conversion from Java character format to
2029 * the national character set in the database.
2030
2031 * <P><B>Note:</B> This stream object can either be a standard
2032 * Java stream object or your own subclass that implements the
2033 * standard interface.
2034 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2035 * it might be more efficient to use a version of
2036 * <code>setNCharacterStream</code> which takes a length parameter.
2037 *
2038 * @param parameterName the name of the parameter
2039 * @param value the parameter value
2040 * @throws SQLException if the driver does not support national
2041 * character sets; if the driver can detect that a data conversion
2042 * error could occur ; if a database access error occurs; or
2043 * this method is called on a closed <code>CallableStatement</code>
2044 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2045 * @since 1.6
2046 */
2047 void setNCharacterStream(String parameterName, Reader value)
2048 throws SQLException;
2049
2050 /**
2051 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object
2052 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code>
2053 * object maps to a SQL <code>NCLOB</code>.
2054 * @param parameterName the name of the column to be set
2055 * @param value the parameter value
2056 * @throws SQLException if the driver does not support national
2057 * character sets; if the driver can detect that a data conversion
2058 * error could occur; or if a database access error occurs
2059 * @since 1.6
2060 */
2061 void setNClob(String parameterName, NClob value)
2062 throws SQLException;
2063
2064 /**
2065 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number
2066 * of characters specified by length otherwise a <code>SQLException</code> will be
2067 * generated when the <code>CallableStatement</code> is executed.
2068 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2069 * because it informs the driver that the parameter value should be sent to
2070 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2071 * driver may have to do extra work to determine whether the parameter
2072 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2073 *
2074 * @param parameterName the name of the parameter to be set
2075 * @param reader An object that contains the data to set the parameter value to.
2076 * @param length the number of characters in the parameter data.
2077 * @throws SQLException if parameterIndex does not correspond to a parameter
2078 * marker in the SQL statement; if the length specified is less than zero;
2079 * if the driver does not support national
2080 * character sets; if the driver can detect that a data conversion
2081 * error could occur; if a database access error occurs or
2082 * this method is called on a closed <code>CallableStatement</code>
2083 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2084 * this method
2085 * @since 1.6
2086 */
2087 void setNClob(String parameterName, Reader reader, long length)
2088 throws SQLException;
2089
2090 /**
2091 * Sets the designated parameter to a <code>Reader</code> object.
2092 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2093 * because it informs the driver that the parameter value should be sent to
2094 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2095 * driver may have to do extra work to determine whether the parameter
2096 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2097 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2098 * it might be more efficient to use a version of
2099 * <code>setNClob</code> which takes a length parameter.
2100 *
2101 * @param parameterName the name of the parameter
2102 * @param reader An object that contains the data to set the parameter value to.
2103 * @throws SQLException if the driver does not support national character sets;
2104 * if the driver can detect that a data conversion
2105 * error could occur; if a database access error occurs or
2106 * this method is called on a closed <code>CallableStatement</code>
2107 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2108 *
2109 * @since 1.6
2110 */
2111 void setNClob(String parameterName, Reader reader)
2112 throws SQLException;
2113
2114 /**
2115 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number
2116 * of characters specified by length otherwise a <code>SQLException</code> will be
2117 * generated when the <code>PreparedStatement</code> is executed.
2118 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method
2119 * because it informs the driver that the parameter value should be sent to
2120 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2121 * driver may have to do extra work to determine whether the parameter
2122 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2123 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2124 * @param reader An object that contains the data to set the parameter value to.
2125 * @param length the number of characters in the parameter data.
2126 * @throws SQLException if parameterIndex does not correspond to a parameter
2127 * marker in the SQL statement; if the length specified is less than zero;
2128 * if the driver does not support national character sets;
2129 * if the driver can detect that a data conversion
2130 * error could occur; if a database access error occurs or
2131 * this method is called on a closed <code>PreparedStatement</code>
2132 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2133 *
2134 * @since 1.6
2135 */
2136 void setNClob(int parameterIndex, Reader reader, long length)
2137 throws SQLException;
2138
2139 /**
2140 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a
2141 * SQL <code>NCLOB</code> value when it sends it to the database.
2142 * @param parameterIndex of the first parameter is 1, the second is 2, ...
2143 * @param value the parameter value
2144 * @throws SQLException if the driver does not support national
2145 * character sets; if the driver can detect that a data conversion
2146 * error could occur ; or if a database access error occurs
2147 * @since 1.6
2148 */
2149 void setNClob(int parameterIndex, NClob value) throws SQLException;
2150
2151 /**
2152 * Sets the designated parameter to a <code>Reader</code> object.
2153 * This method differs from the <code>setCharacterStream (int, Reader)</code> method
2154 * because it informs the driver that the parameter value should be sent to
2155 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the
2156 * driver may have to do extra work to determine whether the parameter
2157 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code>
2158 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
2159 * it might be more efficient to use a version of
2160 * <code>setNClob</code> which takes a length parameter.
2161 *
2162 * @param parameterIndex index of the first parameter is 1, the second is 2, ...
2163 * @param reader An object that contains the data to set the parameter value to.
2164 * @throws SQLException if parameterIndex does not correspond to a parameter
2165 * marker in the SQL statement;
2166 * if the driver does not support national character sets;
2167 * if the driver can detect that a data conversion
2168 * error could occur; if a database access error occurs or
2169 * this method is called on a closed <code>PreparedStatement</code>
2170 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2171 *
2172 * @since 1.6
2173 */
2174 void setNClob(int parameterIndex, Reader reader)
2175 throws SQLException;
2176
2177 /**
2178 * Sets the designated parameter to the given <code>java.net.URL</code> value.
2179 * The driver converts this to an SQL <code>DATALINK</code> value
2180 * when it sends it to the database.
2181 *
2182 * @param parameterIndex the first parameter is 1, the second is 2, ...
2183 * @param x the <code>java.net.URL</code> object to be set
2184 * @exception SQLException if a database access error occurs or
2185 * this method is called on a closed <code>PreparedStatement</code>
2186 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
2187 * @since 1.4
2188 */
2189 void setURL(int parameterIndex, java.net.URL x) throws SQLException;
2190
2191 }
|