CallableStatement.java revision f33eae7e84eb6d3b0f4e86b59605bb3de73009f3
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 java.sql; 19 20import java.math.BigDecimal; 21import java.util.Calendar; 22import java.util.Map; 23import java.net.URL; 24import java.io.InputStream; 25import java.io.Reader; 26 27/** 28 * An interface used to call <i>Stored Procedures</i>. 29 * <p> 30 * The JDBC API provides an SQL escape syntax allowing <i>Stored Procedures</i> 31 * to be called in a standard way for all databases. The JDBC escape syntax has 32 * two forms. One form includes a result parameter. The second form does not 33 * include a result parameter. Where the result parameter is used, it must be 34 * declared as an {@code OUT} parameter. Other parameters can be declared as 35 * {@code IN}, {@code OUT}, or {@code INOUT}. Parameters are referenced either by 36 * name or by a numerical index starting at 1. 37 * <p> 38 * The correct syntax is: 39 * <dd> 40 * <dl> 41 * { ?= call <procedurename> [( [parameter1,parameter2,...] )] } 42 * </dl> 43 * <dl> 44 * { call <procedurename> [( [parameter1,parameter2,...] )] } 45 * </dl> 46 * </code></dd> 47 * {@code IN} parameters are set before calling the procedure, 48 * using the setter methods which are inherited from {@code PreparedStatement}. 49 * For {@code OUT} parameters, their type must be registered before executing 50 * the stored procedure. The values are retrieved using the getter methods 51 * defined in the {@code CallableStatement} interface. 52 * <p> 53 * {@code CallableStatement}s can return one or more {@code ResultSets}. In the 54 * event that multiple {@code ResultSets} are returned, they are accessed using 55 * the methods inherited from the {@code Statement} interface. 56 */ 57public interface CallableStatement extends PreparedStatement { 58 59 /** 60 * Gets the value of a specified JDBC {@code ARRAY} parameter as a 61 * {@code java.sql.Array}. 62 * 63 * @param parameterIndex 64 * the parameter index, where the first parameter has 65 * index 1. 66 * @return a {@code java.sql.Array} containing the parameter value. 67 * @throws SQLException 68 * if a database error occurs. 69 */ 70 public Array getArray(int parameterIndex) throws SQLException; 71 72 /** 73 * Gets the value of a specified JDBC {@code ARRAY} parameter as a {@code 74 * java.sql.Array}. 75 * 76 * @param parameterName 77 * the desired parameter's name. 78 * @return a {@code java.sql.Array} containing the parameter's value. 79 * @throws SQLException 80 * if there is a problem accessing the database. 81 */ 82 public Array getArray(String parameterName) throws SQLException; 83 84 /** 85 * Returns a new {@link BigDecimal} representation of the JDBC {@code 86 * NUMERIC} parameter specified by the input index. 87 * 88 * @param parameterIndex 89 * the parameter number index where the first parameter has index 90 * 1. 91 * @return a {@code java.math.BigDecimal} representing the value of the 92 * specified parameter. The value {@code null} is returned if 93 * the parameter in question is an SQL {@code NULL}. 94 * @throws SQLException 95 * if a database error occurs. 96 */ 97 public BigDecimal getBigDecimal(int parameterIndex) throws SQLException; 98 99 /** 100 * Returns a new {@link BigDecimal} representation of the JDBC {@code 101 * NUMERIC} parameter specified by the input index. The number of digits 102 * after the decimal point is specified by {@code scale}. 103 * 104 * @param parameterIndex 105 * the parameter number index, where the first parameter has 106 * index 1. 107 * @param scale 108 * the number of digits after the decimal point to get. 109 * @return a {@code java.math.BigDecimal} representing the value of the 110 * specified parameter. The value {@code null} is returned if 111 * the parameter in question is an SQL {@code NULL}. 112 * @throws SQLException 113 * if a database error occurs. 114 * @deprecated Use {@link #getBigDecimal(int)} or 115 * {@link #getBigDecimal(String)} 116 */ 117 @Deprecated 118 public BigDecimal getBigDecimal(int parameterIndex, int scale) 119 throws SQLException; 120 121 /** 122 * Returns a new {@link BigDecimal} representation of the JDBC {@code 123 * NUMERIC} parameter specified by the input name. 124 * 125 * @param parameterName 126 * the desired parameter's name. 127 * @return a {@code java.math.BigDecimal} representing the value of the 128 * specified parameter. The value {@code null} is returned if 129 * the parameter in question is an SQL {@code NULL}. 130 * @throws SQLException 131 * if a database error occurs. 132 */ 133 public BigDecimal getBigDecimal(String parameterName) throws SQLException; 134 135 /** 136 * Gets the value of a specified JDBC {@code BLOB} parameter as a {@code 137 * java.sql.Blob}. 138 * 139 * @param parameterIndex 140 * the parameter number index, where the first parameter has 141 * index 1. 142 * @return a {@code java.sql.Blob} representing the value of the 143 * specified parameter. The value {@code null} is returned if 144 * the parameter in question is an SQL {@code NULL}. 145 * @throws SQLException 146 * if a database error occurs. 147 */ 148 public Blob getBlob(int parameterIndex) throws SQLException; 149 150 /** 151 * Gets the value of a specified JDBC {@code BLOB} parameter as a {@code 152 * java.sql.Blob}. 153 * 154 * @param parameterName 155 * the desired parameter's name. 156 * @return a {@code java.sql.Blob} representing the value of the 157 * specified parameter. The value {@code null} is returned if 158 * the parameter in question is an SQL {@code NULL}. 159 * @throws SQLException 160 * if a database error occurs. 161 */ 162 public Blob getBlob(String parameterName) throws SQLException; 163 164 /** 165 * Gets the value of a specified JDBC {@code BIT} parameter as a boolean. 166 * 167 * @param parameterIndex 168 * the parameter number index, where the first parameter has 169 * index 1. 170 * @return a {@code boolean} representing the parameter value. {@code false} 171 * is returned if the value is SQL {@code NULL}. 172 * @throws SQLException 173 * if a database error occurs. 174 */ 175 public boolean getBoolean(int parameterIndex) throws SQLException; 176 177 /** 178 * Gets the value of a specified JDBC {@code BIT} parameter as a {@code 179 * boolean}. 180 * 181 * @param parameterName 182 * the desired parameter's name. 183 * @return a {@code boolean} representation of the value of the parameter. 184 * {@code false} is returned if the SQL value is {@code NULL}. 185 * @throws SQLException 186 * if a database error occurs. 187 */ 188 public boolean getBoolean(String parameterName) throws SQLException; 189 190 /** 191 * Gets the value of a specified JDBC {@code TINYINT} parameter as a {@code 192 * byte}. 193 * 194 * @param parameterIndex 195 * the parameter number index, where the first parameter has 196 * index 1. 197 * @return a {@code byte} representation of the value of the parameter. 198 * {@code 0} is returned if the value is SQL {@code NULL}. 199 * @throws SQLException 200 * if a database error occurs. 201 */ 202 public byte getByte(int parameterIndex) throws SQLException; 203 204 /** 205 * Gets the value of a specified JDBC {@code TINYINT} parameter as a Java 206 * {@code byte}. 207 * 208 * @param parameterName 209 * the desired parameter's name. 210 * @return a {@code byte} representation of the value of the parameter. 211 * {@code 0} is returned if the SQL value is {@code NULL}. 212 * @throws SQLException 213 * if a database error occurs. 214 */ 215 public byte getByte(String parameterName) throws SQLException; 216 217 /** 218 * Returns a byte array representation of the indexed JDBC {@code BINARY} or 219 * {@code VARBINARY} parameter. 220 * 221 * @param parameterIndex 222 * the parameter number index, where the first parameter has 223 * index 1. 224 * @return an array of bytes giving the value of the parameter. {@code null} 225 * is returned if the value is SQL {@code NULL}. 226 * @throws SQLException 227 * if a database error occurs. 228 */ 229 public byte[] getBytes(int parameterIndex) throws SQLException; 230 231 /** 232 * Returns a byte array representation of the named JDBC {@code BINARY} or 233 * {@code VARBINARY} parameter. 234 * 235 * @param parameterName 236 * the name of the parameter. 237 * @return an array of bytes giving the value of the parameter. {@code null} 238 * is returned if the value is SQL {@code NULL}. 239 * @throws SQLException 240 * if a database error occurs. 241 */ 242 public byte[] getBytes(String parameterName) throws SQLException; 243 244 /** 245 * Gets the value of a specified JDBC {@code CLOB} parameter as a {@code 246 * java.sql.Clob}. 247 * 248 * @param parameterIndex 249 * the parameter number index, where the first parameter has 250 * index 1. 251 * @return a {@code java.sql.Clob} representing the value of the 252 * parameter. {@code null} is returned if the value is SQL 253 * {@code NULL}. 254 * @throws SQLException 255 * if a database error occurs. 256 * @see Clob 257 */ 258 public Clob getClob(int parameterIndex) throws SQLException; 259 260 /** 261 * Gets the value of a specified JDBC {@code CLOB} parameter as a {@code 262 * java.sql.Clob}. 263 * 264 * @param parameterName 265 * the name of the parameter. 266 * @return a {@code java.sql.Clob} with the value of the parameter. {@code 267 * null} is returned if the value is SQL {@code NULL}. 268 * @throws SQLException 269 * if a database error occurs. 270 * @see Clob 271 */ 272 public Clob getClob(String parameterName) throws SQLException; 273 274 /** 275 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 276 * java.sql.Date}. 277 * 278 * @param parameterIndex 279 * the parameter number index, where the first parameter has 280 * index 1. 281 * @return the {@code java.sql.Date} representing the parameter's value. 282 * {@code null} is returned if the value is SQL {@code NULL}. 283 * @throws SQLException 284 * if a database error occurs. 285 * @see Date 286 */ 287 public Date getDate(int parameterIndex) throws SQLException; 288 289 /** 290 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 291 * java.sql.Date}, using the specified {@code Calendar} to construct the date. 292 * <p> 293 * The JDBC driver uses the calendar to create the Date using a particular 294 * timezone and locale. The default behavior of the driver is to use the Java 295 * virtual machine default settings. 296 * 297 * @param parameterIndex 298 * the parameter number index, where the first parameter has 299 * index 1. 300 * @param cal 301 * the {@code Calendar} to use to construct the date 302 * @return the {@code java.sql.Date} giving the parameter's value. {@code null} 303 * is returned if the value is SQL {@code NULL}. 304 * @throws SQLException 305 * if a database error occurs. 306 * @see Date 307 */ 308 public Date getDate(int parameterIndex, Calendar cal) throws SQLException; 309 310 /** 311 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 312 * java.sql.Date}. 313 * 314 * @param parameterName 315 * the name of the desired parameter. 316 * @return the {@code java.sql.Date} giving the parameter's value. {@code null} 317 * is returned if the value is SQL {@code NULL}. 318 * @throws SQLException 319 * if a database error occurs. 320 * @see Date 321 */ 322 public Date getDate(String parameterName) throws SQLException; 323 324 /** 325 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 326 * java.sql.Date}, using the specified {@code Calendar} to construct the date. 327 * <p> 328 * The JDBC driver uses the calendar to create the date using a particular 329 * timezone and locale. The default behavior of the driver is to use the Java 330 * virtual machine default settings. 331 * 332 * @param parameterName 333 * the name of the desired parameter. 334 * @param cal 335 * used for creating the returned {@code Date}. 336 * @return the {@code java.sql.Date} giving the parameter's value. {@code null} 337 * is returned if the value is SQL {@code NULL}. 338 * @throws SQLException 339 * if a database error occurs. 340 * @see Date 341 */ 342 public Date getDate(String parameterName, Calendar cal) throws SQLException; 343 344 /** 345 * Gets the value of the specified JDBC {@code DOUBLE} parameter as a 346 * {@code double}. 347 * 348 * @param parameterIndex 349 * the parameter number index, where the first parameter has 350 * index 1. 351 * @return the parameter's value as a {@code double}. {@code 0.0} 352 * is returned if the value is SQL {@code NULL}. 353 * @throws SQLException 354 * if a database error occurs. 355 */ 356 public double getDouble(int parameterIndex) throws SQLException; 357 358 /** 359 * Gets the value of the specified JDBC {@code DOUBLE} parameter as a 360 * {@code double}. 361 * 362 * @param parameterName 363 * the name of the desired parameter. 364 * @return the parameter's value as a {@code double}. {@code 0.0} 365 * is returned if the value is SQL {@code NULL}. 366 * @throws SQLException 367 * if there is a problem accessing the database. 368 */ 369 public double getDouble(String parameterName) throws SQLException; 370 371 /** 372 * Gets the value of the specified JDBC {@code FLOAT} parameter as a {@code 373 * float}. 374 * 375 * @param parameterIndex 376 * the parameter number index, where the first parameter has 377 * index 1. 378 * @return the parameter's value as a {@code float}. {@code 0.0} 379 * is returned if the value is SQL {@code NULL}. 380 * @throws SQLException 381 * if a database error occurs. 382 */ 383 public float getFloat(int parameterIndex) throws SQLException; 384 385 /** 386 * Gets the value of the specified JDBC {@code FLOAT} parameter as a Java 387 * {@code float}. 388 * 389 * @param parameterName 390 * the name of the desired parameter. 391 * @return the parameter's value as a {@code float}. {@code 0.0} 392 * is returned if the value is SQL {@code NULL}. 393 * @throws SQLException 394 * if there is a problem accessing the database. 395 */ 396 public float getFloat(String parameterName) throws SQLException; 397 398 /** 399 * Gets the value of the specified JDBC {@code INTEGER} parameter as an 400 * {@code int}. 401 * 402 * @param parameterIndex 403 * the parameter number index, where the first parameter has 404 * index 1. 405 * @return the {@code int} giving the parameter's value. {@code 0} 406 * is returned if the value is SQL {@code NULL}. 407 * @throws SQLException 408 * if a database error occurs. 409 */ 410 public int getInt(int parameterIndex) throws SQLException; 411 412 /** 413 * Gets the value of the specified JDBC {@code INTEGER} parameter as an 414 * {@code int}. 415 * 416 * @param parameterName 417 * the name of the desired parameter. 418 * @return the {@code int} giving the parameter's value. {@code 0} 419 * is returned if the value is SQL {@code NULL}. 420 * @throws SQLException 421 * if a database error occurs. 422 */ 423 public int getInt(String parameterName) throws SQLException; 424 425 /** 426 * Gets the value of the specified JDBC {@code BIGINT} parameter as a 427 * {@code long}. 428 * 429 * @param parameterIndex 430 * the parameter number index, where the first parameter has 431 * index 1. 432 * @return the {@code long} giving the parameter's value. {@code 0} 433 * is returned if the value is SQL {@code NULL}. 434 * @throws SQLException 435 * if a database error occurs. 436 */ 437 public long getLong(int parameterIndex) throws SQLException; 438 439 /** 440 * Gets the value of the specified JDBC {@code BIGINT} parameter as a 441 * {@code long}. 442 * 443 * @param parameterName 444 * the name of the desired parameter. 445 * @return the {@code long} giving the parameter's value. {@code 0} 446 * is returned if the value is SQL {@code NULL}. 447 * @throws SQLException 448 * if a database error occurs. 449 */ 450 public long getLong(String parameterName) throws SQLException; 451 452 /** 453 * Gets the value of the specified parameter as a Java {@code Object}. 454 * <p> 455 * The object type returned is the JDBC type registered for the parameter 456 * with a {@code registerOutParameter} call. If a parameter was registered 457 * as a {@code java.sql.Types.OTHER} then it may hold abstract types that 458 * are particular to the connected database. 459 * 460 * @param parameterIndex 461 * the parameter number index, where the first parameter has 462 * index 1. 463 * @return an Object holding the value of the parameter. 464 * @throws SQLException 465 * if a database error occurs. 466 */ 467 public Object getObject(int parameterIndex) throws SQLException; 468 469 /** 470 * Gets the value of the specified parameter as an {@code Object}. The 471 * {@code Map} gives the correspondence between SQL types and Java classes. 472 * 473 * @param parameterIndex 474 * the parameter number index, where the first parameter has 475 * index 1. 476 * @param map 477 * the {@code Map} giving the correspondence between SQL 478 * types and Java classes. 479 * @return an Object holding the value of the parameter. 480 * @throws SQLException 481 * if a database error occurs. 482 */ 483 public Object getObject(int parameterIndex, Map<String, Class<?>> map) 484 throws SQLException; 485 486 /** 487 * Gets the value of the specified parameter as an {@code Object}. 488 * <p> 489 * The object type returned is the JDBC type that was registered for 490 * the parameter by an earlier call to {@link #registerOutParameter}. 491 * If a parameter was registered as a {@code java.sql.Types.OTHER} 492 * then it may hold abstract types that are particular to the 493 * connected database. 494 * 495 * @param parameterName 496 * the parameter name. 497 * @return the Java {@code Object} representation of the value of the 498 * parameter. 499 * @throws SQLException 500 * if there is a problem accessing the database. 501 */ 502 public Object getObject(String parameterName) throws SQLException; 503 504 /** 505 * Gets the value of a specified parameter as an {@code Object}. The 506 * actual return type is determined by the {@code Map} parameter which 507 * gives the correspondence between SQL types and Java classes. 508 * 509 * @param parameterName 510 * the parameter name. 511 * @param map 512 * the {@code Map} of SQL types to their Java counterparts 513 * @return an {@code Object} holding the value of the parameter. 514 * @throws SQLException 515 * if there is a problem accessing the database. 516 */ 517 public Object getObject(String parameterName, Map<String, Class<?>> map) 518 throws SQLException; 519 520 /** 521 * Gets the value of a specified SQL {@code REF(<structured type>)} 522 * parameter as a {@code java.sql.Ref}. 523 * 524 * @param parameterIndex 525 * the parameter number index, where the first parameter has 526 * index 1. 527 * @return a {@code java.sql.Ref} with the parameter value. {@code null} 528 * is returned if the value is SQL {@code NULL}. 529 * @throws SQLException 530 * if a database error occurs. 531 */ 532 public Ref getRef(int parameterIndex) throws SQLException; 533 534 /** 535 * Gets the value of a specified SQL {@code REF(<structured type>)} 536 * parameter as a {@code java.sql.Ref}. 537 * 538 * @param parameterName 539 * the desired parameter's name. 540 * @return the parameter's value in the form of a {@code 541 * java.sql.Ref}. A {@code null} reference is returned if the 542 * parameter's value is SQL {@code NULL}. 543 * @throws SQLException 544 * if there is a problem accessing the database. 545 * @see Ref 546 */ 547 public Ref getRef(String parameterName) throws SQLException; 548 549 /** 550 * Gets the value of a specified JDBC {@code SMALLINT} parameter as a 551 * {@code short}. 552 * 553 * @param parameterIndex 554 * the parameter number index, where the first parameter has 555 * index 1. 556 * @return the parameter's value as a {@code short}. 0 is returned 557 * if the parameter's value is SQL {@code NULL}. 558 * @throws SQLException 559 * if a database error occurs. 560 */ 561 public short getShort(int parameterIndex) throws SQLException; 562 563 /** 564 * Gets the value of a specified JDBC {@code SMALLINT} parameter as a 565 * {@code short}. 566 * 567 * @param parameterName 568 * the desired parameter's name. 569 * @return the parameter's value as a {@code short}. 0 is returned 570 * if the parameter's value is SQL {@code NULL}. 571 * @throws SQLException 572 * if there is a problem accessing the database. 573 */ 574 public short getShort(String parameterName) throws SQLException; 575 576 /** 577 * Returns the indexed parameter's value as a {@code String}. The 578 * parameter value must be one of the JDBC types {@code CHAR}, 579 * {@code VARCHAR} or {@code LONGVARCHAR}. 580 * <p> 581 * The {@code String} corresponding to a {@code CHAR} of fixed length 582 * will be of identical length to the value in the database inclusive 583 * of padding characters. 584 * 585 * @param parameterIndex 586 * the parameter number index, where the first parameter has 587 * index 1. 588 * @return the parameter's value as a {@code String}. {@code null} 589 * is returned if the value is SQL {@code NULL}. 590 * @throws SQLException 591 * if there is a problem accessing the database. 592 */ 593 public String getString(int parameterIndex) throws SQLException; 594 595 /** 596 * Returns the named parameter's value as a string. The parameter value must 597 * be one of the JDBC types {@code CHAR}, {@code VARCHAR} or {@code 598 * LONGVARCHAR}. 599 * <p> 600 * The string corresponding to a {@code CHAR} of fixed length will be of 601 * identical length to the value in the database inclusive of padding 602 * characters. 603 * 604 * @param parameterName 605 * the desired parameter's name. 606 * @return the parameter's value as a {@code String}. {@code null} 607 * is returned if the value is SQL {@code NULL}. 608 * @throws SQLException 609 * if there is a problem accessing the database. 610 */ 611 public String getString(String parameterName) throws SQLException; 612 613 /** 614 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 615 * java.sql.Time}. 616 * 617 * @param parameterIndex 618 * the parameter number index, where the first parameter has 619 * index 1. 620 * @return the parameter's value as a {@code java.sql.Time}. 621 * {@code null} is returned if the value is SQL {@code NULL}. 622 * @throws SQLException 623 * if a database error occurs. 624 * @see Time 625 */ 626 public Time getTime(int parameterIndex) throws SQLException; 627 628 /** 629 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 630 * java.sql.Time}, using the supplied {@code Calendar} to construct the 631 * time. The JDBC driver uses the calendar to handle specific timezones 632 * and locales in order to determine {@code Time}. 633 * 634 * @param parameterIndex 635 * the parameter number index, where the first parameter has 636 * index 1. 637 * @param cal 638 * the calendar to use in constructing {@code Time}. 639 * @return the parameter's value as a {@code java.sql.Time}. 640 * {@code null} is returned if the value is SQL {@code NULL}. 641 * @throws SQLException 642 * if a database error occurs. 643 * @see Time 644 * @see java.util.Calendar 645 */ 646 public Time getTime(int parameterIndex, Calendar cal) throws SQLException; 647 648 /** 649 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 650 * java.sql.Time}. 651 * 652 * @param parameterName 653 * the name of the desired parameter. 654 * @return a new {@code java.sql.Time} with the parameter's value. A {@code 655 * null} reference is returned for an SQL value of {@code NULL}. 656 * @throws SQLException 657 * if a database error occurs. 658 * @see Time 659 */ 660 public Time getTime(String parameterName) throws SQLException; 661 662 /** 663 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 664 * java.sql.Time}, using the supplied {@code Calendar} to construct 665 * the time. The JDBC driver uses the calendar to handle specific 666 * timezones and locales when creating {@code Time}. 667 * 668 * @param parameterName 669 * the name of the desired parameter. 670 * @param cal 671 * used for creating the returned {@code Time} 672 * @return a new {@code java.sql.Time} with the parameter's value. A {@code 673 * null} reference is returned for an SQL value of {@code NULL}. 674 * @throws SQLException 675 * if a database error occurs. 676 * @see Time 677 * @see java.util.Calendar 678 */ 679 public Time getTime(String parameterName, Calendar cal) throws SQLException; 680 681 /** 682 * Returns the indexed parameter's {@code TIMESTAMP} value as a {@code 683 * java.sql.Timestamp}. 684 * 685 * @param parameterIndex 686 * the parameter number index, where the first parameter has 687 * index 1 688 * @return the parameter's value as a {@code java.sql.Timestamp}. A 689 * {@code null} reference is returned for an SQL value of {@code 690 * NULL}. 691 * @throws SQLException 692 * if a database error occurs. 693 * @see Timestamp 694 */ 695 public Timestamp getTimestamp(int parameterIndex) throws SQLException; 696 697 /** 698 * Returns the indexed parameter's {@code TIMESTAMP} value as a {@code 699 * java.sql.Timestamp}. The JDBC driver uses the supplied {@code Calendar} 700 * to handle specific timezones and locales when creating the result. 701 * 702 * @param parameterIndex 703 * the parameter number index, where the first parameter has 704 * index 1 705 * @param cal 706 * used for creating the returned {@code Timestamp} 707 * @return the parameter's value as a {@code java.sql.Timestamp}. A 708 * {@code null} reference is returned for an SQL value of {@code 709 * NULL}. 710 * @throws SQLException 711 * if a database error occurs. 712 * @see Timestamp 713 */ 714 public Timestamp getTimestamp(int parameterIndex, Calendar cal) 715 throws SQLException; 716 717 /** 718 * Returns the named parameter's {@code TIMESTAMP} value as a {@code 719 * java.sql.Timestamp}. 720 * 721 * @param parameterName 722 * the name of the desired parameter. 723 * @return the parameter's value as a {@code java.sql.Timestamp}. A 724 * {@code null} reference is returned for an SQL value of {@code 725 * NULL}. 726 * @throws SQLException 727 * if a database error occurs. 728 * @see Timestamp 729 */ 730 public Timestamp getTimestamp(String parameterName) throws SQLException; 731 732 /** 733 * Returns the indexed parameter's {@code TIMESTAMP} value as a {@code 734 * java.sql.Timestamp}. The JDBC driver uses the supplied {@code Calendar} 735 * to handle specific timezones and locales when creating the result. 736 * 737 * @param parameterName 738 * the name of the desired parameter. 739 * @param cal 740 * used for creating the returned {@code Timestamp} 741 * @return the parameter's value as a {@code java.sql.Timestamp}. A 742 * {@code null} reference is returned for an SQL value of {@code 743 * NULL}. 744 * @throws SQLException 745 * if a database error occurs. 746 * @see Timestamp 747 */ 748 public Timestamp getTimestamp(String parameterName, Calendar cal) 749 throws SQLException; 750 751 /** 752 * Gets the value of a specified JDBC {@code DATALINK} parameter as a 753 * {@code java.net.URL}. 754 * 755 * @param parameterIndex 756 * the parameter number index, where the first parameter has 757 * index 1. 758 * @return a {@code URL} giving the parameter's value. {@code null} 759 * is returned if the value is SQL {@code NULL}. 760 * @throws SQLException 761 * if a database error occurs. 762 * @see java.net.URL 763 */ 764 public URL getURL(int parameterIndex) throws SQLException; 765 766 /** 767 * Returns the named parameter's JDBC {@code DATALINK} value in a new Java 768 * {@code java.net.URL}. 769 * 770 * @param parameterName 771 * the name of the desired parameter. 772 * @return a new {@code java.net.URL} encapsulating the parameter value. A 773 * {@code null} reference is returned for an SQL value of {@code 774 * NULL}. 775 * @throws SQLException 776 * if a database error occurs. 777 * @see java.net.URL 778 */ 779 public URL getURL(String parameterName) throws SQLException; 780 781 /** 782 * Defines the type of a specified {@code OUT} parameter. All {@code OUT} 783 * parameters must have their type defined before a stored procedure is 784 * executed. 785 * <p> 786 * The type supplied in the {@code sqlType} parameter fixes the 787 * type that will be returned by the getter methods of 788 * {@code CallableStatement}. 789 * If a database specific type is expected for a parameter, the Type {@code 790 * java.sql.Types.OTHER} should be used. Note that there is another variant 791 * of this method for User Defined Types or a {@code REF} type. 792 * 793 * @param parameterIndex 794 * the parameter number index, where the first parameter has 795 * index 1 796 * @param sqlType 797 * the JDBC type as defined by {@code java.sql.Types}. The JDBC 798 * types {@code NUMERIC} and {@code DECIMAL} should be defined 799 * using {@link #registerOutParameter(int, int, int)}. 800 * @throws SQLException 801 * if a database error occurs. 802 * @see Types 803 */ 804 public void registerOutParameter(int parameterIndex, int sqlType) 805 throws SQLException; 806 807 /** 808 * Defines the Type of a specified {@code OUT} parameter. All {@code OUT} 809 * parameters must have their type defined before a stored procedure is 810 * executed. This version of the {@code registerOutParameter} method, which 811 * has a scale parameter, should be used for the JDBC types {@code NUMERIC} 812 * and {@code DECIMAL}, where there is a need to specify the number of 813 * digits expected after the decimal point. 814 * <p> 815 * The type supplied in the {@code sqlType} parameter fixes the 816 * type that will be returned by the getter methods of 817 * {@code CallableStatement}. 818 * 819 * @param parameterIndex 820 * the parameter number index, where the first parameter has 821 * index 1 822 * @param sqlType 823 * the JDBC type as defined by {@code java.sql.Types}. 824 * @param scale 825 * the number of digits after the decimal point. Must be greater 826 * than or equal to 0. 827 * @throws SQLException 828 * if a database error occurs. 829 * @see Types 830 */ 831 public void registerOutParameter(int parameterIndex, int sqlType, int scale) 832 throws SQLException; 833 834 /** 835 * Defines the Type of a specified {@code OUT} parameter. This variant 836 * of the method is designed for use with parameters that are 837 * <i>User Defined Types</i> (UDT) or a {@code REF} type, although it 838 * can be used for any type. 839 * 840 * @param paramIndex 841 * the parameter number index, where the first parameter has 842 * index 1. 843 * @param sqlType 844 * a JDBC type expressed as a constant from {@link Types}. 845 * @param typeName 846 * an SQL type name. For a {@code REF} type, this name should be 847 * the fully qualified name of the referenced type. 848 * @throws SQLException 849 * if a database error occurs. 850 * @see Ref 851 */ 852 public void registerOutParameter(int paramIndex, int sqlType, 853 String typeName) throws SQLException; 854 855 /** 856 * Defines the Type of a specified {@code OUT} parameter. All OUT parameters 857 * must have their Type defined before a stored procedure is executed. 858 * <p> 859 * The type supplied in the {@code sqlType} parameter fixes the 860 * type that will be returned by the getter methods of 861 * {@code CallableStatement}. 862 * If a database-specific type is expected for a parameter, the Type {@code 863 * java.sql.Types.OTHER} should be used. Note that there is another variant 864 * of this method for User Defined Types or a {@code REF} type. 865 * 866 * @param parameterName 867 * the parameter name. 868 * @param sqlType 869 * a JDBC type expressed as a constant from {@link Types}. Types 870 * {@code NUMERIC} and {@code DECIMAL} should be defined using 871 * the variant of this method that takes a {@code scale} 872 * parameter. 873 * @throws SQLException 874 * if a database error occurs. 875 */ 876 public void registerOutParameter(String parameterName, int sqlType) 877 throws SQLException; 878 879 /** 880 * Defines the Type of a specified {@code OUT} parameter. All {@code OUT} 881 * parameters must have their Type defined before a stored procedure is 882 * executed. This version of the {@code registerOutParameter} method, which 883 * has a scale parameter, should be used for the JDBC types {@code NUMERIC} 884 * and {@code DECIMAL}, where there is a need to specify the number of 885 * digits expected after the decimal point. 886 * <p> 887 * The type supplied in the {@code sqlType} parameter fixes the 888 * type that will be returned by the getter methods of 889 * {@code CallableStatement}. 890 * 891 * @param parameterName 892 * the parameter name. 893 * @param sqlType 894 * a JDBC type expressed as a constant from {@link Types}. 895 * @param scale 896 * the number of digits after the decimal point. Must be greater 897 * than or equal to 0. 898 * @throws SQLException 899 * if a database error occurs. 900 */ 901 public void registerOutParameter(String parameterName, int sqlType, 902 int scale) throws SQLException; 903 904 /** 905 * Defines the Type of a specified {@code OUT} parameter. This variant of 906 * the method is designed for use with parameters that are <i>User Defined 907 * Types</i> (UDT) or a {@code REF} type, although it can be used for any 908 * type. 909 * 910 * @param parameterName 911 * the parameter name 912 * @param sqlType 913 * a JDBC type expressed as a constant from {@link Types} 914 * @param typeName 915 * the fully qualified name of an SQL structured type. For a 916 * {@code REF} type, this name should be the fully qualified name 917 * of the referenced type. 918 * @throws SQLException 919 * if a database error occurs. 920 */ 921 public void registerOutParameter(String parameterName, int sqlType, 922 String typeName) throws SQLException; 923 924 /** 925 * Sets the value of a specified parameter to the content of a supplied 926 * {@code InputStream}, which has a specified number of bytes. 927 * <p> 928 * This is a good method for setting an SQL {@code LONGVARCHAR} parameter 929 * where the length of the data is large. Data is read from the {@code 930 * InputStream} until end-of-file is reached or the specified number of 931 * bytes is copied. 932 * 933 * @param parameterName 934 * the parameter name 935 * @param theInputStream 936 * the ASCII input stream carrying the data to update the 937 * parameter with. 938 * @param length 939 * the number of bytes in the {@code InputStream} to copy to the 940 * parameter. 941 * @throws SQLException 942 * if a database error occurs. 943 */ 944 public void setAsciiStream(String parameterName, 945 InputStream theInputStream, int length) throws SQLException; 946 947 /** 948 * Sets the value of a specified parameter to a supplied {@code 949 * java.math.BigDecimal} value. 950 * 951 * @param parameterName 952 * the name of the parameter. 953 * @param theBigDecimal 954 * the {@code java.math.BigInteger} value to set. 955 * @throws SQLException 956 * if a database error occurs. 957 */ 958 public void setBigDecimal(String parameterName, BigDecimal theBigDecimal) 959 throws SQLException; 960 961 /** 962 * Sets the value of a specified parameter to the content of a supplied 963 * binary {@code InputStream}, which has a specified number of bytes. 964 * <p> 965 * Use this method when a large amount of data needs to be set into a 966 * {@code LONGVARBINARY} parameter. 967 * 968 * @param parameterName 969 * the name of the parameter. 970 * @param theInputStream 971 * the binary {@code InputStream} carrying the data to update the 972 * parameter. 973 * @param length 974 * the number of bytes in the {@code InputStream} to copy to the 975 * parameter. 976 * @throws SQLException 977 * if a database error occurs. 978 */ 979 public void setBinaryStream(String parameterName, 980 InputStream theInputStream, int length) throws SQLException; 981 982 /** 983 * Sets the value of a specified parameter to a supplied {@code boolean} 984 * value. 985 * 986 * @param parameterName 987 * the parameter name. 988 * @param theBoolean 989 * the new value with which to update the parameter. 990 * @throws SQLException 991 * if a database error occurs. 992 */ 993 public void setBoolean(String parameterName, boolean theBoolean) 994 throws SQLException; 995 996 /** 997 * Sets the value of a specified parameter to a supplied {@code byte} value. 998 * 999 * @param parameterName 1000 * the parameter name. 1001 * @param theByte 1002 * the new value with which to update the parameter. 1003 * @throws SQLException 1004 * if a database error occurs. 1005 */ 1006 public void setByte(String parameterName, byte theByte) throws SQLException; 1007 1008 /** 1009 * Sets the value of a specified parameter to a supplied array of bytes. The 1010 * array is mapped to {@code VARBINARY} or else {@code LONGVARBINARY} in the 1011 * connected database. 1012 * 1013 * @param parameterName 1014 * the parameter name. 1015 * @param theBytes 1016 * the new value with which to update the parameter. 1017 * @throws SQLException 1018 * if a database error occurs. 1019 */ 1020 public void setBytes(String parameterName, byte[] theBytes) 1021 throws SQLException; 1022 1023 /** 1024 * Sets the value of a specified parameter to the character content of a 1025 * {@code Reader} object, with the specified length of character data. 1026 * 1027 * @param parameterName 1028 * the parameter name. 1029 * @param reader 1030 * the new value with which to update the parameter. 1031 * @param length 1032 * a count of the characters contained in {@code reader}. 1033 * @throws SQLException 1034 * if a database error occurs. 1035 */ 1036 public void setCharacterStream(String parameterName, Reader reader, 1037 int length) throws SQLException; 1038 1039 /** 1040 * Sets the value of a specified parameter to a supplied {@code 1041 * java.sql.Date} value. 1042 * 1043 * @param parameterName 1044 * the parameter name. 1045 * @param theDate 1046 * the new value with which to update the parameter. 1047 * @throws SQLException 1048 * if a database error occurs. 1049 */ 1050 public void setDate(String parameterName, Date theDate) throws SQLException; 1051 1052 /** 1053 * Sets the value of a specified parameter to a supplied {@code 1054 * java.sql.Date} value, using a supplied calendar to map the date. The 1055 * calendar allows the application to control the timezone used to compute 1056 * the SQL {@code DATE} in the database. In case that no calendar is 1057 * supplied, the driver uses the default timezone of the Java virtual 1058 * machine. 1059 * 1060 * @param parameterName 1061 * the parameter name. 1062 * @param theDate 1063 * the new value with which to update the parameter. 1064 * @param cal 1065 * a {@code Calendar} to use to construct the SQL {@code DATE} 1066 * value. 1067 * @throws SQLException 1068 * if a database error occurs. 1069 * @see java.util.Calendar 1070 * @see Date 1071 */ 1072 public void setDate(String parameterName, Date theDate, Calendar cal) 1073 throws SQLException; 1074 1075 /** 1076 * Sets the value of a specified parameter to a supplied {@code double} 1077 * value. 1078 * 1079 * @param parameterName 1080 * the parameter name. 1081 * @param theDouble 1082 * the new value with which to update the parameter. 1083 * @throws SQLException 1084 * if a database error occurs. 1085 */ 1086 public void setDouble(String parameterName, double theDouble) 1087 throws SQLException; 1088 1089 /** 1090 * Sets the value of a specified parameter to to a supplied {@code float} 1091 * value. 1092 * 1093 * @param parameterName 1094 * the parameter name. 1095 * @param theFloat 1096 * the new value with which to update the parameter. 1097 * @throws SQLException 1098 * if a database error occurs. 1099 */ 1100 public void setFloat(String parameterName, float theFloat) 1101 throws SQLException; 1102 1103 /** 1104 * Sets the value of a specified parameter to a supplied {@code int} value. 1105 * 1106 * @param parameterName 1107 * the parameter name. 1108 * @param theInt 1109 * the new value with which to update the parameter. 1110 * @throws SQLException 1111 * if a database error occurs. 1112 */ 1113 public void setInt(String parameterName, int theInt) throws SQLException; 1114 1115 /** 1116 * Sets the value of a specified parameter to a supplied {@code long} value. 1117 * 1118 * @param parameterName 1119 * the parameter name. 1120 * @param theLong 1121 * the new value with which to update the parameter. 1122 * @throws SQLException 1123 * if a database error occurs. 1124 */ 1125 public void setLong(String parameterName, long theLong) throws SQLException; 1126 1127 /** 1128 * Sets the value of a specified parameter to SQL {@code NULL}. Don't use 1129 * this version of {@code setNull} for <i>User Defined Types</i> (UDT) or 1130 * for {@code REF} type parameters. 1131 * 1132 * @param parameterName 1133 * the parameter name. 1134 * @param sqlType 1135 * a JDBC type expressed as a constant from {@link Types}. 1136 * @throws SQLException 1137 * if a database error occurs. 1138 */ 1139 public void setNull(String parameterName, int sqlType) throws SQLException; 1140 1141 /** 1142 * Sets the value of a specified parameter to be SQL {@code NULL} where the 1143 * parameter type is either {@code REF} or user defined (e.g. {@code STRUCT} 1144 * , {@code JAVA_OBJECT} etc). 1145 * <p> 1146 * For reasons of portability, the caller is expected to supply both the SQL 1147 * type code and type name (which is just the parameter name if the type is 1148 * user defined, referred to as a {@code UDT}, or the name of the referenced 1149 * type in case of a {@code REF} type). 1150 * 1151 * @param parameterName 1152 * the parameter name. 1153 * @param sqlType 1154 * a JDBC type expressed as a constant from {@link Types}. 1155 * @param typeName 1156 * if the target parameter is a user defined type then this 1157 * should contain the full type name. The fully qualified name of 1158 * a {@code UDT} or {@code REF} type is ignored if the parameter 1159 * is not a {@code UDT}. 1160 * @throws SQLException 1161 * if a database error occurs. 1162 * @see Types 1163 */ 1164 public void setNull(String parameterName, int sqlType, String typeName) 1165 throws SQLException; 1166 1167 /** 1168 * Sets the value of a specified parameter using a supplied object. Prior to 1169 * issuing this request to the connected database {@code theObject} is 1170 * transformed to the corresponding SQL type according to the standard Java 1171 * to SQL mapping rules. 1172 * <p> 1173 * If the object's class implements the interface {@code SQLData}, the JDBC 1174 * driver calls {@code SQLData.writeSQL} to write it to the SQL data stream. 1175 * If {@code theObject} implements any of the following interfaces then the 1176 * driver is in charge of mapping the value to the appropriate SQL type. 1177 * <ul><li>{@link Ref}</li> 1178 * <li>{@link Struct}</li> 1179 * <li>{@link Array}</li> 1180 * <li>{@link Clob}</li> 1181 * <li>{@link Blob}</li> </ul> 1182 * 1183 * @param parameterName 1184 * the parameter name 1185 * @param theObject 1186 * the new value with which to update the parameter 1187 * @throws SQLException 1188 * if a database error occurs. 1189 * @see SQLData 1190 */ 1191 public void setObject(String parameterName, Object theObject) 1192 throws SQLException; 1193 1194 /** 1195 * Sets the value of a specified parameter using a supplied object. 1196 * <p> 1197 * The parameter {@code theObject} is converted to the given {@code 1198 * targetSqlType} before it is sent to the database. If the object has a 1199 * custom mapping (its class implements the interface {@code SQLData}), the 1200 * JDBC driver calls the method {@code SQLData.writeSQL} to write it to the 1201 * SQL data stream. If {@code theObject} is an instance of one of the 1202 * following types 1203 * <ul> 1204 * <li>{@link Ref}</li> 1205 * <li>{@link Struct}</li> 1206 * <li>{@link Array}</li> 1207 * <li>{@link Clob}</li> 1208 * <li>{@link Blob}</li> 1209 * </ul> 1210 * then the driver is in charge of mapping the value to the appropriate 1211 * SQL type and deliver it to the database. 1212 * 1213 * @param parameterName 1214 * the parameter name. 1215 * @param theObject 1216 * the new value with which to update the parameter. 1217 * @param targetSqlType 1218 * a JDBC type expressed as a constant from {@link Types}. 1219 * @throws SQLException 1220 * if a database error occurs. 1221 * @see SQLData 1222 */ 1223 public void setObject(String parameterName, Object theObject, 1224 int targetSqlType) throws SQLException; 1225 1226 /** 1227 * Sets the value of a specified parameter using a supplied object. 1228 * <p> 1229 * The object is converted to the given {@code targetSqlType} before it is 1230 * sent to the database. If the object has a custom mapping (its class 1231 * implements the interface {@code SQLData}), the JDBC driver calls the 1232 * method {@code SQLData.writeSQL} to write it to the SQL data stream. If 1233 * {@code theObject} implements any of the following interfaces 1234 * <ul> 1235 * <li>{@link Ref}</li> 1236 * <li>{@link Struct}</li> 1237 * <li>{@link Array}</li> 1238 * <li>{@link Clob}</li> 1239 * <li>{@link Blob}</li> 1240 * </ul> 1241 * then the driver is charge of mapping the value to the appropriate 1242 * SQL type. 1243 * 1244 * @param parameterName 1245 * the parameter name. 1246 * @param theObject 1247 * the new value with which to update the parameter. 1248 * @param targetSqlType 1249 * a JDBC type expressed as a constant from {@link Types}. 1250 * @param scale 1251 * where applicable, the number of digits after the decimal. 1252 * point. 1253 * @throws SQLException 1254 * if a database error occurs. 1255 * @see SQLData 1256 */ 1257 public void setObject(String parameterName, Object theObject, 1258 int targetSqlType, int scale) throws SQLException; 1259 1260 /** 1261 * Sets the value of a specified parameter to a supplied {@code short} 1262 * value. 1263 * 1264 * @param parameterName 1265 * the name of the parameter. 1266 * @param theShort 1267 * a short value to update the parameter. 1268 * @throws SQLException 1269 * if a database error occurs. 1270 */ 1271 public void setShort(String parameterName, short theShort) 1272 throws SQLException; 1273 1274 /** 1275 * Sets the value of a specified parameter to a supplied {@code String}. 1276 * 1277 * @param parameterName 1278 * the name of the parameter. 1279 * @param theString 1280 * a {@code String} value to update the parameter. 1281 * @throws SQLException 1282 * if a database error occurs. 1283 */ 1284 public void setString(String parameterName, String theString) 1285 throws SQLException; 1286 1287 /** 1288 * Sets the value of the parameter named {@code parameterName} to the value 1289 * of the supplied {@code java.sql.Time}. 1290 * 1291 * @param parameterName 1292 * the parameter name. 1293 * @param theTime 1294 * the new value with which to update the parameter. 1295 * @throws SQLException 1296 * if a database error occurs. 1297 * @see Time 1298 */ 1299 public void setTime(String parameterName, Time theTime) throws SQLException; 1300 1301 /** 1302 * Sets the value of the parameter named {@code parameterName} to the value 1303 * of the supplied {@code java.sql.Time} using the supplied calendar. 1304 * <p> 1305 * The driver uses the supplied {@code Calendar} to create the SQL 1306 * {@code TIME} value, which allows it to use a custom timezone - 1307 * otherwise the driver uses the default timezone of the Java 1308 * virtual machine. 1309 * 1310 * @param parameterName 1311 * the parameter name. 1312 * @param theTime 1313 * the new value with which to update the parameter. 1314 * @param cal 1315 * used for creating the new SQL {@code TIME} value. 1316 * @throws SQLException 1317 * if a database error occurs. 1318 * @see Time 1319 */ 1320 public void setTime(String parameterName, Time theTime, Calendar cal) 1321 throws SQLException; 1322 1323 /** 1324 * Sets the value of a specified parameter to a supplied {@code 1325 * java.sql.Timestamp} value. 1326 * 1327 * @param parameterName 1328 * the parameter name. 1329 * @param theTimestamp 1330 * the new value with which to update the parameter. 1331 * @throws SQLException 1332 * if a database error occurs. 1333 * @see Timestamp 1334 */ 1335 public void setTimestamp(String parameterName, Timestamp theTimestamp) 1336 throws SQLException; 1337 1338 /** 1339 * Sets the value of a specified parameter to a supplied {@code 1340 * java.sql.Timestamp} value, using the supplied calendar. 1341 * <p> 1342 * The driver uses the supplied calendar to create the SQL {@code TIMESTAMP} 1343 * value, which allows it to use a custom timezone - otherwise the driver 1344 * uses the default timezone of the Java virtual machine. 1345 * 1346 * @param parameterName 1347 * the parameter name. 1348 * @param theTimestamp 1349 * the new value with which to update the parameter. 1350 * @param cal 1351 * used for creating the new SQL {@code TIME} value. 1352 * @throws SQLException 1353 * if a database error occurs. 1354 * @see Timestamp 1355 * @see java.util.Calendar 1356 */ 1357 public void setTimestamp(String parameterName, Timestamp theTimestamp, 1358 Calendar cal) throws SQLException; 1359 1360 /** 1361 * Sets the value of a specified parameter to the supplied {@code 1362 * java.net.URL}. 1363 * 1364 * @param parameterName 1365 * the parameter name. 1366 * @param theURL 1367 * the new value with which to update the parameter. 1368 * @throws SQLException 1369 * if a database error occurs. 1370 * @see java.net.URL 1371 */ 1372 public void setURL(String parameterName, URL theURL) throws SQLException; 1373 1374 /** 1375 * Gets whether the value of the last {@code OUT} parameter read was SQL 1376 * {@code NULL}. 1377 * 1378 * @return true if the last parameter was SQL {@code NULL}, {@code false} 1379 * otherwise. 1380 * @throws SQLException 1381 * if a database error occurs. 1382 */ 1383 public boolean wasNull() throws SQLException; 1384} 1385