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 18 package java.sql; 19 20 import java.io.InputStream; 21 import java.io.Reader; 22 import java.math.BigDecimal; 23 import java.net.URL; 24 import java.util.Calendar; 25 import java.util.Map; 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 */ 57 public 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 */ getArray(int parameterIndex)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 */ getArray(String parameterName)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 */ getBigDecimal(int parameterIndex)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 {@link #getBigDecimal(String)} instead. 115 */ 116 @Deprecated getBigDecimal(int parameterIndex, int scale)117 public BigDecimal getBigDecimal(int parameterIndex, int scale) 118 throws SQLException; 119 120 /** 121 * Returns a new {@link BigDecimal} representation of the JDBC {@code 122 * NUMERIC} parameter specified by the input name. 123 * 124 * @param parameterName 125 * the desired parameter's name. 126 * @return a {@code java.math.BigDecimal} representing the value of the 127 * specified parameter. The value {@code null} is returned if 128 * the parameter in question is an SQL {@code NULL}. 129 * @throws SQLException 130 * if a database error occurs. 131 */ getBigDecimal(String parameterName)132 public BigDecimal getBigDecimal(String parameterName) throws SQLException; 133 134 /** 135 * Gets the value of a specified JDBC {@code BLOB} parameter as a {@code 136 * java.sql.Blob}. 137 * 138 * @param parameterIndex 139 * the parameter number index, where the first parameter has 140 * index 1. 141 * @return a {@code java.sql.Blob} representing the value of the 142 * specified parameter. The value {@code null} is returned if 143 * the parameter in question is an SQL {@code NULL}. 144 * @throws SQLException 145 * if a database error occurs. 146 */ getBlob(int parameterIndex)147 public Blob getBlob(int parameterIndex) throws SQLException; 148 149 /** 150 * Gets the value of a specified JDBC {@code BLOB} parameter as a {@code 151 * java.sql.Blob}. 152 * 153 * @param parameterName 154 * the desired parameter's name. 155 * @return a {@code java.sql.Blob} representing the value of the 156 * specified parameter. The value {@code null} is returned if 157 * the parameter in question is an SQL {@code NULL}. 158 * @throws SQLException 159 * if a database error occurs. 160 */ getBlob(String parameterName)161 public Blob getBlob(String parameterName) throws SQLException; 162 163 /** 164 * Gets the value of a specified JDBC {@code BIT} parameter as a boolean. 165 * 166 * @param parameterIndex 167 * the parameter number index, where the first parameter has 168 * index 1. 169 * @return a {@code boolean} representing the parameter value. {@code false} 170 * is returned if the value is SQL {@code NULL}. 171 * @throws SQLException 172 * if a database error occurs. 173 */ getBoolean(int parameterIndex)174 public boolean getBoolean(int parameterIndex) throws SQLException; 175 176 /** 177 * Gets the value of a specified JDBC {@code BIT} parameter as a {@code 178 * boolean}. 179 * 180 * @param parameterName 181 * the desired parameter's name. 182 * @return a {@code boolean} representation of the value of the parameter. 183 * {@code false} is returned if the SQL value is {@code NULL}. 184 * @throws SQLException 185 * if a database error occurs. 186 */ getBoolean(String parameterName)187 public boolean getBoolean(String parameterName) throws SQLException; 188 189 /** 190 * Gets the value of a specified JDBC {@code TINYINT} parameter as a {@code 191 * byte}. 192 * 193 * @param parameterIndex 194 * the parameter number index, where the first parameter has 195 * index 1. 196 * @return a {@code byte} representation of the value of the parameter. 197 * {@code 0} is returned if the value is SQL {@code NULL}. 198 * @throws SQLException 199 * if a database error occurs. 200 */ getByte(int parameterIndex)201 public byte getByte(int parameterIndex) throws SQLException; 202 203 /** 204 * Gets the value of a specified JDBC {@code TINYINT} parameter as a Java 205 * {@code byte}. 206 * 207 * @param parameterName 208 * the desired parameter's name. 209 * @return a {@code byte} representation of the value of the parameter. 210 * {@code 0} is returned if the SQL value is {@code NULL}. 211 * @throws SQLException 212 * if a database error occurs. 213 */ getByte(String parameterName)214 public byte getByte(String parameterName) throws SQLException; 215 216 /** 217 * Returns a byte array representation of the indexed JDBC {@code BINARY} or 218 * {@code VARBINARY} parameter. 219 * 220 * @param parameterIndex 221 * the parameter number index, where the first parameter has 222 * index 1. 223 * @return an array of bytes giving the value of the parameter. {@code null} 224 * is returned if the value is SQL {@code NULL}. 225 * @throws SQLException 226 * if a database error occurs. 227 */ getBytes(int parameterIndex)228 public byte[] getBytes(int parameterIndex) throws SQLException; 229 230 /** 231 * Returns a byte array representation of the named JDBC {@code BINARY} or 232 * {@code VARBINARY} parameter. 233 * 234 * @param parameterName 235 * the name of the parameter. 236 * @return an array of bytes giving the value of the parameter. {@code null} 237 * is returned if the value is SQL {@code NULL}. 238 * @throws SQLException 239 * if a database error occurs. 240 */ getBytes(String parameterName)241 public byte[] getBytes(String parameterName) throws SQLException; 242 243 /** 244 * Gets the value of a specified JDBC {@code CLOB} parameter as a {@code 245 * java.sql.Clob}. 246 * 247 * @param parameterIndex 248 * the parameter number index, where the first parameter has 249 * index 1. 250 * @return a {@code java.sql.Clob} representing the value of the 251 * parameter. {@code null} is returned if the value is SQL 252 * {@code NULL}. 253 * @throws SQLException 254 * if a database error occurs. 255 * @see Clob 256 */ getClob(int parameterIndex)257 public Clob getClob(int parameterIndex) throws SQLException; 258 259 /** 260 * Gets the value of a specified JDBC {@code CLOB} parameter as a {@code 261 * java.sql.Clob}. 262 * 263 * @param parameterName 264 * the name of the parameter. 265 * @return a {@code java.sql.Clob} with the value of the parameter. {@code 266 * null} is returned if the value is SQL {@code NULL}. 267 * @throws SQLException 268 * if a database error occurs. 269 * @see Clob 270 */ getClob(String parameterName)271 public Clob getClob(String parameterName) throws SQLException; 272 273 /** 274 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 275 * java.sql.Date}. 276 * 277 * @param parameterIndex 278 * the parameter number index, where the first parameter has 279 * index 1. 280 * @return the {@code java.sql.Date} representing the parameter's value. 281 * {@code null} is returned if the value is SQL {@code NULL}. 282 * @throws SQLException 283 * if a database error occurs. 284 * @see Date 285 */ getDate(int parameterIndex)286 public Date getDate(int parameterIndex) throws SQLException; 287 288 /** 289 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 290 * java.sql.Date}, using the specified {@code Calendar} to construct the date. 291 * 292 * <p>The JDBC driver uses the calendar to create the Date using a particular 293 * timezone and locale. The default behavior of the driver is to use the VM defaults. 294 * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>". 295 * 296 * @param parameterIndex 297 * the parameter number index, where the first parameter has 298 * index 1. 299 * @param cal 300 * the {@code Calendar} to use to construct the date 301 * @return the {@code java.sql.Date} giving the parameter's value. {@code null} 302 * is returned if the value is SQL {@code NULL}. 303 * @throws SQLException 304 * if a database error occurs. 305 * @see Date 306 */ getDate(int parameterIndex, Calendar cal)307 public Date getDate(int parameterIndex, Calendar cal) throws SQLException; 308 309 /** 310 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 311 * java.sql.Date}. 312 * 313 * @param parameterName 314 * the name of the desired parameter. 315 * @return the {@code java.sql.Date} giving the parameter's value. {@code null} 316 * is returned if the value is SQL {@code NULL}. 317 * @throws SQLException 318 * if a database error occurs. 319 * @see Date 320 */ getDate(String parameterName)321 public Date getDate(String parameterName) throws SQLException; 322 323 /** 324 * Gets the value of the specified JDBC {@code DATE} parameter as a {@code 325 * java.sql.Date}, using the specified {@code Calendar} to construct the date. 326 * 327 * <p>The JDBC driver uses the calendar to create the date using a particular 328 * timezone and locale. The default behavior of the driver is to use the VM defaults. 329 * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>". 330 * 331 * @param parameterName 332 * the name of the desired parameter. 333 * @param cal 334 * used for creating the returned {@code Date}. 335 * @return the {@code java.sql.Date} giving the parameter's value. {@code null} 336 * is returned if the value is SQL {@code NULL}. 337 * @throws SQLException 338 * if a database error occurs. 339 * @see Date 340 */ getDate(String parameterName, Calendar cal)341 public Date getDate(String parameterName, Calendar cal) throws SQLException; 342 343 /** 344 * Gets the value of the specified JDBC {@code DOUBLE} parameter as a 345 * {@code double}. 346 * 347 * @param parameterIndex 348 * the parameter number index, where the first parameter has 349 * index 1. 350 * @return the parameter's value as a {@code double}. {@code 0.0} 351 * is returned if the value is SQL {@code NULL}. 352 * @throws SQLException 353 * if a database error occurs. 354 */ getDouble(int parameterIndex)355 public double getDouble(int parameterIndex) throws SQLException; 356 357 /** 358 * Gets the value of the specified JDBC {@code DOUBLE} parameter as a 359 * {@code double}. 360 * 361 * @param parameterName 362 * the name of the desired parameter. 363 * @return the parameter's value as a {@code double}. {@code 0.0} 364 * is returned if the value is SQL {@code NULL}. 365 * @throws SQLException 366 * if there is a problem accessing the database. 367 */ getDouble(String parameterName)368 public double getDouble(String parameterName) throws SQLException; 369 370 /** 371 * Gets the value of the specified JDBC {@code FLOAT} parameter as a {@code 372 * float}. 373 * 374 * @param parameterIndex 375 * the parameter number index, where the first parameter has 376 * index 1. 377 * @return the parameter's value as a {@code float}. {@code 0.0} 378 * is returned if the value is SQL {@code NULL}. 379 * @throws SQLException 380 * if a database error occurs. 381 */ getFloat(int parameterIndex)382 public float getFloat(int parameterIndex) throws SQLException; 383 384 /** 385 * Gets the value of the specified JDBC {@code FLOAT} parameter as a Java 386 * {@code float}. 387 * 388 * @param parameterName 389 * the name of the desired parameter. 390 * @return the parameter's value as a {@code float}. {@code 0.0} 391 * is returned if the value is SQL {@code NULL}. 392 * @throws SQLException 393 * if there is a problem accessing the database. 394 */ getFloat(String parameterName)395 public float getFloat(String parameterName) throws SQLException; 396 397 /** 398 * Gets the value of the specified JDBC {@code INTEGER} parameter as an 399 * {@code int}. 400 * 401 * @param parameterIndex 402 * the parameter number index, where the first parameter has 403 * index 1. 404 * @return the {@code int} giving the parameter's value. {@code 0} 405 * is returned if the value is SQL {@code NULL}. 406 * @throws SQLException 407 * if a database error occurs. 408 */ getInt(int parameterIndex)409 public int getInt(int parameterIndex) throws SQLException; 410 411 /** 412 * Gets the value of the specified JDBC {@code INTEGER} parameter as an 413 * {@code int}. 414 * 415 * @param parameterName 416 * the name of the desired parameter. 417 * @return the {@code int} giving the parameter's value. {@code 0} 418 * is returned if the value is SQL {@code NULL}. 419 * @throws SQLException 420 * if a database error occurs. 421 */ getInt(String parameterName)422 public int getInt(String parameterName) throws SQLException; 423 424 /** 425 * Gets the value of the specified JDBC {@code BIGINT} parameter as a 426 * {@code long}. 427 * 428 * @param parameterIndex 429 * the parameter number index, where the first parameter has 430 * index 1. 431 * @return the {@code long} giving the parameter's value. {@code 0} 432 * is returned if the value is SQL {@code NULL}. 433 * @throws SQLException 434 * if a database error occurs. 435 */ getLong(int parameterIndex)436 public long getLong(int parameterIndex) throws SQLException; 437 438 /** 439 * Gets the value of the specified JDBC {@code BIGINT} parameter as a 440 * {@code long}. 441 * 442 * @param parameterName 443 * the name of the desired parameter. 444 * @return the {@code long} giving the parameter's value. {@code 0} 445 * is returned if the value is SQL {@code NULL}. 446 * @throws SQLException 447 * if a database error occurs. 448 */ getLong(String parameterName)449 public long getLong(String parameterName) throws SQLException; 450 451 /** 452 * Gets the value of the specified parameter as a Java {@code Object}. 453 * <p> 454 * The object type returned is the JDBC type registered for the parameter 455 * with a {@code registerOutParameter} call. If a parameter was registered 456 * as a {@code java.sql.Types.OTHER} then it may hold abstract types that 457 * are particular to the connected database. 458 * 459 * @param parameterIndex 460 * the parameter number index, where the first parameter has 461 * index 1. 462 * @return an Object holding the value of the parameter. 463 * @throws SQLException 464 * if a database error occurs. 465 */ getObject(int parameterIndex)466 public Object getObject(int parameterIndex) throws SQLException; 467 468 /** 469 * Gets the value of the specified parameter as an {@code Object}. The 470 * {@code Map} gives the correspondence between SQL types and Java classes. 471 * 472 * @param parameterIndex 473 * the parameter number index, where the first parameter has 474 * index 1. 475 * @param map 476 * the {@code Map} giving the correspondence between SQL 477 * types and Java classes. 478 * @return an Object holding the value of the parameter. 479 * @throws SQLException 480 * if a database error occurs. 481 */ getObject(int parameterIndex, Map<String, Class<?>> map)482 public Object getObject(int parameterIndex, Map<String, Class<?>> map) 483 throws SQLException; 484 485 /** 486 * Gets the value of the specified parameter as an {@code Object}. 487 * <p> 488 * The object type returned is the JDBC type that was registered for 489 * the parameter by an earlier call to {@link #registerOutParameter}. 490 * If a parameter was registered as a {@code java.sql.Types.OTHER} 491 * then it may hold abstract types that are particular to the 492 * connected database. 493 * 494 * @param parameterName 495 * the parameter name. 496 * @return the Java {@code Object} representation of the value of the 497 * parameter. 498 * @throws SQLException 499 * if there is a problem accessing the database. 500 */ getObject(String parameterName)501 public Object getObject(String parameterName) throws SQLException; 502 503 /** 504 * Gets the value of a specified parameter as an {@code Object}. The 505 * actual return type is determined by the {@code Map} parameter which 506 * gives the correspondence between SQL types and Java classes. 507 * 508 * @param parameterName 509 * the parameter name. 510 * @param map 511 * the {@code Map} of SQL types to their Java counterparts 512 * @return an {@code Object} holding the value of the parameter. 513 * @throws SQLException 514 * if there is a problem accessing the database. 515 */ getObject(String parameterName, Map<String, Class<?>> map)516 public Object getObject(String parameterName, Map<String, Class<?>> map) 517 throws SQLException; 518 519 /** 520 * Gets the value of a specified SQL {@code REF(<structured type>)} 521 * parameter as a {@code java.sql.Ref}. 522 * 523 * @param parameterIndex 524 * the parameter number index, where the first parameter has 525 * index 1. 526 * @return a {@code java.sql.Ref} with the parameter value. {@code null} 527 * is returned if the value is SQL {@code NULL}. 528 * @throws SQLException 529 * if a database error occurs. 530 */ getRef(int parameterIndex)531 public Ref getRef(int parameterIndex) throws SQLException; 532 533 /** 534 * Gets the value of a specified SQL {@code REF(<structured type>)} 535 * parameter as a {@code java.sql.Ref}. 536 * 537 * @param parameterName 538 * the desired parameter's name. 539 * @return the parameter's value in the form of a {@code 540 * java.sql.Ref}. A {@code null} reference is returned if the 541 * parameter's value is SQL {@code NULL}. 542 * @throws SQLException 543 * if there is a problem accessing the database. 544 * @see Ref 545 */ getRef(String parameterName)546 public Ref getRef(String parameterName) throws SQLException; 547 548 /** 549 * Gets the value of a specified JDBC {@code SMALLINT} parameter as a 550 * {@code short}. 551 * 552 * @param parameterIndex 553 * the parameter number index, where the first parameter has 554 * index 1. 555 * @return the parameter's value as a {@code short}. 0 is returned 556 * if the parameter's value is SQL {@code NULL}. 557 * @throws SQLException 558 * if a database error occurs. 559 */ getShort(int parameterIndex)560 public short getShort(int parameterIndex) throws SQLException; 561 562 /** 563 * Gets the value of a specified JDBC {@code SMALLINT} parameter as a 564 * {@code short}. 565 * 566 * @param parameterName 567 * the desired parameter's name. 568 * @return the parameter's value as a {@code short}. 0 is returned 569 * if the parameter's value is SQL {@code NULL}. 570 * @throws SQLException 571 * if there is a problem accessing the database. 572 */ getShort(String parameterName)573 public short getShort(String parameterName) throws SQLException; 574 575 /** 576 * Returns the indexed parameter's value as a {@code String}. The 577 * parameter value must be one of the JDBC types {@code CHAR}, 578 * {@code VARCHAR} or {@code LONGVARCHAR}. 579 * <p> 580 * The {@code String} corresponding to a {@code CHAR} of fixed length 581 * will be of identical length to the value in the database inclusive 582 * of padding characters. 583 * 584 * @param parameterIndex 585 * the parameter number index, where the first parameter has 586 * index 1. 587 * @return the parameter's value as a {@code String}. {@code null} 588 * is returned if the value is SQL {@code NULL}. 589 * @throws SQLException 590 * if there is a problem accessing the database. 591 */ getString(int parameterIndex)592 public String getString(int parameterIndex) throws SQLException; 593 594 /** 595 * Returns the named parameter's value as a string. The parameter value must 596 * be one of the JDBC types {@code CHAR}, {@code VARCHAR} or {@code 597 * LONGVARCHAR}. 598 * <p> 599 * The string corresponding to a {@code CHAR} of fixed length will be of 600 * identical length to the value in the database inclusive of padding 601 * characters. 602 * 603 * @param parameterName 604 * the desired parameter's name. 605 * @return the parameter's value as a {@code String}. {@code null} 606 * is returned if the value is SQL {@code NULL}. 607 * @throws SQLException 608 * if there is a problem accessing the database. 609 */ getString(String parameterName)610 public String getString(String parameterName) throws SQLException; 611 612 /** 613 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 614 * java.sql.Time}. 615 * 616 * @param parameterIndex 617 * the parameter number index, where the first parameter has 618 * index 1. 619 * @return the parameter's value as a {@code java.sql.Time}. 620 * {@code null} is returned if the value is SQL {@code NULL}. 621 * @throws SQLException 622 * if a database error occurs. 623 * @see Time 624 */ getTime(int parameterIndex)625 public Time getTime(int parameterIndex) throws SQLException; 626 627 /** 628 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 629 * java.sql.Time}, using the supplied {@code Calendar} to construct the 630 * time. The JDBC driver uses the calendar to handle specific timezones 631 * and locales in order to determine {@code Time}. 632 * 633 * @param parameterIndex 634 * the parameter number index, where the first parameter has 635 * index 1. 636 * @param cal 637 * the calendar to use in constructing {@code Time}. 638 * @return the parameter's value as a {@code java.sql.Time}. 639 * {@code null} is returned if the value is SQL {@code NULL}. 640 * @throws SQLException 641 * if a database error occurs. 642 * @see Time 643 * @see java.util.Calendar 644 */ getTime(int parameterIndex, Calendar cal)645 public Time getTime(int parameterIndex, Calendar cal) throws SQLException; 646 647 /** 648 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 649 * java.sql.Time}. 650 * 651 * @param parameterName 652 * the name of the desired parameter. 653 * @return a new {@code java.sql.Time} with the parameter's value. A {@code 654 * null} reference is returned for an SQL value of {@code NULL}. 655 * @throws SQLException 656 * if a database error occurs. 657 * @see Time 658 */ getTime(String parameterName)659 public Time getTime(String parameterName) throws SQLException; 660 661 /** 662 * Gets the value of a specified JDBC {@code TIME} parameter as a {@code 663 * java.sql.Time}, using the supplied {@code Calendar} to construct 664 * the time. The JDBC driver uses the calendar to handle specific 665 * timezones and locales when creating {@code Time}. 666 * 667 * @param parameterName 668 * the name of the desired parameter. 669 * @param cal 670 * used for creating the returned {@code Time} 671 * @return a new {@code java.sql.Time} with the parameter's value. A {@code 672 * null} reference is returned for an SQL value of {@code NULL}. 673 * @throws SQLException 674 * if a database error occurs. 675 * @see Time 676 * @see java.util.Calendar 677 */ getTime(String parameterName, Calendar cal)678 public Time getTime(String parameterName, Calendar cal) throws SQLException; 679 680 /** 681 * Returns the indexed parameter's {@code TIMESTAMP} value as a {@code 682 * java.sql.Timestamp}. 683 * 684 * @param parameterIndex 685 * the parameter number index, where the first parameter has 686 * index 1 687 * @return the parameter's value as a {@code java.sql.Timestamp}. A 688 * {@code null} reference is returned for an SQL value of {@code 689 * NULL}. 690 * @throws SQLException 691 * if a database error occurs. 692 * @see Timestamp 693 */ getTimestamp(int parameterIndex)694 public Timestamp getTimestamp(int parameterIndex) throws SQLException; 695 696 /** 697 * Returns the indexed parameter's {@code TIMESTAMP} value as a {@code 698 * java.sql.Timestamp}. The JDBC driver uses the supplied {@code Calendar} 699 * to handle specific timezones and locales when creating the result. 700 * 701 * @param parameterIndex 702 * the parameter number index, where the first parameter has 703 * index 1 704 * @param cal 705 * used for creating the returned {@code Timestamp} 706 * @return the parameter's value as a {@code java.sql.Timestamp}. A 707 * {@code null} reference is returned for an SQL value of {@code 708 * NULL}. 709 * @throws SQLException 710 * if a database error occurs. 711 * @see Timestamp 712 */ getTimestamp(int parameterIndex, Calendar cal)713 public Timestamp getTimestamp(int parameterIndex, Calendar cal) 714 throws SQLException; 715 716 /** 717 * Returns the named parameter's {@code TIMESTAMP} value as a {@code 718 * java.sql.Timestamp}. 719 * 720 * @param parameterName 721 * the name of the desired parameter. 722 * @return the parameter's value as a {@code java.sql.Timestamp}. A 723 * {@code null} reference is returned for an SQL value of {@code 724 * NULL}. 725 * @throws SQLException 726 * if a database error occurs. 727 * @see Timestamp 728 */ getTimestamp(String parameterName)729 public Timestamp getTimestamp(String parameterName) throws SQLException; 730 731 /** 732 * Returns the indexed parameter's {@code TIMESTAMP} value as a {@code 733 * java.sql.Timestamp}. The JDBC driver uses the supplied {@code Calendar} 734 * to handle specific timezones and locales when creating the result. 735 * 736 * @param parameterName 737 * the name of the desired parameter. 738 * @param cal 739 * used for creating the returned {@code Timestamp} 740 * @return the parameter's value as a {@code java.sql.Timestamp}. A 741 * {@code null} reference is returned for an SQL value of {@code 742 * NULL}. 743 * @throws SQLException 744 * if a database error occurs. 745 * @see Timestamp 746 */ getTimestamp(String parameterName, Calendar cal)747 public Timestamp getTimestamp(String parameterName, Calendar cal) 748 throws SQLException; 749 750 /** 751 * Gets the value of a specified JDBC {@code DATALINK} parameter as a 752 * {@code java.net.URL}. 753 * 754 * @param parameterIndex 755 * the parameter number index, where the first parameter has 756 * index 1. 757 * @return a {@code URL} giving the parameter's value. {@code null} 758 * is returned if the value is SQL {@code NULL}. 759 * @throws SQLException 760 * if a database error occurs. 761 * @see java.net.URL 762 */ getURL(int parameterIndex)763 public URL getURL(int parameterIndex) throws SQLException; 764 765 /** 766 * Returns the named parameter's JDBC {@code DATALINK} value in a new Java 767 * {@code java.net.URL}. 768 * 769 * @param parameterName 770 * the name of the desired parameter. 771 * @return a new {@code java.net.URL} encapsulating the parameter value. A 772 * {@code null} reference is returned for an SQL value of {@code 773 * NULL}. 774 * @throws SQLException 775 * if a database error occurs. 776 * @see java.net.URL 777 */ getURL(String parameterName)778 public URL getURL(String parameterName) throws SQLException; 779 780 /** 781 * Defines the type of a specified {@code OUT} parameter. All {@code OUT} 782 * parameters must have their type defined before a stored procedure is 783 * executed. 784 * <p> 785 * The type supplied in the {@code sqlType} parameter fixes the 786 * type that will be returned by the getter methods of 787 * {@code CallableStatement}. 788 * If a database specific type is expected for a parameter, the Type {@code 789 * java.sql.Types.OTHER} should be used. Note that there is another variant 790 * of this method for User Defined Types or a {@code REF} type. 791 * 792 * @param parameterIndex 793 * the parameter number index, where the first parameter has 794 * index 1 795 * @param sqlType 796 * the JDBC type as defined by {@code java.sql.Types}. The JDBC 797 * types {@code NUMERIC} and {@code DECIMAL} should be defined 798 * using {@link #registerOutParameter(int, int, int)}. 799 * @throws SQLException 800 * if a database error occurs. 801 * @see Types 802 */ registerOutParameter(int parameterIndex, int sqlType)803 public void registerOutParameter(int parameterIndex, int sqlType) 804 throws SQLException; 805 806 /** 807 * Defines the Type of a specified {@code OUT} parameter. All {@code OUT} 808 * parameters must have their type defined before a stored procedure is 809 * executed. This version of the {@code registerOutParameter} method, which 810 * has a scale parameter, should be used for the JDBC types {@code NUMERIC} 811 * and {@code DECIMAL}, where there is a need to specify the number of 812 * digits expected after the decimal point. 813 * <p> 814 * The type supplied in the {@code sqlType} parameter fixes the 815 * type that will be returned by the getter methods of 816 * {@code CallableStatement}. 817 * 818 * @param parameterIndex 819 * the parameter number index, where the first parameter has 820 * index 1 821 * @param sqlType 822 * the JDBC type as defined by {@code java.sql.Types}. 823 * @param scale 824 * the number of digits after the decimal point. Must be greater 825 * than or equal to 0. 826 * @throws SQLException 827 * if a database error occurs. 828 * @see Types 829 */ registerOutParameter(int parameterIndex, int sqlType, int scale)830 public void registerOutParameter(int parameterIndex, int sqlType, int scale) 831 throws SQLException; 832 833 /** 834 * Defines the Type of a specified {@code OUT} parameter. This variant 835 * of the method is designed for use with parameters that are 836 * <i>User Defined Types</i> (UDT) or a {@code REF} type, although it 837 * can be used for any type. 838 * 839 * @param paramIndex 840 * the parameter number index, where the first parameter has 841 * index 1. 842 * @param sqlType 843 * a JDBC type expressed as a constant from {@link Types}. 844 * @param typeName 845 * an SQL type name. For a {@code REF} type, this name should be 846 * the fully qualified name of the referenced type. 847 * @throws SQLException 848 * if a database error occurs. 849 * @see Ref 850 */ registerOutParameter(int paramIndex, int sqlType, String typeName)851 public void registerOutParameter(int paramIndex, int sqlType, 852 String typeName) throws SQLException; 853 854 /** 855 * Defines the Type of a specified {@code OUT} parameter. All OUT parameters 856 * must have their Type defined before a stored procedure is executed. 857 * <p> 858 * The type supplied in the {@code sqlType} parameter fixes the 859 * type that will be returned by the getter methods of 860 * {@code CallableStatement}. 861 * If a database-specific type is expected for a parameter, the Type {@code 862 * java.sql.Types.OTHER} should be used. Note that there is another variant 863 * of this method for User Defined Types or a {@code REF} type. 864 * 865 * @param parameterName 866 * the parameter name. 867 * @param sqlType 868 * a JDBC type expressed as a constant from {@link Types}. Types 869 * {@code NUMERIC} and {@code DECIMAL} should be defined using 870 * the variant of this method that takes a {@code scale} 871 * parameter. 872 * @throws SQLException 873 * if a database error occurs. 874 */ registerOutParameter(String parameterName, int sqlType)875 public void registerOutParameter(String parameterName, int sqlType) 876 throws SQLException; 877 878 /** 879 * Defines the Type of a specified {@code OUT} parameter. All {@code OUT} 880 * parameters must have their Type defined before a stored procedure is 881 * executed. This version of the {@code registerOutParameter} method, which 882 * has a scale parameter, should be used for the JDBC types {@code NUMERIC} 883 * and {@code DECIMAL}, where there is a need to specify the number of 884 * digits expected after the decimal point. 885 * <p> 886 * The type supplied in the {@code sqlType} parameter fixes the 887 * type that will be returned by the getter methods of 888 * {@code CallableStatement}. 889 * 890 * @param parameterName 891 * the parameter name. 892 * @param sqlType 893 * a JDBC type expressed as a constant from {@link Types}. 894 * @param scale 895 * the number of digits after the decimal point. Must be greater 896 * than or equal to 0. 897 * @throws SQLException 898 * if a database error occurs. 899 */ registerOutParameter(String parameterName, int sqlType, int scale)900 public void registerOutParameter(String parameterName, int sqlType, 901 int scale) throws SQLException; 902 903 /** 904 * Defines the Type of a specified {@code OUT} parameter. This variant of 905 * the method is designed for use with parameters that are <i>User Defined 906 * Types</i> (UDT) or a {@code REF} type, although it can be used for any 907 * type. 908 * 909 * @param parameterName 910 * the parameter name 911 * @param sqlType 912 * a JDBC type expressed as a constant from {@link Types} 913 * @param typeName 914 * the fully qualified name of an SQL structured type. For a 915 * {@code REF} type, this name should be the fully qualified name 916 * of the referenced type. 917 * @throws SQLException 918 * if a database error occurs. 919 */ registerOutParameter(String parameterName, int sqlType, String typeName)920 public void registerOutParameter(String parameterName, int sqlType, 921 String typeName) throws SQLException; 922 923 /** 924 * Sets the value of a specified parameter to the content of a supplied 925 * {@code InputStream}, which has a specified number of bytes. 926 * <p> 927 * This is a good method for setting an SQL {@code LONGVARCHAR} parameter 928 * where the length of the data is large. Data is read from the {@code 929 * InputStream} until end-of-file is reached or the specified number of 930 * bytes is copied. 931 * 932 * @param parameterName 933 * the parameter name 934 * @param theInputStream 935 * the ASCII input stream carrying the data to update the 936 * parameter with. 937 * @param length 938 * the number of bytes in the {@code InputStream} to copy to the 939 * parameter. 940 * @throws SQLException 941 * if a database error occurs. 942 */ setAsciiStream(String parameterName, InputStream theInputStream, int length)943 public void setAsciiStream(String parameterName, 944 InputStream theInputStream, int length) throws SQLException; 945 946 /** 947 * Sets the value of a specified parameter to a supplied {@code 948 * java.math.BigDecimal} value. 949 * 950 * @param parameterName 951 * the name of the parameter. 952 * @param theBigDecimal 953 * the {@code java.math.BigInteger} value to set. 954 * @throws SQLException 955 * if a database error occurs. 956 */ setBigDecimal(String parameterName, BigDecimal theBigDecimal)957 public void setBigDecimal(String parameterName, BigDecimal theBigDecimal) 958 throws SQLException; 959 960 /** 961 * Sets the value of a specified parameter to the content of a supplied 962 * binary {@code InputStream}, which has a specified number of bytes. 963 * <p> 964 * Use this method when a large amount of data needs to be set into a 965 * {@code LONGVARBINARY} parameter. 966 * 967 * @param parameterName 968 * the name of the parameter. 969 * @param theInputStream 970 * the binary {@code InputStream} carrying the data to update the 971 * parameter. 972 * @param length 973 * the number of bytes in the {@code InputStream} to copy to the 974 * parameter. 975 * @throws SQLException 976 * if a database error occurs. 977 */ setBinaryStream(String parameterName, InputStream theInputStream, int length)978 public void setBinaryStream(String parameterName, 979 InputStream theInputStream, int length) throws SQLException; 980 981 /** 982 * Sets the value of a specified parameter to a supplied {@code boolean} 983 * value. 984 * 985 * @param parameterName 986 * the parameter name. 987 * @param theBoolean 988 * the new value with which to update the parameter. 989 * @throws SQLException 990 * if a database error occurs. 991 */ setBoolean(String parameterName, boolean theBoolean)992 public void setBoolean(String parameterName, boolean theBoolean) 993 throws SQLException; 994 995 /** 996 * Sets the value of a specified parameter to a supplied {@code byte} value. 997 * 998 * @param parameterName 999 * the parameter name. 1000 * @param theByte 1001 * the new value with which to update the parameter. 1002 * @throws SQLException 1003 * if a database error occurs. 1004 */ setByte(String parameterName, byte theByte)1005 public void setByte(String parameterName, byte theByte) throws SQLException; 1006 1007 /** 1008 * Sets the value of a specified parameter to a supplied array of bytes. The 1009 * array is mapped to {@code VARBINARY} or else {@code LONGVARBINARY} in the 1010 * connected database. 1011 * 1012 * @param parameterName 1013 * the parameter name. 1014 * @param theBytes 1015 * the new value with which to update the parameter. 1016 * @throws SQLException 1017 * if a database error occurs. 1018 */ setBytes(String parameterName, byte[] theBytes)1019 public void setBytes(String parameterName, byte[] theBytes) 1020 throws SQLException; 1021 1022 /** 1023 * Sets the value of a specified parameter to the character content of a 1024 * {@code Reader} object, with the specified length of character data. 1025 * 1026 * @param parameterName 1027 * the parameter name. 1028 * @param reader 1029 * the new value with which to update the parameter. 1030 * @param length 1031 * a count of the characters contained in {@code reader}. 1032 * @throws SQLException 1033 * if a database error occurs. 1034 */ setCharacterStream(String parameterName, Reader reader, int length)1035 public void setCharacterStream(String parameterName, Reader reader, 1036 int length) throws SQLException; 1037 1038 /** 1039 * Sets the value of a specified parameter to a supplied {@code 1040 * java.sql.Date} value. 1041 * 1042 * @param parameterName 1043 * the parameter name. 1044 * @param theDate 1045 * the new value with which to update the parameter. 1046 * @throws SQLException 1047 * if a database error occurs. 1048 */ setDate(String parameterName, Date theDate)1049 public void setDate(String parameterName, Date theDate) throws SQLException; 1050 1051 /** 1052 * Sets the value of a specified parameter to a supplied {@code 1053 * java.sql.Date} value, using a supplied calendar to map the date. The 1054 * calendar allows the application to control the timezone used to compute 1055 * the SQL {@code DATE} in the database. In case that no calendar is 1056 * supplied, the driver uses the default timezone of the Java virtual 1057 * machine. 1058 * 1059 * @param parameterName 1060 * the parameter name. 1061 * @param theDate 1062 * the new value with which to update the parameter. 1063 * @param cal 1064 * a {@code Calendar} to use to construct the SQL {@code DATE} 1065 * value. 1066 * @throws SQLException 1067 * if a database error occurs. 1068 * @see java.util.Calendar 1069 * @see Date 1070 */ setDate(String parameterName, Date theDate, Calendar cal)1071 public void setDate(String parameterName, Date theDate, Calendar cal) 1072 throws SQLException; 1073 1074 /** 1075 * Sets the value of a specified parameter to a supplied {@code double} 1076 * value. 1077 * 1078 * @param parameterName 1079 * the parameter name. 1080 * @param theDouble 1081 * the new value with which to update the parameter. 1082 * @throws SQLException 1083 * if a database error occurs. 1084 */ setDouble(String parameterName, double theDouble)1085 public void setDouble(String parameterName, double theDouble) 1086 throws SQLException; 1087 1088 /** 1089 * Sets the value of a specified parameter to to a supplied {@code float} 1090 * value. 1091 * 1092 * @param parameterName 1093 * the parameter name. 1094 * @param theFloat 1095 * the new value with which to update the parameter. 1096 * @throws SQLException 1097 * if a database error occurs. 1098 */ setFloat(String parameterName, float theFloat)1099 public void setFloat(String parameterName, float theFloat) 1100 throws SQLException; 1101 1102 /** 1103 * Sets the value of a specified parameter to a supplied {@code int} value. 1104 * 1105 * @param parameterName 1106 * the parameter name. 1107 * @param theInt 1108 * the new value with which to update the parameter. 1109 * @throws SQLException 1110 * if a database error occurs. 1111 */ setInt(String parameterName, int theInt)1112 public void setInt(String parameterName, int theInt) throws SQLException; 1113 1114 /** 1115 * Sets the value of a specified parameter to a supplied {@code long} value. 1116 * 1117 * @param parameterName 1118 * the parameter name. 1119 * @param theLong 1120 * the new value with which to update the parameter. 1121 * @throws SQLException 1122 * if a database error occurs. 1123 */ setLong(String parameterName, long theLong)1124 public void setLong(String parameterName, long theLong) throws SQLException; 1125 1126 /** 1127 * Sets the value of a specified parameter to SQL {@code NULL}. Don't use 1128 * this version of {@code setNull} for <i>User Defined Types</i> (UDT) or 1129 * for {@code REF} type parameters. 1130 * 1131 * @param parameterName 1132 * the parameter name. 1133 * @param sqlType 1134 * a JDBC type expressed as a constant from {@link Types}. 1135 * @throws SQLException 1136 * if a database error occurs. 1137 */ setNull(String parameterName, int sqlType)1138 public void setNull(String parameterName, int sqlType) throws SQLException; 1139 1140 /** 1141 * Sets the value of a specified parameter to be SQL {@code NULL} where the 1142 * parameter type is either {@code REF} or user defined (e.g. {@code STRUCT} 1143 * , {@code JAVA_OBJECT} etc). 1144 * <p> 1145 * For reasons of portability, the caller is expected to supply both the SQL 1146 * type code and type name (which is just the parameter name if the type is 1147 * user defined, referred to as a {@code UDT}, or the name of the referenced 1148 * type in case of a {@code REF} type). 1149 * 1150 * @param parameterName 1151 * the parameter name. 1152 * @param sqlType 1153 * a JDBC type expressed as a constant from {@link Types}. 1154 * @param typeName 1155 * if the target parameter is a user defined type then this 1156 * should contain the full type name. The fully qualified name of 1157 * a {@code UDT} or {@code REF} type is ignored if the parameter 1158 * is not a {@code UDT}. 1159 * @throws SQLException 1160 * if a database error occurs. 1161 * @see Types 1162 */ setNull(String parameterName, int sqlType, String typeName)1163 public void setNull(String parameterName, int sqlType, String typeName) 1164 throws SQLException; 1165 1166 /** 1167 * Sets the value of a specified parameter using a supplied object. Prior to 1168 * issuing this request to the connected database {@code theObject} is 1169 * transformed to the corresponding SQL type according to the standard Java 1170 * to SQL mapping rules. 1171 * <p> 1172 * If the object's class implements the interface {@code SQLData}, the JDBC 1173 * driver calls {@code SQLData.writeSQL} to write it to the SQL data stream. 1174 * If {@code theObject} implements any of the following interfaces then the 1175 * driver is in charge of mapping the value to the appropriate SQL type. 1176 * <ul><li>{@link Ref}</li> 1177 * <li>{@link Struct}</li> 1178 * <li>{@link Array}</li> 1179 * <li>{@link Clob}</li> 1180 * <li>{@link Blob}</li> </ul> 1181 * 1182 * @param parameterName 1183 * the parameter name 1184 * @param theObject 1185 * the new value with which to update the parameter 1186 * @throws SQLException 1187 * if a database error occurs. 1188 * @see SQLData 1189 */ setObject(String parameterName, Object theObject)1190 public void setObject(String parameterName, Object theObject) 1191 throws SQLException; 1192 1193 /** 1194 * Sets the value of a specified parameter using a supplied object. 1195 * <p> 1196 * The parameter {@code theObject} is converted to the given {@code 1197 * targetSqlType} before it is sent to the database. If the object has a 1198 * custom mapping (its class implements the interface {@code SQLData}), the 1199 * JDBC driver calls the method {@code SQLData.writeSQL} to write it to the 1200 * SQL data stream. If {@code theObject} is an instance of one of the 1201 * following types 1202 * <ul> 1203 * <li>{@link Ref}</li> 1204 * <li>{@link Struct}</li> 1205 * <li>{@link Array}</li> 1206 * <li>{@link Clob}</li> 1207 * <li>{@link Blob}</li> 1208 * </ul> 1209 * then the driver is in charge of mapping the value to the appropriate 1210 * SQL type and deliver it to the database. 1211 * 1212 * @param parameterName 1213 * the parameter name. 1214 * @param theObject 1215 * the new value with which to update the parameter. 1216 * @param targetSqlType 1217 * a JDBC type expressed as a constant from {@link Types}. 1218 * @throws SQLException 1219 * if a database error occurs. 1220 * @see SQLData 1221 */ setObject(String parameterName, Object theObject, int targetSqlType)1222 public void setObject(String parameterName, Object theObject, 1223 int targetSqlType) throws SQLException; 1224 1225 /** 1226 * Sets the value of a specified parameter using a supplied object. 1227 * <p> 1228 * The object is converted to the given {@code targetSqlType} before it is 1229 * sent to the database. If the object has a custom mapping (its class 1230 * implements the interface {@code SQLData}), the JDBC driver calls the 1231 * method {@code SQLData.writeSQL} to write it to the SQL data stream. If 1232 * {@code theObject} implements any of the following interfaces 1233 * <ul> 1234 * <li>{@link Ref}</li> 1235 * <li>{@link Struct}</li> 1236 * <li>{@link Array}</li> 1237 * <li>{@link Clob}</li> 1238 * <li>{@link Blob}</li> 1239 * </ul> 1240 * then the driver is charge of mapping the value to the appropriate 1241 * SQL type. 1242 * 1243 * @param parameterName 1244 * the parameter name. 1245 * @param theObject 1246 * the new value with which to update the parameter. 1247 * @param targetSqlType 1248 * a JDBC type expressed as a constant from {@link Types}. 1249 * @param scale 1250 * where applicable, the number of digits after the decimal. 1251 * point. 1252 * @throws SQLException 1253 * if a database error occurs. 1254 * @see SQLData 1255 */ setObject(String parameterName, Object theObject, int targetSqlType, int scale)1256 public void setObject(String parameterName, Object theObject, 1257 int targetSqlType, int scale) throws SQLException; 1258 1259 /** 1260 * Sets the value of a specified parameter to a supplied {@code short} 1261 * value. 1262 * 1263 * @param parameterName 1264 * the name of the parameter. 1265 * @param theShort 1266 * a short value to update the parameter. 1267 * @throws SQLException 1268 * if a database error occurs. 1269 */ setShort(String parameterName, short theShort)1270 public void setShort(String parameterName, short theShort) 1271 throws SQLException; 1272 1273 /** 1274 * Sets the value of a specified parameter to a supplied {@code String}. 1275 * 1276 * @param parameterName 1277 * the name of the parameter. 1278 * @param theString 1279 * a {@code String} value to update the parameter. 1280 * @throws SQLException 1281 * if a database error occurs. 1282 */ setString(String parameterName, String theString)1283 public void setString(String parameterName, String theString) 1284 throws SQLException; 1285 1286 /** 1287 * Sets the value of the parameter named {@code parameterName} to the value 1288 * of the supplied {@code java.sql.Time}. 1289 * 1290 * @param parameterName 1291 * the parameter name. 1292 * @param theTime 1293 * the new value with which to update the parameter. 1294 * @throws SQLException 1295 * if a database error occurs. 1296 * @see Time 1297 */ setTime(String parameterName, Time theTime)1298 public void setTime(String parameterName, Time theTime) throws SQLException; 1299 1300 /** 1301 * Sets the value of the parameter named {@code parameterName} to the value 1302 * of the supplied {@code java.sql.Time} using the supplied calendar. 1303 * 1304 * <p>The driver uses the supplied {@code Calendar} to create the SQL 1305 * {@code TIME} value, which allows it to use a custom timezone - 1306 * otherwise the driver uses the VM defaults. 1307 * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>". 1308 * 1309 * @param parameterName 1310 * the parameter name. 1311 * @param theTime 1312 * the new value with which to update the parameter. 1313 * @param cal 1314 * used for creating the new SQL {@code TIME} value. 1315 * @throws SQLException 1316 * if a database error occurs. 1317 * @see Time 1318 */ setTime(String parameterName, Time theTime, Calendar cal)1319 public void setTime(String parameterName, Time theTime, Calendar cal) 1320 throws SQLException; 1321 1322 /** 1323 * Sets the value of a specified parameter to a supplied {@code 1324 * java.sql.Timestamp} value. 1325 * 1326 * @param parameterName 1327 * the parameter name. 1328 * @param theTimestamp 1329 * the new value with which to update the parameter. 1330 * @throws SQLException 1331 * if a database error occurs. 1332 * @see Timestamp 1333 */ setTimestamp(String parameterName, Timestamp theTimestamp)1334 public void setTimestamp(String parameterName, Timestamp theTimestamp) 1335 throws SQLException; 1336 1337 /** 1338 * Sets the value of a specified parameter to a supplied {@code 1339 * java.sql.Timestamp} value, using the supplied calendar. 1340 * 1341 * <p>The driver uses the supplied calendar to create the SQL {@code TIMESTAMP} 1342 * value, which allows it to use a custom timezone - otherwise the driver 1343 * uses the VM defaults. 1344 * See "<a href="../util/Locale.html#default_locale">Be wary of the default locale</a>". 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 */ setTimestamp(String parameterName, Timestamp theTimestamp, Calendar cal)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 */ setURL(String parameterName, URL theURL)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 */ wasNull()1383 public boolean wasNull() throws SQLException; 1384 1385 /** 1386 * Gets the value of a specified {@code ROWID} parameter as a {@code 1387 * java.sql.RowId}. 1388 * 1389 * @param parameterIndex 1390 * the parameter number index, where the first parameter has 1391 * index 1. 1392 * @throws SQLException 1393 * if a database error occurs. 1394 */ getRowId(int parameterIndex)1395 public RowId getRowId(int parameterIndex) throws SQLException; 1396 1397 /** 1398 * Returns the value of the specified SQL ROWID parameter as a {@code 1399 * java.sql.RowId}. 1400 * @param parameterName the parameter name 1401 * @throws SQLException if a database error occurs 1402 */ getRowId(String parameterName)1403 public RowId getRowId(String parameterName) throws SQLException; 1404 1405 /** 1406 * Sets the named parameter to the given {@code rowId}. 1407 * @throws SQLException if a database error occurs 1408 */ setRowId(String parameterName, RowId rowId)1409 public void setRowId(String parameterName, RowId rowId) throws SQLException; 1410 1411 /** 1412 * Sets the named parameter to the given {@code string}. 1413 * @throws SQLException if a database error occurs 1414 */ setNString(String parameterName, String string)1415 public void setNString(String parameterName, String string) throws SQLException; 1416 1417 /** 1418 * Sets the named parameter to the characters from the given {@code reader}. 1419 * @throws SQLException if a database error occurs 1420 */ setNCharacterStream(String parameterName, Reader reader, long length)1421 public void setNCharacterStream(String parameterName, Reader reader, long length) throws SQLException; 1422 1423 /** 1424 * Sets the named parameter to the given {@code nclob}. 1425 * @throws SQLException if a database error occurs 1426 */ setNClob(String parameterName, NClob nclob)1427 public void setNClob(String parameterName, NClob nclob) throws SQLException; 1428 1429 /** 1430 * Sets the named parameter to the next {@code length} characters from the given {@code reader}. 1431 * @throws SQLException if a database error occurs 1432 */ setClob(String parameterName, Reader reader, long length)1433 public void setClob(String parameterName, Reader reader, long length) throws SQLException; 1434 1435 /** 1436 * Sets the named parameter to the next {@code length} bytes from the given {@code inputStream}. 1437 * @throws SQLException if a database error occurs 1438 */ setBlob(String parameterName, InputStream inputStream, long length)1439 public void setBlob(String parameterName, InputStream inputStream, long length) throws SQLException; 1440 1441 /** 1442 * Sets the named parameter to the next {@code length} characters from the given {@code reader}. 1443 * @throws SQLException if a database error occurs 1444 */ setNClob(String parameterName, Reader reader, long length)1445 public void setNClob(String parameterName, Reader reader, long length) throws SQLException; 1446 1447 /** 1448 * Returns the value of the specified SQL NCLOB parameter as a {@code 1449 * java.sql.NClob}. 1450 * 1451 * @param parameterIndex 1452 * the parameter number index, where the first parameter has 1453 * index 1. 1454 * @throws SQLException 1455 * if a database error occurs. 1456 */ getNClob(int parameterIndex)1457 public NClob getNClob(int parameterIndex) throws SQLException; 1458 1459 /** 1460 * Returns the value of the specified SQL NCLOB parameter as a {@code 1461 * java.sql.NClob}. 1462 * @param parameterName the parameter name 1463 * @throws SQLException if a database error occurs 1464 */ getNClob(String parameterName)1465 public NClob getNClob(String parameterName) throws SQLException; 1466 1467 /** 1468 * Sets the named parameter to the given {@code sqlXml}. 1469 * @throws SQLException if a database error occurs 1470 */ setSQLXML(String parameterName, SQLXML sqlXml)1471 public void setSQLXML(String parameterName, SQLXML sqlXml) throws SQLException; 1472 1473 /** 1474 * Returns the value of the specified SQL XML parameter as a {@code 1475 * java.sql.SQLXML}. 1476 * 1477 * @param parameterIndex 1478 * the parameter number index, where the first parameter has 1479 * index 1. 1480 * @throws SQLException 1481 * if a database error occurs. 1482 */ getSQLXML(int parameterIndex)1483 public SQLXML getSQLXML(int parameterIndex) throws SQLException; 1484 1485 /** 1486 * Returns the value of the specified SQL XML parameter as a {@code 1487 * java.sql.SQLXML}. 1488 * @param parameterName the parameter name 1489 * @throws SQLException if a database error occurs 1490 */ getSQLXML(String parameterName)1491 public SQLXML getSQLXML(String parameterName) throws SQLException; 1492 1493 /** 1494 * Returns the value of the specified SQL NCHAR, NVARCHAR, or LONGNVARCHAR parameter as a 1495 * {@code java.lang.String}. 1496 * 1497 * @param parameterIndex 1498 * the parameter number index, where the first parameter has 1499 * index 1. 1500 * @throws SQLException 1501 * if a database error occurs. 1502 */ getNString(int parameterIndex)1503 public String getNString(int parameterIndex) throws SQLException; 1504 1505 /** 1506 * Returns the value of the specified SQL NCHAR, NVARCHAR, or LONGNVARCHAR parameter as a {@code 1507 * java.lang.String}. 1508 * @param parameterName the parameter name 1509 * @throws SQLException if a database error occurs 1510 */ getNString(String parameterName)1511 public String getNString(String parameterName) throws SQLException; 1512 1513 /** 1514 * Returns the value of the specified SQL NCHAR, NVARCHAR, or LONGNVARCHAR parameter 1515 * as a {@link Reader}. 1516 * 1517 * @param parameterIndex 1518 * the parameter number index, where the first parameter has 1519 * index 1. 1520 * @throws SQLException 1521 * if a database error occurs. 1522 */ getNCharacterStream(int parameterIndex)1523 public Reader getNCharacterStream(int parameterIndex) throws SQLException; 1524 1525 /** 1526 * Returns the value of the specified SQL NCHAR, NVARCHAR, or LONGNVARCHAR parameter as a {@code 1527 * java.io.Reader}. 1528 * @param parameterName the parameter name 1529 * @throws SQLException if a database error occurs 1530 */ getNCharacterStream(String parameterName)1531 public Reader getNCharacterStream(String parameterName) throws SQLException; 1532 1533 /** 1534 * Returns the value of the specified parameter as a {@code java.io.Reader}. 1535 * @param parameterIndex 1536 * the parameter number index, where the first parameter has 1537 * index 1. 1538 * @throws SQLException 1539 * if a database error occurs. 1540 */ getCharacterStream(int parameterIndex)1541 public Reader getCharacterStream(int parameterIndex) throws SQLException; 1542 1543 /** 1544 * Returns the value of the specified parameter as a {@code java.io.Reader}. 1545 * @param parameterName the parameter name 1546 * @throws SQLException if a database error occurs 1547 */ getCharacterStream(String parameterName)1548 public Reader getCharacterStream(String parameterName) throws SQLException; 1549 1550 /** 1551 * Sets the named parameter to the given {@code blob}. 1552 * @throws SQLException if a database error occurs 1553 */ setBlob(String parameterName, Blob blob)1554 public void setBlob(String parameterName, Blob blob) throws SQLException; 1555 1556 /** 1557 * Sets the named parameter to the given {@code clob}. 1558 * @throws SQLException if a database error occurs 1559 */ setClob(String parameterName, Clob clob)1560 public void setClob(String parameterName, Clob clob) throws SQLException; 1561 1562 /** 1563 * Sets the named parameter to the next {@code length} bytes from the given {@code inputStream}. 1564 * @throws SQLException if a database error occurs 1565 */ setAsciiStream(String parameterName, InputStream x, long length)1566 public void setAsciiStream(String parameterName, InputStream x, long length) throws SQLException; 1567 1568 /** 1569 * Sets the named parameter to the bytes from the given {@code reader}. 1570 * @throws SQLException if a database error occurs 1571 */ setAsciiStream(String parameterName, InputStream x)1572 public void setAsciiStream(String parameterName, InputStream x) throws SQLException; 1573 1574 /** 1575 * Sets the named parameter to the next {@code length} bytes from the given {@code inputStream}. 1576 * @throws SQLException if a database error occurs 1577 */ setBinaryStream(String parameterName, InputStream x, long length)1578 public void setBinaryStream(String parameterName, InputStream x, long length) throws SQLException; 1579 1580 /** 1581 * Sets the named parameter to the bytes from the given {@code reader}. 1582 * @throws SQLException if a database error occurs 1583 */ setBinaryStream(String parameterName, InputStream x)1584 public void setBinaryStream(String parameterName, InputStream x) throws SQLException; 1585 1586 /** 1587 * Sets the named parameter to the next {@code length} characters from the given {@code reader}. 1588 * @throws SQLException if a database error occurs 1589 */ setCharacterStream(String parameterName, Reader reader, long length)1590 public void setCharacterStream(String parameterName, Reader reader, long length) throws SQLException; 1591 1592 /** 1593 * Sets the named parameter to the characters from the given {@code reader}. 1594 * @throws SQLException if a database error occurs 1595 */ setCharacterStream(String parameterName, Reader reader)1596 public void setCharacterStream(String parameterName, Reader reader) throws SQLException; 1597 1598 /** 1599 * Sets the named parameter to the characters from the given {@code reader}. 1600 * @throws SQLException if a database error occurs 1601 */ setNCharacterStream(String parameterName, Reader value)1602 public void setNCharacterStream(String parameterName, Reader value) throws SQLException; 1603 1604 /** 1605 * Sets the named parameter to the characters from the given {@code reader}. 1606 * @throws SQLException if a database error occurs 1607 */ setClob(String parameterName, Reader reader)1608 public void setClob(String parameterName, Reader reader) throws SQLException; 1609 1610 /** 1611 * Sets the named parameter to the bytes from the given {@code inputStream}. 1612 * @throws SQLException if a database error occurs 1613 */ setBlob(String parameterName, InputStream inputStream)1614 public void setBlob(String parameterName, InputStream inputStream) throws SQLException; 1615 1616 /** 1617 * Sets the named parameter to the characters from the given {@code reader}. 1618 * @throws SQLException if a database error occurs 1619 */ setNClob(String parameterName, Reader reader)1620 public void setNClob(String parameterName, Reader reader) throws SQLException; 1621 } 1622