Source for java.sql.CallableStatement

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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: }