RowSet.java revision cec4dd4b1d33f78997603d0f89c0d0e56e64dbcd
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package javax.sql; 19 20import java.sql.ResultSet; 21import java.sql.SQLException; 22import java.sql.Array; 23import java.sql.Blob; 24import java.sql.Clob; 25import java.sql.Date; 26import java.sql.Ref; 27import java.sql.Time; 28import java.sql.Timestamp; 29import java.util.Map; 30import java.io.InputStream; 31import java.io.Reader; 32import java.util.Calendar; 33import java.math.BigDecimal; 34 35/** 36 * An interface which provides means to access data which 37 * persists on a database. It extends the functionality of 38 * {@link java.sql.ResultSet ResultSet} into a form that it can be used as a 39 * JavaBean component, suited for a visual programming environment. 40 * <p> 41 * {@code RowSet} provides getters and setters for properties relating to the 42 * general database environment together with the getters and setters for 43 * distinct data values which constitute the row set. The {@code RowSet} class 44 * supports JavaBean events so that other components in an application can be 45 * informed when changes happen such as changes in data values. 46 * <p> 47 * {@code RowSet} is a facility implemented on top of the remainder of the JDBC 48 * API. It may be <i>connected</i>, maintaining a connection to the database 49 * throughout its lifecycle. The changes made on a <i>disconnected</i> {@code 50 * RowSet} on the other hand can be persisted only establishing a new connection 51 * with the database each time. 52 * <p> 53 * Disconnected {@code RowSets} make use of {@code RowSetReaders} to populate 54 * the {@code RowSet} with data, possibly from a non-relational database source. 55 * They may also use {@code RowSetWriters} to send data back to the underlying 56 * data store. There is considerable freedom in the way that {@code 57 * RowSetReaders} and {@code RowSetWriters} may be implemented to retrieve and 58 * store data. 59 * 60 * @see RowSetReader 61 * @see RowSetWriter 62 */ 63public interface RowSet extends ResultSet { 64 65 /** 66 * Registers the supplied {@link RowSetListener} with this {@code RowSet}. 67 * Once registered, the {@link RowSetListener} is notified of events 68 * generated by the {@code RowSet}. 69 * 70 * @param theListener 71 * an object which implements the {@code rowSetListener} 72 * interface. 73 */ 74 public void addRowSetListener(RowSetListener theListener); 75 76 /** 77 * Clears the parameters previously set for this {@code RowSet}. 78 * <p> 79 * The {@code RowSet} object retains its value until either a new value for 80 * a parameter is set or its value is actively reset. {@code 81 * clearParameters} provides a facility to clear the values for all 82 * parameters with one method call. 83 * 84 * @throws SQLException 85 * if a problem occurs accessing the database. 86 */ 87 public void clearParameters() throws SQLException; 88 89 /** 90 * Fetches data for this {@code RowSet} from the database. If successful, 91 * any existing data for the {@code RowSet} is discarded and its metadata is 92 * overwritten. 93 * <p> 94 * Data is retrieved connecting to the database and executing an 95 * according SQL statement. This requires some or all of the following 96 * properties to be set: URL, database name, user name, password, 97 * transaction isolation, type map; plus some or all of the properties: 98 * command, read only, maximum field size, maximum rows, escape processing, 99 * and query timeout. 100 * <p> 101 * The {@code RowSet} may use a {@code RowSetReader} to access the database 102 * it will then invoke the {@link RowSetReader#readData} method on the 103 * reader to fetch the data. When the new data is fetched all the listeners 104 * are notified to take appropriate measures. 105 * 106 * @throws SQLException 107 * if a problem occurs accessing the database or if the 108 * properties needed to access the database have not been set. 109 * @see RowSetMetaData 110 * @see RowSetReader 111 */ 112 public void execute() throws SQLException; 113 114 /** 115 * Gets the {@code RowSet}'s command property. 116 * 117 * @return a string containing the {@code RowSet}'s command property. A 118 * command is a SQL statement which is executed to fetch required 119 * data into the {@code RowSet}. 120 */ 121 public String getCommand(); 122 123 /** 124 * Gets the ODBC Data Source Name property associated with this {@code 125 * RowSet}. The database name can be used to find a {@link DataSource} 126 * which has been registered with a naming service - the {@link DataSource} 127 * can then be used to create a connection to the database. 128 * 129 * @return the name of the database. 130 */ 131 public String getDataSourceName(); 132 133 /** 134 * Reports if escape processing is enabled for this {@code RowSet}. If 135 * escape processing is on, the driver performs a substitution of the escape 136 * syntax with the applicable code before sending an SQL command to the 137 * database. The default value for escape processing is {@code true}. 138 * 139 * @return {@code true} if escape processing is enabled, {@code 140 * false} otherwise. 141 * @throws SQLException 142 * if a problem occurs accessing the database. 143 */ 144 public boolean getEscapeProcessing() throws SQLException; 145 146 /** 147 * Gets the maximum number of bytes that can be returned for column values 148 * which are of type {@code BINARY}, {@code VARBINARY}, {@code 149 * LONGVARBINARYBINARY}, {@code CHAR}, {@code VARCHAR}, or {@code 150 * LONGVARCHAR}. Excess data is silently discarded if the number is 151 * exceeded. 152 * 153 * @return the current maximum size in bytes. 0 implies no size limit. 154 * @throws SQLException 155 * if a problem occurs accessing the database. 156 */ 157 public int getMaxFieldSize() throws SQLException; 158 159 /** 160 * Gets the maximum number of rows for this {@code RowSet}. Excess rows are 161 * discarded silently if the limit is exceeded. 162 * 163 * @return the previous maximum number of rows. 0 implies no row limit. 164 * @throws SQLException 165 * if a problem occurs accessing the database. 166 */ 167 public int getMaxRows() throws SQLException; 168 169 /** 170 * Gets the value of the password property for this {@code RowSet}. This 171 * property is used when a connection to the database is established. 172 * Therefore it should be set prior to invoking the {@link #execute} method. 173 * 174 * @return the value of the password property. 175 */ 176 public String getPassword(); 177 178 /** 179 * Gets the timeout for the driver when a query operation is executed. If a 180 * query takes longer than the timeout then a {@code SQLException} is 181 * thrown. 182 * 183 * @return the timeout value in seconds. 184 * @throws SQLException 185 * if an error occurs accessing the database. 186 */ 187 public int getQueryTimeout() throws SQLException; 188 189 /** 190 * Gets the transaction isolation level property set for this 191 * {@code RowSet}. The transaction isolation level defines the 192 * policy implemented on the database for maintaining the data 193 * values consistent. 194 * 195 * @return the current transaction isolation level. Must be one of: 196 * <ul> 197 * <li>{@code Connection.TRANSACTION_READ_UNCOMMITTED}</li> 198 * <li>{@code Connection.TRANSACTION_READ_COMMITTED}</li> 199 * <li>{@code Connection.TRANSACTION_REPEATABLE_READ}</li> 200 * <li>{@code Connection.TRANSACTION_SERIALIZABLE}</li> 201 * </ul> 202 * @see java.sql.Connection 203 */ 204 public int getTransactionIsolation(); 205 206 /** 207 * Gets the custom mapping of SQL User-Defined Types (UDTs) and Java classes 208 * for this {@code RowSet}, if applicable. 209 * 210 * @return the custom mappings of SQL types to Java classes. 211 * @throws SQLException 212 * if an error occurs accessing the database. 213 */ 214 public Map<String, Class<?>> getTypeMap() throws SQLException; 215 216 /** 217 * Gets the URL property value for this {@code RowSet}. If there is no 218 * {@code DataSource} object specified, the {@code RowSet} uses the URL to 219 * establish a connection to the database. The default value for the URL is 220 * {@code null}. 221 * 222 * @return a String holding the value of the URL property. 223 * @throws SQLException 224 * if an error occurs accessing the database. 225 */ 226 public String getUrl() throws SQLException; 227 228 /** 229 * Gets the value of the {@code username} property for this {@code RowSet}. 230 * The {@code username} is used when establishing a connection to the 231 * database and should be set before the {@code execute} method is invoked. 232 * 233 * @return a {@code String} holding the value of the {@code username} 234 * property. 235 */ 236 public String getUsername(); 237 238 /** 239 * Indicates if this {@code RowSet} is read-only. 240 * 241 * @return {@code true} if this {@code RowSet} is read-only, {@code false} 242 * if it is updatable. 243 */ 244 public boolean isReadOnly(); 245 246 /** 247 * Removes a specified {@link RowSetListener} object from the set of 248 * listeners which will be notified of events by this {@code RowSet}. 249 * 250 * @param theListener 251 * the {@link RowSetListener} to remove from the set of listeners 252 * for this {@code RowSet}. 253 */ 254 public void removeRowSetListener(RowSetListener theListener); 255 256 /** 257 * Sets the specified {@code ARRAY} parameter in the {@code RowSet} command 258 * with the supplied {@code java.sql.Array} value. 259 * 260 * @param parameterIndex 261 * the index of the parameter to set; the first parameter's index 262 * is 1. 263 * @param theArray 264 * the {@code Array} data value to which the parameter is set. 265 * @throws SQLException 266 * if an error occurs accessing the database. 267 */ 268 public void setArray(int parameterIndex, Array theArray) 269 throws SQLException; 270 271 /** 272 * Sets the value of the specified parameter in the {@code RowSet} command 273 * with the ASCII data in the supplied {@code java.io.InputStream} value. 274 * Data is read from the {@code InputStream} until end-of-file is reached. 275 * 276 * @param parameterIndex 277 * the index of the parameter to set; the first parameter's index 278 * is 1. 279 * @param theInputStream 280 * the ASCII data value to which the parameter is set. 281 * @param length 282 * the length of the data in bytes. 283 * @throws SQLException 284 * if an error occurs accessing the database. 285 */ 286 public void setAsciiStream(int parameterIndex, InputStream theInputStream, 287 int length) throws SQLException; 288 289 /** 290 * Sets the value of the specified SQL {@code NUMERIC} parameter in the 291 * {@code RowSet} command with the data in the supplied {@code 292 * java.math.BigDecimal} value. 293 * 294 * @param parameterIndex 295 * the index of the parameter to set; the first parameter's index 296 * is 1. 297 * @param theBigDecimal 298 * the big decimal value to which the parameter is set. 299 * @throws SQLException 300 * if an error occurs accessing the database. 301 */ 302 public void setBigDecimal(int parameterIndex, BigDecimal theBigDecimal) 303 throws SQLException; 304 305 /** 306 * Sets the value of the specified parameter in the {@code RowSet} command 307 * to the binary data in the supplied input stream. Data is read from the 308 * input stream until end-of-file is reached. 309 * 310 * @param parameterIndex 311 * the index of the parameter to set; the first parameter's index 312 * is 1. 313 * @param theInputStream 314 * the binary data stream to which the parameter is set. 315 * @param length 316 * the length of the data in bytes. 317 * @throws SQLException 318 * if an error occurs accessing the database. 319 */ 320 public void setBinaryStream(int parameterIndex, InputStream theInputStream, 321 int length) throws SQLException; 322 323 /** 324 * Sets the value of the specified parameter in the {@code RowSet} command 325 * to the supplied {@code Blob} value. 326 * 327 * @param parameterIndex 328 * the index of the parameter to set; the first parameter's index 329 * is 1. 330 * @param theBlob 331 * the {@code Blob} value to which the parameter is set. 332 * @throws SQLException 333 * if an error occurs accessing the database. 334 */ 335 public void setBlob(int parameterIndex, Blob theBlob) throws SQLException; 336 337 /** 338 * Sets the value of the specified parameter in the {@code RowSet} command 339 * to the supplied boolean. 340 * 341 * @param parameterIndex 342 * the index of the parameter to set; the first parameter's index 343 * is 1. 344 * @param theBoolean 345 * the {@code boolean} value to which the parameter is set. 346 * @throws SQLException 347 * if an error occurs accessing the database. 348 */ 349 public void setBoolean(int parameterIndex, boolean theBoolean) 350 throws SQLException; 351 352 /** 353 * Sets the value of the specified parameter in the {@code RowSet} command 354 * to the supplied byte value. 355 * 356 * @param parameterIndex 357 * the index of the parameter to set; the first parameter's index 358 * is 1. 359 * @param theByte 360 * the {@code byte} value to which the parameter is set. 361 * @throws SQLException 362 * if an error occurs accessing the database. 363 */ 364 public void setByte(int parameterIndex, byte theByte) throws SQLException; 365 366 /** 367 * Sets the value of the specified parameter in the {@code RowSet} command 368 * to the supplied byte array value. 369 * 370 * @param parameterIndex 371 * the index of the parameter to set; the first parameter's index 372 * is 1. 373 * @param theByteArray 374 * the {@code Array} of {@code bytes} to which the parameter is set. 375 * @throws SQLException 376 * if an error occurs accessing the database. 377 */ 378 public void setBytes(int parameterIndex, byte[] theByteArray) 379 throws SQLException; 380 381 /** 382 * Sets the value of the specified parameter in the {@code RowSet} command 383 * to the sequence of Unicode characters carried by the supplied {@code 384 * java.io.Reader}. 385 * 386 * @param parameterIndex 387 * the index of the parameter to set; the first parameter's index 388 * is 1. 389 * @param theReader 390 * the {@code Reader} which contains the Unicode data to set the 391 * parameter. 392 * @param length 393 * the length of the data in the {@code Reader} in characters. 394 * @throws SQLException 395 * if an error occurs accessing the database. 396 */ 397 public void setCharacterStream(int parameterIndex, Reader theReader, 398 int length) throws SQLException; 399 400 /** 401 * Sets the value of the specified parameter in the {@code RowSet} command 402 * with the value of a supplied {@code java.sql.Clob}. 403 * 404 * @param parameterIndex 405 * the index of the parameter to set; the first parameter's index 406 * is 1. 407 * @param theClob 408 * the {@code Clob} value to which the parameter is set. 409 * @throws SQLException 410 * if an error occurs accessing the database. 411 */ 412 public void setClob(int parameterIndex, Clob theClob) throws SQLException; 413 414 /** 415 * Sets the Command property for this {@code RowSet} - the command is an SQL 416 * query which runs when the {@code execute} method is invoked. This 417 * property is optional for databases that do not support commands. 418 * 419 * @param cmd 420 * the SQL query. Can be {@code null}. 421 * @throws SQLException 422 * if an error occurs accessing the database. 423 */ 424 public void setCommand(String cmd) throws SQLException; 425 426 /** 427 * Sets the concurrency property of this {@code RowSet}. The default value 428 * is {@code ResultSet.CONCUR_READ_ONLY}. 429 * 430 * @param concurrency 431 * the concurrency value. One of: 432 * <ul> 433 * <li>{@code ResultSet.CONCUR_READ_ONLY}</li> 434 * <li>{@code ResultSet.CONCUR_UPDATABLE}</li> 435 * </ul> 436 * @throws SQLException 437 * if an error occurs accessing the database. 438 * @see java.sql.ResultSet 439 */ 440 public void setConcurrency(int concurrency) throws SQLException; 441 442 /** 443 * Sets the database name property for the {@code RowSet}. 444 * <p> 445 * The database name can be used to find a {@link DataSource} which has been 446 * registered with a naming service - the {@link DataSource} can then be 447 * used to create a connection to the database. 448 * 449 * @param name 450 * the database name. 451 * @throws SQLException 452 * if an error occurs accessing the database. 453 */ 454 public void setDataSourceName(String name) throws SQLException; 455 456 /** 457 * Sets the value of the specified parameter in the {@code RowSet} command 458 * with the value of a supplied {@code java.sql.Date}. 459 * 460 * @param parameterIndex 461 * the index of the parameter to set; the first parameter's index 462 * is 1. 463 * @param theDate 464 * the date value to which the parameter is set. 465 * @throws SQLException 466 * if an error occurs accessing the database. 467 */ 468 public void setDate(int parameterIndex, Date theDate) throws SQLException; 469 470 /** 471 * Sets the value of the specified parameter in the {@code RowSet} command 472 * with the value of a supplied {@code java.sql.Date}, where the conversion 473 * of the date to an SQL {@code DATE} value is calculated using a supplied 474 * {@code Calendar}. 475 * 476 * @param parameterIndex 477 * the index of the parameter to set; the first parameter's index 478 * is 1. 479 * @param theDate 480 * the date to which the parameter is set. 481 * @param theCalendar 482 * the {@code Calendar} to use in converting the Date to an SQL 483 * {@code DATE} value. 484 * @throws SQLException 485 * if an error occurs accessing the database. 486 */ 487 public void setDate(int parameterIndex, Date theDate, Calendar theCalendar) 488 throws SQLException; 489 490 /** 491 * Sets the value of the specified parameter in the {@code RowSet} command 492 * with the supplied {@code double}. 493 * 494 * @param parameterIndex 495 * the index of the parameter to set; the first parameter's index 496 * is 1. 497 * @param theDouble 498 * the {@code double} value to which the parameter is set. 499 * @throws SQLException 500 * if an error occurs accessing the database. 501 */ 502 public void setDouble(int parameterIndex, double theDouble) 503 throws SQLException; 504 505 /** 506 * Sets the escape processing status for this {@code RowSet}. If escape 507 * processing is on, the driver performs a substitution of the escape syntax 508 * with the applicable code before sending an SQL command to the database. 509 * The default value for escape processing is {@code true}. 510 * 511 * @param enable 512 * {@code true} to enable escape processing, {@code false} to 513 * turn it off. 514 * @throws SQLException 515 * if an error occurs accessing the database. 516 */ 517 public void setEscapeProcessing(boolean enable) throws SQLException; 518 519 /** 520 * Sets the value of the specified parameter in the {@code RowSet} command 521 * with the supplied {@code float}. 522 * 523 * @param parameterIndex 524 * the index of the parameter to set; the first parameter's index 525 * is 1. 526 * @param theFloat 527 * the {@code float} value to which the parameter is set. 528 * @throws SQLException 529 * if an error occurs accessing the database. 530 */ 531 public void setFloat(int parameterIndex, float theFloat) 532 throws SQLException; 533 534 /** 535 * Sets the value of the specified parameter in the {@code RowSet} command 536 * with the supplied {@code integer}. 537 * 538 * @param parameterIndex 539 * the index of the parameter to set; the first parameter's index 540 * is 1. 541 * @param theInteger 542 * the {@code integer} value to which the parameter is set. 543 * @throws SQLException 544 * if an error occurs accessing the database. 545 */ 546 public void setInt(int parameterIndex, int theInteger) throws SQLException; 547 548 /** 549 * Sets the value of the specified parameter in the {@code RowSet} command 550 * with the supplied {@code long}. 551 * 552 * @param parameterIndex 553 * the index of the parameter to set; the first parameter's index 554 * is 1. 555 * @param theLong 556 * the {@code long} value value to which the parameter is set. 557 * @throws SQLException 558 * if an error occurs accessing the database. 559 */ 560 public void setLong(int parameterIndex, long theLong) throws SQLException; 561 562 /** 563 * Sets the maximum number of bytes which can be returned for a column value 564 * where the column type is one of {@code BINARY}, {@code VARBINARY}, 565 * {@code LONGVARBINARYBINARY}, {@code CHAR}, {@code VARCHAR}, or {@code 566 * LONGVARCHAR}. Data which exceeds this limit is silently discarded. For 567 * portability, a value greater than 256 is recommended. 568 * 569 * @param max 570 * the maximum size of the returned column value in bytes. 0 571 * implies no size limit. 572 * @throws SQLException 573 * if an error occurs accessing the database. 574 */ 575 public void setMaxFieldSize(int max) throws SQLException; 576 577 /** 578 * Sets the maximum number of rows which can be held by the {@code RowSet}. 579 * Any additional rows are silently discarded. 580 * 581 * @param max 582 * the maximum number of rows which can be held in the {@code 583 * RowSet}. 0 means no limit. 584 * @throws SQLException 585 * if an error occurs accessing the database. 586 */ 587 public void setMaxRows(int max) throws SQLException; 588 589 /** 590 * Sets the value of the specified parameter in the {@code RowSet} command 591 * to SQL {@code NULL}. 592 * 593 * @param parameterIndex 594 * the index of the parameter to set; the first parameter's index 595 * is 1. 596 * @param sqlType 597 * the type of the parameter, as defined by {@code 598 * java.sql.Types}. 599 * @throws SQLException 600 * if an error occurs accessing the database. 601 */ 602 public void setNull(int parameterIndex, int sqlType) throws SQLException; 603 604 /** 605 * Sets the value of the specified parameter in the {@code RowSet} command 606 * to SQL {@code NULL}. This form of the {@code setNull} method should be 607 * used for User Defined Types and {@code REF} parameters. 608 * 609 * @param parameterIndex 610 * the index of the parameter to set; the first parameter's index 611 * is 1. 612 * @param sqlType 613 * the type of the parameter, as defined by {@code 614 * java.sql.Types}. 615 * @param typeName 616 * the fully qualified name of an SQL user defined type or the 617 * name of the SQL structured type referenced by a {@code REF} 618 * type. Ignored if the sqlType is not a UDT or REF type. 619 * @throws SQLException 620 * if an error occurs accessing the database. 621 */ 622 public void setNull(int parameterIndex, int sqlType, String typeName) 623 throws SQLException; 624 625 /** 626 * Sets the value of the specified parameter in the {@code RowSet} command 627 * to a supplied Java object. 628 * <p> 629 * The JDBC specification provides a standard mapping for Java objects to 630 * SQL data types. Database specific types can be mapped by JDBC driver 631 * specific Java types. 632 * 633 * @param parameterIndex 634 * the index of the parameter to set; the first parameter's index 635 * is 1. 636 * @param theObject 637 * the Java object containing the data value to which the 638 * parameter is set. 639 * @throws SQLException 640 * if an error occurs accessing the database. 641 */ 642 public void setObject(int parameterIndex, Object theObject) 643 throws SQLException; 644 645 /** 646 * Sets the value of the specified parameter in the {@code RowSet} command 647 * to a supplied Java object. 648 * 649 * @param parameterIndex 650 * the index of the parameter to set; the first parameter's index 651 * is 1. 652 * @param theObject 653 * the Java object containing the data value. 654 * @param targetSqlType 655 * the SQL type to send to the database, as defined in {@code 656 * java.sql.Types}. 657 * @throws SQLException 658 * if an error occurs accessing the database. 659 */ 660 public void setObject(int parameterIndex, Object theObject, 661 int targetSqlType) throws SQLException; 662 663 /** 664 * Sets the value of the specified parameter in the {@code RowSet} command 665 * to a supplied Java object. 666 * 667 * @param parameterIndex 668 * the index of the parameter to set; the first parameter's index 669 * is 1. 670 * @param theObject 671 * the Java object containing the data value. 672 * @param targetSqlType 673 * the SQL type to send to the database, as defined in {@code 674 * java.sql.Types}. 675 * @param scale 676 * the number of digits after the decimal point, for {@code 677 * java.sql.Types.DECIMAL} and {@code java.sql.Types.NUMERIC} 678 * types. Ignored for all other types. 679 * @throws SQLException 680 * if an error occurs accessing the database. 681 */ 682 public void setObject(int parameterIndex, Object theObject, 683 int targetSqlType, int scale) throws SQLException; 684 685 /** 686 * Sets the database Password for this {@code RowSet}. This property is used 687 * when a connection to the database is established. Therefore it should be 688 * set prior to invoking the {@link #execute} method. 689 * 690 * @param password 691 * a {@code String} holding the password. 692 * @throws SQLException 693 * if an error occurs accessing the database. 694 */ 695 public void setPassword(String password) throws SQLException; 696 697 /** 698 * Gets the timeout for the driver when a query operation is executed. If a 699 * query takes longer than the timeout, a {@code SQLException} is thrown. 700 * 701 * @param seconds 702 * the number of seconds for the timeout. 703 * @throws SQLException 704 * if an error occurs accessing the database. 705 */ 706 public void setQueryTimeout(int seconds) throws SQLException; 707 708 /** 709 * Sets whether the {@code RowSet} is read-only or updatable. 710 * 711 * @param readOnly 712 * {@code true} to set the {@code RowSet} to read-only state, 713 * {@code false} to allow updates. 714 * @throws SQLException 715 * if an error occurs accessing the database. 716 */ 717 public void setReadOnly(boolean readOnly) throws SQLException; 718 719 /** 720 * Sets the value of the specified parameter in the {@code RowSet} command 721 * to a supplied {@code java.sql.Ref}. This is sent to the database as an 722 * SQL {@code REF} value. 723 * 724 * @param parameterIndex 725 * the index of the parameter to set; the first parameter's index 726 * is 1. 727 * @param theRef 728 * the value to which the parameter is set. 729 * @throws SQLException 730 * if an error occurs accessing the database. 731 * @see java.sql.Ref 732 */ 733 public void setRef(int parameterIndex, Ref theRef) throws SQLException; 734 735 /** 736 * Sets the value of the specified parameter in the {@code RowSet} command 737 * to a supplied {@code short integer}. 738 * 739 * @param parameterIndex 740 * the index of the parameter to set; the first parameter's index 741 * is 1. 742 * @param theShort 743 * the value to which the parameter is set. 744 * @throws SQLException 745 * if an error occurs accessing the database. 746 */ 747 public void setShort(int parameterIndex, short theShort) 748 throws SQLException; 749 750 /** 751 * Sets the value of the specified parameter in the {@code RowSet} command 752 * to a supplied {@code String}. The string is placed into the database as a 753 * {@code VARCHAR} or {@code LONGVARCHAR} SQL value, depending on the 754 * database limits for the length of {@code VARCHAR} values. 755 * 756 * @param parameterIndex 757 * the index of the parameter to set; the first parameter's index 758 * is 1. 759 * @param theString 760 * the value to which the parameter is set. 761 * @throws SQLException 762 * if an error occurs accessing the database. 763 */ 764 public void setString(int parameterIndex, String theString) 765 throws SQLException; 766 767 /** 768 * Sets the value of the specified parameter in the {@code RowSet} command 769 * to a supplied {@code java.sql.Time}, converting it to an SQL {@code TIME} 770 * value using the system default {@code Calendar}. 771 * 772 * @param parameterIndex 773 * the index of the parameter to set; the first parameter's index 774 * is 1. 775 * @param theTime 776 * the value to which the parameter is set. 777 * @throws SQLException 778 * if an error occurs accessing the database. 779 * @see java.util.Calendar 780 * @see java.sql.Time 781 */ 782 public void setTime(int parameterIndex, Time theTime) throws SQLException; 783 784 /** 785 * Sets the value of the specified parameter in the {@code RowSet} command 786 * to a supplied {@code java.sql.Time}, converting it to an SQL {@code TIME} 787 * value using a supplied {@code Calendar}. 788 * 789 * @param parameterIndex 790 * the index of the parameter to set; the first parameter's index 791 * is 1. 792 * @param theTime 793 * the value to which the parameter is set. 794 * @param theCalendar 795 * the {@code Calendar} to use in the conversion operation. 796 * @throws SQLException 797 * if an error occurs accessing the database. 798 * @see java.util.Calendar 799 * @see java.sql.Time 800 */ 801 public void setTime(int parameterIndex, Time theTime, Calendar theCalendar) 802 throws SQLException; 803 804 /** 805 * Sets the value of the specified parameter in the {@code RowSet} command 806 * to a supplied {@code java.sql.Timestamp}, converting it to an SQL {@code 807 * TIMESTAMP} value using the system default {@code Calendar}. 808 * 809 * @param parameterIndex 810 * the index of the parameter to set; the first parameter's index 811 * is 1. 812 * @param theTimestamp 813 * the value to which the parameter is set. 814 * @throws SQLException 815 * if an error occurs accessing the database. 816 * @see java.util.Calendar 817 * @see java.sql.Timestamp 818 */ 819 public void setTimestamp(int parameterIndex, Timestamp theTimestamp) 820 throws SQLException; 821 822 /** 823 * Sets the value of the specified parameter in the {@code RowSet} command 824 * to a supplied {@code java.sql.Timestamp}, converting it to an SQL {@code 825 * TIMESTAMP} value using a supplied {@code Calendar}. 826 * 827 * @param parameterIndex 828 * the index of the parameter to set; the first parameter's index 829 * is 1. 830 * @param theTimestamp 831 * the value to which the parameter is set. 832 * @param theCalendar 833 * the {@code Calendar} to use in the conversion operation 834 * @throws SQLException 835 * if an error occurs accessing the database. 836 * @see java.util.Calendar 837 * @see java.sql.Timestamp 838 */ 839 public void setTimestamp(int parameterIndex, Timestamp theTimestamp, 840 Calendar theCalendar) throws SQLException; 841 842 /** 843 * Sets the target instance's transaction isolation level to one of a 844 * discrete set of possible values. The transaction isolation level defines 845 * the policy implemented on the database for maintaining the data values 846 * consistent. 847 * <p> 848 * Keep in mind that setting a transaction isolation level has no effect 849 * unless your driver and DBMS support it. 850 * 851 * @param level 852 * the transaction isolation level. One of: 853 * <ul> 854 * <li>{@code Connection.TRANSACTION_READ_UNCOMMITTED}</li> 855 * <li>{@code Connection.TRANSACTION_READ_COMMITTED}</li> 856 * <li>{@code Connection.TRANSACTION_REPEATABLE_READ}</li> 857 * <li>{@code Connection.TRANSACTION_SERIALIZABLE}</li> 858 * </ul> 859 * @throws SQLException 860 * if an error occurs accessing the database. 861 * @see java.sql.Connection 862 */ 863 public void setTransactionIsolation(int level) throws SQLException; 864 865 /** 866 * Sets the type of this {@code RowSet}. By default, the type is 867 * non-scrollable. 868 * 869 * @param type 870 * the type for the {@code RowSet}. One of: 871 * <ul> 872 * <li>{@code ResultSet.TYPE_FORWARD_ONLY}</li> 873 * <li>{@code ResultSet.TYPE_SCROLL_INSENSITIVE}</li> 874 * <li>{@code ResultSet.TYPE_SCROLL_SENSITIVE}</li> 875 * </ul> 876 * @throws SQLException 877 * if an error occurs accessing the database. 878 */ 879 public void setType(int type) throws SQLException; 880 881 /** 882 * Sets the mapping of SQL User Defined Types (UDTs) to Java classes. The 883 * Java classes must all implement the {@link java.sql.SQLData SQLData} 884 * interface. 885 * 886 * @param theTypeMap 887 * the names of SQL UDTs and the Java classes to which they are 888 * mapped. 889 * @throws SQLException 890 * if an error occurs accessing the database. 891 */ 892 public void setTypeMap(Map<String, Class<?>> theTypeMap) 893 throws SQLException; 894 895 /** 896 * Sets the URL used by this {@code RowSet} to access the database via a 897 * {@code DriverManager}. The URL is optional - an alternative is to use a 898 * database name to create a connection. 899 * 900 * @param theURL 901 * the URL for the database. Can be {@code null}. 902 * @throws SQLException 903 * if an error occurs accessing the database. 904 */ 905 public void setUrl(String theURL) throws SQLException; 906 907 /** 908 * Sets the {@code Username} property for the {@code RowSet}, used to 909 * authenticate a connection to the database. 910 * 911 * @param theUsername 912 * the new user name for this row set. 913 * @throws SQLException 914 * if an error occurs accessing the database. 915 */ 916 public void setUsername(String theUsername) throws SQLException; 917} 918