home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / main.bin / Statement.java < prev    next >
Text File  |  1997-05-20  |  11KB  |  273 lines
  1. /*
  2.  * @(#)Statement.java    1.6 97/02/11
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.sql;
  24.  
  25. /**
  26.  * <P>A Statement object is used for executing a static SQL statement
  27.  * and obtaining the results produced by it. 
  28.  *
  29.  * <P>Only one ResultSet per Statement can be open at any point in
  30.  * time. Therefore, if the reading of one ResultSet is interleaved
  31.  * with the reading of another, each must have been generated by
  32.  * different Statements. All statement execute methods implicitly
  33.  * close a statment's current ResultSet if an open one exists.
  34.  *
  35.  * @see Connection#createStatement
  36.  * @see ResultSet 
  37.  */
  38. public interface Statement {
  39.  
  40.     /**
  41.      * Execute a SQL statement that returns a single ResultSet.
  42.      *
  43.      * @param sql typically this is a static SQL SELECT statement
  44.      * @return a ResultSet that contains the data produced by the
  45.      * query; never null 
  46.      * @exception SQLException if a database-access error occurs.
  47.      */
  48.     ResultSet executeQuery(String sql) throws SQLException;
  49.  
  50.     /**
  51.      * Execute a SQL INSERT, UPDATE or DELETE statement. In addition,
  52.      * SQL statements that return nothing such as SQL DDL statements
  53.      * can be executed.
  54.      *
  55.      * @param sql a SQL INSERT, UPDATE or DELETE statement or a SQL
  56.      * statement that returns nothing
  57.      * @return either the row count for INSERT, UPDATE or DELETE or 0
  58.      * for SQL statements that return nothing
  59.      * @exception SQLException if a database-access error occurs.
  60.      */
  61.     int executeUpdate(String sql) throws SQLException;
  62.  
  63.     /**
  64.      * In many cases, it is desirable to immediately release a
  65.      * Statements's database and JDBC resources instead of waiting for
  66.      * this to happen when it is automatically closed; the close
  67.      * method provides this immediate release.
  68.      *
  69.      * <P><B>Note:</B> A Statement is automatically closed when it is
  70.      * garbage collected. When a Statement is closed, its current
  71.      * ResultSet, if one exists, is also closed.  
  72.      *
  73.      * @exception SQLException if a database-access error occurs.
  74.      */
  75.     void close() throws SQLException;
  76.  
  77.     //----------------------------------------------------------------------
  78.  
  79.     /**
  80.      * The maxFieldSize limit (in bytes) is the maximum amount of data
  81.      * returned for any column value; it only applies to BINARY,
  82.      * VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR
  83.      * columns.  If the limit is exceeded, the excess data is silently
  84.      * discarded.
  85.      *
  86.      * @return the current max column size limit; zero means unlimited 
  87.      * @exception SQLException if a database-access error occurs.
  88.      */
  89.     int getMaxFieldSize() throws SQLException;
  90.     
  91.     /**
  92.      * The maxFieldSize limit (in bytes) is set to limit the size of
  93.      * data that can be returned for any column value; it only applies
  94.      * to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and
  95.      * LONGVARCHAR fields.  If the limit is exceeded, the excess data
  96.      * is silently discarded. For maximum portability use values
  97.      * greater than 256.
  98.      *
  99.      * @param max the new max column size limit; zero means unlimited 
  100.      * @exception SQLException if a database-access error occurs.
  101.      */
  102.     void setMaxFieldSize(int max) throws SQLException;
  103.  
  104.     /**
  105.      * The maxRows limit is the maximum number of rows that a
  106.      * ResultSet can contain.  If the limit is exceeded, the excess
  107.      * rows are silently dropped.
  108.      *
  109.      * @return the current max row limit; zero means unlimited
  110.      * @exception SQLException if a database-access error occurs.
  111.      */
  112.     int getMaxRows() throws SQLException;
  113.  
  114.     /**
  115.      * The maxRows limit is set to limit the number of rows that any
  116.      * ResultSet can contain.  If the limit is exceeded, the excess
  117.      * rows are silently dropped.
  118.      *
  119.      * @param max the new max rows limit; zero means unlimited 
  120.      * @exception SQLException if a database-access error occurs.
  121.      */
  122.     void setMaxRows(int max) throws SQLException;
  123.  
  124.     /**
  125.      * If escape scanning is on (the default), the driver will do
  126.      * escape substitution before sending the SQL to the database.
  127.      *
  128.      * Note: Since prepared statements have usually been parsed prior
  129.      * to making this call, disabling escape processing for prepared
  130.      * statements will like have no affect.
  131.      *
  132.      * @param enable true to enable; false to disable
  133.      * @exception SQLException if a database-access error occurs.
  134.      */
  135.     void setEscapeProcessing(boolean enable) throws SQLException;
  136.  
  137.     /**
  138.      * The queryTimeout limit is the number of seconds the driver will
  139.      * wait for a Statement to execute. If the limit is exceeded, a
  140.      * SQLException is thrown.
  141.      *
  142.      * @return the current query timeout limit in seconds; zero means unlimited 
  143.      * @exception SQLException if a database-access error occurs.
  144.      */
  145.     int getQueryTimeout() throws SQLException;
  146.  
  147.     /**
  148.      * The queryTimeout limit is the number of seconds the driver will
  149.      * wait for a Statement to execute. If the limit is exceeded, a
  150.      * SQLException is thrown.
  151.      *
  152.      * @param seconds the new query timeout limit in seconds; zero means unlimited 
  153.      * @exception SQLException if a database-access error occurs.
  154.      */
  155.     void setQueryTimeout(int seconds) throws SQLException;
  156.  
  157.     /**
  158.      * Cancel can be used by one thread to cancel a statement that
  159.      * is being executed by another thread.
  160.      *
  161.      * @exception SQLException if a database-access error occurs.
  162.      */
  163.     void cancel() throws SQLException;
  164.  
  165.     /**
  166.      * The first warning reported by calls on this Statement is
  167.      * returned.  A Statment's execute methods clear its SQLWarning
  168.      * chain. Subsequent Statement warnings will be chained to this
  169.      * SQLWarning.
  170.      *
  171.      * <p>The warning chain is automatically cleared each time
  172.      * a statement is (re)executed.
  173.      *
  174.      * <P><B>Note:</B> If you are processing a ResultSet then any
  175.      * warnings associated with ResultSet reads will be chained on the
  176.      * ResultSet object.
  177.      *
  178.      * @return the first SQLWarning or null 
  179.      * @exception SQLException if a database-access error occurs.
  180.      */
  181.     SQLWarning getWarnings() throws SQLException;
  182.  
  183.     /**
  184.      * After this call, getWarnings returns null until a new warning is
  185.      * reported for this Statement.  
  186.      *
  187.      * @exception SQLException if a database-access error occurs.
  188.      */
  189.     void clearWarnings() throws SQLException;
  190.  
  191.     /**
  192.      * setCursorname defines the SQL cursor name that will be used by
  193.      * subsequent Statement execute methods. This name can then be
  194.      * used in SQL positioned update/delete statements to identify the
  195.      * current row in the ResultSet generated by this statement.  If
  196.      * the database doesn't support positioned update/delete, this
  197.      * method is a noop.
  198.      *
  199.      * <P><B>Note:</B> By definition, positioned update/delete
  200.      * execution must be done by a different Statement than the one
  201.      * which generated the ResultSet being used for positioning. Also,
  202.      * cursor names must be unique within a Connection.
  203.      *
  204.      * @param name the new cursor name.  
  205.      * @exception SQLException if a database-access error occurs.
  206.      */
  207.     void setCursorName(String name) throws SQLException;
  208.     
  209.     //----------------------- Multiple Results --------------------------
  210.  
  211.     /**
  212.      * Execute a SQL statement that may return multiple results.
  213.      * Under some (uncommon) situations a single SQL statement may return
  214.      * multiple result sets and/or update counts.  Normally you can ignore
  215.      * this, unless you're executing a stored procedure that you know may
  216.      * return multiple results, or unless you're dynamically executing an
  217.      * unknown SQL string.  The "execute", "getMoreResults", "getResultSet"
  218.      * and "getUpdateCount" methods let you navigate through multiple results.
  219.      *
  220.      * The "execute" method executes a SQL statement and indicates the
  221.      * form of the first result.  You can then use getResultSet or
  222.      * getUpdateCount to retrieve the result, and getMoreResults to
  223.      * move to any subsequent result(s).
  224.      *
  225.      * @param sql any SQL statement
  226.      * @return true if the next result is a ResultSet; false if it is
  227.      * an update count or there are no more results
  228.      * @exception SQLException if a database-access error occurs.
  229.      * @see #getResultSet
  230.      * @see #getUpdateCount
  231.      * @see #getMoreResults 
  232.      */
  233.     boolean execute(String sql) throws SQLException;
  234.     
  235.     /**
  236.      *  getResultSet returns the current result as a ResultSet.  It
  237.      *  should only be called once per result.
  238.      *
  239.      * @return the current result as a ResultSet; null if the result
  240.      * is an update count or there are no more results
  241.      * @exception SQLException if a database-access error occurs.
  242.      * @see #execute 
  243.      */
  244.     ResultSet getResultSet() throws SQLException; 
  245.  
  246.     /**
  247.      *  getUpdateCount returns the current result as an update count;
  248.      *  if the result is a ResultSet or there are no more results, -1
  249.      *  is returned.  It should only be called once per result.
  250.      * 
  251.      * @return the current result as an update count; -1 if it is a
  252.      * ResultSet or there are no more results
  253.      * @exception SQLException if a database-access error occurs.
  254.      * @see #execute 
  255.      */
  256.     int getUpdateCount() throws SQLException; 
  257.  
  258.     /**
  259.      * getMoreResults moves to a Statement's next result.  It returns true if 
  260.      * this result is a ResultSet.  getMoreResults also implicitly
  261.      * closes any current ResultSet obtained with getResultSet.
  262.      *
  263.      * There are no more results when (!getMoreResults() &&
  264.      * (getUpdateCount() == -1)
  265.      *
  266.      * @return true if the next result is a ResultSet; false if it is
  267.      * an update count or there are no more results
  268.      * @exception SQLException if a database-access error occurs.
  269.      * @see #execute 
  270.      */
  271.     boolean getMoreResults() throws SQLException; 
  272. }    
  273.