Source for java.sql.Statement

   1: /* Statement.java -- Interface for executing SQL statements.
   2:    Copyright (C) 1999, 2000, 2002, 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: 
  39: package java.sql;
  40: 
  41: /**
  42:  * This interface provides a mechanism for executing SQL statements.
  43:  *
  44:  * @author Aaron M. Renn (arenn@urbanophile.com)
  45:  */
  46: public interface Statement 
  47: {
  48:   int CLOSE_CURRENT_RESULT = 1;
  49:   int KEEP_CURRENT_RESULT = 2;
  50:   int CLOSE_ALL_RESULTS = 3;
  51:   int SUCCESS_NO_INFO = -2;
  52:   int EXECUTE_FAILED = -3;
  53:   int RETURN_GENERATED_KEYS = 1;
  54:   int NO_GENERATED_KEYS = 2;
  55: 
  56:   /**
  57:    * This method executes the specified SQL SELECT statement and returns a
  58:    * (possibly empty) <code>ResultSet</code> with the results of the query.
  59:    *
  60:    * @param sql The SQL statement to execute.
  61:    * @return The result set of the SQL statement.
  62:    * @exception SQLException If an error occurs.
  63:    */
  64:   ResultSet executeQuery(String sql) throws SQLException;
  65: 
  66:   /**
  67:    * This method executes the specified SQL INSERT, UPDATE, or DELETE statement
  68:    * and returns the number of rows affected, which may be 0.
  69:    * 
  70:    * @param sql The SQL statement to execute.
  71:    * @return The number of rows affected by the SQL statement.
  72:    * @exception SQLException If an error occurs.
  73:    */
  74:   int executeUpdate(String sql) throws SQLException;
  75: 
  76:   /**
  77:    * This method closes the statement and frees any associated resources.
  78:    *
  79:    * @exception SQLException If an error occurs.
  80:    */
  81:   void close() throws SQLException;
  82: 
  83:   /**
  84:    * This method returns the maximum length of any column value in bytes.
  85:    *
  86:    * @return The maximum length of any column value in bytes.
  87:    * @exception SQLException If an error occurs.
  88:    */
  89:   int getMaxFieldSize() throws SQLException;
  90: 
  91:   /**
  92:    * This method sets the limit for the maximum length of any column in bytes.
  93:    *
  94:    * @param maxSize The new maximum length of any column in bytes.
  95:    * @exception SQLException If an error occurs.
  96:    */
  97:   void setMaxFieldSize(int maxSize) throws SQLException;
  98: 
  99:   /**
 100:    * This method returns the maximum possible number of rows in a result set.
 101:    *
 102:    * @return The maximum possible number of rows in a result set.
 103:    * @exception SQLException If an error occurs.
 104:    */
 105:   int getMaxRows() throws SQLException;
 106: 
 107:   /**
 108:    * This method sets the maximum number of rows that can be present in a
 109:    * result set.
 110:    *
 111:    * @param maxRows The maximum possible number of rows in a result set.
 112:    * @exception SQLException If an error occurs.
 113:    */
 114:   void setMaxRows(int maxRows) throws SQLException;
 115: 
 116:   /**
 117:    * This method sets the local escape processing mode on or off.  The
 118:    * default value is on.
 119:    *
 120:    * @param escape <code>true</code> to enable local escape processing, 
 121:    *               <code>false</code> to disable it.
 122:    * @exception SQLException If an error occurs.
 123:    */
 124:   void setEscapeProcessing(boolean escape) throws SQLException;
 125: 
 126:   /**
 127:    * The method returns the number of seconds a statement may be in process
 128:    * before timing out.  A value of 0 means there is no timeout.
 129:    *
 130:    * @return The SQL statement timeout in seconds.
 131:    * @exception SQLException If an error occurs.
 132:    */
 133:   int getQueryTimeout() throws SQLException;
 134: 
 135:   /**
 136:    * This method sets the number of seconds a statement may be in process
 137:    * before timing out.  A value of 0 means there is no timeout.
 138:    *
 139:    * @param seconds The new SQL statement timeout value.
 140:    * @exception SQLException If an error occurs.
 141:    */
 142:   void setQueryTimeout(int seconds) throws SQLException;
 143: 
 144:   /**
 145:    * This method cancels an outstanding statement, if the database supports
 146:    * that operation.
 147:    *
 148:    * @exception SQLException If an error occurs.
 149:    */
 150:   void cancel() throws SQLException;
 151: 
 152:   /**
 153:    * This method returns the first SQL warning attached to this statement.
 154:    * Subsequent warnings will be chained to this one.
 155:    *
 156:    * @return The first SQL warning for this statement.
 157:    * @exception SQLException If an error occurs.
 158:    */
 159:   SQLWarning getWarnings() throws SQLException;
 160: 
 161:   /**
 162:    * This method clears any SQL warnings that have been attached to this
 163:    * statement.
 164:    *
 165:    * @exception SQLException If an error occurs.
 166:    */
 167:   void clearWarnings() throws SQLException;
 168: 
 169:   /**
 170:    * This method sets the cursor name that will be used by the result set.
 171:    *
 172:    * @param name The cursor name to use for this statement.
 173:    * @exception SQLException If an error occurs.
 174:    */
 175:   void setCursorName(String name) throws SQLException;
 176: 
 177:   /**
 178:    * This method executes an arbitrary SQL statement of any time.  The
 179:    * methods <code>getResultSet</code>, <code>getMoreResults</code> and
 180:    * <code>getUpdateCount</code> retrieve the results.
 181:    *
 182:    * @return <code>true</code> if a result set was returned, <code>false</code>
 183:    *         if an update count was returned.
 184:    * @exception SQLException If an error occurs.
 185:    */
 186:   boolean execute(String sql) throws SQLException;
 187: 
 188:   /**
 189:    * This method returns the result set of the SQL statement that was
 190:    * executed.  This should be called only once per result set returned.
 191:    *
 192:    * @return The result set of the query, or <code>null</code> if there was
 193:    *         no result set (for example, if the statement was an UPDATE).
 194:    * @exception SQLException If an error occurs.
 195:    * @see #execute(String)
 196:    * @see #execute(String, int)
 197:    * @see #execute(String, int[])
 198:    * @see #execute(String, String[])
 199:    */
 200:   ResultSet getResultSet() throws SQLException;
 201: 
 202:   /**
 203:    * This method returns the update count of the SQL statement that was
 204:    * executed.  This should be called only once per executed SQL statement.
 205:    *
 206:    * @return The update count of the query, or -1 if there was no update
 207:    *         count (for example, if the statement was a SELECT).
 208:    * @exception SQLException If an error occurs.
 209:    * @see #execute(String)
 210:    * @see #execute(String, int)
 211:    * @see #execute(String, int[])
 212:    * @see #execute(String, String[])
 213:    */
 214:   int getUpdateCount() throws SQLException;
 215: 
 216:   /**
 217:    * This method advances the result set pointer to the next result set, 
 218:    * which can then be retrieved using <code>getResultSet</code>
 219:    *
 220:    * @return <code>true</code> if there is another result set, 
 221:    *         <code>false</code> otherwise (for example, the next result is an
 222:    *         update count).
 223:    * @exception SQLException If an error occurs.
 224:    * @see #execute(String)
 225:    * @see #execute(String, int)
 226:    * @see #execute(String, int[])
 227:    * @see #execute(String, String[])
 228:    */
 229:   boolean getMoreResults() throws SQLException;
 230: 
 231:   /**
 232:    * This method informs the driver which direction the result set will
 233:    * be accessed in.
 234:    *
 235:    * @param direction The direction the result set will be accessed in (?????)
 236:    * @exception SQLException If an error occurs.
 237:    */
 238:   void setFetchDirection(int direction) throws SQLException;
 239: 
 240:   /**
 241:    * This method returns the current direction that the driver thinks the
 242:    * result set will be accessed int.
 243:    *
 244:    * @return The direction the result set will be accessed in (????)
 245:    * @exception SQLException If an error occurs.
 246:    */
 247:   int getFetchDirection() throws SQLException;
 248: 
 249:   /**
 250:    * This method informs the driver how many rows it should fetch from the
 251:    * database at a time.
 252:    *
 253:    * @param numRows The number of rows the driver should fetch at a time
 254:    *                to populate the result set.
 255:    * @exception SQLException If an error occurs.
 256:    */
 257:   void setFetchSize(int numRows) throws SQLException;
 258: 
 259:   /**
 260:    * This method returns the number of rows the driver believes should be
 261:    * fetched from the database at a time.
 262:    *
 263:    * @return The number of rows that will be fetched from the database at a time.
 264:    * @exception SQLException If an error occurs.
 265:    */
 266:   int getFetchSize() throws SQLException;
 267: 
 268:   /**
 269:    * This method returns the concurrency type of the result set for this
 270:    * statement. This will be one of the concurrency types defined in
 271:    * <code>ResultSet</code>.
 272:    *
 273:    * @return The concurrency type of the result set for this statement.
 274:    * @exception SQLException If an error occurs.
 275:    * @see ResultSet
 276:    */
 277:   int getResultSetConcurrency() throws SQLException;
 278: 
 279:   /**
 280:    * This method returns the result set type for this statement.  This will
 281:    * be one of the result set types defined in <code>ResultSet</code>.
 282:    *
 283:    * @return The result set type for this statement.
 284:    * @exception SQLException If an error occurs.
 285:    * @see ResultSet
 286:    */
 287:   int getResultSetType() throws SQLException;
 288: 
 289:   /**
 290:    * This method adds a SQL statement to a SQL batch.  A driver is not
 291:    * required to implement this method.
 292:    *
 293:    * @param sql The sql statement to add to the batch.
 294:    * @exception SQLException If an error occurs.
 295:    */
 296:   void addBatch(String sql) throws SQLException;
 297: 
 298:   /**
 299:    * This method clears out any SQL statements that have been populated in
 300:    * the current batch.  A driver is not required to implement this method.
 301:    *
 302:    * @exception SQLException If an error occurs.
 303:    */
 304:   void clearBatch() throws SQLException;
 305: 
 306:   /**
 307:    * This method executes the SQL batch and returns an array of update
 308:    * counts - one for each SQL statement in the batch - ordered in the same
 309:    * order the statements were added to the batch.  A driver is not required
 310:    * to implement this method.
 311:    *
 312:    * @return An array of update counts for this batch.
 313:    * @exception SQLException If an error occurs.
 314:    */
 315:   int[] executeBatch() throws SQLException;
 316: 
 317:   /**
 318:    * This method returns the <code>Connection</code> instance that was
 319:    * used to create this object.
 320:    *
 321:    * @return The connection used to create this object.
 322:    * @exception SQLException If an error occurs.
 323:    */
 324:   Connection getConnection() throws SQLException;
 325: 
 326:   /**
 327:    * @since 1.4
 328:    */
 329:   boolean getMoreResults(int current) throws SQLException;
 330: 
 331:   /**
 332:    * @since 1.4
 333:    */
 334:   ResultSet getGeneratedKeys() throws SQLException;
 335: 
 336:   /**
 337:    * @since 1.4
 338:    */
 339:   int executeUpdate(String sql, int autoGeneratedKeys)
 340:     throws SQLException;
 341: 
 342:   /**
 343:    * @since 1.4
 344:    */
 345:   int executeUpdate(String sql, int[] columnIndexes)
 346:     throws SQLException;
 347: 
 348:   /**
 349:    * @since 1.4
 350:    */
 351:   int executeUpdate(String sql, String[] columnNames)
 352:     throws SQLException;
 353: 
 354:   /**
 355:    * @since 1.4
 356:    */
 357:   boolean execute(String sql, int autoGeneratedKeys)
 358:     throws SQLException;
 359: 
 360:   /**
 361:    * @since 1.4
 362:    */
 363:   boolean execute(String sql, int[] columnIndexes) throws SQLException;
 364: 
 365:   /**
 366:    * @since 1.4
 367:    */
 368:   boolean execute(String sql, String[] columnNames)
 369:     throws SQLException;
 370: 
 371:   /**
 372:    * @since 1.4
 373:    */
 374:   int getResultSetHoldability() throws SQLException;
 375: }