1 /* 2 * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sql; 27 28 import java.sql.*; 29 import java.io.*; 30 import java.math.*; 31 import java.util.*; 32 33 /** 34 * The interface that adds support to the JDBC API for the 35 * JavaBeans<sup><font size=-2>TM</font></sup> 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 reader (a <code>RowSetReader</code> object) 70 * and a writer (a <code>RowSetWriter</code> object) associated with it. 71 * The 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 87 public 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> obejct. 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.BigDeciaml</code> 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</code> 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</code> 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</code> 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</code> 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</code> object. The 1171 * <code>Reader</code> 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</code> then the reader must contain the number of characters specified * by scaleOrLength. If these conditions are not true the driver will generate a 1204 * <code>SQLException</code> when the prepared statement is executed. 1205 * 1206 * <p>The given Java object will be converted to the targetSqlType 1207 * before being sent to the database. 1208 * <P> 1209 * If the object is of a class implementing <code>SQLData</code>, 1210 * the rowset should call the method <code>SQLData.writeSQL</code> 1211 * to write the object to an <code>SQLOutput</code> data stream. 1212 * If, on the other hand, the object is of a class implementing 1213 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1214 * <code>Struct</code>, <code>java.net.URL</code>, 1215 * or <code>Array</code>, the driver should pass it to the database as a 1216 * value of the corresponding SQL type. 1217 * <P> 1218 * 1219 * <p>Note that this method may be used to pass datatabase-specific 1220 * abstract data types. 1221 * 1222 * @param parameterIndex the first parameter is 1, the second is 2, ... 1223 * @param x the object containing the input parameter value 1224 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>) 1225 * to be sent to the database. The scale argument may further qualify this 1226 * type. 1227 * @param scaleOrLength for <code>java.sql.Types.DECIMAL</code> 1228 * or <code>java.sql.Types.NUMERIC types</code>, 1229 * this is the number of digits after the decimal point. For 1230 * Java Object types <code>InputStream</code> and <code>Reader</code>, 1231 * this is the length 1232 * of the data in the stream or reader. For all other types, 1233 * this value will be ignored. 1234 * @exception SQLException if a database access error occurs 1235 * @see java.sql.Types 1236 */ 1237 void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) 1238 throws SQLException; 1239 1240 /** 1241 * Sets the value of the designated parameter with the given object. The second 1242 * argument must be an object type; for integral values, the 1243 * <code>java.lang</code> equivalent objects should be used. 1244 * 1245 * <p>The given Java object will be converted to the given targetSqlType 1246 * before being sent to the database. 1247 * 1248 * If the object has a custom mapping (is of a class implementing the 1249 * interface <code>SQLData</code>), 1250 * the JDBC driver should call the method <code>SQLData.writeSQL</code> to write it 1251 * to the SQL data stream. 1252 * If, on the other hand, the object is of a class implementing 1253 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1254 * <code>Struct</code>, <code>java.net.URL</code>, 1255 * or <code>Array</code>, the driver should pass it to the database as a 1256 * value of the corresponding SQL type. 1257 * <P> 1258 * Note that this method may be used to pass datatabase- 1259 * specific abstract data types. 1260 * 1261 * @param parameterName the name of the parameter 1262 * @param x the object containing the input parameter value 1263 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 1264 * sent to the database. The scale argument may further qualify this type. 1265 * @param scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types, 1266 * this is the number of digits after the decimal point. For all other 1267 * types, this value will be ignored. 1268 * @exception SQLException if a database access error occurs or 1269 * this method is called on a closed <code>CallableStatement</code> 1270 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is 1271 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 1272 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 1273 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 1274 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 1275 * or <code>STRUCT</code> data type and the JDBC driver does not support 1276 * this data type 1277 * @see Types 1278 * @see #getObject 1279 * @since 1.4 1280 */ 1281 void setObject(String parameterName, Object x, int targetSqlType, int scale) 1282 throws SQLException; 1283 1284 /** 1285 * Sets the designated parameter in this <code>RowSet</code> object's command 1286 * with a Java <code>Object</code>. For integral values, the 1287 * <code>java.lang</code> equivalent objects should be used. 1288 * This method is like <code>setObject</code> above, but the scale used is the scale 1289 * of the second parameter. Scalar values have a scale of zero. Literal 1290 * values have the scale present in the literal. 1291 * <P> 1292 * Even though it is supported, it is not recommended that this method 1293 * be called with floating point input values. 1294 * 1295 * @param parameterIndex the first parameter is 1, the second is 2, ... 1296 * @param x the object containing the input parameter value 1297 * @param targetSqlType the SQL type (as defined in <code>java.sql.Types</code>) 1298 * to be sent to the database 1299 * @exception SQLException if a database access error occurs 1300 */ 1301 void setObject(int parameterIndex, Object x, 1302 int targetSqlType) throws SQLException; 1303 1304 /** 1305 * Sets the value of the designated parameter with the given object. 1306 * This method is like the method <code>setObject</code> 1307 * above, except that it assumes a scale of zero. 1308 * 1309 * @param parameterName the name of the parameter 1310 * @param x the object containing the input parameter value 1311 * @param targetSqlType the SQL type (as defined in java.sql.Types) to be 1312 * sent to the database 1313 * @exception SQLException if a database access error occurs or 1314 * this method is called on a closed <code>CallableStatement</code> 1315 * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is 1316 * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>, 1317 * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>, 1318 * <code>NCLOB</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>, 1319 * <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code> 1320 * or <code>STRUCT</code> data type and the JDBC driver does not support 1321 * this data type 1322 * @see #getObject 1323 * @since 1.4 1324 */ 1325 void setObject(String parameterName, Object x, int targetSqlType) 1326 throws SQLException; 1327 1328 /** 1329 * Sets the value of the designated parameter with the given object. 1330 * The second parameter must be of type <code>Object</code>; therefore, the 1331 * <code>java.lang</code> equivalent objects should be used for built-in types. 1332 * 1333 * <p>The JDBC specification specifies a standard mapping from 1334 * Java <code>Object</code> types to SQL types. The given argument 1335 * will be converted to the corresponding SQL type before being 1336 * sent to the database. 1337 * 1338 * <p>Note that this method may be used to pass datatabase- 1339 * specific abstract data types, by using a driver-specific Java 1340 * type. 1341 * 1342 * If the object is of a class implementing the interface <code>SQLData</code>, 1343 * the JDBC driver should call the method <code>SQLData.writeSQL</code> 1344 * to write it to the SQL data stream. 1345 * If, on the other hand, the object is of a class implementing 1346 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1347 * <code>Struct</code>, <code>java.net.URL</code>, 1348 * or <code>Array</code>, the driver should pass it to the database as a 1349 * value of the corresponding SQL type. 1350 * <P> 1351 * This method throws an exception if there is an ambiguity, for example, if the 1352 * object is of a class implementing more than one of the interfaces named above. 1353 * 1354 * @param parameterName the name of the parameter 1355 * @param x the object containing the input parameter value 1356 * @exception SQLException if a database access error occurs, 1357 * this method is called on a closed <code>CallableStatement</code> or if the given 1358 * <code>Object</code> parameter is ambiguous 1359 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1360 * this method 1361 * @see #getObject 1362 * @since 1.4 1363 */ 1364 void setObject(String parameterName, Object x) throws SQLException; 1365 1366 /** 1367 * Sets the designated parameter in this <code>RowSet</code> object's command 1368 * with a Java <code>Object</code>. For integral values, the 1369 * <code>java.lang</code> equivalent objects should be used. 1370 * 1371 * <p>The JDBC specification provides a standard mapping from 1372 * Java Object types to SQL types. The driver will convert the 1373 * given Java object to its standard SQL mapping before sending it 1374 * to the database. 1375 * 1376 * <p>Note that this method may be used to pass datatabase-specific 1377 * abstract data types by using a driver-specific Java type. 1378 * 1379 * If the object is of a class implementing <code>SQLData</code>, 1380 * the rowset should call the method <code>SQLData.writeSQL</code> 1381 * to write the object to an <code>SQLOutput</code> data stream. 1382 * If, on the other hand, the object is of a class implementing 1383 * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>, <code>NClob</code>, 1384 * <code>Struct</code>, <code>java.net.URL</code>, 1385 * or <code>Array</code>, the driver should pass it to the database as a 1386 * value of the corresponding SQL type. 1387 * <P> 1388 * <P> 1389 * An exception is thrown if there is an ambiguity, for example, if the 1390 * object is of a class implementing more than one of these interfaces. 1391 * 1392 * @param parameterIndex The first parameter is 1, the second is 2, ... 1393 * @param x The object containing the input parameter value 1394 * @exception SQLException if a database access error occurs 1395 */ 1396 void setObject(int parameterIndex, Object x) throws SQLException; 1397 1398 1399 /** 1400 * Sets the designated parameter in this <code>RowSet</code> object's command 1401 * with the given <code>Ref</code> value. The driver will convert this 1402 * to the appropriate <code>REF(<structured-type>)</code> value. 1403 * 1404 * @param i the first parameter is 1, the second is 2, ... 1405 * @param x an object representing data of an SQL <code>REF</code> type 1406 * @exception SQLException if a database access error occurs 1407 */ 1408 void setRef (int i, Ref x) throws SQLException; 1409 1410 /** 1411 * Sets the designated parameter in this <code>RowSet</code> object's command 1412 * with the given <code>Blob</code> value. The driver will convert this 1413 * to the <code>BLOB</code> value that the <code>Blob</code> object 1414 * represents before sending it to the database. 1415 * 1416 * @param i the first parameter is 1, the second is 2, ... 1417 * @param x an object representing a BLOB 1418 * @exception SQLException if a database access error occurs 1419 */ 1420 void setBlob (int i, Blob x) throws SQLException; 1421 1422 /** 1423 * Sets the designated parameter to a <code>InputStream</code> object. The inputstream must contain the number 1424 * of characters specified by length otherwise a <code>SQLException</code> will be 1425 * generated when the <code>PreparedStatement</code> is executed. 1426 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code> 1427 * method because it informs the driver that the parameter value should be 1428 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1429 * the driver may have to do extra work to determine whether the parameter 1430 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1431 * @param parameterIndex index of the first parameter is 1, 1432 * the second is 2, ... 1433 * @param inputStream An object that contains the data to set the parameter 1434 * value to. 1435 * @param length the number of bytes in the parameter data. 1436 * @throws SQLException if a database access error occurs, 1437 * this method is called on a closed <code>PreparedStatement</code>, 1438 * if parameterIndex does not correspond 1439 * to a parameter marker in the SQL statement, if the length specified 1440 * is less than zero or if the number of bytes in the inputstream does not match 1441 * the specfied length. 1442 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1443 * 1444 * @since 1.6 1445 */ 1446 void setBlob(int parameterIndex, InputStream inputStream, long length) 1447 throws SQLException; 1448 1449 /** 1450 * Sets the designated parameter to a <code>InputStream</code> object. 1451 * This method differs from the <code>setBinaryStream (int, InputStream)</code> 1452 * method because it informs the driver that the parameter value should be 1453 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1454 * the driver may have to do extra work to determine whether the parameter 1455 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1456 * 1457 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1458 * it might be more efficient to use a version of 1459 * <code>setBlob</code> which takes a length parameter. 1460 * 1461 * @param parameterIndex index of the first parameter is 1, 1462 * the second is 2, ... 1463 * @param inputStream An object that contains the data to set the parameter 1464 * value to. 1465 * @throws SQLException if a database access error occurs, 1466 * this method is called on a closed <code>PreparedStatement</code> or 1467 * if parameterIndex does not correspond 1468 * to a parameter marker in the SQL statement, 1469 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1470 * 1471 * @since 1.6 1472 */ 1473 void setBlob(int parameterIndex, InputStream inputStream) 1474 throws SQLException; 1475 1476 /** 1477 * Sets the designated parameter to a <code>InputStream</code> object. The <code>inputstream</code> must contain the number 1478 * of characters specified by length, otherwise a <code>SQLException</code> will be 1479 * generated when the <code>CallableStatement</code> is executed. 1480 * This method differs from the <code>setBinaryStream (int, InputStream, int)</code> 1481 * method because it informs the driver that the parameter value should be 1482 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1483 * the driver may have to do extra work to determine whether the parameter 1484 * data should be sent to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1485 * 1486 * @param parameterName the name of the parameter to be set 1487 * the second is 2, ... 1488 * 1489 * @param inputStream An object that contains the data to set the parameter 1490 * value to. 1491 * @param length the number of bytes in the parameter data. 1492 * @throws SQLException if parameterIndex does not correspond 1493 * to a parameter marker in the SQL statement, or if the length specified 1494 * is less than zero; if the number of bytes in the inputstream does not match 1495 * the specfied length; if a database access error occurs or 1496 * this method is called on a closed <code>CallableStatement</code> 1497 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1498 * this method 1499 * 1500 * @since 1.6 1501 */ 1502 void setBlob(String parameterName, InputStream inputStream, long length) 1503 throws SQLException; 1504 1505 /** 1506 * Sets the designated parameter to the given <code>java.sql.Blob</code> object. 1507 * The driver converts this to an SQL <code>BLOB</code> value when it 1508 * sends it to the database. 1509 * 1510 * @param parameterName the name of the parameter 1511 * @param x a <code>Blob</code> object that maps an SQL <code>BLOB</code> value 1512 * @exception SQLException if a database access error occurs or 1513 * this method is called on a closed <code>CallableStatement</code> 1514 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1515 * this method 1516 * @since 1.6 1517 */ 1518 void setBlob (String parameterName, Blob x) throws SQLException; 1519 1520 /** 1521 * Sets the designated parameter to a <code>InputStream</code> object. 1522 * This method differs from the <code>setBinaryStream (int, InputStream)</code> 1523 * method because it informs the driver that the parameter value should be 1524 * sent to the server as a <code>BLOB</code>. When the <code>setBinaryStream</code> method is used, 1525 * the driver may have to do extra work to determine whether the parameter 1526 * data should be send to the server as a <code>LONGVARBINARY</code> or a <code>BLOB</code> 1527 * 1528 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1529 * it might be more efficient to use a version of 1530 * <code>setBlob</code> which takes a length parameter. 1531 * 1532 * @param parameterName the name of the parameter 1533 * @param inputStream An object that contains the data to set the parameter 1534 * value to. 1535 * @throws SQLException if a database access error occurs or 1536 * this method is called on a closed <code>CallableStatement</code> 1537 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1538 * 1539 * @since 1.6 1540 */ 1541 void setBlob(String parameterName, InputStream inputStream) 1542 throws SQLException; 1543 1544 /** 1545 * Sets the designated parameter in this <code>RowSet</code> object's command 1546 * with the given <code>Clob</code> value. The driver will convert this 1547 * to the <code>CLOB</code> value that the <code>Clob</code> object 1548 * represents before sending it to the database. 1549 * 1550 * @param i the first parameter is 1, the second is 2, ... 1551 * @param x an object representing a CLOB 1552 * @exception SQLException if a database access error occurs 1553 */ 1554 void setClob (int i, Clob x) throws SQLException; 1555 1556 /** 1557 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number 1558 * of characters specified by length otherwise a <code>SQLException</code> will be 1559 * generated when the <code>PreparedStatement</code> is executed. 1560 *This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 1561 * because it informs the driver that the parameter value should be sent to 1562 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1563 * driver may have to do extra work to determine whether the parameter 1564 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1565 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1566 * @param reader An object that contains the data to set the parameter value to. 1567 * @param length the number of characters in the parameter data. 1568 * @throws SQLException if a database access error occurs, this method is called on 1569 * a closed <code>PreparedStatement</code>, if parameterIndex does not correspond to a parameter 1570 * marker in the SQL statement, or if the length specified is less than zero. 1571 * 1572 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1573 * @since 1.6 1574 */ 1575 void setClob(int parameterIndex, Reader reader, long length) 1576 throws SQLException; 1577 1578 /** 1579 * Sets the designated parameter to a <code>Reader</code> object. 1580 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1581 * because it informs the driver that the parameter value should be sent to 1582 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1583 * driver may have to do extra work to determine whether the parameter 1584 * data should be sent to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1585 * 1586 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1587 * it might be more efficient to use a version of 1588 * <code>setClob</code> which takes a length parameter. 1589 * 1590 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1591 * @param reader An object that contains the data to set the parameter value to. 1592 * @throws SQLException if a database access error occurs, this method is called on 1593 * a closed <code>PreparedStatement</code>or if parameterIndex does not correspond to a parameter 1594 * marker in the SQL statement 1595 * 1596 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1597 * @since 1.6 1598 */ 1599 void setClob(int parameterIndex, Reader reader) 1600 throws SQLException; 1601 1602 /** 1603 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number 1604 * of characters specified by length otherwise a <code>SQLException</code> will be 1605 * generated when the <code>CallableStatement</code> is executed. 1606 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 1607 * because it informs the driver that the parameter value should be sent to 1608 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1609 * driver may have to do extra work to determine whether the parameter 1610 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1611 * @param parameterName the name of the parameter to be set 1612 * @param reader An object that contains the data to set the parameter value to. 1613 * @param length the number of characters in the parameter data. 1614 * @throws SQLException if parameterIndex does not correspond to a parameter 1615 * marker in the SQL statement; if the length specified is less than zero; 1616 * a database access error occurs or 1617 * this method is called on a closed <code>CallableStatement</code> 1618 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1619 * this method 1620 * 1621 * @since 1.6 1622 */ 1623 void setClob(String parameterName, Reader reader, long length) 1624 throws SQLException; 1625 1626 /** 1627 * Sets the designated parameter to the given <code>java.sql.Clob</code> object. 1628 * The driver converts this to an SQL <code>CLOB</code> value when it 1629 * sends it to the database. 1630 * 1631 * @param parameterName the name of the parameter 1632 * @param x a <code>Clob</code> object that maps an SQL <code>CLOB</code> value 1633 * @exception SQLException if a database access error occurs or 1634 * this method is called on a closed <code>CallableStatement</code> 1635 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1636 * this method 1637 * @since 1.6 1638 */ 1639 void setClob (String parameterName, Clob x) throws SQLException; 1640 1641 /** 1642 * Sets the designated parameter to a <code>Reader</code> object. 1643 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 1644 * because it informs the driver that the parameter value should be sent to 1645 * the server as a <code>CLOB</code>. When the <code>setCharacterStream</code> method is used, the 1646 * driver may have to do extra work to determine whether the parameter 1647 * data should be send to the server as a <code>LONGVARCHAR</code> or a <code>CLOB</code> 1648 * 1649 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 1650 * it might be more efficient to use a version of 1651 * <code>setClob</code> which takes a length parameter. 1652 * 1653 * @param parameterName the name of the parameter 1654 * @param reader An object that contains the data to set the parameter value to. 1655 * @throws SQLException if a database access error occurs or this method is called on 1656 * a closed <code>CallableStatement</code> 1657 * 1658 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 1659 * @since 1.6 1660 */ 1661 void setClob(String parameterName, Reader reader) 1662 throws SQLException; 1663 1664 /** 1665 * Sets the designated parameter in this <code>RowSet</code> object's command 1666 * with the given <code>Array</code> value. The driver will convert this 1667 * to the <code>ARRAY</code> value that the <code>Array</code> object 1668 * represents before sending it to the database. 1669 * 1670 * @param i the first parameter is 1, the second is 2, ... 1671 * @param x an object representing an SQL array 1672 * @exception SQLException if a database access error occurs 1673 */ 1674 void setArray (int i, Array x) throws SQLException; 1675 1676 /** 1677 * Sets the designated parameter in this <code>RowSet</code> object's command 1678 * with the given <code>java.sql.Date</code> value. The driver will convert this 1679 * to an SQL <code>DATE</code> value, using the given <code>java.util.Calendar</code> 1680 * object to calculate the date. 1681 * 1682 * @param parameterIndex the first parameter is 1, the second is 2, ... 1683 * @param x the parameter value 1684 * @param cal the <code>java.util.Calendar</code> object to use for calculating the date 1685 * @exception SQLException if a database access error occurs 1686 */ 1687 void setDate(int parameterIndex, java.sql.Date x, Calendar cal) 1688 throws SQLException; 1689 1690 /** 1691 * Sets the designated parameter to the given <code>java.sql.Date</code> value 1692 * using the default time zone of the virtual machine that is running 1693 * the application. 1694 * The driver converts this 1695 * to an SQL <code>DATE</code> value when it sends it to the database. 1696 * 1697 * @param parameterName the name of the parameter 1698 * @param x the parameter value 1699 * @exception SQLException if a database access error occurs or 1700 * this method is called on a closed <code>CallableStatement</code> 1701 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1702 * this method 1703 * @see #getDate 1704 * @since 1.4 1705 */ 1706 void setDate(String parameterName, java.sql.Date x) 1707 throws SQLException; 1708 1709 /** 1710 * Sets the designated parameter to the given <code>java.sql.Date</code> value, 1711 * using the given <code>Calendar</code> object. The driver uses 1712 * the <code>Calendar</code> object to construct an SQL <code>DATE</code> value, 1713 * which the driver then sends to the database. With a 1714 * a <code>Calendar</code> object, the driver can calculate the date 1715 * taking into account a custom timezone. If no 1716 * <code>Calendar</code> object is specified, the driver uses the default 1717 * timezone, which is that of the virtual machine running the application. 1718 * 1719 * @param parameterName the name of the parameter 1720 * @param x the parameter value 1721 * @param cal the <code>Calendar</code> object the driver will use 1722 * to construct the date 1723 * @exception SQLException if a database access error occurs or 1724 * this method is called on a closed <code>CallableStatement</code> 1725 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1726 * this method 1727 * @see #getDate 1728 * @since 1.4 1729 */ 1730 void setDate(String parameterName, java.sql.Date x, Calendar cal) 1731 throws SQLException; 1732 1733 /** 1734 * Sets the designated parameter in this <code>RowSet</code> object's command 1735 * with the given <code>java.sql.Time</code> value. The driver will convert this 1736 * to an SQL <code>TIME</code> value, using the given <code>java.util.Calendar</code> 1737 * object to calculate it, before sending it to the database. 1738 * 1739 * @param parameterIndex the first parameter is 1, the second is 2, ... 1740 * @param x the parameter value 1741 * @param cal the <code>java.util.Calendar</code> object to use for calculating the time 1742 * @exception SQLException if a database access error occurs 1743 */ 1744 void setTime(int parameterIndex, java.sql.Time x, Calendar cal) 1745 throws SQLException; 1746 1747 /** 1748 * Sets the designated parameter to the given <code>java.sql.Time</code> value. 1749 * The driver converts this 1750 * to an SQL <code>TIME</code> value when it sends it to the database. 1751 * 1752 * @param parameterName the name of the parameter 1753 * @param x the parameter value 1754 * @exception SQLException if a database access error occurs or 1755 * this method is called on a closed <code>CallableStatement</code> 1756 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1757 * this method 1758 * @see #getTime 1759 * @since 1.4 1760 */ 1761 void setTime(String parameterName, java.sql.Time x) 1762 throws SQLException; 1763 1764 /** 1765 * Sets the designated parameter to the given <code>java.sql.Time</code> value, 1766 * using the given <code>Calendar</code> object. The driver uses 1767 * the <code>Calendar</code> object to construct an SQL <code>TIME</code> value, 1768 * which the driver then sends to the database. With a 1769 * a <code>Calendar</code> object, the driver can calculate the time 1770 * taking into account a custom timezone. If no 1771 * <code>Calendar</code> object is specified, the driver uses the default 1772 * timezone, which is that of the virtual machine running the application. 1773 * 1774 * @param parameterName the name of the parameter 1775 * @param x the parameter value 1776 * @param cal the <code>Calendar</code> object the driver will use 1777 * to construct the time 1778 * @exception SQLException if a database access error occurs or 1779 * this method is called on a closed <code>CallableStatement</code> 1780 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1781 * this method 1782 * @see #getTime 1783 * @since 1.4 1784 */ 1785 void setTime(String parameterName, java.sql.Time x, Calendar cal) 1786 throws SQLException; 1787 1788 /** 1789 * Sets the designated parameter in this <code>RowSet</code> object's command 1790 * with the given <code>java.sql.Timestamp</code> value. The driver will 1791 * convert this to an SQL <code>TIMESTAMP</code> value, using the given 1792 * <code>java.util.Calendar</code> object to calculate it, before sending it to the 1793 * database. 1794 * 1795 * @param parameterIndex the first parameter is 1, the second is 2, ... 1796 * @param x the parameter value 1797 * @param cal the <code>java.util.Calendar</code> object to use for calculating the 1798 * timestamp 1799 * @exception SQLException if a database access error occurs 1800 */ 1801 void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) 1802 throws SQLException; 1803 1804 /** 1805 * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value, 1806 * using the given <code>Calendar</code> object. The driver uses 1807 * the <code>Calendar</code> object to construct an SQL <code>TIMESTAMP</code> value, 1808 * which the driver then sends to the database. With a 1809 * a <code>Calendar</code> object, the driver can calculate the timestamp 1810 * taking into account a custom timezone. If no 1811 * <code>Calendar</code> object is specified, the driver uses the default 1812 * timezone, which is that of the virtual machine running the application. 1813 * 1814 * @param parameterName the name of the parameter 1815 * @param x the parameter value 1816 * @param cal the <code>Calendar</code> object the driver will use 1817 * to construct the timestamp 1818 * @exception SQLException if a database access error occurs or 1819 * this method is called on a closed <code>CallableStatement</code> 1820 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 1821 * this method 1822 * @see #getTimestamp 1823 * @since 1.4 1824 */ 1825 void setTimestamp(String parameterName, java.sql.Timestamp x, Calendar cal) 1826 throws SQLException; 1827 1828 /** 1829 * Clears the parameters set for this <code>RowSet</code> object's command. 1830 * <P>In general, parameter values remain in force for repeated use of a 1831 * <code>RowSet</code> object. Setting a parameter value automatically clears its 1832 * previous value. However, in some cases it is useful to immediately 1833 * release the resources used by the current parameter values, which can 1834 * be done by calling the method <code>clearParameters</code>. 1835 * 1836 * @exception SQLException if a database access error occurs 1837 */ 1838 void clearParameters() throws SQLException; 1839 1840 //--------------------------------------------------------------------- 1841 // Reading and writing data 1842 //--------------------------------------------------------------------- 1843 1844 /** 1845 * Fills this <code>RowSet</code> object with data. 1846 * <P> 1847 * The <code>execute</code> method may use the following properties 1848 * to create a connection for reading data: url, data source name, 1849 * user name, password, transaction isolation, and type map. 1850 * 1851 * The <code>execute</code> method may use the following properties 1852 * to create a statement to execute a command: 1853 * command, read only, maximum field size, 1854 * maximum rows, escape processing, and query timeout. 1855 * <P> 1856 * If the required properties have not been set, an exception is 1857 * thrown. If this method is successful, the current contents of the rowset are 1858 * discarded and the rowset's metadata is also (re)set. If there are 1859 * outstanding updates, they are ignored. 1860 * <P> 1861 * If this <code>RowSet</code> object does not maintain a continuous connection 1862 * with its source of data, it may use a reader (a <code>RowSetReader</code> 1863 * object) to fill itself with data. In this case, a reader will have been 1864 * registered with this <code>RowSet</code> object, and the method 1865 * <code>execute</code> will call on the reader's <code>readData</code> 1866 * method as part of its implementation. 1867 * 1868 * @exception SQLException if a database access error occurs or any of the 1869 * properties necessary for making a connection and creating 1870 * a statement have not been set 1871 */ 1872 void execute() throws SQLException; 1873 1874 //-------------------------------------------------------------------- 1875 // Events 1876 //-------------------------------------------------------------------- 1877 1878 /** 1879 * Registers the given listener so that it will be notified of events 1880 * that occur on this <code>RowSet</code> object. 1881 * 1882 * @param listener a component that has implemented the <code>RowSetListener</code> 1883 * interface and wants to be notified when events occur on this 1884 * <code>RowSet</code> object 1885 * @see #removeRowSetListener 1886 */ 1887 void addRowSetListener(RowSetListener listener); 1888 1889 /** 1890 * Removes the specified listener from the list of components that will be 1891 * notified when an event occurs on this <code>RowSet</code> object. 1892 * 1893 * @param listener a component that has been registered as a listener for this 1894 * <code>RowSet</code> object 1895 * @see #addRowSetListener 1896 */ 1897 void removeRowSetListener(RowSetListener listener); 1898 1899 /** 1900 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an 1901 * SQL <code>XML</code> value when it sends it to the database. 1902 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 1903 * @param xmlObject a <code>SQLXML</code> object that maps an SQL <code>XML</code> value 1904 * @throws SQLException if a database access error occurs, this method 1905 * is called on a closed result set, 1906 * the <code>java.xml.transform.Result</code>, 1907 * <code>Writer</code> or <code>OutputStream</code> has not been closed 1908 * for the <code>SQLXML</code> object or 1909 * if there is an error processing the XML value. The <code>getCause</code> method 1910 * of the exception may provide a more detailed exception, for example, if the 1911 * stream does not contain valid XML. 1912 * @since 1.6 1913 */ 1914 void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException; 1915 1916 /** 1917 * Sets the designated parameter to the given <code>java.sql.SQLXML</code> object. The driver converts this to an 1918 * <code>SQL XML</code> value when it sends it to the database. 1919 * @param parameterName the name of the parameter 1920 * @param xmlObject a <code>SQLXML</code> object that maps an <code>SQL XML</code> value 1921 * @throws SQLException if a database access error occurs, this method 1922 * is called on a closed result set, 1923 * the <code>java.xml.transform.Result</code>, 1924 * <code>Writer</code> or <code>OutputStream</code> has not been closed 1925 * for the <code>SQLXML</code> object or 1926 * if there is an error processing the XML value. The <code>getCause</code> method 1927 * of the exception may provide a more detailed exception, for example, if the 1928 * stream does not contain valid XML. 1929 * @since 1.6 1930 */ 1931 void setSQLXML(String parameterName, SQLXML xmlObject) throws SQLException; 1932 1933 /** 1934 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The 1935 * driver converts this to a SQL <code>ROWID</code> value when it sends it 1936 * to the database 1937 * 1938 * @param parameterIndex the first parameter is 1, the second is 2, ... 1939 * @param x the parameter value 1940 * @throws SQLException if a database access error occurs 1941 * 1942 * @since 1.6 1943 */ 1944 void setRowId(int parameterIndex, RowId x) throws SQLException; 1945 1946 /** 1947 * Sets the designated parameter to the given <code>java.sql.RowId</code> object. The 1948 * driver converts this to a SQL <code>ROWID</code> when it sends it to the 1949 * database. 1950 * 1951 * @param parameterName the name of the parameter 1952 * @param x the parameter value 1953 * @throws SQLException if a database access error occurs 1954 * @since 1.6 1955 */ 1956 void setRowId(String parameterName, RowId x) throws SQLException; 1957 1958 /** 1959 * Sets the designated paramter to the given <code>String</code> object. 1960 * The driver converts this to a SQL <code>NCHAR</code> or 1961 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> value 1962 * (depending on the argument's 1963 * size relative to the driver's limits on <code>NVARCHAR</code> values) 1964 * when it sends it to the database. 1965 * 1966 * @param parameterIndex of the first parameter is 1, the second is 2, ... 1967 * @param value the parameter value 1968 * @throws SQLException if the driver does not support national 1969 * character sets; if the driver can detect that a data conversion 1970 * error could occur ; or if a database access error occurs 1971 * @since 1.6 1972 */ 1973 void setNString(int parameterIndex, String value) throws SQLException; 1974 1975 /** 1976 * Sets the designated paramter to the given <code>String</code> object. 1977 * The driver converts this to a SQL <code>NCHAR</code> or 1978 * <code>NVARCHAR</code> or <code>LONGNVARCHAR</code> 1979 * @param parameterName the name of the column to be set 1980 * @param value the parameter value 1981 * @throws SQLException if the driver does not support national 1982 * character sets; if the driver can detect that a data conversion 1983 * error could occur; or if a database access error occurs 1984 * @since 1.6 1985 */ 1986 public void setNString(String parameterName, String value) 1987 throws SQLException; 1988 1989 /** 1990 * Sets the designated parameter to a <code>Reader</code> object. The 1991 * <code>Reader</code> reads the data till end-of-file is reached. The 1992 * driver does the necessary conversion from Java character format to 1993 * the national character set in the database. 1994 * @param parameterIndex of the first parameter is 1, the second is 2, ... 1995 * @param value the parameter value 1996 * @param length the number of characters in the parameter data. 1997 * @throws SQLException if the driver does not support national 1998 * character sets; if the driver can detect that a data conversion 1999 * error could occur ; or if a database access error occurs 2000 * @since 1.6 2001 */ 2002 void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException; 2003 2004 /** 2005 * Sets the designated parameter to a <code>Reader</code> object. The 2006 * <code>Reader</code> reads the data till end-of-file is reached. The 2007 * driver does the necessary conversion from Java character format to 2008 * the national character set in the database. 2009 * @param parameterName the name of the column to be set 2010 * @param value the parameter value 2011 * @param length the number of characters in the parameter data. 2012 * @throws SQLException if the driver does not support national 2013 * character sets; if the driver can detect that a data conversion 2014 * error could occur; or if a database access error occurs 2015 * @since 1.6 2016 */ 2017 public void setNCharacterStream(String parameterName, Reader value, long length) 2018 throws SQLException; 2019 2020 /** 2021 * Sets the designated parameter to a <code>Reader</code> object. The 2022 * <code>Reader</code> reads the data till end-of-file is reached. The 2023 * driver does the necessary conversion from Java character format to 2024 * the national character set in the database. 2025 2026 * <P><B>Note:</B> This stream object can either be a standard 2027 * Java stream object or your own subclass that implements the 2028 * standard interface. 2029 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 2030 * it might be more efficient to use a version of 2031 * <code>setNCharacterStream</code> which takes a length parameter. 2032 * 2033 * @param parameterName the name of the parameter 2034 * @param value the parameter value 2035 * @throws SQLException if the driver does not support national 2036 * character sets; if the driver can detect that a data conversion 2037 * error could occur ; if a database access error occurs; or 2038 * this method is called on a closed <code>CallableStatement</code> 2039 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 2040 * @since 1.6 2041 */ 2042 void setNCharacterStream(String parameterName, Reader value) throws SQLException; 2043 2044 /** 2045 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The object 2046 * implements the <code>java.sql.NClob</code> interface. This <code>NClob</code> 2047 * object maps to a SQL <code>NCLOB</code>. 2048 * @param parameterName the name of the column to be set 2049 * @param value the parameter value 2050 * @throws SQLException if the driver does not support national 2051 * character sets; if the driver can detect that a data conversion 2052 * error could occur; or if a database access error occurs 2053 * @since 1.6 2054 */ 2055 void setNClob(String parameterName, NClob value) throws SQLException; 2056 2057 /** 2058 * Sets the designated parameter to a <code>Reader</code> object. The <code>reader</code> must contain the number 2059 * of characters specified by length otherwise a <code>SQLException</code> will be 2060 * generated when the <code>CallableStatement</code> is executed. 2061 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 2062 * because it informs the driver that the parameter value should be sent to 2063 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 2064 * driver may have to do extra work to determine whether the parameter 2065 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 2066 * 2067 * @param parameterName the name of the parameter to be set 2068 * @param reader An object that contains the data to set the parameter value to. 2069 * @param length the number of characters in the parameter data. 2070 * @throws SQLException if parameterIndex does not correspond to a parameter 2071 * marker in the SQL statement; if the length specified is less than zero; 2072 * if the driver does not support national 2073 * character sets; if the driver can detect that a data conversion 2074 * error could occur; if a database access error occurs or 2075 * this method is called on a closed <code>CallableStatement</code> 2076 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support 2077 * this method 2078 * @since 1.6 2079 */ 2080 void setNClob(String parameterName, Reader reader, long length) 2081 throws SQLException; 2082 2083 /** 2084 * Sets the designated parameter to a <code>Reader</code> object. 2085 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 2086 * because it informs the driver that the parameter value should be sent to 2087 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 2088 * driver may have to do extra work to determine whether the parameter 2089 * data should be send to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 2090 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 2091 * it might be more efficient to use a version of 2092 * <code>setNClob</code> which takes a length parameter. 2093 * 2094 * @param parameterName the name of the parameter 2095 * @param reader An object that contains the data to set the parameter value to. 2096 * @throws SQLException if the driver does not support national character sets; 2097 * if the driver can detect that a data conversion 2098 * error could occur; if a database access error occurs or 2099 * this method is called on a closed <code>CallableStatement</code> 2100 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 2101 * 2102 * @since 1.6 2103 */ 2104 void setNClob(String parameterName, Reader reader) 2105 throws SQLException; 2106 2107 /** 2108 * Sets the designated parameter to a <code>Reader</code> object. The reader must contain the number 2109 * of characters specified by length otherwise a <code>SQLException</code> will be 2110 * generated when the <code>PreparedStatement</code> is executed. 2111 * This method differs from the <code>setCharacterStream (int, Reader, int)</code> method 2112 * because it informs the driver that the parameter value should be sent to 2113 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 2114 * driver may have to do extra work to determine whether the parameter 2115 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 2116 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 2117 * @param reader An object that contains the data to set the parameter value to. 2118 * @param length the number of characters in the parameter data. 2119 * @throws SQLException if parameterIndex does not correspond to a parameter 2120 * marker in the SQL statement; if the length specified is less than zero; 2121 * if the driver does not support national character sets; 2122 * if the driver can detect that a data conversion 2123 * error could occur; if a database access error occurs or 2124 * this method is called on a closed <code>PreparedStatement</code> 2125 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 2126 * 2127 * @since 1.6 2128 */ 2129 void setNClob(int parameterIndex, Reader reader, long length) 2130 throws SQLException; 2131 2132 /** 2133 * Sets the designated parameter to a <code>java.sql.NClob</code> object. The driver converts this to a 2134 * SQL <code>NCLOB</code> value when it sends it to the database. 2135 * @param parameterIndex of the first parameter is 1, the second is 2, ... 2136 * @param value the parameter value 2137 * @throws SQLException if the driver does not support national 2138 * character sets; if the driver can detect that a data conversion 2139 * error could occur ; or if a database access error occurs 2140 * @since 1.6 2141 */ 2142 void setNClob(int parameterIndex, NClob value) throws SQLException; 2143 2144 /** 2145 * Sets the designated parameter to a <code>Reader</code> object. 2146 * This method differs from the <code>setCharacterStream (int, Reader)</code> method 2147 * because it informs the driver that the parameter value should be sent to 2148 * the server as a <code>NCLOB</code>. When the <code>setCharacterStream</code> method is used, the 2149 * driver may have to do extra work to determine whether the parameter 2150 * data should be sent to the server as a <code>LONGNVARCHAR</code> or a <code>NCLOB</code> 2151 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if 2152 * it might be more efficient to use a version of 2153 * <code>setNClob</code> which takes a length parameter. 2154 * 2155 * @param parameterIndex index of the first parameter is 1, the second is 2, ... 2156 * @param reader An object that contains the data to set the parameter value to. 2157 * @throws SQLException if parameterIndex does not correspond to a parameter 2158 * marker in the SQL statement; 2159 * if the driver does not support national character sets; 2160 * if the driver can detect that a data conversion 2161 * error could occur; if a database access error occurs or 2162 * this method is called on a closed <code>PreparedStatement</code> 2163 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 2164 * 2165 * @since 1.6 2166 */ 2167 void setNClob(int parameterIndex, Reader reader) 2168 throws SQLException; 2169 2170 /** 2171 * Sets the designated parameter to the given <code>java.net.URL</code> value. 2172 * The driver converts this to an SQL <code>DATALINK</code> value 2173 * when it sends it to the database. 2174 * 2175 * @param parameterIndex the first parameter is 1, the second is 2, ... 2176 * @param x the <code>java.net.URL</code> object to be set 2177 * @exception SQLException if a database access error occurs or 2178 * this method is called on a closed <code>PreparedStatement</code> 2179 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method 2180 * @since 1.4 2181 */ 2182 void setURL(int parameterIndex, java.net.URL x) throws SQLException; 2183 2184 2185 2186 } 2187