package org.okip.service.dbc.api;



/*
   Copyright (c) 2002 Massachusetts Institute of Technology

   This work, including any software, documents, or other related items
   (the "Work"), is being provided by the copyright holder(s) subject to
   the terms of the MIT OKI(TM) API Definition License. By obtaining,
   using and/or copying this Work, you agree that you have read,
   understand, and will comply with the following terms and conditions of
   the MIT OKI(TM) API Definition License:

   You may use, copy, and distribute unmodified versions of this Work for
   any purpose, without fee or royalty, provided that you include the
   following on ALL copies of the Work that you make or distribute:

    *  The full text of the MIT OKI(TM) API Definition License in a
       location viewable to users of the redistributed Work.

    *  Any pre-existing intellectual property disclaimers, notices, or
       terms and conditions. If none exist, a short notice similar to the
       following should be used within the body of any redistributed
       Work: "Copyright (c) 2002 Massachusetts Institute of Technology. All
       Rights Reserved."

   You may modify or create Derivatives of this Work only for your
   internal purposes. You shall not distribute or transfer any such
   Derivative of this Work to any location or any other third party. For
   purposes of this license, "Derivative" shall mean any derivative of
   the Work as defined in the United States Copyright Act of 1976, such
   as a translation or modification.

   THIS WORK PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE WORK
   OR THE USE OR OTHER DEALINGS IN THE WORK.

   The name and trademarks of copyright holder(s) and/or MIT may NOT be
   used in advertising or publicity pertaining to the Work without
   specific, written prior permission. Title to copyright in the Work and
   any associated documentation will at all times remain with the
   copyright holders.

*/

/*
 * $Source: /cvs/oki/tech/src/org/okip/service/dbc/api/Connection.java,v $
 */

/**
 * A connection (session) with a specific database. SQL statements are
 * executed and results are returned within the context of a
 * connection.
 * <p>
 * @see(java.sql.Connection)
 * <p>
 * Licensed under the {@link org.okip.service.ApiLicense MIT OKI&#153; API Definition License}.
 *
 * @version $Name:  $ / $Revision: 1.9 $ / $Date: 2002/08/30 19:28:46 $ */
public interface Connection
extends java.io.Serializable {

  /**
   * Clears all warnings reported for this
   * Connection object.
   *
   * @throws DbcException
   *
   */
  void clearWarnings()
  throws DbcException;

  /**
   * Releases this Connection object's database
   * and JDBC resources immediately instead of
   * waiting for them to be automatically released.
   *
   * @throws DbcException
   *
   */
  void close()
  throws DbcException;

  /**
   * Makes all changes made since the previous
   * commit/rollback permanent and releases any
   * database locks currently held by this
   * Connection object.
   *
   * @throws DbcException
   *
   */
  void commit()
  throws DbcException;

  /**
   * Creates a Statement object for sending
   * SQL statements to the database.
   *
   * @return Statement
   *
   * @throws DbcException
   *
   */
  Statement createStatement()
  throws DbcException;

  /**
   * Creates a Statement object that will
   * generate ResultSet objects with the
   * given type and concurrency.
   *
   * @param resultSetType
   * @param resultSetConcurrency
   *
   * @return Statement
   *
   * @throws DbcException
   *
   */
  Statement createStatement(int resultSetType, int resultSetConcurrency)
  throws DbcException;

  /**
   * Creates a Statement object that will
   * generate ResultSet objects with the
   * given type, concurrency, and holdability.
   *
   * @param resultSetType
   * @param resultSetConcurrency
   * @param resultSetHoldability
   *
   * @return Statement
   *
   * @throws DbcException
   *
   */
  Statement createStatement(int resultSetType, int resultSetConcurrency,
                            int resultSetHoldability)
  throws DbcException;

  /**
   * Retrieves the current auto-commit mode
   * for this Connection object.
   *
   * @return boolean
   *
   * @throws DbcException
   *
   */
  boolean getAutoCommit()
  throws DbcException;

  /**
   * Retrieves this Connection object's
   * current catalog name.
   *
   * @return catalog
   *
   * @throws DbcException
   *
   */
  String getCatalog()
  throws DbcException;

  /**
   * Retrieves the current holdability of
   * ResultSet objects created using this
   * Connection object.
   *
   * @return int
   *
   * @throws DbcException
   *
   */
  int getHoldability()
  throws DbcException;

  /**
   * Retrieves a DatabaseMetaData object that
   * contains metadata about the database to
   * which this Connection object represents
   * a connection.
   *
   * @return DatabaseMetaData
   *
   * @throws DbcException
   *
   */
  DatabaseMetaData getMetaData()
  throws DbcException;

  /**
   * Retrieves this Connection object's current
   * transaction isolation level.
   *
   * @return int
   *
   * @throws DbcException
   *
   */
  int getTransactionIsolation()
  throws DbcException;

  /**
   * Retrieves the Map object associated
   * with this Connection object.
   *
   * @return map
   *
   * @throws DbcException
   *
   */
  java.util.Map getTypeMap()
  throws DbcException;

  /**
   * Retrieves the first warning reported
   * by calls on this Connection object.
   *
   *
   * @return java.sql.SQLWarning
   *
   * @throws DbcException
   *
   */
  java.sql.SQLWarning getWarnings()
  throws DbcException;

  /**
   * Retrieves whether this Connection object
   * has been closed.
   *
   * @return boolean
   *
   * @throws DbcException
   *
   */
  boolean isClosed()
  throws DbcException;

  /**
   * Retrieves whether this Connection object
   * is in read-only mode.
   *
   * @return boolean
   *
   * @throws DbcException
   *
   */
  boolean isReadOnly()
  throws DbcException;

  /**
   * Converts the given SQL statement into
   * the system's native SQL grammar.
   *
   * @param sql
   *
   * @return String
   *
   * @throws DbcException
   *
   */
  String nativeSQL(String sql)
  throws DbcException;

  /**
   * Creates a CallableStatement object
   * for calling database stored procedures.
   *
   * @param sql
   *
   * @return CallableStatement
   *
   * @throws DbcException
   *
   */
  CallableStatement prepareCall(String sql)
  throws DbcException;

  /**
   * Creates a CallableStatement object that
   * will generate ResultSet objects with the
   * given type and concurrency.
   *
   * @param sql
   * @param resultSetType
   * @param resultSetConcurrency
   *
   * @return CallableStatement
   *
   * @throws DbcException
   *
   */
  CallableStatement prepareCall(String sql, int resultSetType,
                                int resultSetConcurrency)
  throws DbcException;

  /**
   * Creates a CallableStatement object that
   * will generate ResultSet objects with the
   * given type, concurrency and holdability.
   *
   * @param sql
   * @param resultSetType
   * @param resultSetConcurrency
   * @param resultSetHoldability
   *
   * @return CallableStatement
   *
   * @throws DbcException
   *
   */
  CallableStatement prepareCall(String sql, int resultSetType,
                                int resultSetConcurrency,
                                int resultSetHoldability)
  throws DbcException;

  /**
   * Creates a PreparedStatement object for sending
   * parameterized SQL statements to the database.
   *
   * @param sql
   *
   * @return PreparedStatement
   *
   * @throws DbcException
   *
   */
  PreparedStatement prepareStatement(String sql)
  throws DbcException;

  /**
   * Creates a default PreparedStatement object
   * that has the capability to retrieve
   * auto-generated keys.
   *
   * @param sql
   * @param autoGeneratedKeys
   *
   * @return PreparedStatement
   *
   * @throws DbcException
   *
   */
  PreparedStatement prepareStatement(String sql, int autoGeneratedKeys)
  throws DbcException;

  /**
   * Creates a default PreparedStatement object
   * capable of returning the auto-generated keys
   * designated by the given array.
   *
   * @param sql
   * @param columnIndexes
   *
   * @return PreparedStatement
   *
   * @throws DbcException
   *
   */
  PreparedStatement prepareStatement(String sql, int[] columnIndexes)
  throws DbcException;

  /**
   * Creates a PreparedStatement object that will
   * generate ResultSet objects with the given
   * type and concurrency.
   *
   * @param sql
   * @param resultSetType
   * @param resultSetConcurrency
   *
   * @return PreparedStatement
   *
   * @throws DbcException
   *
   */
  PreparedStatement prepareStatement(String sql, int resultSetType,
                                     int resultSetConcurrency)
  throws DbcException;

  /**
   * Creates a PreparedStatement object that will
   * generate ResultSet objects with the given type,
   * concurrency, and holdability.
   *
   * @param sql
   * @param resultSetType
   * @param resultSetConcurrency
   * @param resultSetHoldability
   *
   * @return PreparedStatement
   *
   * @throws DbcException
   *
   */
  PreparedStatement prepareStatement(String sql, int resultSetType,
                                     int resultSetConcurrency,
                                     int resultSetHoldability)
  throws DbcException;

  /**
   * Creates a default PreparedStatement object
   * capable of returning the auto-generated keys
   * designated by the given array.
   *
   * @param sql
   * @param columnNames
   *
   * @return PreparedStatement
   *
   * @throws DbcException
   *
   */
  PreparedStatement prepareStatement(String sql, String[] columnNames)
  throws DbcException;

  /**
   * Removes the given Savepoint object from
   * the current transaction.
   *
   *
   * @throws DbcException
   *
   */

   void releaseSavepoint(Object savepoint)
   throws DbcException;

  /**
   * Undoes all changes made in the current
   * transaction and releases anydatabase locks
   * currently held by this Connection object.
   *
   * @throws DbcException
   *
   */
  void rollback()
  throws DbcException;

  /**
   * Undoes all changes made after the given
   * Savepoint object was set.
   *
   *
   * @param autoCommit
   *
   * @throws DbcException
   *
   */

  void rollback(Object savepoint)
  throws DbcException;

  /**
   * Sets this connection's auto-commit mode
   * to the given state.
   *
   * @param authCommit
   *
   * @throws DbcException
   *
   */
  void setAutoCommit(boolean autoCommit)
  throws DbcException;

  /**
   * Sets the given catalog name in order to
   * select a subspace of this Connection
   * object's database in which to work.
   *
   * @param catalog
   *
   * @throws DbcException
   *
   */
  void setCatalog(String catalog)
  throws DbcException;

  /**
   * Changes the holdability of ResultSet
   * objects created using this Connection
   * object to the given holdability.
   *
   * @param holdability
   *
   * @throws DbcException
   *
   */
  void setHoldability(int holdability)
  throws DbcException;

  /**
   * Puts this connection in read-only mode
   * as a hint to the driver to enable
   * database optimizations.
   *
   * @param readOnly
   *
   * @throws DbcException
   *
   */
  void setReadOnly(boolean readOnly)
  throws DbcException;

  /**
   * Creates an unnamed savepoint in the current
   * transaction and returns the new Savepoint
   * object that represents it.
   *
   * @return Savepoint
   *
   * @throws DbcException
   *
   */
  Object setSavepoint()
  throws DbcException;

  /**
   * Creates a savepoint with the given name in
   * the current transaction and returns the new
   * Savepoint object that represents it.
   *
   * @param name
   *
   * @return Savepoint
   *
   * @throws DbcException
   *
   */
  Object setSavepoint(String name)
  throws DbcException;

  /**
   * Attempts to change the transaction isolation
   * level for this Connection object to the one given.
   *
   * @param level
   *
   * @throws DbcException
   *
   */
  void setTransactionIsolation(int level)
  throws DbcException;

  /**
   * Installs the given TypeMap object as
   * the type map for this Connection object.
   *
   * @param map
   *
   * @throws DbcException
   *
   */
  void setTypeMap(java.util.Map map)
  throws DbcException;

}