Source for java.sql.PreparedStatement

   1: /* PreparedStatement.java -- Interface for pre-compiled statements.
   2:    Copyright (C) 1999, 2000, 2006 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: 
  46: /**
  47:  * This interface provides a mechanism for executing pre-compiled
  48:  * statements.  This provides greater efficiency when calling the same
  49:  * statement multiple times.  Parameters are allowed in a statement,
  50:  * providings for maximum reusability.
  51:  * 
  52:  * <p> Note that in this class parameter indices start at 1, not 0.</p>
  53:  *
  54:  * @author Aaron M. Renn (arenn@urbanophile.com)
  55:  */
  56: public interface PreparedStatement extends Statement 
  57: {
  58:   /**
  59:    * This method executes a prepared SQL query and returns its ResultSet.
  60:    *
  61:    * @return The ResultSet of the SQL statement.
  62:    * @exception SQLException If an error occurs.
  63:    */
  64:   ResultSet executeQuery() throws SQLException;
  65: 
  66:   /**
  67:    * This method executes an SQL INSERT, UPDATE or DELETE statement.  SQL
  68:    * statements that return nothing such as SQL DDL statements can be executed.
  69:    *
  70:    * @return The result is either the row count for INSERT, UPDATE or DELETE
  71:    *         statements; or 0 for SQL statements that return nothing.
  72:    * @exception SQLException If an error occurs.
  73:    */
  74:   int executeUpdate() throws SQLException;
  75: 
  76:   /**
  77:    * This method populates the specified parameter with a SQL NULL value
  78:    * for the specified type.
  79:    *
  80:    * @param index The index of the parameter to set.
  81:    * @param sqlType The SQL type identifier of the parameter from 
  82:    *                <code>Types</code>
  83:    *
  84:    * @exception SQLException If an error occurs.
  85:    */
  86:   void setNull(int index, int sqlType) throws SQLException;
  87: 
  88:   /**
  89:    * This method sets the specified parameter from the given Java
  90:    * <code>boolean</code> value.
  91:    *
  92:    * @param index The index of the parameter value to set.
  93:    * @param value The value of the parameter.
  94:    * @exception SQLException If an error occurs.
  95:    */
  96:   void setBoolean(int index, boolean value) throws SQLException;
  97: 
  98:   /**
  99:    * This method sets the specified parameter from the given Java
 100:    * <code>byte</code> value.
 101:    *
 102:    * @param index The index of the parameter value to set.
 103:    * @param value The value of the parameter.
 104:    * @exception SQLException If an error occurs.
 105:    */
 106:   void setByte(int index, byte value) throws SQLException;
 107: 
 108:   /**
 109:    * This method sets the specified parameter from the given Java
 110:    * <code>short</code> value.
 111:    *
 112:    * @param index The index of the parameter value to set.
 113:    * @param value The value of the parameter.
 114:    * @exception SQLException If an error occurs.
 115:    */
 116:   void setShort(int index, short value) throws SQLException;
 117: 
 118:   /**
 119:    * This method sets the specified parameter from the given Java
 120:    * <code>int</code> value.
 121:    *
 122:    * @param index The index of the parameter value to set.
 123:    * @param value The value of the parameter.
 124:    * @exception SQLException If an error occurs.
 125:    */
 126:   void setInt(int index, int value) throws SQLException;
 127: 
 128:   /**
 129:    * This method sets the specified parameter from the given Java
 130:    * <code>long</code> value.
 131:    *
 132:    * @param index The index of the parameter value to set.
 133:    * @param value The value of the parameter.
 134:    * @exception SQLException If an error occurs.
 135:    */
 136:   void setLong(int index, long value) throws SQLException;
 137: 
 138:   /**
 139:    * This method sets the specified parameter from the given Java
 140:    * <code>float</code> value.
 141:    *
 142:    * @param index The index of the parameter value to set.
 143:    * @param value The value of the parameter.
 144:    * @exception SQLException If an error occurs.
 145:    */
 146:   void setFloat(int index, float value) throws SQLException;
 147: 
 148:   /**
 149:    * This method sets the specified parameter from the given Java
 150:    * <code>double</code> value.
 151:    *
 152:    * @param index The index of the parameter value to set.
 153:    * @param value The value of the parameter.
 154:    * @exception SQLException If an error occurs.
 155:    */
 156:   void setDouble(int index, double value) throws SQLException;
 157: 
 158:   /**
 159:    * This method sets the specified parameter from the given Java
 160:    * <code>java.math.BigDecimal</code> value.
 161:    *
 162:    * @param index The index of the parameter value to set.
 163:    * @param value The value of the parameter.
 164:    * @exception SQLException If an error occurs.
 165:    */
 166:   void setBigDecimal(int index, BigDecimal value) throws
 167:       SQLException;
 168: 
 169:   /**
 170:    * This method sets the specified parameter from the given Java
 171:    * <code>String</code> value.
 172:    *
 173:    * @param index The index of the parameter value to set.
 174:    * @param value The value of the parameter.
 175:    * @exception SQLException If an error occurs.
 176:    */
 177:   void setString(int index, String value) throws SQLException;
 178: 
 179:   /**
 180:    * This method sets the specified parameter from the given Java
 181:    * <code>byte</code> array value.
 182:    *
 183:    * @param index The index of the parameter value to set.
 184:    * @param value The value of the parameter.
 185:    * @exception SQLException If an error occurs.
 186:    */
 187:   void setBytes(int index, byte[] value) throws SQLException;
 188: 
 189:   /**
 190:    * This method sets the specified parameter from the given Java
 191:    * <code>java.sql.Date</code> value.
 192:    *
 193:    * @param index The index of the parameter value to set.
 194:    * @param value The value of the parameter.
 195:    * @exception SQLException If an error occurs.
 196:    */
 197:   void setDate(int index, Date value) throws SQLException;
 198: 
 199:   /**
 200:    * This method sets the specified parameter from the given Java
 201:    * <code>java.sql.Time</code> value.
 202:    *
 203:    * @param index The index of the parameter value to set.
 204:    * @param value The value of the parameter.
 205:    * @exception SQLException If an error occurs.
 206:    */
 207:   void setTime(int index, Time value) throws SQLException;
 208: 
 209:   /**
 210:    * This method sets the specified parameter from the given Java
 211:    * <code>java.sql.Timestamp</code> value.
 212:    *
 213:    * @param index The index of the parameter value to set.
 214:    * @param value The value of the parameter.
 215:    * @exception SQLException If an error occurs.
 216:    */
 217:   void setTimestamp(int index, Timestamp value)
 218:     throws SQLException;
 219: 
 220:   /**
 221:    * This method sets the specified parameter from the given Java
 222:    * ASCII <code>InputStream</code> value.
 223:    *
 224:    * @param index The index of the parameter value to set.
 225:    * @param stream The stream from which the parameter value is read.
 226:    * @param count The number of bytes in the stream.
 227:    * @exception SQLException If an error occurs.
 228:    */
 229:   void setAsciiStream(int index, InputStream stream, int count)
 230:     throws SQLException;
 231: 
 232:   /**
 233:    * This method sets the specified parameter from the given Java
 234:    * Unicode UTF-8 <code>InputStream</code> value.
 235:    *
 236:    * @param index The index of the parameter value to set.
 237:    * @param stream The stream from which the parameter value is read.
 238:    * @param count The number of bytes in the stream.
 239:    * @exception SQLException If an error occurs.
 240:    * @deprecated
 241:    */
 242:   void setUnicodeStream(int index, InputStream stream, int count)
 243:     throws SQLException;
 244: 
 245:   /**
 246:    * This method sets the specified parameter from the given Java
 247:    * binary <code>InputStream</code> value.
 248:    *
 249:    * @param index The index of the parameter value to set.
 250:    * @param stream The stream from which the parameter value is read.
 251:    * @param count The number of bytes in the stream.
 252:    * @exception SQLException If an error occurs.
 253:    */
 254:   void setBinaryStream(int index, InputStream stream, int count)
 255:     throws SQLException;
 256: 
 257:   /**
 258:    * This method clears all of the input parameter that have been
 259:    * set on this statement.
 260:    *
 261:    * @exception SQLException If an error occurs.
 262:    */
 263:   void clearParameters() throws SQLException;
 264: 
 265:   /**
 266:    * This method sets the specified parameter from the given Java
 267:    * <code>Object</code> value.  The specified SQL object type will be used.
 268:    *
 269:    * @param index The index of the parameter value to set.
 270:    * @param value The value of the parameter.
 271:    * @param sqlType The SQL type to use for the parameter, from 
 272:    *                <code>Types</code>
 273:    * @param scale The scale of the value, for numeric values only.
 274:    * @exception SQLException If an error occurs.
 275:    * @see Types
 276:    */
 277:   void setObject(int index, Object value, int sqlType, int scale)
 278:     throws SQLException;
 279: 
 280:   /**
 281:    * This method sets the specified parameter from the given Java
 282:    * <code>Object</code> value.  The specified SQL object type will be used.
 283:    *
 284:    * @param index The index of the parameter value to set.
 285:    * @param value The value of the parameter.
 286:    * @param sqlType The SQL type to use for the parameter, from 
 287:    *                      <code>Types</code>
 288:    * @exception SQLException If an error occurs.
 289:    * @see Types
 290:    */
 291:   void setObject(int index, Object value, int sqlType)
 292:     throws SQLException;
 293: 
 294:   /**
 295:    * This method sets the specified parameter from the given Java
 296:    * <code>Object</code> value.  The default object type to SQL type mapping
 297:    * will be used.
 298:    *
 299:    * @param index The index of the parameter value to set.
 300:    * @param value The value of the parameter.
 301:    * @exception SQLException If an error occurs.
 302:    */
 303:   void setObject(int index, Object value) throws SQLException;
 304: 
 305:   /**
 306:    * This method executes a prepared SQL query.
 307:    * Some prepared statements return multiple results; the execute method
 308:    * handles these complex statements as well as the simpler form of
 309:    * statements handled by executeQuery and executeUpdate.
 310:    *
 311:    * @return The result of the SQL statement.
 312:    * @exception SQLException If an error occurs.
 313:    */
 314:   boolean execute() throws SQLException;
 315: 
 316:   /**
 317:    * This method adds a set of parameters to the batch for JDBC 2.0.
 318:    * @exception SQLException If an error occurs.
 319:    */
 320:   void addBatch() throws SQLException;
 321: 
 322:   /**
 323:    * This method sets the specified parameter from the given Java
 324:    * character <code>Reader</code> value.
 325:    *
 326:    * @param index The index of the parameter value to set.
 327:    * @param reader The reader from which the parameter value is read.
 328:    * @param count The number of characters in the stream.
 329:    * @exception SQLException If an error occurs.
 330:    */
 331:   void setCharacterStream(int index, Reader reader, int count)
 332:   throws SQLException;
 333: 
 334:   /**
 335:    * This method sets the specified parameter from the given Java
 336:    * <code>Ref</code> value.  The default object type to SQL type mapping
 337:    * will be used.
 338:    *
 339:    * @param index The index of the parameter value to set.
 340:    * @param value The <code>Ref</code> used to set the value of the parameter.
 341:    * @exception SQLException If an error occurs.
 342:    */
 343:   void setRef(int index, Ref value) throws SQLException;
 344: 
 345:   /**
 346:    * This method sets the specified parameter from the given Java
 347:    * <code>Blob</code> value.  The default object type to SQL type mapping
 348:    * will be used.
 349:    *
 350:    * @param index The index of the parameter value to set.
 351:    * @param value The <code>Blob</code> used to set the 
 352:    *             value of the parameter.
 353:    * @exception SQLException If an error occurs.
 354:    */
 355:   void setBlob(int index, Blob value) throws SQLException;
 356: 
 357:   /**
 358:    * This method sets the specified parameter from the given Java
 359:    * <code>Clob</code> value.  The default object type to SQL type mapping
 360:    * will be used.
 361:    *
 362:    * @param index The index of the parameter value to set.
 363:    * @param value The <code>Clob</code> used to set the
 364:    *              value of the parameter.
 365:    * @exception SQLException If an error occurs.
 366:    */
 367:   void setClob(int index, Clob value) throws SQLException;
 368: 
 369:   /**
 370:    * This method sets the specified parameter from the given Java
 371:    * <code>Array</code> value.  The default object type to SQL type mapping
 372:    * will be used.
 373:    *
 374:    * @param index The index of the parameter value to set.
 375:    * @param value The value of the parameter.
 376:    * @exception SQLException If an error occurs.
 377:    */
 378:   void setArray(int index, Array value) throws SQLException;
 379: 
 380:   /**
 381:    * This method returns meta data for the result set from this statement.
 382:    *
 383:    * @return Meta data for the result set from this statement.
 384:    * @exception SQLException If an error occurs.
 385:    */
 386:   ResultSetMetaData getMetaData() throws SQLException;
 387: 
 388:   /**
 389:    * This method sets the specified parameter from the given Java
 390:    * <code>java.sql.Date</code> value.
 391:    *
 392:    * @param index The index of the parameter value to set.
 393:    * @param value The value of the parameter.
 394:    * @param cal The <code>Calendar</code> to use for timezone and locale.
 395:    * @exception SQLException If an error occurs.
 396:    */
 397:   void setDate(int index, Date value, Calendar cal)
 398:     throws SQLException;
 399: 
 400:   /**
 401:    * This method sets the specified parameter from the given Java
 402:    * <code>java.sql.Time</code> value.
 403:    *
 404:    * @param index The index of the parameter value to set.
 405:    * @param value The value of the parameter.
 406:    * @param cal The <code>Calendar</code> to use for timezone and locale.
 407:    * @exception SQLException If an error occurs.
 408:    */
 409:   void setTime(int index, Time value, Calendar cal)
 410:     throws SQLException;
 411: 
 412:   /**
 413:    * This method sets the specified parameter from the given Java
 414:    * <code>java.sql.Timestamp</code> value.
 415:    *
 416:    * @param index The index of the parameter value to set.
 417:    * @param value The value of the parameter.
 418:    * @param cal The <code>Calendar</code> to use for timezone and locale.
 419:    * @exception SQLException If an error occurs.
 420:    */
 421:   void setTimestamp(int index, Timestamp value, Calendar cal)
 422:     throws SQLException;
 423: 
 424:   /**
 425:    * This method populates the specified parameter with a SQL NULL value
 426:    * for the specified type.
 427:    *
 428:    * @param index The index of the parameter to set.
 429:    * @param sqlType The SQL type identifier of the parameter from
 430:    *                <code>Types</code>
 431:    * @param typeName The name of the data type, for user defined types.
 432:    * @exception SQLException If an error occurs.
 433:    */
 434:   void setNull(int index, int sqlType, String typeName)
 435:     throws SQLException;
 436: 
 437:   /**
 438:    * This method sets the specified parameter from the given Java
 439:    * <code>java.net.URL</code> value.
 440:    * 
 441:    * @param index The index of the parameter to set.
 442:    * @param value The value of the parameter.
 443:    * @exception SQLException If an error occurs.
 444:    * @since 1.4
 445:    */
 446:   void setURL(int index, URL value) throws SQLException;
 447: 
 448:   /**
 449:    * Returns information about the parameters set on this 
 450:    * <code>PreparedStatement</code> (see {@link ParameterMetaData} for a
 451:    * detailed description of the provided information).
 452:    * 
 453:    * @return Meta data for the parameters of this statement.
 454:    * @see ParameterMetaData
 455:    * @since 1.4
 456:    */
 457:   ParameterMetaData getParameterMetaData() throws SQLException;
 458: }