home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / main.bin / Connection.java < prev    next >
Text File  |  1997-05-20  |  12KB  |  315 lines
  1. /*
  2.  * @(#)Connection.java    1.5 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 Connection represents a session with a specific
  27.  * database. Within the context of a Connection, SQL statements are
  28.  * executed and results are returned.
  29.  *
  30.  * <P>A Connection's database is able to provide information
  31.  * describing its tables, its supported SQL grammar, its stored
  32.  * procedures, the capabilities of this connection, etc. This
  33.  * information is obtained with the getMetaData method.
  34.  *
  35.  * <P><B>Note:</B> By default the Connection automatically commits
  36.  * changes after executing each statement. If auto commit has been
  37.  * disabled, an explicit commit must be done or database changes will
  38.  * not be saved.
  39.  *
  40.  * @see DriverManager#getConnection
  41.  * @see Statement 
  42.  * @see ResultSet
  43.  * @see DatabaseMetaData
  44.  */
  45. public interface Connection {
  46.  
  47.     /**
  48.      * SQL statements without parameters are normally
  49.      * executed using Statement objects. If the same SQL statement 
  50.      * is executed many times, it is more efficient to use a 
  51.      * PreparedStatement
  52.      *
  53.      * @return a new Statement object 
  54.      * @exception SQLException if a database-access error occurs.
  55.      */
  56.     Statement createStatement() throws SQLException;
  57.  
  58.     /**
  59.      * A SQL statement with or without IN parameters can be
  60.      * pre-compiled and stored in a PreparedStatement object. This
  61.      * object can then be used to efficiently execute this statement
  62.      * multiple times.
  63.      *
  64.      * <P><B>Note:</B> This method is optimized for handling
  65.      * parametric SQL statements that benefit from precompilation. If
  66.      * the driver supports precompilation, prepareStatement will send
  67.      * the statement to the database for precompilation. Some drivers
  68.      * may not support precompilation. In this case, the statement may
  69.      * not be sent to the database until the PreparedStatement is
  70.      * executed.  This has no direct affect on users; however, it does
  71.      * affect which method throws certain SQLExceptions.
  72.      *
  73.      * @param sql a SQL statement that may contain one or more '?' IN
  74.      * parameter placeholders
  75.      * @return a new PreparedStatement object containing the
  76.      * pre-compiled statement 
  77.      * @exception SQLException if a database-access error occurs.
  78.      */
  79.     PreparedStatement prepareStatement(String sql)
  80.         throws SQLException;
  81.  
  82.     /**
  83.      * A SQL stored procedure call statement is handled by creating a
  84.      * CallableStatement for it. The CallableStatement provides
  85.      * methods for setting up its IN and OUT parameters, and
  86.      * methods for executing it.
  87.      *
  88.      * <P><B>Note:</B> This method is optimized for handling stored
  89.      * procedure call statements. Some drivers may send the call
  90.      * statement to the database when the prepareCall is done; others
  91.      * may wait until the CallableStatement is executed. This has no
  92.      * direct affect on users; however, it does affect which method
  93.      * throws certain SQLExceptions.
  94.      *
  95.      * @param sql a SQL statement that may contain one or more '?'
  96.      * parameter placeholders. Typically this  statement is a JDBC
  97.      * function call escape string.
  98.      * @return a new CallableStatement object containing the
  99.      * pre-compiled SQL statement 
  100.      * @exception SQLException if a database-access error occurs.
  101.      */
  102.     CallableStatement prepareCall(String sql) throws SQLException;
  103.                         
  104.     /**
  105.      * A driver may convert the JDBC sql grammar into its system's
  106.      * native SQL grammar prior to sending it; nativeSQL returns the
  107.      * native form of the statement that the driver would have sent.
  108.      *
  109.      * @param sql a SQL statement that may contain one or more '?'
  110.      * parameter placeholders
  111.      * @return the native form of this statement
  112.      * @exception SQLException if a database-access error occurs.
  113.      */
  114.     String nativeSQL(String sql) throws SQLException;
  115.  
  116.     /**
  117.      * If a connection is in auto-commit mode, then all its SQL
  118.      * statements will be executed and committed as individual
  119.      * transactions.  Otherwise, its SQL statements are grouped into
  120.      * transactions that are terminated by either commit() or
  121.      * rollback().  By default, new connections are in auto-commit
  122.      * mode.
  123.      *
  124.      * The commit occurs when the statement completes or the next
  125.      * execute occurs, whichever comes first. In the case of
  126.      * statements returning a ResultSet, the statement completes when
  127.      * the last row of the ResultSet has been retrieved or the
  128.      * ResultSet has been closed. In advanced cases, a single
  129.      * statement may return multiple results as well as output
  130.      * parameter values. Here the commit occurs when all results and
  131.      * output param values have been retrieved.
  132.      *
  133.      * @param autoCommit true enables auto-commit; false disables
  134.      * auto-commit.  
  135.      * @exception SQLException if a database-access error occurs.
  136.      */
  137.     void setAutoCommit(boolean autoCommit) throws SQLException;
  138.  
  139.     /**
  140.      * Get the current auto-commit state.
  141.      *
  142.      * @return Current state of auto-commit mode.
  143.      * @exception SQLException if a database-access error occurs.
  144.      * @see #setAutoCommit 
  145.      */
  146.     boolean getAutoCommit() throws SQLException;
  147.  
  148.     /**
  149.      * Commit makes all changes made since the previous
  150.      * commit/rollback permanent and releases any database locks
  151.      * currently held by the Connection. This method should only be
  152.      * used when auto commit has been disabled.
  153.      *
  154.      * @exception SQLException if a database-access error occurs.
  155.      * @see #setAutoCommit 
  156.      */
  157.     void commit() throws SQLException;
  158.  
  159.     /**
  160.      * Rollback drops all changes made since the previous
  161.      * commit/rollback and releases any database locks currently held
  162.      * by the Connection. This method should only be used when auto
  163.      * commit has been disabled.
  164.      *
  165.      * @exception SQLException if a database-access error occurs.
  166.      * @see #setAutoCommit 
  167.      */
  168.     void rollback() throws SQLException;
  169.  
  170.     /**
  171.      * In some cases, it is desirable to immediately release a
  172.      * Connection's database and JDBC resources instead of waiting for
  173.      * them to be automatically released; the close method provides this
  174.      * immediate release. 
  175.      *
  176.      * <P><B>Note:</B> A Connection is automatically closed when it is
  177.      * garbage collected. Certain fatal errors also result in a closed
  178.      * Connection.
  179.      *
  180.      * @exception SQLException if a database-access error occurs.
  181.      */
  182.     void close() throws SQLException;;
  183.  
  184.     /**
  185.      * Tests to see if a Connection is closed.
  186.      *
  187.      * @return true if the connection is closed; false if it's still open
  188.      * @exception SQLException if a database-access error occurs.
  189.      */
  190.     boolean isClosed() throws SQLException;;
  191.  
  192.     //======================================================================
  193.     // Advanced features:
  194.  
  195.     /**
  196.      * A Connection's database is able to provide information
  197.      * describing its tables, its supported SQL grammar, its stored
  198.      * procedures, the capabilities of this connection, etc. This
  199.      * information is made available through a DatabaseMetaData
  200.      * object.
  201.      *
  202.      * @return a DatabaseMetaData object for this Connection 
  203.      * @exception SQLException if a database-access error occurs.
  204.      */
  205.     DatabaseMetaData getMetaData() throws SQLException;;
  206.  
  207.     /**
  208.      * You can put a connection in read-only mode as a hint to enable 
  209.      * database optimizations.
  210.      *
  211.      * <P><B>Note:</B> setReadOnly cannot be called while in the
  212.      * middle of a transaction.
  213.      *
  214.      * @param readOnly true enables read-only mode; false disables
  215.      * read-only mode.  
  216.      * @exception SQLException if a database-access error occurs.
  217.      */
  218.     void setReadOnly(boolean readOnly) throws SQLException;
  219.  
  220.     /**
  221.      * Tests to see if the connection is in read-only mode.
  222.      *
  223.      * @return true if connection is read-only
  224.      * @exception SQLException if a database-access error occurs.
  225.      */
  226.     boolean isReadOnly() throws SQLException;
  227.  
  228.     /**
  229.      * A sub-space of this Connection's database may be selected by setting a
  230.      * catalog name. If the driver does not support catalogs it will
  231.      * silently ignore this request.
  232.      *
  233.      * @exception SQLException if a database-access error occurs.
  234.      */
  235.     void setCatalog(String catalog) throws SQLException;
  236.  
  237.     /**
  238.      * Return the Connection's current catalog name.
  239.      *
  240.      * @return the current catalog name or null
  241.      * @exception SQLException if a database-access error occurs.
  242.      */
  243.     String getCatalog() throws SQLException;
  244.  
  245.     /**
  246.      * Transactions are not supported. 
  247.      */
  248.     int TRANSACTION_NONE         = 0;
  249.  
  250.     /**
  251.      * Dirty reads, non-repeatable reads and phantom reads can occur.
  252.      */
  253.     int TRANSACTION_READ_UNCOMMITTED = 1;
  254.  
  255.     /**
  256.      * Dirty reads are prevented; non-repeatable reads and phantom
  257.      * reads can occur.
  258.      */
  259.     int TRANSACTION_READ_COMMITTED   = 2;
  260.  
  261.     /**
  262.      * Dirty reads and non-repeatable reads are prevented; phantom
  263.      * reads can occur.     
  264.      */
  265.     int TRANSACTION_REPEATABLE_READ  = 4;
  266.  
  267.     /**
  268.      * Dirty reads, non-repeatable reads and phantom reads are prevented.
  269.      */
  270.     int TRANSACTION_SERIALIZABLE     = 8;
  271.  
  272.     /**
  273.      * You can call this method to try to change the transaction
  274.      * isolation level using one of the TRANSACTION_* values.
  275.      *
  276.      * <P><B>Note:</B> setTransactionIsolation cannot be called while
  277.      * in the middle of a transaction.
  278.      *
  279.      * @param level one of the TRANSACTION_* isolation values with the
  280.      * exception of TRANSACTION_NONE; some databases may not support
  281.      * other values
  282.      * @exception SQLException if a database-access error occurs.
  283.      * @see DatabaseMetaData#supportsTransactionIsolationLevel 
  284.      */
  285.     void setTransactionIsolation(int level) throws SQLException;
  286.  
  287.     /**
  288.      * Get this Connection's current transaction isolation mode.
  289.      *
  290.      * @return the current TRANSACTION_* mode value
  291.      * @exception SQLException if a database-access error occurs.
  292.      */
  293.     int getTransactionIsolation() throws SQLException;
  294.  
  295.     /**
  296.      * The first warning reported by calls on this Connection is
  297.      * returned.  
  298.      *
  299.      * <P><B>Note:</B> Subsequent warnings will be chained to this
  300.      * SQLWarning.
  301.      *
  302.      * @return the first SQLWarning or null 
  303.      * @exception SQLException if a database-access error occurs.
  304.      */
  305.     SQLWarning getWarnings() throws SQLException;
  306.  
  307.     /**
  308.      * After this call, getWarnings returns null until a new warning is
  309.      * reported for this Connection.  
  310.      *
  311.      * @exception SQLException if a database-access error occurs.
  312.      */
  313.     void clearWarnings() throws SQLException;
  314. }
  315.