libjava/java/sql/CallableStatement.java

   1 /* CallableStatement.java -- A statement for calling stored procedures.
   2    Copyright (C) 1999, 2000, 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.sql;
  39
  40 import java.io.InputStream;
  41 import java.io.Reader;
  42 import java.math.BigDecimal;
  43 import java.net.URL;
  44 import java.util.Calendar;
  45 import java.util.Map;
  46
  47 /**
  48  * This interface provides a mechanism for calling stored procedures.
  49  *
  50  * @author Aaron M. Renn (arenn@urbanophile.com)
  51  */
  52 public interface CallableStatement extends PreparedStatement
  53 {
  54   /**
  55    * This method registers the specified parameter as an output parameter
  56    * of the specified SQL type.
  57    *
  58    * @param index The index of the parameter to register as output.
  59    * @param type The SQL type value from <code>Types</code>.
  60    * @exception SQLException If an error occurs.
  61    */
  62   void registerOutParameter(int parameterIndex, int sqlType)
  63     throws SQLException;
  64
  65   /**
  66    * This method registers the specified parameter as an output parameter
  67    * of the specified SQL type and scale.
  68    *
  69    * @param index The index of the parameter to register as output.
  70    * @param type The SQL type value from <code>Types</code>.
  71    * @param scale The scale of the value that will be returned.
  72    * @exception SQLException If an error occurs.
  73    */
  74   void registerOutParameter(int parameterIndex, int sqlType, int scale)
  75     throws SQLException;
  76
  77   /**
  78    * This method tests whether the value of the last parameter that was fetched
  79    * was actually a SQL NULL value.
  80    *
  81    * @return <code>true</code> if the last parameter fetched was a NULL,
  82    *         <code>false</code> otherwise.
  83    * @exception SQLException If an error occurs.
  84    */
  85   boolean wasNull() throws SQLException;
  86
  87   /**
  88    * This method returns the value of the specified parameter as a Java
  89    * <code>String</code>.
  90    *
  91    * @param index The index of the parameter to return.
  92    * @return The parameter value as a <code>String</code>.
  93    * @exception SQLException If an error occurs.
  94    */
  95   String getString(int parameterIndex) throws SQLException;
  96
  97   /**
  98    * This method returns the value of the specified parameter as a Java
  99    * <code>boolean</code>.
 100    *
 101    * @param index The index of the parameter to return.
 102    * @return The parameter value as a <code>boolean</code>.
 103    * @exception SQLException If an error occurs.
 104    */
 105   boolean getBoolean(int parameterIndex) throws SQLException;
 106
 107   /**
 108    * This method returns the value of the specified parameter as a Java
 109    * <code>byte</code>.
 110    *
 111    * @param index The index of the parameter to return.
 112    * @return The parameter value as a <code>byte</code>.
 113    * @exception SQLException If an error occurs.
 114    */
 115   byte getByte(int parameterIndex) throws SQLException;
 116
 117   /**
 118    * This method returns the value of the specified parameter as a Java
 119    * <code>short</code>.
 120    *
 121    * @param index The index of the parameter to return.
 122    * @return The parameter value as a <code>short</code>.
 123    * @exception SQLException If an error occurs.
 124    */
 125   short getShort(int parameterIndex) throws SQLException;
 126
 127   /**
 128    * This method returns the value of the specified parameter as a Java
 129    * <code>int</code>.
 130    *
 131    * @param index The index of the parameter to return.
 132    * @return The parameter value as a <code>int</code>.
 133    * @exception SQLException If an error occurs.
 134    */
 135   int getInt(int parameterIndex) throws SQLException;
 136
 137   /**
 138    * This method returns the value of the specified parameter as a Java
 139    * <code>long</code>.
 140    *
 141    * @param index The index of the parameter to return.
 142    * @return The parameter value as a <code>long</code>.
 143    * @exception SQLException If an error occurs.
 144    */
 145   long getLong(int parameterIndex) throws SQLException;
 146
 147   /**
 148    * This method returns the value of the specified parameter as a Java
 149    * <code>float</code>.
 150    *
 151    * @param index The index of the parameter to return.
 152    * @return The parameter value as a <code>float</code>.
 153    * @exception SQLException If an error occurs.
 154    */
 155   float getFloat(int parameterIndex) throws SQLException;
 156
 157   /**
 158    * This method returns the value of the specified parameter as a Java
 159    * <code>double</code>.
 160    *
 161    * @param index The index of the parameter to return.
 162    * @return The parameter value as a <code>double</code>.
 163    * @exception SQLException If an error occurs.
 164    */
 165   double getDouble(int parameterIndex) throws SQLException;
 166
 167   /**
 168    * This method returns the value of the specified parameter as a Java
 169    * <code>BigDecimal</code>.
 170    *
 171    * @param parameterIndex The index of the parameter to return.
 172    * @param scale The number of digits to the right of the decimal to return.
 173    * @return The parameter value as a <code>BigDecimal</code>.
 174    * @exception SQLException If an error occurs.
 175    * @deprecated Use getBigDecimal(int parameterIndex)
 176    *             or getBigDecimal(String parameterName) instead.
 177    */
 178   BigDecimal getBigDecimal(int parameterIndex, int scale)
 179     throws SQLException;
 180
 181   /**
 182    * This method returns the value of the specified parameter as a Java
 183    * byte array.
 184    *
 185    * @param parameterIndex The index of the parameter to return.
 186    * @return The parameter value as a byte array
 187    * @exception SQLException If an error occurs.
 188    */
 189   byte[] getBytes(int parameterIndex) throws SQLException;
 190
 191   /**
 192    * This method returns the value of the specified parameter as a Java
 193    * <code>java.sql.Date</code>.
 194    *
 195    * @param index The index of the parameter to return.
 196    * @return The parameter value as a <code>java.sql.Date</code>.
 197    * @exception SQLException If an error occurs.
 198    */
 199   Date getDate(int parameterIndex) throws SQLException;
 200
 201   /**
 202    * This method returns the value of the specified parameter as a Java
 203    * <code>java.sql.Time</code>.
 204    *
 205    * @param index The index of the parameter to return.
 206    * @return The parameter value as a <code>java.sql.Time</code>.
 207    * @exception SQLException If an error occurs.
 208    */
 209   Time getTime(int parameterIndex) throws SQLException;
 210
 211   /**
 212    * This method returns the value of the specified parameter as a Java
 213    * <code>java.sql.Timestamp</code>.
 214    *
 215    * @param index The index of the parameter to return.
 216    * @return The parameter value as a <code>java.sql.Timestamp</code>.
 217    * @exception SQLException If an error occurs.
 218    */
 219   Timestamp getTimestamp(int parameterIndex) throws SQLException;
 220
 221   /**
 222    * This method returns the value of the specified parameter as a Java
 223    * <code>Object</code>.
 224    *
 225    * @param parameterIndex The index of the parameter to return.
 226    * @return The parameter value as an <code>Object</code>.
 227    * @exception SQLException If an error occurs.
 228    * @since 1.2
 229    */
 230   Object getObject(int parameterIndex) throws SQLException;
 231
 232   /**
 233    * This method returns the value of the specified parameter as a Java
 234    * <code>BigDecimal</code>.
 235    *
 236    * @param parameterIndex The index of the parameter to return.
 237    * @return The parameter value as a <code>BigDecimal</code>.
 238    * @exception SQLException If an error occurs.
 239    * @since 1.2
 240    */
 241   BigDecimal getBigDecimal(int parameterIndex) throws SQLException;
 242
 243   /**
 244    * This method returns the value of the specified parameter as a Java
 245    * <code>Object</code>.
 246    *
 247    * @param index The index of the parameter to return.
 248    * @param map The mapping to use for conversion from SQL to Java types.
 249    * @return The parameter value as an <code>Object</code>.
 250    * @exception SQLException If an error occurs.
 251    * @since 1.2
 252    */
 253   Object getObject(int index, Map map) throws SQLException;
 254
 255   /**
 256    * This method returns the value of the specified parameter as a Java
 257    * <code>Ref</code>.
 258    *
 259    * @param index The index of the parameter to return.
 260    * @return The parameter value as a <code>Ref</code>.
 261    * @exception SQLException If an error occurs.
 262    * @since 1.2
 263    */
 264   Ref getRef(int index) throws SQLException;
 265
 266   /**
 267    * This method returns the value of the specified parameter as a Java
 268    * <code>Blob</code>.
 269    *
 270    * @param index The index of the parameter to return.
 271    * @return The parameter value as a <code>Blob</code>.
 272    * @exception SQLException If an error occurs.
 273    * @since 1.2
 274    */
 275   Blob getBlob(int index) throws SQLException;
 276
 277   /**
 278    * This method returns the value of the specified parameter as a Java
 279    * <code>Clob</code>.
 280    *
 281    * @param index The index of the parameter to return.
 282    * @return The parameter value as a <code>Clob</code>.
 283    * @exception SQLException If an error occurs.
 284    * @since 1.2
 285    */
 286   Clob getClob(int index) throws SQLException;
 287
 288   /**
 289    * This method returns the value of the specified parameter as a Java
 290    * <code>Array</code>.
 291    *
 292    * @param parameterIndex The index of the parameter to return.
 293    * @return The parameter value as a <code>Array</code>.
 294    * @exception SQLException If an error occurs.
 295    * @since 1.2
 296    */
 297   Array getArray(int index) throws SQLException;
 298
 299   /**
 300    * This method returns the value of the specified parameter as a Java
 301    * <code>java.sql.Date</code>.
 302    *
 303    * @param parameterIndex The index of the parameter to return.
 304    * @param cal The <code>Calendar</code> to use for timezone and locale.
 305    * @return The parameter value as a <code>java.sql.Date</code>.
 306    * @exception SQLException If an error occurs.
 307    * @since 1.2
 308    */
 309   Date getDate(int parameterIndex, Calendar cal) throws SQLException;
 310
 311   /**
 312    * This method returns the value of the specified parameter as a Java
 313    * <code>java.sql.Time</code>.
 314    *
 315    * @param parameterIndex The index of the parameter to return.
 316    * @param cal The <code>Calendar</code> to use for timezone and locale.
 317    * @return The parameter value as a <code>java.sql.Time</code>.
 318    * @exception SQLException If an error occurs.
 319    * @since 1.2
 320    */
 321   Time getTime(int parameterIndex, Calendar cal) throws SQLException;
 322
 323   /**
 324    * This method returns the value of the specified parameter as a Java
 325    * <code>java.sql.Timestamp</code>.
 326    *
 327    * @param index The index of the parameter to return.
 328    * @return The parameter value as a <code>java.sql.Timestamp</code>.
 329    * @exception SQLException If an error occurs.
 330    * @since 1.2
 331    */
 332   Timestamp getTimestamp(int parameterIndex, Calendar cal)
 333     throws SQLException;
 334
 335   /**
 336    * This method registers the specified parameter as an output parameter
 337    * of the specified SQL type.
 338    *
 339    * @param index The index of the parameter to register as output.
 340    * @param type The SQL type value from <code>Types</code>.
 341    * @param name The user defined data type name.
 342    * @exception SQLException If an error occurs.
 343    * @since 1.2
 344    */
 345   void registerOutParameter(int paramIndex, int sqlType,
 346                                    String typeName)
 347     throws SQLException;
 348
 349   /**
 350    * This method registers the specified parameter as an output parameter
 351    * of the specified SQL type.
 352    *
 353    * @param parameterName The name of the parameter to register as output.
 354    * @param sqlType The SQL type value from <code>Types</code>.
 355    * @exception SQLException If an error occurs.
 356    * @since 1.4
 357    */
 358   void registerOutParameter(String parameterName, int sqlType)
 359     throws SQLException;
 360
 361   /**
 362    * This method registers the specified parameter as an output parameter
 363    * of the specified SQL type.  This version of registerOutParameter is used
 364    * for NUMERIC or DECIMAL types.
 365    *
 366    * @param parameterName The name of the parameter to register as output.
 367    * @param sqlType The SQL type value from <code>Types</code>.
 368    * @param scale Number of digits to the right of the decimal point.
 369    * @exception SQLException If an error occurs.
 370    * @since 1.4
 371    */
 372   void registerOutParameter(String parameterName, int sqlType,
 373                                    int scale)
 374     throws SQLException;
 375
 376
 377   /**
 378    * This method registers the specified parameter as an output parameter
 379    * of the specified SQL type.  This version of registerOutParameter is used
 380    * for user-named or REF types. If the type of the output parameter does
 381    * not have such a type, the typeName argument is ignored.
 382    *
 383    * @param parameterName The name of the parameter to register as output.
 384    * @param sqlType The SQL type value from <code>Types</code>.
 385    * @param typeName The SQL structured type name.
 386    * @exception SQLException If an error occurs.
 387    * @since 1.4
 388    */
 389   void registerOutParameter(String parameterName, int sqlType,
 390                                    String typeName)
 391     throws SQLException;
 392
 393   /**
 394    * @since 1.4
 395    */
 396   URL getURL(int parameterIndex) throws SQLException;
 397
 398   /**
 399    * @since 1.4
 400    */
 401   void setURL(String parameterName, URL val) throws SQLException;
 402
 403   /**
 404    * @since 1.4
 405    */
 406   void setNull(String parameterName, int sqlType) throws SQLException;
 407
 408   /**
 409    * @since 1.4
 410    */
 411   void setBoolean(String parameterName, boolean x) throws SQLException;
 412
 413   /**
 414    * @since 1.4
 415    */
 416   void setByte(String parameterName, byte x) throws SQLException;
 417
 418   /**
 419    * @since 1.4
 420    */
 421   void setShort(String parameterName, short x) throws SQLException;
 422
 423   /**
 424    * @since 1.4
 425    */
 426   void setInt(String parameterName, int x) throws SQLException;
 427
 428   /**
 429    * @since 1.4
 430    */
 431   void setLong(String parameterName, long x) throws SQLException;
 432
 433   /**
 434    * @since 1.4
 435    */
 436   void setFloat(String parameterName, float x) throws SQLException;
 437
 438   /**
 439    * @since 1.4
 440    */
 441   void setDouble(String parameterName, double x) throws SQLException;
 442
 443   /**
 444    * @since 1.4
 445    */
 446   void setBigDecimal(String parameterName, BigDecimal x)
 447     throws SQLException;
 448
 449   /**
 450    * @since 1.4
 451    */
 452   void setString(String parameterName, String x) throws SQLException;
 453
 454   /**
 455    * @since 1.4
 456    */
 457   void setBytes(String parameterName, byte[] x) throws SQLException;
 458
 459   /**
 460    * @since 1.4
 461    */
 462   void setDate(String parameterName, Date x) throws SQLException;
 463
 464   /**
 465    * @since 1.4
 466    */
 467   void setTime(String parameterName, Time x) throws SQLException;
 468
 469   /**
 470    * @since 1.4
 471    */
 472   void setTimestamp(String parameterName, Timestamp x)
 473     throws SQLException;
 474
 475   /**
 476    * @since 1.4
 477    */
 478   void setAsciiStream(String parameterName, InputStream x, int length)
 479       throws SQLException;
 480
 481   /**
 482    * @since 1.4
 483    */
 484   void setBinaryStream(String parameterName, InputStream x, int length)
 485       throws SQLException;
 486
 487   /**
 488    * @since 1.4
 489    */
 490   void setObject(String parameterName, Object x, int targetSqlType,
 491                         int scale)
 492     throws SQLException;
 493
 494   /**
 495    * @since 1.4
 496    */
 497   void setObject(String parameterName, Object x, int targetSqlType)
 498     throws SQLException;
 499
 500   /**
 501    * @since 1.4
 502    */
 503   void setObject(String parameterName, Object x) throws SQLException;
 504
 505   /**
 506    * @since 1.4
 507    */
 508   void setCharacterStream(String parameterName, Reader reader,
 509                                  int length)
 510     throws SQLException;
 511
 512   /**
 513    * @since 1.4
 514    */
 515   void setDate(String parameterName, Date x, Calendar cal)
 516     throws SQLException;
 517
 518   /**
 519    * @since 1.4
 520    */
 521   void setTime(String parameterName, Time x, Calendar cal)
 522     throws SQLException;
 523
 524   /**
 525    * @since 1.4
 526    */
 527   void setTimestamp(String parameterName, Timestamp x, Calendar cal)
 528     throws SQLException;
 529
 530   /**
 531    * @since 1.4
 532    */
 533   void setNull(String parameterName, int sqlType, String typeName)
 534     throws SQLException;
 535
 536   /**
 537    * @since 1.4
 538    */
 539   String getString(String parameterName) throws SQLException;
 540
 541   /**
 542    * @since 1.4
 543    */
 544   boolean getBoolean(String parameterName) throws SQLException;
 545
 546   /**
 547    * @since 1.4
 548    */
 549   byte getByte(String parameterName) throws SQLException;
 550
 551   /**
 552    * @since 1.4
 553    */
 554   short getShort(String parameterName) throws SQLException;
 555
 556   /**
 557    * @since 1.4
 558    */
 559   int getInt(String parameterName) throws SQLException;
 560
 561   /**
 562    * @since 1.4
 563    */
 564   long getLong(String parameterName) throws SQLException;
 565
 566   /**
 567    * @since 1.4
 568    */
 569   float getFloat(String parameterName) throws SQLException;
 570
 571   /**
 572    * @since 1.4
 573    */
 574   double getDouble(String parameterName) throws SQLException;
 575
 576   /**
 577    * @since 1.4
 578    */
 579   byte[] getBytes(String parameterName) throws SQLException;
 580
 581   /**
 582    * @since 1.4
 583    */
 584   Date getDate(String parameterName) throws SQLException;
 585
 586   /**
 587    * @since 1.4
 588    */
 589   Time getTime(String parameterName) throws SQLException;
 590
 591   /**
 592    * @since 1.4
 593    */
 594   Timestamp getTimestamp(String parameterName) throws SQLException;
 595
 596   /**
 597    * @since 1.4
 598    */
 599   Object getObject(String parameterName) throws SQLException;
 600
 601   /**
 602    * @since 1.4
 603    */
 604   BigDecimal getBigDecimal(String parameterName) throws SQLException;
 605
 606   /**
 607    * @since 1.4
 608    */
 609   Object getObject(String parameterName, Map map) throws SQLException;
 610
 611   /**
 612    * @since 1.4
 613    */
 614   Ref getRef(String parameterName) throws SQLException;
 615
 616   /**
 617    * @since 1.4
 618    */
 619   Blob getBlob(String parameterName) throws SQLException;
 620
 621   /**
 622    * @since 1.4
 623    */
 624   Clob getClob(String parameterName) throws SQLException;
 625
 626   /**
 627    * @since 1.4
 628    */
 629   Array getArray(String parameterName) throws SQLException;
 630
 631   /**
 632    * @since 1.4
 633    */
 634   Date getDate(String parameterName, Calendar cal) throws SQLException;
 635
 636   /**
 637    * @since 1.4
 638    */
 639   Time getTime(String parameterName, Calendar cal) throws SQLException;
 640
 641   /**
 642    * @since 1.4
 643    */
 644   Timestamp getTimestamp(String parameterName, Calendar cal)
 645     throws SQLException;
 646
 647   /**
 648    * @since 1.4
 649    */
 650   URL getURL(String parameterName) throws SQLException;
 651 }