1/* 2 * Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.sql; 27 28import java.sql.*; 29import java.io.*; 30import java.math.*; 31import java.util.*; 32 33/** 34 * The interface that adds support to the JDBC API for the 35 * JavaBeans™ component model. 36 * A rowset, which can be used as a JavaBeans component in 37 * a visual Bean development environment, can be created and 38 * configured at design time and executed at run time. 39 * <P> 40 * The <code>RowSet</code> 41 * interface provides a set of JavaBeans properties that allow a <code>RowSet</code> 42 * instance to be configured to connect to a JDBC data source and read 43 * some data from the data source. A group of setter methods (<code>setInt</code>, 44 * <code>setBytes</code>, <code>setString</code>, and so on) 45 * provide a way to pass input parameters to a rowset's command property. 46 * This command is the SQL query the rowset uses when it gets its data from 47 * a relational database, which is generally the case. 48 * <P> 49 * The <code>RowSet</code> 50 * interface supports JavaBeans events, allowing other components in an 51 * application to be notified when an event occurs on a rowset, 52 * such as a change in its value. 53 * 54 * <P>The <code>RowSet</code> interface is unique in that it is intended to be 55 * implemented using the rest of the JDBC API. In other words, a 56 * <code>RowSet</code> implementation is a layer of software that executes "on top" 57 * of a JDBC driver. Implementations of the <code>RowSet</code> interface can 58 * be provided by anyone, including JDBC driver vendors who want to 59 * provide a <code>RowSet</code> implementation as part of their JDBC products. 60 * <P> 61 * A <code>RowSet</code> object may make a connection with a data source and 62 * maintain that connection throughout its life cycle, in which case it is 63 * called a <i>connected</i> rowset. A rowset may also make a connection with 64 * a data source, get data from it, and then close the connection. Such a rowset 65 * is called a <i>disconnected</i> rowset. A disconnected rowset may make 66 * changes to its data while it is disconnected and then send the changes back 67 * to the original source of the data, but it must reestablish a connection to do so. 68 * <P> 69 * A disconnected rowset may have a {@code Reader} (a <code>RowSetReader</code> object) 70 * and a writer (a <code>RowSetWriter</code> object) associated with it. 71 * The {@code Reader} may be implemented in many different ways to populate a rowset 72 * with data, including getting data from a non-relational data source. The 73 * writer can also be implemented in many different ways to propagate changes 74 * made to the rowset's data back to the underlying data source. 75 * <P> 76 * Rowsets are easy to use. The <code>RowSet</code> interface extends the standard 77 * <code>java.sql.ResultSet</code> interface. The <code>RowSetMetaData</code> 78 * interface extends the <code>java.sql.ResultSetMetaData</code> interface. 79 * Thus, developers familiar 80 * with the JDBC API will have to learn a minimal number of new APIs to 81 * use rowsets. In addition, third-party software tools that work with 82 * JDBC <code>ResultSet</code> objects will also easily be made to work with rowsets. 83 * 84 * @since 1.4 85 */ 86 87public interface RowSet extends ResultSet { 88 89 //----------------------------------------------------------------------- 90 // Properties 91 //----------------------------------------------------------------------- 92 93 //----------------------------------------------------------------------- 94 // The following properties may be used to create a Connection. 95 //----------------------------------------------------------------------- 96 97 /** 98 * Retrieves the url property this <code>RowSet</code> object will use to 99 * create a connection if it uses the <code>DriverManager</code> 100 * instead of a <code>DataSource</code> object to establish the connection. 101 * The default value is <code>null</code>. 102 * 103 * @return a string url 104 * @exception SQLException if a database access error occurs 105 * @see #setUrl 106 */ 107 String getUrl() throws SQLException; 108 109 /** 110 * Sets the URL this <code>RowSet</code> object will use when it uses the 111 * <code>DriverManager</code> to create a connection. 112 * 113 * Setting this property is optional. If a URL is used, a JDBC driver 114 * that accepts the URL must be loaded before the 115 * rowset is used to connect to a database. The rowset will use the URL 116 * internally to create a database connection when reading or writing 117 * data. Either a URL or a data source name is used to create a 118 * connection, whichever was set to non null value most recently. 119 * 120 * @param url a string value; may be <code>null</code> 121 * @exception SQLException if a database access error occurs 122 * @see #getUrl 123 */ 124 void setUrl(String url) throws SQLException; 125 126 /** 127 * Retrieves the logical name that identifies the data source for this 128 * <code>RowSet</code> object. 129 * 130 * @return a data source name 131 * @see #setDataSourceName 132 * @see #setUrl 133 */ 134 String getDataSourceName(); 135 136 /** 137 * Sets the data source name property for this <code>RowSet</code> object to the 138 * given <code>String</code>. 139 * <P> 140 * The value of the data source name property can be used to do a lookup of 141 * a <code>DataSource</code> object that has been registered with a naming 142 * service. After being retrieved, the <code>DataSource</code> object can be 143 * used to create a connection to the data source that it represents. 144 * 145 * @param name the logical name of the data source for this <code>RowSet</code> 146 * object; may be <code>null</code> 147 * @exception SQLException if a database access error occurs 148 * @see #getDataSourceName 149 */ 150 void setDataSourceName(String name) throws SQLException; 151 152 /** 153 * Retrieves the username used to create a database connection for this 154 * <code>RowSet</code> object. 155 * The username property is set at run time before calling the method 156 * <code>execute</code>. It is 157 * not usually part of the serialized state of a <code>RowSet</code> object. 158 * 159 * @return the username property 160 * @see #setUsername 161 */ 162 String getUsername(); 163 164 /** 165 * Sets the username property for this <code>RowSet</code> object to the 166 * given <code>String</code>. 167 * 168 * @param name a user name 169 * @exception SQLException if a database access error occurs 170 * @see #getUsername 171 */ 172 void setUsername(String name) throws SQLException; 173 174 /** 175 * Retrieves the password used to create a database connection. 176 * The password property is set at run time before calling the method 177 * <code>execute</code>. It is not usually part of the serialized state 178 * of a <code>RowSet</code> object. 179 * 180 * @return the password for making a database connection 181 * @see #setPassword 182 */ 183 String getPassword(); 184 185 /** 186 * Sets the database password for this <code>RowSet</code> object to 187 * the given <code>String</code>. 188 * 189 * @param password the password string 190 * @exception SQLException if a database access error occurs 191 * @see #getPassword 192 */ 193 void setPassword(String password) throws SQLException; 194 195 /** 196 * Retrieves the transaction isolation level set for this 197 * <code>RowSet</code> object. 198 * 199 * @return the transaction isolation level; one of 200 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>, 201 * <code>Connection.TRANSACTION_READ_COMMITTED</code>, 202 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or 203 * <code>Connection.TRANSACTION_SERIALIZABLE</code> 204 * @see #setTransactionIsolation 205 */ 206 int getTransactionIsolation(); 207 208 /** 209 * Sets the transaction isolation level for this <code>RowSet</code> object. 210 * 211 * @param level the transaction isolation level; one of 212 * <code>Connection.TRANSACTION_READ_UNCOMMITTED</code>, 213 * <code>Connection.TRANSACTION_READ_COMMITTED</code>, 214 * <code>Connection.TRANSACTION_REPEATABLE_READ</code>, or 215 * <code>Connection.TRANSACTION_SERIALIZABLE</code> 216 * @exception SQLException if a database access error occurs 217 * @see #getTransactionIsolation 218 */ 219 void setTransactionIsolation(int level) throws SQLException; 220 221 /** 222 * Retrieves the <code>Map</code> object associated with this 223 * <code>RowSet</code> object, which specifies the custom mapping 224 * of SQL user-defined types, if any. The default is for the 225 * type map to be empty. 226 * 227 * @return a <code>java.util.Map</code> object containing the names of 228 * SQL user-defined types and the Java classes to which they are 229 * to be mapped 230 * 231 * @exception SQLException if a database access error occurs 232 * @see #setTypeMap 233 */ 234 java.util.Map<String,Class<?>> getTypeMap() throws SQLException; 235 236 /** 237 * Installs the given <code>java.util.Map</code> object as the default 238 * type map for this <code>RowSet</code> object. This type map will be 239 * used unless another type map is supplied as a method parameter. 240 * 241 * @param map a <code>java.util.Map</code> object containing the names of 242 * SQL user-defined types and the Java classes to which they are 243 * to be mapped 244 * @exception SQLException if a database access error occurs 245 * @see #getTypeMap 246 */ 247 void setTypeMap(java.util.Map<String,Class<?>> map) throws SQLException; 248 249 //----------------------------------------------------------------------- 250 // The following properties may be used to create a Statement. 251 //----------------------------------------------------------------------- 252 253 /** 254 * Retrieves this <code>RowSet</code> object's command property. 255 * 256 * The command property contains a command string, which must be an SQL 257 * query, that can be executed to fill the rowset with data. 258 * The default value is <code>null</code>. 259 * 260 * @return the command string; may be <code>null</code> 261 * @see #setCommand 262 */ 263 String getCommand(); 264 265 /** 266 * Sets this <code>RowSet</code> object's command property to the given 267 * SQL query. 268 * 269 * This property is optional 270 * when a rowset gets its data from a data source that does not support 271 * commands, such as a spreadsheet. 272 * 273 * @param cmd the SQL query that will be used to get the data for this 274 * <code>RowSet</code> object; may be <code>null</code> 275 * @exception SQLException if a database access error occurs 276 * @see #getCommand 277 */ 278 void setCommand(String cmd) throws SQLException; 279 280 /** 281 * Retrieves whether this <code>RowSet</code> object is read-only. 282 * If updates are possible, the default is for a rowset to be 283 * updatable. 284 * <P> 285 * Attempts to update a read-only rowset will result in an 286 * <code>SQLException</code> being thrown. 287 * 288 * @return <code>true</code> if this <code>RowSet</code> object is 289 * read-only; <code>false</code> if it is updatable 290 * @see #setReadOnly 291 */ 292 boolean isReadOnly(); 293 294 /** 295 * Sets whether this <code>RowSet</code> object is read-only to the 296 * given <code>boolean</code>. 297 * 298 * @param value <code>true</code> if read-only; <code>false</code> if 299 * updatable 300 * @exception SQLException if a database access error occurs 301 * @see #isReadOnly 302 */ 303 void setReadOnly(boolean value) throws SQLException; 304 305 /** 306 * Retrieves the maximum number of bytes that may be returned 307 * for certain column values. 308 * This limit applies only to <code>BINARY</code>, 309 * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>, 310 * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code> 311 * and <code>NVARCHAR</code> columns. 312 * If the limit is exceeded, the excess data is silently discarded. 313 * 314 * @return the current maximum column size limit; zero means that there 315 * is no limit 316 * @exception SQLException if a database access error occurs 317 * @see #setMaxFieldSize 318 */ 319 int getMaxFieldSize() throws SQLException; 320 321 /** 322 * Sets the maximum number of bytes that can be returned for a column 323 * value to the given number of bytes. 324 * This limit applies only to <code>BINARY</code>, 325 * <code>VARBINARY</code>, <code>LONGVARBINARYBINARY</code>, <code>CHAR</code>, 326 * <code>VARCHAR</code>, <code>LONGVARCHAR</code>, <code>NCHAR</code> 327 * and <code>NVARCHAR</code> columns. 328 * If the limit is exceeded, the excess data is silently discarded. 329 * For maximum portability, use values greater than 256. 330 * 331 * @param max the new max column size limit in bytes; zero means unlimited 332 * @exception SQLException if a database access error occurs 333 * @see #getMaxFieldSize 334 */ 335 void setMaxFieldSize(int max) throws SQLException; 336 337 /** 338 * Retrieves the maximum number of rows that this <code>RowSet</code> 339 * object can contain. 340 * If the limit is exceeded, the excess rows are silently dropped. 341 * 342 * @return the current maximum number of rows that this <code>RowSet</code> 343 * object can contain; zero means unlimited 344 * @exception SQLException if a database access error occurs 345 * @see #setMaxRows 346 */ 347 int getMaxRows() throws SQLException; 348 349 /** 350 * Sets the maximum number of rows that this <code>RowSet</code> 351 * object can contain to the specified number. 352 * If the limit is exceeded, the excess rows are silently dropped. 353 * 354 * @param max the new maximum number of rows; zero means unlimited 355 * @exception SQLException if a database access error occurs 356 * @see #getMaxRows 357 */ 358 void setMaxRows(int max) throws SQLException; 359 360 /** 361 * Retrieves whether escape processing is enabled for this 362 * <code>RowSet</code> object. 363 * If escape scanning is enabled, which is the default, the driver will do 364 * escape substitution before sending an SQL statement to the database. 365 * 366 * @return <code>true</code> if escape processing is enabled; 367 * <code>false</code> if it is disabled 368 * @exception SQLException if a database access error occurs 369 * @see #setEscapeProcessing 370 */ 371 boolean getEscapeProcessing() throws SQLException; 372 373 /** 374 * Sets escape processing for this <code>RowSet</code> object on or 375 * off. If escape scanning is on (the default), the driver will do 376 * escape substitution before sending an SQL statement to the database. 377 * 378 * @param enable <code>true</code> to enable escape processing; 379 * <code>false</code> to disable it 380 * @exception SQLException if a database access error occurs 381 * @see #getEscapeProcessing 382 */ 383 void setEscapeProcessing(boolean enable) throws SQLException; 384 385 /** 386 * Retrieves the maximum number of seconds the driver will wait for 387 * a statement to execute. 388 * If this limit is exceeded, an <code>SQLException</code> is thrown. 389 * 390 * @return the current query timeout limit in seconds; zero means 391 * unlimited 392 * @exception SQLException if a database access error occurs 393 * @see #setQueryTimeout 394 */ 395 int getQueryTimeout() throws SQLException; 396 397 /** 398 * Sets the maximum time the driver will wait for 399 * a statement to execute to the given number of seconds. 400 * If this limit is exceeded, an <code>SQLException</code> is thrown. 401 * 402 * @param seconds the new query timeout limit in seconds; zero means 403 * that there is no limit 404 * @exception SQLException if a database access error occurs 405 * @see #getQueryTimeout 406 */ 407 void setQueryTimeout(int seconds) throws SQLException; 408 409 /** 410 * Sets the type of this <code>RowSet</code> object to the given type. 411 * This method is used to change the type of a rowset, which is by 412 * default read-only and non-scrollable. 413 * 414 * @param type one of the <code>ResultSet</code> constants specifying a type: 415 * <code>ResultSet.TYPE_FORWARD_ONLY</code>, 416 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or 417 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code> 418 * @exception SQLException if a database access error occurs 419 * @see java.sql.ResultSet#getType 420 */ 421 void setType(int type) throws SQLException; 422 423 /** 424 * Sets the concurrency of this <code>RowSet</code> object to the given 425 * concurrency level. This method is used to change the concurrency level 426 * of a rowset, which is by default <code>ResultSet.CONCUR_READ_ONLY</code> 427 * 428 * @param concurrency one of the <code>ResultSet</code> constants specifying a 429 * concurrency level: <code>ResultSet.CONCUR_READ_ONLY</code> or 430 * <code>ResultSet.CONCUR_UPDATABLE</code> 431 * @exception SQLException if a database access error occurs 432 * @see ResultSet#getConcurrency 433 */ 434 void setConcurrency(int concurrency) throws SQLException; 435 436 //----------------------------------------------------------------------- 437 // Parameters 438 //----------------------------------------------------------------------- 439 440 /** 441 * The <code>RowSet</code> setter methods are used to set any input parameters 442 * needed by the <code>RowSet</code> object's command. 443 * Parameters are set at run time, as opposed to design time. 444 */ 445 446 /** 447 * Sets the designated parameter in this <code>RowSet</code> object's SQL 448 * command to SQL <code>NULL</code>. 449 * 450 * <P><B>Note:</B> You must specify the parameter's SQL type. 451 * 452 * @param parameterIndex the first parameter is 1, the second is 2, ... 453 * @param sqlType a SQL type code defined by <code>java.sql.Types</code> 454 * @exception SQLException if a database access error occurs 455 */ 456 void setNull(int parameterIndex, int sqlType) throws SQLException; 457 458 /** 459 * Sets the designated parameter to SQL <code>NULL</code>. 460 * 461 * <P><B>Note:</B> You must specify the parameter's SQL type. 462 * 463 * @param parameterName the name of the parameter 464 * @param sqlType the SQL type code defined in <code>java.sql.Types</code> 465 * @exception SQLException if a database access error occurs or 466 * this method is called on a closed <code>CallableStatement</code> 467 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 468 * this method 469 * @since 1.4 470 */ 471 void setNull(String parameterName, int sqlType) throws SQLException; 472 473 /** 474 * Sets the designated parameter in this <code>RowSet</code> object's SQL 475 * command to SQL <code>NULL</code>. This version of the method <code>setNull</code> 476 * should be used for SQL user-defined types (UDTs) and <code>REF</code> type 477 * parameters. Examples of UDTs include: <code>STRUCT</code>, <code>DISTINCT</code>, 478 * <code>JAVA_OBJECT</code>, and named array types. 479 * 480 * <P><B>Note:</B> To be portable, applications must give the 481 * SQL type code and the fully qualified SQL type name when specifying 482 * a NULL UDT or <code>REF</code> parameter. In the case of a UDT, 483 * the name is the type name of the parameter itself. For a <code>REF</code> 484 * parameter, the name is the type name of the referenced type. If 485 * a JDBC driver does not need the type code or type name information, 486 * it may ignore it. 487 * 488 * Although it is intended for UDT and <code>REF</code> parameters, 489 * this method may be used to set a null parameter of any JDBC type. 490 * If the parameter does not have a user-defined or <code>REF</code> type, 491 * the typeName parameter is ignored. 492 * 493 * 494 * @param paramIndex the first parameter is 1, the second is 2, ... 495 * @param sqlType a value from <code>java.sql.Types</code> 496 * @param typeName the fully qualified name of an SQL UDT or the type 497 * name of the SQL structured type being referenced by a <code>REF</code> 498 * type; ignored if the parameter is not a UDT or <code>REF</code> type 499 * @exception SQLException if a database access error occurs 500 */ 501 void setNull (int paramIndex, int sqlType, String typeName) 502 throws SQLException; 503 504 /** 505 * Sets the designated parameter to SQL <code>NULL</code>. 506 * This version of the method <code>setNull</code> should 507 * be used for user-defined types and REF type parameters. Examples 508 * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and 509 * named array types. 510 * 511 * <P><B>Note:</B> To be portable, applications must give the 512 * SQL type code and the fully-qualified SQL type name when specifying 513 * a NULL user-defined or REF parameter. In the case of a user-defined type 514 * the name is the type name of the parameter itself. For a REF 515 * parameter, the name is the type name of the referenced type. If 516 * a JDBC driver does not need the type code or type name information, 517 * it may ignore it. 518 * 519 * Although it is intended for user-defined and Ref parameters, 520 * this method may be used to set a null parameter of any JDBC type. 521 * If the parameter does not have a user-defined or REF type, the given 522 * typeName is ignored. 523 * 524 * 525 * @param parameterName the name of the parameter 526 * @param sqlType a value from <code>java.sql.Types</code> 527 * @param typeName the fully-qualified name of an SQL user-defined type; 528 * ignored if the parameter is not a user-defined type or 529 * SQL <code>REF</code> value 530 * @exception SQLException if a database access error occurs or 531 * this method is called on a closed <code>CallableStatement</code> 532 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 533 * this method 534 * @since 1.4 535 */ 536 void setNull (String parameterName, int sqlType, String typeName) 537 throws SQLException; 538 539 /** 540 * Sets the designated parameter in this <code>RowSet</code> object's command 541 * to the given Java <code>boolean</code> value. The driver converts this to 542 * an SQL <code>BIT</code> value before sending it to the database. 543 * 544 * @param parameterIndex the first parameter is 1, the second is 2, ... 545 * @param x the parameter value 546 * @exception SQLException if a database access error occurs 547 */ 548 void setBoolean(int parameterIndex, boolean x) throws SQLException; 549 550 /** 551 * Sets the designated parameter to the given Java <code>boolean</code> value. 552 * The driver converts this 553 * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database. 554 * 555 * @param parameterName the name of the parameter 556 * @param x the parameter value 557 * @exception SQLException if a database access error occurs or 558 * this method is called on a closed <code>CallableStatement</code> 559 * @see #getBoolean 560 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 561 * this method 562 * @since 1.4 563 */ 564 void setBoolean(String parameterName, boolean x) throws SQLException; 565 566 /** 567 * Sets the designated parameter in this <code>RowSet</code> object's command 568 * to the given Java <code>byte</code> value. The driver converts this to 569 * an SQL <code>TINYINT</code> value before sending it to the database. 570 * 571 * @param parameterIndex the first parameter is 1, the second is 2, ... 572 * @param x the parameter value 573 * @exception SQLException if a database access error occurs 574 */ 575 void setByte(int parameterIndex, byte x) throws SQLException; 576 577 /** 578 * Sets the designated parameter to the given Java <code>byte</code> value. 579 * The driver converts this 580 * to an SQL <code>TINYINT</code> value when it sends it to the database. 581 * 582 * @param parameterName the name of the parameter 583 * @param x the parameter value 584 * @exception SQLException if a database access error occurs or 585 * this method is called on a closed <code>CallableStatement</code> 586 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 587 * this method 588 * @see #getByte 589 * @since 1.4 590 */ 591 void setByte(String parameterName, byte x) throws SQLException; 592 593 /** 594 * Sets the designated parameter in this <code>RowSet</code> object's command 595 * to the given Java <code>short</code> value. The driver converts this to 596 * an SQL <code>SMALLINT</code> value before sending it to the database. 597 * 598 * @param parameterIndex the first parameter is 1, the second is 2, ... 599 * @param x the parameter value 600 * @exception SQLException if a database access error occurs 601 */ 602 void setShort(int parameterIndex, short x) throws SQLException; 603 604 /** 605 * Sets the designated parameter to the given Java <code>short</code> value. 606 * The driver converts this 607 * to an SQL <code>SMALLINT</code> value when it sends it to the database. 608 * 609 * @param parameterName the name of the parameter 610 * @param x the parameter value 611 * @exception SQLException if a database access error occurs or 612 * this method is called on a closed <code>CallableStatement</code> 613 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 614 * this method 615 * @see #getShort 616 * @since 1.4 617 */ 618 void setShort(String parameterName, short x) throws SQLException; 619 620 /** 621 * Sets the designated parameter in this <code>RowSet</code> object's command 622 * to the given Java <code>int</code> value. The driver converts this to 623 * an SQL <code>INTEGER</code> value before sending it to the database. 624 * 625 * @param parameterIndex the first parameter is 1, the second is 2, ... 626 * @param x the parameter value 627 * @exception SQLException if a database access error occurs 628 */ 629 void setInt(int parameterIndex, int x) throws SQLException; 630 631 /** 632 * Sets the designated parameter to the given Java <code>int</code> value. 633 * The driver converts this 634 * to an SQL <code>INTEGER</code> value when it sends it to the database. 635 * 636 * @param parameterName the name of the parameter 637 * @param x the parameter value 638 * @exception SQLException if a database access error occurs or 639 * this method is called on a closed <code>CallableStatement</code> 640 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 641 * this method 642 * @see #getInt 643 * @since 1.4 644 */ 645 void setInt(String parameterName, int x) throws SQLException; 646 647 /** 648 * Sets the designated parameter in this <code>RowSet</code> object's command 649 * to the given Java <code>long</code> value. The driver converts this to 650 * an SQL <code>BIGINT</code> value before sending it to the database. 651 * 652 * @param parameterIndex the first parameter is 1, the second is 2, ... 653 * @param x the parameter value 654 * @exception SQLException if a database access error occurs 655 */ 656 void setLong(int parameterIndex, long x) throws SQLException; 657 658 /** 659 * Sets the designated parameter to the given Java <code>long</code> value. 660 * The driver converts this 661 * to an SQL <code>BIGINT</code> value when it sends it to the database. 662 * 663 * @param parameterName the name of the parameter 664 * @param x the parameter value 665 * @exception SQLException if a database access error occurs or 666 * this method is called on a closed <code>CallableStatement</code> 667 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 668 * this method 669 * @see #getLong 670 * @since 1.4 671 */ 672 void setLong(String parameterName, long x) throws SQLException; 673 674 /** 675 * Sets the designated parameter in this <code>RowSet</code> object's command 676 * to the given Java <code>float</code> value. The driver converts this to 677 * an SQL <code>REAL</code> value before sending it to the database. 678 * 679 * @param parameterIndex the first parameter is 1, the second is 2, ... 680 * @param x the parameter value 681 * @exception SQLException if a database access error occurs 682 */ 683 void setFloat(int parameterIndex, float x) throws SQLException; 684 685 /** 686 * Sets the designated parameter to the given Java <code>float</code> value. 687 * The driver converts this 688 * to an SQL <code>FLOAT</code> value when it sends it to the database. 689 * 690 * @param parameterName the name of the parameter 691 * @param x the parameter value 692 * @exception SQLException if a database access error occurs or 693 * this method is called on a closed <code>CallableStatement</code> 694 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 695 * this method 696 * @see #getFloat 697 * @since 1.4 698 */ 699 void setFloat(String parameterName, float x) throws SQLException; 700 701 /** 702 * Sets the designated parameter in this <code>RowSet</code> object's command 703 * to the given Java <code>double</code> value. The driver converts this to 704 * an SQL <code>DOUBLE</code> value before sending it to the database. 705 * 706 * @param parameterIndex the first parameter is 1, the second is 2, ... 707 * @param x the parameter value 708 * @exception SQLException if a database access error occurs 709 */ 710 void setDouble(int parameterIndex, double x) throws SQLException; 711 712 /** 713 * Sets the designated parameter to the given Java <code>double</code> value. 714 * The driver converts this 715 * to an SQL <code>DOUBLE</code> value when it sends it to the database. 716 * 717 * @param parameterName the name of the parameter 718 * @param x the parameter value 719 * @exception SQLException if a database access error occurs or 720 * this method is called on a closed <code>CallableStatement</code> 721 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 722 * this method 723 * @see #getDouble 724 * @since 1.4 725 */ 726 void setDouble(String parameterName, double x) throws SQLException; 727 728 /** 729 * Sets the designated parameter in this <code>RowSet</code> object's command 730 * to the given {@code java.math.BigDecimal} value. 731 * The driver converts this to 732 * an SQL <code>NUMERIC</code> value before sending it to the database. 733 * 734 * @param parameterIndex the first parameter is 1, the second is 2, ... 735 * @param x the parameter value 736 * @exception SQLException if a database access error occurs 737 */ 738 void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException; 739 740 /** 741 * Sets the designated parameter to the given 742 * <code>java.math.BigDecimal</code> value. 743 * The driver converts this to an SQL <code>NUMERIC</code> value when 744 * it sends it to the database. 745 * 746 * @param parameterName the name of the parameter 747 * @param x the parameter value 748 * @exception SQLException if a database access error occurs or 749 * this method is called on a closed <code>CallableStatement</code> 750 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 751 * this method 752 * @see #getBigDecimal 753 * @since 1.4 754 */ 755 void setBigDecimal(String parameterName, BigDecimal x) throws SQLException; 756 757 /** 758 * Sets the designated parameter in this <code>RowSet</code> object's command 759 * to the given Java <code>String</code> value. Before sending it to the 760 * database, the driver converts this to an SQL <code>VARCHAR</code> or 761 * <code>LONGVARCHAR</code> value, depending on the argument's size relative 762 * to the driver's limits on <code>VARCHAR</code> values. 763 * 764 * @param parameterIndex the first parameter is 1, the second is 2, ... 765 * @param x the parameter value 766 * @exception SQLException if a database access error occurs 767 */ 768 void setString(int parameterIndex, String x) throws SQLException; 769 770 /** 771 * Sets the designated parameter to the given Java <code>String</code> value. 772 * The driver converts this 773 * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value 774 * (depending on the argument's 775 * size relative to the driver's limits on <code>VARCHAR</code> values) 776 * when it sends it to the database. 777 * 778 * @param parameterName the name of the parameter 779 * @param x the parameter value 780 * @exception SQLException if a database access error occurs or 781 * this method is called on a closed <code>CallableStatement</code> 782 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 783 * this method 784 * @see #getString 785 * @since 1.4 786 */ 787 void setString(String parameterName, String x) throws SQLException; 788 789 /** 790 * Sets the designated parameter in this <code>RowSet</code> object's command 791 * to the given Java array of <code>byte</code> values. Before sending it to the 792 * database, the driver converts this to an SQL <code>VARBINARY</code> or 793 * <code>LONGVARBINARY</code> value, depending on the argument's size relative 794 * to the driver's limits on <code>VARBINARY</code> values. 795 * 796 * @param parameterIndex the first parameter is 1, the second is 2, ... 797 * @param x the parameter value 798 * @exception SQLException if a database access error occurs 799 */ 800 void setBytes(int parameterIndex, byte x[]) throws SQLException; 801 802 /** 803 * Sets the designated parameter to the given Java array of bytes. 804 * The driver converts this to an SQL <code>VARBINARY</code> or 805 * <code>LONGVARBINARY</code> (depending on the argument's size relative 806 * to the driver's limits on <code>VARBINARY</code> values) when it sends 807 * it to the database. 808 * 809 * @param parameterName the name of the parameter 810 * @param x the parameter value 811 * @exception SQLException if a database access error occurs or 812 * this method is called on a closed <code>CallableStatement</code> 813 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 814 * this method 815 * @see #getBytes 816 * @since 1.4 817 */ 818 void setBytes(String parameterName, byte x[]) throws SQLException; 819 820 /** 821 * Sets the designated parameter in this <code>RowSet</code> object's command 822 * to the given <code>java.sql.Date</code> value. The driver converts this to 823 * an SQL <code>DATE</code> value before sending it to the database, using the 824 * default <code>java.util.Calendar</code> to calculate the date. 825 * 826 * @param parameterIndex the first parameter is 1, the second is 2, ... 827 * @param x the parameter value 828 * @exception SQLException if a database access error occurs 829 */ 830 void setDate(int parameterIndex, java.sql.Date x) throws SQLException; 831 832 /** 833 * Sets the designated parameter in this <code>RowSet</code> object's command 834 * to the given <code>java.sql.Time</code> value. The driver converts this to 835 * an SQL <code>TIME</code> value before sending it to the database, using the 836 * default <code>java.util.Calendar</code> to calculate it. 837 * 838 * @param parameterIndex the first parameter is 1, the second is 2, ... 839 * @param x the parameter value 840 * @exception SQLException if a database access error occurs 841 */ 842 void setTime(int parameterIndex, java.sql.Time x) throws SQLException; 843 844 /** 845 * Sets the designated parameter in this <code>RowSet</code> object's command 846 * to the given <code>java.sql.Timestamp</code> value. The driver converts this to 847 * an SQL <code>TIMESTAMP</code> value before sending it to the database, using the 848 * default <code>java.util.Calendar</code> to calculate it. 849 * 850 * @param parameterIndex the first parameter is 1, the second is 2, ... 851 * @param x the parameter value 852 * @exception SQLException if a database access error occurs 853 */ 854 void setTimestamp(int parameterIndex, java.sql.Timestamp x) 855 throws SQLException; 856 857 /** 858 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value. 859 * The driver 860 * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the 861 * database. 862 * 863 * @param parameterName the name of the parameter 864 * @param x the parameter value 865 * @exception SQLException if a database access error occurs or 866 * this method is called on a closed <code>CallableStatement</code> 867 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 868 * this method 869 * @see #getTimestamp 870 * @since 1.4 871 */ 872 void setTimestamp(String parameterName, java.sql.Timestamp x) 873 throws SQLException; 874 875 /** 876 * Sets the designated parameter in this <code>RowSet</code> object's command 877 * to the given <code>java.io.InputStream</code> value. 878 * It may be more practical to send a very large ASCII value via a 879 * <code>java.io.InputStream</code> rather than as a <code>LONGVARCHAR</code> 880 * parameter. The driver will read the data from the stream 881 * as needed until it reaches end-of-file. 882 * 883 * <P><B>Note:</B> This stream object can either be a standard 884 * Java stream object or your own subclass that implements the 885 * standard interface. 886 * 887 * @param parameterIndex the first parameter is 1, the second is 2, ... 888 * @param x the Java input stream that contains the ASCII parameter value 889 * @param length the number of bytes in the stream 890 * @exception SQLException if a database access error occurs 891 */ 892 void setAsciiStream(int parameterIndex, java.io.InputStream x, int length) 893 throws SQLException; 894 895 /** 896 * Sets the designated parameter to the given input stream, which will have 897 * the specified number of bytes. 898 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 899 * parameter, it may be more practical to send it via a 900 * <code>java.io.InputStream</code>. Data will be read from the stream 901 * as needed until end-of-file is reached. The JDBC driver will 902 * do any necessary conversion from ASCII to the database char format. 903 * 904 * <P><B>Note:</B> This stream object can either be a standard 905 * Java stream object or your own subclass that implements the 906 * standard interface. 907 * 908 * @param parameterName the name of the parameter 909 * @param x the Java input stream that contains the ASCII parameter value 910 * @param length the number of bytes in the stream 911 * @exception SQLException if a database access error occurs or 912 * this method is called on a closed <code>CallableStatement</code> 913 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 914 * this method 915 * @since 1.4 916 */ 917 void setAsciiStream(String parameterName, java.io.InputStream x, int length) 918 throws SQLException; 919 920 /** 921 * Sets the designated parameter in this <code>RowSet</code> object's command 922 * to the given <code>java.io.InputStream</code> value. 923 * It may be more practical to send a very large binary value via a 924 * <code>java.io.InputStream</code> rather than as a <code>LONGVARBINARY</code> 925 * parameter. The driver will read the data from the stream 926 * as needed until it reaches end-of-file. 927 * 928 * <P><B>Note:</B> This stream object can either be a standard 929 * Java stream object or your own subclass that implements the 930 * standard interface. 931 * 932 * @param parameterIndex the first parameter is 1, the second is 2, ... 933 * @param x the java input stream which contains the binary parameter value 934 * @param length the number of bytes in the stream 935 * @exception SQLException if a database access error occurs 936 */ 937 void setBinaryStream(int parameterIndex, java.io.InputStream x, 938 int length) throws SQLException; 939 940 /** 941 * Sets the designated parameter to the given input stream, which will have 942 * the specified number of bytes. 943 * When a very large binary value is input to a <code>LONGVARBINARY</code> 944 * parameter, it may be more practical to send it via a 945 * <code>java.io.InputStream</code> object. The data will be read from the stream 946 * as needed until end-of-file is reached. 947 * 948 * <P><B>Note:</B> This stream object can either be a standard 949 * Java stream object or your own subclass that implements the 950 * standard interface. 951 * 952 * @param parameterName the name of the parameter 953 * @param x the java input stream which contains the binary parameter value 954 * @param length the number of bytes in the stream 955 * @exception SQLException if a database access error occurs or 956 * this method is called on a closed <code>CallableStatement</code> 957 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 958 * this method 959 * @since 1.4 960 */ 961 void setBinaryStream(String parameterName, java.io.InputStream x, 962 int length) throws SQLException; 963 964 /** 965 * Sets the designated parameter in this <code>RowSet</code> object's command 966 * to the given <code>java.io.Reader</code> value. 967 * It may be more practical to send a very large UNICODE value via a 968 * <code>java.io.Reader</code> rather than as a <code>LONGVARCHAR</code> 969 * parameter. The driver will read the data from the stream 970 * as needed until it reaches end-of-file. 971 * 972 * <P><B>Note:</B> This stream object can either be a standard 973 * Java stream object or your own subclass that implements the 974 * standard interface. 975 * 976 * @param parameterIndex the first parameter is 1, the second is 2, ... 977 * @param reader the {@code Reader} object that contains the UNICODE data 978 * to be set 979 * @param length the number of characters in the stream 980 * @exception SQLException if a database access error occurs 981 */ 982 void setCharacterStream(int parameterIndex, 983 Reader reader, 984 int length) throws SQLException; 985 986 /** 987 * Sets the designated parameter to the given {@code Reader} 988 * object, which is the given number of characters long. 989 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 990 * parameter, it may be more practical to send it via a 991 * <code>java.io.Reader</code> object. The data will be read from the stream 992 * as needed until end-of-file is reached. The JDBC driver will 993 * do any necessary conversion from UNICODE to the database char format. 994 * 995 * <P><B>Note:</B> This stream object can either be a standard 996 * Java stream object or your own subclass that implements the 997 * standard interface. 998 * 999 * @param parameterName the name of the parameter 1000 * @param reader the <code>java.io.Reader</code> object that 1001 * contains the UNICODE data used as the designated parameter 1002 * @param length the number of characters in the stream 1003 * @exception SQLException if a database access error occurs or 1004 * this method is called on a closed <code>CallableStatement</code> 1005 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1006 * this method 1007 * @since 1.4 1008 */ 1009 void setCharacterStream(String parameterName, 1010 java.io.Reader reader, 1011 int length) throws SQLException; 1012 1013 /** 1014 * Sets the designated parameter in this <code>RowSet</code> object's command 1015 * to the given input stream. 1016 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 1017 * parameter, it may be more practical to send it via a 1018 * <code>java.io.InputStream</code>. Data will be read from the stream 1019 * as needed until end-of-file is reached. The JDBC driver will 1020 * do any necessary conversion from ASCII to the database char format. 1021 * 1022 * <P><B>Note:</B> This stream object can either be a standard 1023 * Java stream object or your own subclass that implements the 1024 * standard interface. 1025 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1026 * it might be more efficient to use a version of 1027 * <code>setAsciiStream</code> which takes a length parameter. 1028 * 1029 * @param parameterIndex the first parameter is 1, the second is 2, ... 1030 * @param x the Java input stream that contains the ASCII parameter value 1031 * @exception SQLException if a database access error occurs or 1032 * this method is called on a closed <code>PreparedStatement</code> 1033 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1034 * @since 1.6 1035 */ 1036 void setAsciiStream(int parameterIndex, java.io.InputStream x) 1037 throws SQLException; 1038 1039 /** 1040 * Sets the designated parameter to the given input stream. 1041 * When a very large ASCII value is input to a <code>LONGVARCHAR</code> 1042 * parameter, it may be more practical to send it via a 1043 * <code>java.io.InputStream</code>. Data will be read from the stream 1044 * as needed until end-of-file is reached. The JDBC driver will 1045 * do any necessary conversion from ASCII to the database char format. 1046 * 1047 * <P><B>Note:</B> This stream object can either be a standard 1048 * Java stream object or your own subclass that implements the 1049 * standard interface. 1050 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1051 * it might be more efficient to use a version of 1052 * <code>setAsciiStream</code> which takes a length parameter. 1053 * 1054 * @param parameterName the name of the parameter 1055 * @param x the Java input stream that contains the ASCII parameter value 1056 * @exception SQLException if a database access error occurs or 1057 * this method is called on a closed <code>CallableStatement</code> 1058 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1059 * @since 1.6 1060 */ 1061 void setAsciiStream(String parameterName, java.io.InputStream x) 1062 throws SQLException; 1063 1064 /** 1065 * Sets the designated parameter in this <code>RowSet</code> object's command 1066 * to the given input stream. 1067 * When a very large binary value is input to a <code>LONGVARBINARY</code> 1068 * parameter, it may be more practical to send it via a 1069 * <code>java.io.InputStream</code> object. The data will be read from the 1070 * stream as needed until end-of-file is reached. 1071 * 1072 * <P><B>Note:</B> This stream object can either be a standard 1073 * Java stream object or your own subclass that implements the 1074 * standard interface. 1075 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1076 * it might be more efficient to use a version of 1077 * <code>setBinaryStream</code> which takes a length parameter. 1078 * 1079 * @param parameterIndex the first parameter is 1, the second is 2, ... 1080 * @param x the java input stream which contains the binary parameter value 1081 * @exception SQLException if a database access error occurs or 1082 * this method is called on a closed <code>PreparedStatement</code> 1083 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1084 * @since 1.6 1085 */ 1086 void setBinaryStream(int parameterIndex, java.io.InputStream x) 1087 throws SQLException; 1088 1089 /** 1090 * Sets the designated parameter to the given input stream. 1091 * When a very large binary value is input to a <code>LONGVARBINARY</code> 1092 * parameter, it may be more practical to send it via a 1093 * <code>java.io.InputStream</code> object. The data will be read from the 1094 * stream as needed until end-of-file is reached. 1095 * 1096 * <P><B>Note:</B> This stream object can either be a standard 1097 * Java stream object or your own subclass that implements the 1098 * standard interface. 1099 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1100 * it might be more efficient to use a version of 1101 * <code>setBinaryStream</code> which takes a length parameter. 1102 * 1103 * @param parameterName the name of the parameter 1104 * @param x the java input stream which contains the binary parameter value 1105 * @exception SQLException if a database access error occurs or 1106 * this method is called on a closed <code>CallableStatement</code> 1107 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1108 * @since 1.6 1109 */ 1110 void setBinaryStream(String parameterName, java.io.InputStream x) 1111 throws SQLException; 1112 1113 /** 1114 * Sets the designated parameter in this <code>RowSet</code> object's command 1115 * to the given {@code Reader} 1116 * object. 1117 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 1118 * parameter, it may be more practical to send it via a 1119 * <code>java.io.Reader</code> object. The data will be read from the stream 1120 * as needed until end-of-file is reached. The JDBC driver will 1121 * do any necessary conversion from UNICODE to the database char format. 1122 * 1123 * <P><B>Note:</B> This stream object can either be a standard 1124 * Java stream object or your own subclass that implements the 1125 * standard interface. 1126 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1127 * it might be more efficient to use a version of 1128 * <code>setCharacterStream</code> which takes a length parameter. 1129 * 1130 * @param parameterIndex the first parameter is 1, the second is 2, ... 1131 * @param reader the <code>java.io.Reader</code> object that contains the 1132 * Unicode data 1133 * @exception SQLException if a database access error occurs or 1134 * this method is called on a closed <code>PreparedStatement</code> 1135 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1136 * @since 1.6 1137 */ 1138 void setCharacterStream(int parameterIndex, 1139 java.io.Reader reader) throws SQLException; 1140 1141 /** 1142 * Sets the designated parameter to the given {@code Reader} 1143 * object. 1144 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code> 1145 * parameter, it may be more practical to send it via a 1146 * <code>java.io.Reader</code> object. The data will be read from the stream 1147 * as needed until end-of-file is reached. The JDBC driver will 1148 * do any necessary conversion from UNICODE to the database char format. 1149 * 1150 * <P><B>Note:</B> This stream object can either be a standard 1151 * Java stream object or your own subclass that implements the 1152 * standard interface. 1153 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1154 * it might be more efficient to use a version of 1155 * <code>setCharacterStream</code> which takes a length parameter. 1156 * 1157 * @param parameterName the name of the parameter 1158 * @param reader the <code>java.io.Reader</code> object that contains the 1159 * Unicode data 1160 * @exception SQLException if a database access error occurs or 1161 * this method is called on a closed <code>CallableStatement</code> 1162 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1163 * @since 1.6 1164 */ 1165 void setCharacterStream(String parameterName, 1166 java.io.Reader reader) throws SQLException; 1167 1168 /** 1169 * Sets the designated parameter in this <code>RowSet</code> object's command 1170 * to a {@code Reader} object. The 1171 * {@code Reader} reads the data till end-of-file is reached. The 1172 * driver does the necessary conversion from Java character format to 1173 * the national character set in the database. 1174 1175 * <P><B>Note:</B> This stream object can either be a standard 1176 * Java stream object or your own subclass that implements the 1177 * standard interface. 1178 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1179 * it might be more efficient to use a version of 1180 * <code>setNCharacterStream</code> which takes a length parameter. 1181 * 1182 * @param parameterIndex of the first parameter is 1, the second is 2, ... 1183 * @param value the parameter value 1184 * @throws SQLException if the driver does not support national 1185 * character sets; if the driver can detect that a data conversion 1186 * error could occur ; if a database access error occurs; or 1187 * this method is called on a closed <code>PreparedStatement</code> 1188 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1189 * @since 1.6 1190 */ 1191 void setNCharacterStream(int parameterIndex, Reader value) throws SQLException; 1192 1193 1194 1195 /** 1196 * Sets the designated parameter in this <code>RowSet</code> object's command 1197 * with the given Java <code>Object</code>. For integral values, the 1198 * <code>java.lang</code> equivalent objects should be used (for example, 1199 * an instance of the class <code>Integer</code> for an <code>int</code>). 1200 * 1201 * If the second argument is an <code>InputStream</code> then the stream must contain 1202 * the number of bytes specified by scaleOrLength. If the second argument is a 1203 * {@code Reader} then the {@code Reader} must contain the number of characters specified 1204 * by scaleOrLength. If these conditions are not true the driver will generate a 1205 * <code>SQLException</code> when the prepared statement is executed. 1206 * 1207 * <p>The given Java object will be converted to the targetSqlType 1208 * before being sent to the database. 1209 * <P> 1210 * If the object is of a class implementing <code>SQLData</code>, 1211 * the rowset should call the method <code>SQLData.writeSQL</code> 1212 * to write the object to an <code>SQLOutput</code> data stream. 1213 * If, on the other hand, the object is of a class implementing 1214 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1215 * <code>Struct</code>, <code>java.net.URL</code>, 1216 * or <code>Array</code>, the driver should pass it to the database as a 1217 * value of the corresponding SQL type. 1218 * 1219 * 1220 * <p>Note that this method may be used to pass database-specific 1221 * abstract data types. 1222 * 1223 * @param parameterIndex the first parameter is 1, the second is 2, ... 1224 * @param x the object containing the input parameter value 1225 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>) 1226 * to be sent to the database. The scale argument may further qualify this 1227 * type. 1228 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code> 1229 * or <code>java.sql.Types.NUMERIC types</code>, 1230 * this is the number of digits after the decimal point. For 1231 * Java Object types <code>InputStream</code> and {@code Reader}, 1232 * this is the length 1233 * of the data in the stream or {@code Reader}. For all other types, 1234 * this value will be ignored. 1235 * @exception SQLException if a database access error occurs 1236 * @see java.sql.Types 1237 */ 1238 void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) 1239 throws SQLException; 1240 1241 /** 1242 * Sets the value of the designated parameter with the given object. The second 1243 * argument must be an object type; for integral values, the 1244 * <code>java.lang</code> equivalent objects should be used. 1245 * 1246 * <p>The given Java object will be converted to the given targetSqlType 1247 * before being sent to the database. 1248 * 1249 * If the object has a custom mapping (is of a class implementing the 1250 * interface <code>SQLData</code>), 1251 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it 1252 * to the SQL data stream. 1253 * If, on the other hand, the object is of a class implementing 1254 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1255 * <code>Struct</code>, <code>java.net.URL</code>, 1256 * or <code>Array</code>, the driver should pass it to the database as a 1257 * value of the corresponding SQL type. 1258 * <P> 1259 * Note that this method may be used to pass database- 1260 * specific abstract data types. 1261 * 1262 * @param parameterName the name of the parameter 1263 * @param x the object containing the input parameter value 1264 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 1265 * sent to the database. The scale argument may further qualify this type. 1266 * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types, 1267 * this is the number of digits after the decimal point. For all other 1268 * types, this value will be ignored. 1269 * @exception SQLException if a database access error occurs or 1270 * this method is called on a closed <code>CallableStatement</code> 1271 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is 1272 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 1273 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 1274 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 1275 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 1276 * or <code>STRUCT</code> data type and the JDBC driver does not support 1277 * this data type 1278 * @see Types 1279 * @see #getObject 1280 * @since 1.4 1281 */ 1282 void setObject(String parameterName, Object x, int targetSqlType, int scale) 1283 throws SQLException; 1284 1285 /** 1286 * Sets the designated parameter in this <code>RowSet</code> object's command 1287 * with a Java <code>Object</code>. For integral values, the 1288 * <code>java.lang</code> equivalent objects should be used. 1289 * This method is like <code>setObject</code> above, but the scale used is the scale 1290 * of the second parameter. Scalar values have a scale of zero. Literal 1291 * values have the scale present in the literal. 1292 * <P> 1293 * Even though it is supported, it is not recommended that this method 1294 * be called with floating point input values. 1295 * 1296 * @param parameterIndex the first parameter is 1, the second is 2, ... 1297 * @param x the object containing the input parameter value 1298 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>) 1299 * to be sent to the database 1300 * @exception SQLException if a database access error occurs 1301 */ 1302 void setObject(int parameterIndex, Object x, 1303 int targetSqlType) throws SQLException; 1304 1305 /** 1306 * Sets the value of the designated parameter with the given object. 1307 * This method is like the method <code>setObject</code> 1308 * above, except that it assumes a scale of zero. 1309 * 1310 * @param parameterName the name of the parameter 1311 * @param x the object containing the input parameter value 1312 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 1313 * sent to the database 1314 * @exception SQLException if a database access error occurs or 1315 * this method is called on a closed <code>CallableStatement</code> 1316 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is 1317 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 1318 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 1319 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 1320 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 1321 * or <code>STRUCT</code> data type and the JDBC driver does not support 1322 * this data type 1323 * @see #getObject 1324 * @since 1.4 1325 */ 1326 void setObject(String parameterName, Object x, int targetSqlType) 1327 throws SQLException; 1328 1329 /** 1330 * Sets the value of the designated parameter with the given object. 1331 * The second parameter must be of type <code>Object</code>; therefore, the 1332 * <code>java.lang</code> equivalent objects should be used for built-in types. 1333 * 1334 * <p>The JDBC specification specifies a standard mapping from 1335 * Java <code>Object</code> types to SQL types. The given argument 1336 * will be converted to the corresponding SQL type before being 1337 * sent to the database. 1338 * 1339 * <p>Note that this method may be used to pass database- 1340 * specific abstract data types, by using a driver-specific Java 1341 * type. 1342 * 1343 * If the object is of a class implementing the interface <code>SQLData</code>, 1344 * the JDBC driver should call the method <code>SQLData.writeSQL</code> 1345 * to write it to the SQL data stream. 1346 * If, on the other hand, the object is of a class implementing 1347 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1348 * <code>Struct</code>, <code>java.net.URL</code>, 1349 * or <code>Array</code>, the driver should pass it to the database as a 1350 * value of the corresponding SQL type. 1351 * <P> 1352 * This method throws an exception if there is an ambiguity, for example, if the 1353 * object is of a class implementing more than one of the interfaces named above. 1354 * 1355 * @param parameterName the name of the parameter 1356 * @param x the object containing the input parameter value 1357 * @exception SQLException if a database access error occurs, 1358 * this method is called on a closed <code>CallableStatement</code> or if the given 1359 * <code>Object</code> parameter is ambiguous 1360 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1361 * this method 1362 * @see #getObject 1363 * @since 1.4 1364 */ 1365 void setObject(String parameterName, Object x) throws SQLException; 1366 1367 /** 1368 * Sets the designated parameter in this <code>RowSet</code> object's command 1369 * with a Java <code>Object</code>. For integral values, the 1370 * <code>java.lang</code> equivalent objects should be used. 1371 * 1372 * <p>The JDBC specification provides a standard mapping from 1373 * Java Object types to SQL types. The driver will convert the 1374 * given Java object to its standard SQL mapping before sending it 1375 * to the database. 1376 * 1377 * <p>Note that this method may be used to pass database-specific 1378 * abstract data types by using a driver-specific Java type. 1379 * 1380 * If the object is of a class implementing <code>SQLData</code>, 1381 * the rowset should call the method <code>SQLData.writeSQL</code> 1382 * to write the object to an <code>SQLOutput</code> data stream. 1383 * If, on the other hand, the object is of a class implementing 1384 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1385 * <code>Struct</code>, <code>java.net.URL</code>, 1386 * or <code>Array</code>, the driver should pass it to the database as a 1387 * value of the corresponding SQL type. 1388 * 1389 * <P> 1390 * An exception is thrown if there is an ambiguity, for example, if the 1391 * object is of a class implementing more than one of these interfaces. 1392 * 1393 * @param parameterIndex The first parameter is 1, the second is 2, ... 1394 * @param x The object containing the input parameter value 1395 * @exception SQLException if a database access error occurs 1396 */ 1397 void setObject(int parameterIndex, Object x) throws SQLException; 1398 1399 1400 /** 1401 * Sets the designated parameter in this <code>RowSet</code> object's command 1402 * with the given <code>Ref</code> value. The driver will convert this 1403 * to the appropriate <code>REF(<structured-type>)</code> value. 1404 * 1405 * @param i the first parameter is 1, the second is 2, ... 1406 * @param x an object representing data of an SQL <code>REF</code> type 1407 * @exception SQLException if a database access error occurs 1408 */ 1409 void setRef (int i, Ref x) throws SQLException; 1410 1411 /** 1412 * Sets the designated parameter in this <code>RowSet</code> object's command 1413 * with the given <code>Blob</code> value. The driver will convert this 1414 * to the <code>BLOB</code> value that the <code>Blob</code> object 1415 * represents before sending it to the database. 1416 * 1417 * @param i the first parameter is 1, the second is 2, ... 1418 * @param x an object representing a BLOB 1419 * @exception SQLException if a database access error occurs 1420 */ 1421 void setBlob (int i, Blob x) throws SQLException; 1422 1423 /** 1424 * Sets the designated parameter to a <code>InputStream</code> object. 1425 * The <code>InputStream</code> 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 <code>InputStream</code> does not match 1443 * the specified 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, long length) 1449 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. 1480 * The {@code InputStream} must contain the number 1481 * of characters specified by length, otherwise a <code>SQLException</code> will be 1482 * generated when the <code>CallableStatement</code> is executed. 1483 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code> 1484 * method because it informs the driver that the parameter value should be 1485 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1486 * the driver may have to do extra work to determine whether the parameter 1487 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1488 * 1489 * @param parameterName the name of the parameter to be set 1490 * the second is 2, ... 1491 * 1492 * @param inputStream An object that contains the data to set the parameter 1493 * value to. 1494 * @param length the number of bytes in the parameter data. 1495 * @throws SQLException if parameterIndex does not correspond 1496 * to a parameter marker in the SQL statement, or if the length specified 1497 * is less than zero; if the number of bytes in the <code>InputStream</code> does not match 1498 * the specified length; if a database access error occurs or 1499 * this method is called on a closed <code>CallableStatement</code> 1500 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1501 * this method 1502 * 1503 * @since 1.6 1504 */ 1505 void setBlob(String parameterName, InputStream inputStream, long length) 1506 throws SQLException; 1507 1508 /** 1509 * Sets the designated parameter to the given <code>java.sql.Blob</code> object. 1510 * The driver converts this to an SQL <code>BLOB</code> value when it 1511 * sends it to the database. 1512 * 1513 * @param parameterName the name of the parameter 1514 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value 1515 * @exception SQLException if a database access error occurs or 1516 * this method is called on a closed <code>CallableStatement</code> 1517 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1518 * this method 1519 * @since 1.6 1520 */ 1521 void setBlob (String parameterName, Blob x) throws SQLException; 1522 1523 /** 1524 * Sets the designated parameter to a <code>InputStream</code> object. 1525 * This method differs from the <code>setBinaryStream (int, InputStream)</code> 1526 * method because it informs the driver that the parameter value should be 1527 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1528 * the driver may have to do extra work to determine whether the parameter 1529 * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1530 * 1531 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1532 * it might be more efficient to use a version of 1533 * <code>setBlob</code> which takes a length parameter. 1534 * 1535 * @param parameterName the name of the parameter 1536 * @param inputStream An object that contains the data to set the parameter 1537 * value to. 1538 * @throws SQLException if a database access error occurs or 1539 * this method is called on a closed <code>CallableStatement</code> 1540 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1541 * 1542 * @since 1.6 1543 */ 1544 void setBlob(String parameterName, InputStream inputStream) 1545 throws SQLException; 1546 1547 /** 1548 * Sets the designated parameter in this <code>RowSet</code> object's command 1549 * with the given <code>Clob</code> value. The driver will convert this 1550 * to the <code>CLOB</code> value that the <code>Clob</code> object 1551 * represents before sending it to the database. 1552 * 1553 * @param i the first parameter is 1, the second is 2, ... 1554 * @param x an object representing a CLOB 1555 * @exception SQLException if a database access error occurs 1556 */ 1557 void setClob (int i, Clob x) throws SQLException; 1558 1559 /** 1560 * Sets the designated parameter to a {@code Reader} object. 1561 * The {@code Reader} must contain the number 1562 * of characters specified by length otherwise a <code>SQLException</code> will be 1563 * generated when the <code>PreparedStatement</code> is executed. 1564 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 1565 * because it informs the driver that the parameter value should be sent to 1566 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1567 * driver may have to do extra work to determine whether the parameter 1568 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1569 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1570 * @param reader An object that contains the data to set the parameter value to. 1571 * @param length the number of characters in the parameter data. 1572 * @throws SQLException if a database access error occurs, this method is called on 1573 * a closed <code>PreparedStatement</code>, if parameterIndex does not correspond to a parameter 1574 * marker in the SQL statement, or if the length specified is less than zero. 1575 * 1576 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1577 * @since 1.6 1578 */ 1579 void setClob(int parameterIndex, Reader reader, long length) 1580 throws SQLException; 1581 1582 /** 1583 * Sets the designated parameter to a {@code Reader} object. 1584 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1585 * because it informs the driver that the parameter value should be sent to 1586 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1587 * driver may have to do extra work to determine whether the parameter 1588 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1589 * 1590 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1591 * it might be more efficient to use a version of 1592 * <code>setClob</code> which takes a length parameter. 1593 * 1594 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1595 * @param reader An object that contains the data to set the parameter value to. 1596 * @throws SQLException if a database access error occurs, this method is called on 1597 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter 1598 * marker in the SQL statement 1599 * 1600 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1601 * @since 1.6 1602 */ 1603 void setClob(int parameterIndex, Reader reader) 1604 throws SQLException; 1605 1606 /** 1607 * Sets the designated parameter to a {@code Reader} object. The 1608 * {@code Reader} must contain the number 1609 * of characters specified by length otherwise a <code>SQLException</code> will be 1610 * generated when the <code>CallableStatement</code> is executed. 1611 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 1612 * because it informs the driver that the parameter value should be sent to 1613 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1614 * driver may have to do extra work to determine whether the parameter 1615 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1616 * @param parameterName the name of the parameter to be set 1617 * @param reader An object that contains the data to set the parameter value to. 1618 * @param length the number of characters in the parameter data. 1619 * @throws SQLException if parameterIndex does not correspond to a parameter 1620 * marker in the SQL statement; if the length specified is less than zero; 1621 * a database access error occurs or 1622 * this method is called on a closed <code>CallableStatement</code> 1623 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1624 * this method 1625 * 1626 * @since 1.6 1627 */ 1628 void setClob(String parameterName, Reader reader, long length) 1629 throws SQLException; 1630 1631 /** 1632 * Sets the designated parameter to the given <code>java.sql.Clob</code> object. 1633 * The driver converts this to an SQL <code>CLOB</code> value when it 1634 * sends it to the database. 1635 * 1636 * @param parameterName the name of the parameter 1637 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value 1638 * @exception SQLException if a database access error occurs or 1639 * this method is called on a closed <code>CallableStatement</code> 1640 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1641 * this method 1642 * @since 1.6 1643 */ 1644 void setClob (String parameterName, Clob x) throws SQLException; 1645 1646 /** 1647 * Sets the designated parameter to a {@code Reader} object. 1648 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1649 * because it informs the driver that the parameter value should be sent to 1650 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1651 * driver may have to do extra work to determine whether the parameter 1652 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1653 * 1654 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1655 * it might be more efficient to use a version of 1656 * <code>setClob</code> which takes a length parameter. 1657 * 1658 * @param parameterName the name of the parameter 1659 * @param reader An object that contains the data to set the parameter value to. 1660 * @throws SQLException if a database access error occurs or this method is called on 1661 * a closed <code>CallableStatement</code> 1662 * 1663 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1664 * @since 1.6 1665 */ 1666 void setClob(String parameterName, Reader reader) 1667 throws SQLException; 1668 1669 /** 1670 * Sets the designated parameter in this <code>RowSet</code> object's command 1671 * with the given <code>Array</code> value. The driver will convert this 1672 * to the <code>ARRAY</code> value that the <code>Array</code> object 1673 * represents before sending it to the database. 1674 * 1675 * @param i the first parameter is 1, the second is 2, ... 1676 * @param x an object representing an SQL array 1677 * @exception SQLException if a database access error occurs 1678 */ 1679 void setArray (int i, Array x) throws SQLException; 1680 1681 /** 1682 * Sets the designated parameter in this <code>RowSet</code> object's command 1683 * with the given <code>java.sql.Date</code> value. The driver will convert this 1684 * to an SQL <code>DATE</code> value, using the given <code>java.util.Calendar</code> 1685 * object to calculate the date. 1686 * 1687 * @param parameterIndex the first parameter is 1, the second is 2, ... 1688 * @param x the parameter value 1689 * @param cal the <code>java.util.Calendar</code> object to use for calculating the date 1690 * @exception SQLException if a database access error occurs 1691 */ 1692 void setDate(int parameterIndex, java.sql.Date x, Calendar cal) 1693 throws SQLException; 1694 1695 /** 1696 * Sets the designated parameter to the given <code>java.sql.Date</code> value 1697 * using the default time zone of the virtual machine that is running 1698 * the application. 1699 * The driver converts this 1700 * to an SQL <code>DATE</code> value when it sends it to the database. 1701 * 1702 * @param parameterName the name of the parameter 1703 * @param x the parameter value 1704 * @exception SQLException if a database access error occurs or 1705 * this method is called on a closed <code>CallableStatement</code> 1706 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1707 * this method 1708 * @see #getDate 1709 * @since 1.4 1710 */ 1711 void setDate(String parameterName, java.sql.Date x) 1712 throws SQLException; 1713 1714 /** 1715 * Sets the designated parameter to the given <code>java.sql.Date</code> value, 1716 * using the given <code>Calendar</code> object. The driver uses 1717 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value, 1718 * which the driver then sends to the database. With a 1719 * a <code>Calendar</code> object, the driver can calculate the date 1720 * taking into account a custom timezone. If no 1721 * <code>Calendar</code> object is specified, the driver uses the default 1722 * timezone, which is that of the virtual machine running the application. 1723 * 1724 * @param parameterName the name of the parameter 1725 * @param x the parameter value 1726 * @param cal the <code>Calendar</code> object the driver will use 1727 * to construct the date 1728 * @exception SQLException if a database access error occurs or 1729 * this method is called on a closed <code>CallableStatement</code> 1730 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1731 * this method 1732 * @see #getDate 1733 * @since 1.4 1734 */ 1735 void setDate(String parameterName, java.sql.Date x, Calendar cal) 1736 throws SQLException; 1737 1738 /** 1739 * Sets the designated parameter in this <code>RowSet</code> object's command 1740 * with the given <code>java.sql.Time</code> value. The driver will convert this 1741 * to an SQL <code>TIME</code> value, using the given <code>java.util.Calendar</code> 1742 * object to calculate it, before sending it to the database. 1743 * 1744 * @param parameterIndex the first parameter is 1, the second is 2, ... 1745 * @param x the parameter value 1746 * @param cal the <code>java.util.Calendar</code> object to use for calculating the time 1747 * @exception SQLException if a database access error occurs 1748 */ 1749 void setTime(int parameterIndex, java.sql.Time x, Calendar cal) 1750 throws SQLException; 1751 1752 /** 1753 * Sets the designated parameter to the given <code>java.sql.Time</code> value. 1754 * The driver converts this 1755 * to an SQL <code>TIME</code> value when it sends it to the database. 1756 * 1757 * @param parameterName the name of the parameter 1758 * @param x the parameter value 1759 * @exception SQLException if a database access error occurs or 1760 * this method is called on a closed <code>CallableStatement</code> 1761 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1762 * this method 1763 * @see #getTime 1764 * @since 1.4 1765 */ 1766 void setTime(String parameterName, java.sql.Time x) 1767 throws SQLException; 1768 1769 /** 1770 * Sets the designated parameter to the given <code>java.sql.Time</code> value, 1771 * using the given <code>Calendar</code> object. The driver uses 1772 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value, 1773 * which the driver then sends to the database. With a 1774 * a <code>Calendar</code> object, the driver can calculate the time 1775 * taking into account a custom timezone. If no 1776 * <code>Calendar</code> object is specified, the driver uses the default 1777 * timezone, which is that of the virtual machine running the application. 1778 * 1779 * @param parameterName the name of the parameter 1780 * @param x the parameter value 1781 * @param cal the <code>Calendar</code> object the driver will use 1782 * to construct the time 1783 * @exception SQLException if a database access error occurs or 1784 * this method is called on a closed <code>CallableStatement</code> 1785 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1786 * this method 1787 * @see #getTime 1788 * @since 1.4 1789 */ 1790 void setTime(String parameterName, java.sql.Time x, Calendar cal) 1791 throws SQLException; 1792 1793 /** 1794 * Sets the designated parameter in this <code>RowSet</code> object's command 1795 * with the given <code>java.sql.Timestamp</code> value. The driver will 1796 * convert this to an SQL <code>TIMESTAMP</code> value, using the given 1797 * <code>java.util.Calendar</code> object to calculate it, before sending it to the 1798 * database. 1799 * 1800 * @param parameterIndex the first parameter is 1, the second is 2, ... 1801 * @param x the parameter value 1802 * @param cal the <code>java.util.Calendar</code> object to use for calculating the 1803 * timestamp 1804 * @exception SQLException if a database access error occurs 1805 */ 1806 void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) 1807 throws SQLException; 1808 1809 /** 1810 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value, 1811 * using the given <code>Calendar</code> object. The driver uses 1812 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value, 1813 * which the driver then sends to the database. With a 1814 * a <code>Calendar</code> object, the driver can calculate the timestamp 1815 * taking into account a custom timezone. If no 1816 * <code>Calendar</code> object is specified, the driver uses the default 1817 * timezone, which is that of the virtual machine running the application. 1818 * 1819 * @param parameterName the name of the parameter 1820 * @param x the parameter value 1821 * @param cal the <code>Calendar</code> object the driver will use 1822 * to construct the timestamp 1823 * @exception SQLException if a database access error occurs or 1824 * this method is called on a closed <code>CallableStatement</code> 1825 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1826 * this method 1827 * @see #getTimestamp 1828 * @since 1.4 1829 */ 1830 void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal) 1831 throws SQLException; 1832 1833 /** 1834 * Clears the parameters set for this <code>RowSet</code> object's command. 1835 * <P>In general, parameter values remain in force for repeated use of a 1836 * <code>RowSet</code> object. Setting a parameter value automatically clears its 1837 * previous value. However, in some cases it is useful to immediately 1838 * release the resources used by the current parameter values, which can 1839 * be done by calling the method <code>clearParameters</code>. 1840 * 1841 * @exception SQLException if a database access error occurs 1842 */ 1843 void clearParameters() throws SQLException; 1844 1845 //--------------------------------------------------------------------- 1846 // Reading and writing data 1847 //--------------------------------------------------------------------- 1848 1849 /** 1850 * Fills this <code>RowSet</code> object with data. 1851 * <P> 1852 * The <code>execute</code> method may use the following properties 1853 * to create a connection for reading data: url, data source name, 1854 * user name, password, transaction isolation, and type map. 1855 * 1856 * The <code>execute</code> method may use the following properties 1857 * to create a statement to execute a command: 1858 * command, read only, maximum field size, 1859 * maximum rows, escape processing, and query timeout. 1860 * <P> 1861 * If the required properties have not been set, an exception is 1862 * thrown. If this method is successful, the current contents of the rowset are 1863 * discarded and the rowset's metadata is also (re)set. If there are 1864 * outstanding updates, they are ignored. 1865 * <P> 1866 * If this <code>RowSet</code> object does not maintain a continuous connection 1867 * with its source of data, it may use a {@code Reader} (a <code>RowSetReader</code> 1868 * object) to fill itself with data. In this case, a {@code Reader} will have been 1869 * registered with this <code>RowSet</code> object, and the method 1870 * <code>execute</code> will call on the {@code Reader}'s <code>readData</code> 1871 * method as part of its implementation. 1872 * 1873 * @exception SQLException if a database access error occurs or any of the 1874 * properties necessary for making a connection and creating 1875 * a statement have not been set 1876 */ 1877 void execute() throws SQLException; 1878 1879 //-------------------------------------------------------------------- 1880 // Events 1881 //-------------------------------------------------------------------- 1882 1883 /** 1884 * Registers the given listener so that it will be notified of events 1885 * that occur on this <code>RowSet</code> object. 1886 * 1887 * @param listener a component that has implemented the <code>RowSetListener</code> 1888 * interface and wants to be notified when events occur on this 1889 * <code>RowSet</code> object 1890 * @see #removeRowSetListener 1891 */ 1892 void addRowSetListener(RowSetListener listener); 1893 1894 /** 1895 * Removes the specified listener from the list of components that will be 1896 * notified when an event occurs on this <code>RowSet</code> object. 1897 * 1898 * @param listener a component that has been registered as a listener for this 1899 * <code>RowSet</code> object 1900 * @see #addRowSetListener 1901 */ 1902 void removeRowSetListener(RowSetListener listener); 1903 1904 /** 1905 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an 1906 * SQL <code>XML</code> value when it sends it to the database. 1907 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1908 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value 1909 * @throws SQLException if a database access error occurs, this method 1910 * is called on a closed result set, 1911 * the <code>java.xml.transform.Result</code>, 1912 * <code>Writer</code> or <code>OutputStream</code> has not been closed 1913 * for the <code>SQLXML</code> object or 1914 * if there is an error processing the XML value. The <code>getCause</code> method 1915 * of the exception may provide a more detailed exception, for example, if the 1916 * stream does not contain valid XML. 1917 * @since 1.6 1918 */ 1919 void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException; 1920 1921 /** 1922 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an 1923 * <code>SQL XML</code> value when it sends it to the database. 1924 * @param parameterName the name of the parameter 1925 * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value 1926 * @throws SQLException if a database access error occurs, this method 1927 * is called on a closed result set, 1928 * the <code>java.xml.transform.Result</code>, 1929 * <code>Writer</code> or <code>OutputStream</code> has not been closed 1930 * for the <code>SQLXML</code> object or 1931 * if there is an error processing the XML value. The <code>getCause</code> method 1932 * of the exception may provide a more detailed exception, for example, if the 1933 * stream does not contain valid XML. 1934 * @since 1.6 1935 */ 1936 void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException; 1937 1938 /** 1939 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The 1940 * driver converts this to a SQL <code>ROWID</code> value when it sends it 1941 * to the database 1942 * 1943 * @param parameterIndex the first parameter is 1, the second is 2, ... 1944 * @param x the parameter value 1945 * @throws SQLException if a database access error occurs 1946 * 1947 * @since 1.6 1948 */ 1949 void setRowId(int parameterIndex, RowId x) throws SQLException; 1950 1951 /** 1952 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The 1953 * driver converts this to a SQL <code>ROWID</code> when it sends it to the 1954 * database. 1955 * 1956 * @param parameterName the name of the parameter 1957 * @param x the parameter value 1958 * @throws SQLException if a database access error occurs 1959 * @since 1.6 1960 */ 1961 void setRowId(String parameterName, RowId x) throws SQLException; 1962 1963 /** 1964 * Sets the designated parameter to the given <code>String</code> object. 1965 * The driver converts this to a SQL <code>NCHAR</code> or 1966 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value 1967 * (depending on the argument's 1968 * size relative to the driver's limits on <code>NVARCHAR</code> values) 1969 * when it sends it to the database. 1970 * 1971 * @param parameterIndex of the first parameter is 1, the second is 2, ... 1972 * @param value the parameter value 1973 * @throws SQLException if the driver does not support national 1974 * character sets; if the driver can detect that a data conversion 1975 * error could occur ; or if a database access error occurs 1976 * @since 1.6 1977 */ 1978 void setNString(int parameterIndex, String value) throws SQLException; 1979 1980 /** 1981 * Sets the designated parameter to the given <code>String</code> object. 1982 * The driver converts this to a SQL <code>NCHAR</code> or 1983 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> 1984 * @param parameterName the name of the column to be set 1985 * @param value the parameter value 1986 * @throws SQLException if the driver does not support national 1987 * character sets; if the driver can detect that a data conversion 1988 * error could occur; or if a database access error occurs 1989 * @since 1.6 1990 */ 1991 public void setNString(String parameterName, String value) 1992 throws SQLException; 1993 1994 /** 1995 * Sets the designated parameter to a {@code Reader} object. The 1996 * {@code Reader} reads the data till end-of-file is reached. The 1997 * driver does the necessary conversion from Java character format to 1998 * the national character set in the database. 1999 * @param parameterIndex of the first parameter is 1, the second is 2, ... 2000 * @param value the parameter value 2001 * @param length the number of characters in the parameter data. 2002 * @throws SQLException if the driver does not support national 2003 * character sets; if the driver can detect that a data conversion 2004 * error could occur ; or if a database access error occurs 2005 * @since 1.6 2006 */ 2007 void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException; 2008 2009 /** 2010 * Sets the designated parameter to a {@code Reader} object. The 2011 * {@code Reader} 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, long length) 2023 throws SQLException; 2024 2025 /** 2026 * Sets the designated parameter to a {@code Reader} object. The 2027 * {@code Reader} 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) throws SQLException; 2048 2049 /** 2050 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object 2051 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code> 2052 * object maps to a SQL <code>NCLOB</code>. 2053 * @param parameterName the name of the column to be set 2054 * @param value the parameter value 2055 * @throws SQLException if the driver does not support national 2056 * character sets; if the driver can detect that a data conversion 2057 * error could occur; or if a database access error occurs 2058 * @since 1.6 2059 */ 2060 void setNClob(String parameterName, NClob value) throws SQLException; 2061 2062 /** 2063 * Sets the designated parameter to a {@code Reader} object. 2064 * The {@code Reader} must contain the number 2065 * of characters specified by length otherwise a <code>SQLException</code> will be 2066 * generated when the <code>CallableStatement</code> is executed. 2067 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 2068 * because it informs the driver that the parameter value should be sent to 2069 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 2070 * driver may have to do extra work to determine whether the parameter 2071 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 2072 * 2073 * @param parameterName the name of the parameter to be set 2074 * @param reader An object that contains the data to set the parameter value to. 2075 * @param length the number of characters in the parameter data. 2076 * @throws SQLException if parameterIndex does not correspond to a parameter 2077 * marker in the SQL statement; if the length specified is less than zero; 2078 * if the driver does not support national 2079 * character sets; if the driver can detect that a data conversion 2080 * error could occur; if a database access error occurs or 2081 * this method is called on a closed <code>CallableStatement</code> 2082 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 2083 * this method 2084 * @since 1.6 2085 */ 2086 void setNClob(String parameterName, Reader reader, long length) 2087 throws SQLException; 2088 2089 /** 2090 * Sets the designated parameter to a {@code Reader} object. 2091 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 2092 * because it informs the driver that the parameter value should be sent to 2093 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 2094 * driver may have to do extra work to determine whether the parameter 2095 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 2096 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 2097 * it might be more efficient to use a version of 2098 * <code>setNClob</code> which takes a length parameter. 2099 * 2100 * @param parameterName the name of the parameter 2101 * @param reader An object that contains the data to set the parameter value to. 2102 * @throws SQLException if the driver does not support national character sets; 2103 * if the driver can detect that a data conversion 2104 * error could occur; if a database access error occurs or 2105 * this method is called on a closed <code>CallableStatement</code> 2106 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 2107 * 2108 * @since 1.6 2109 */ 2110 void setNClob(String parameterName, Reader reader) 2111 throws SQLException; 2112 2113 /** 2114 * Sets the designated parameter to a {@code Reader} object. 2115 * The {@code 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} 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 2192 2193} 2194