Quadcap Embeddable Database

com/quadcap/jdbc/Connection.java

Go to the documentation of this file.

package com.quadcap.jdbc;

/* Copyright 1999 - 2003 Quadcap Software.  All rights reserved.
 *
 * This software is distributed under the Quadcap Free Software License.
 * This software may be used or modified for any purpose, personal or
 * commercial.  Open Source redistributions are permitted.  Commercial
 * redistribution of larger works derived from, or works which bundle
 * this software requires a "Commercial Redistribution License"; see
 * http://www.quadcap.com/purchase.
 *
 * Redistributions qualify as "Open Source" under  one of the following terms:
 *   
 *    Redistributions are made at no charge beyond the reasonable cost of
 *    materials and delivery.
 *
 *    Redistributions are accompanied by a copy of the Source Code or by an
 *    irrevocable offer to provide a copy of the Source Code for up to three
 *    years at the cost of materials and delivery.  Such redistributions
 *    must allow further use, modification, and redistribution of the Source
 *    Code under substantially the same terms as this license.
 *
 * Redistributions of source code must retain the copyright notices as they
 * appear in each source code file, these license terms, and the
 * disclaimer/limitation of liability set forth as paragraph 6 below.
 *
 * Redistributions in binary form must reproduce this Copyright Notice,
 * these license terms, and the disclaimer/limitation of liability set
 * forth as paragraph 6 below, in the documentation and/or other materials
 * provided with the distribution.
 *
 * The Software is provided on an "AS IS" basis.  No warranty is
 * provided that the Software is free of defects, or fit for a
 * particular purpose.  
 *
 * Limitation of Liability. Quadcap Software shall not be liable
 * for any damages suffered by the Licensee or any third party resulting
 * from use of the Software.
 */

import java.io.IOException;

import java.util.Map;

import java.sql.CallableStatement;
import java.sql.ResultSet;
//#ifdef JDK14
import java.sql.Savepoint;
//#endif 
import java.sql.SQLException;
import java.sql.SQLWarning;

import com.quadcap.sql.Database;
import com.quadcap.sql.DbException;
import com.quadcap.sql.Session;

import com.quadcap.util.ConfigNumber;
import com.quadcap.util.Debug;
import com.quadcap.util.Util;

/**
 * This class implements the <code>java.sql.Connection</code> interface,
 * which provides facilities for executing SQL statements, performing
 * transaction commit and rollback, and obtaining information about
 * the database via <code>DatabaseMetaData</code>.
 *
 * @author Stan Bailes
 */
public class Connection implements java.sql.Connection {
    /*{com.quadcap.qed.Trace-vars.xml-1052}
     * <config-var>
     *   <config-name>qed.trace.Connection</config-name>
     *   <config-dflt>0</config-dflt>
     *   <config-desc>
     *   <pre>
     *     bit 0: Connection lifecycle
     *     bit 1: Connection methods
     *    </pre>
     *    </config-desc>
     * </config-var>
     */

    //#ifdef DEBUG
    static final ConfigNumber   trace =
    ConfigNumber.find("qed.trace.Connection", "0");
    //#endif

    Database                    db;
    com.quadcap.sql.Connection  qConn           = null;
    boolean                     closed          = false;
    Map                         typeMap         = null;

    /**
     * Construct a new connection object for the specified database
     * and userid.
     * @deprecated <i>Pay no attention to that man behind the curtains.</i>
     *
     * @param db the database
     * @param auth the userid
     * @param passwd the password
     */
    public Connection(Database db, String auth, String passwd)
        throws SQLException
    {
        this.db = db;
        if (auth == null) auth = "";
        this.qConn = new com.quadcap.sql.Connection(db, auth.toUpperCase(),
                                                    passwd);
        //#ifdef DEBUG
        if (trace.bit(0)) {
            Debug.println("Connection.init(" + qConn + ")");
        }
        //#endif
    }

    /**
     * Return the database to which this connection is bound.
     * @deprecated <i>Pay no attention to that man behind the curtains.</i>
     *
     * @return the connection's database
     */
    public Database getDatabase() {
        return db;
    }

    /**
     * Return the connection's session.  
     * @deprecated <i>Pay no attention to that man behind the curtains.</i>
     *
     * @return the connection's session
     */
    public final com.quadcap.sql.Connection getConnection() {
        return qConn;
    }

    //------------------------------------------------------------------
    // java.sql.Connection implementation
    //------------------------------------------------------------------
    
    /**
     * Clears all warnings that have been reported on calls to this
     * connection.  QED doesn't currently throw any SQLWarnings,
     * so this operation does nothing.
     */
    public void clearWarnings() {
    }
    
    /**
     * Close this connection, which implicitly ends (i.e., commits) any
     * pending transactions for this connection, closes any 
     * <code>ResultSet</code>s opened on this connection, and marks
     * the connection as closed.  It is an error to attempt to use
     * this connection after the close operation
     *
     * @exception SQLException may be thrown
     */
    public void close() throws SQLException {
        //#ifdef DEBUG
        if (trace.bit(0)) {
            Debug.println("Connection[" + qConn + "].close()");
        }
        //#endif
        closed = true;
        try {
            if (qConn != null) qConn.close();
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        } finally {
            qConn = null;
        }
    }
            
    /**
     * Make sure the connection closes on gc...
     */
    public void finalize() throws Throwable {
        if (!closed) {
            try {
                close();
            } catch (Throwable t) {}
        }
        super.finalize();
    }

    /**
     * Commit any pending changes for the current transaction.  This
     * ends the transaction; any further statements executed by this
     * connection will cause a new transaction to be started.  This
     * method closes any <code>ResultSet</code>s opened on this connection.
     *
     * @exception SQLException may be thrown
     */
    public void commit() throws SQLException {
        //#ifdef DEBUG
        if (trace.bit(1)) {
            Debug.println("Connection.commit()");
        }
        //#endif
        if (closed) throw new SQLException("Connection closed", "08003");
        try {
            qConn.endTransaction();
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        }
    }
    
    /**
     * Return a new <code>Statement</code> object that can be used to
     * execute SQL statements on this connection
     *
     * @return a new <code>Statement</code> object
     * @exception SQLException may be thrown
     */
    public java.sql.Statement createStatement() throws SQLException {
        if (closed) throw new SQLException("Connection closed", "08003");
        try {
            return new Statement(this);
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        }
    }
    
    /**
     * Return the current value for the <code>autoCommit</code> variable.
     * By default, connections are created with <code>autoCommit</code>
     * equal to <code>true</code>
     *
     * @return the current <code>autoCommit</code> state
     */
    public boolean getAutoCommit() throws SQLException {
        if (closed) throw new SQLException("Connection closed", "08003");
        return qConn.getAutoCommit();
    }
    
    /**
     * QED doesn't support catalogs, so this function returns
     * <code>null</code>
     *
     * @return null
     */
    public String getCatalog() {
        return null;
    }
    
    /**
     * Return a <code>DatabaseMetaData</code> object that can be used
     * to get information about the features supported by QED.
     *
     * @return a <code>DatabaseMetaData</code>
     */
    DatabaseMetaData                    dbm = null;
    public java.sql.DatabaseMetaData getMetaData() throws SQLException {
        try {
            if (dbm == null) {
                dbm = new DatabaseMetaData(this);
            }
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        }
        return dbm;
    }
    
    /**
     * Return the current transaction isolation level -- QED currently
     * only supports <code>TRANSACTION_SERIALIZABLE</code>
     *
     * @return <code>TRANSACTION_SERIALIZABLE</code>
     */
    public int getTransactionIsolation() {
        return TRANSACTION_SERIALIZABLE;
    }
    
    /**
     * QED doesn't generate any <code>SQLWarning</code>s, so this function
     * always returns <code>null</code>
     *
     * @return null
     */
    public SQLWarning getWarnings() {
        return null;
    }
    
    /**
     * Return true if this connection has been closed.
     *
     * @return  true if this connection has been closed.
     */
    public boolean isClosed() {
        return closed;
    }
    
    /**
     * Return true if this connection is read only.  QED doesn't currently
     * support read-only connections, so this always returns
     * false
     *
     * @return false
     */
    public boolean isReadOnly() {
        return false;
    }
    
    /**
     * This function is supposed to translate the specified query into
     * the native query language of the underlying DBMS.  In QED, the
     * native query language is SQL-92, and JDBC escapes are directly
     * supported by the DBMS, so this translation is a no-op, and always
     * returns the original string
     *
     * @param stmt an SQL statement
     * @return the same SQL statement
     */
    public String nativeSQL(String stmt) {
        return stmt;
    }
    
    /**
     * QED doesn't support stored procedures, so this method returns
     * a "not implemented" exception
     *
     * @param sql the SQL statement
     * @return never
     * @exception SQLException "not implemented"
     */
    public CallableStatement prepareCall(String sql) throws SQLException {
        throw new SQLException("Not implemented");
    }
    
    /**
     * QED doesn't support stored procedures, so this method returns
     * a "not implemented" exception
     *
     * @param sql the SQL statement
     * @param resultType the desired <code>ResultSet</code> type
     * @param resultSetConcurrency the desired <code>ResultSet</code> 
     *          concurrency
     * @return never
     * @exception SQLException "not implemented"
     */
    public CallableStatement prepareCall(String sql, int resultType,
                                         int resultSetConcurrency)
        throws SQLException
    {
        throw new SQLException("Not implemented");
    }
    
    /**
     * Returns a new <code>PreparedStatement</code> statement, which is
     * a pre-compiled representation of the statement <i>sql</i>, with
     * place holders for parameters specified using the <code>'?'</code>
     * character.
     *
     * @param sql the SQL statement
     * @return the <code>PreparedStatement</code> statement that can be
     *          used to invoke the SQL statement, after the parameters
     *          represented by the <code>'?'</code> characters are
     *          supplied
     * @exception SQLException may be thrown
     */
    public java.sql.PreparedStatement prepareStatement(String sql)
        throws SQLException
    {
        if (closed) throw new SQLException("Connection closed", "08003");
        try {
            return new PreparedStatement(this, sql);
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        }
    }
    
    /**
     * Returns a new <code>PreparedStatement</code> statement, which is
     * a pre-compiled representation of the statement <i>sql</i>, with
     * place holders for parameters specified using the <code>'?'</code>
     * character.
     *
     * @param sql the SQL statement
     * @param resultType the desired <code>ResultSet</code> type
     * @param resultSetConcurrency the desired <code>ResultSet</code> 
     *          concurrency
     * @return the <code>PreparedStatement</code> statement that can be
     *          used to invoke the SQL statement, after the parameters
     *          represented by the <code>'?'</code> characters are
     *          supplied
     * @exception SQLException may be thrown
     */
    public java.sql.PreparedStatement prepareStatement(String sql, 
                                                       int resultType,
                                                       int resultSetConcurrency)
        throws SQLException
    {
        if (closed) throw new SQLException("Connection closed", "08003");
        try {
            return new PreparedStatement(this, sql, resultType,
                                         resultSetConcurrency);
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        }
    }
    
    /**
     * Roll back any pending changes for the current transaction.  This
     * ends the transaction; any further statements executed by this
     * connection will cause a new transaction to be started.  This
     * method closes any <code>ResultSet</code>s opened on this connection.
     *
     * @exception SQLException may be thrown
     */
    public void rollback() throws SQLException {
        //#ifdef DEBUG
        if (trace.bit(1)) {
            Debug.println("Connection.rollback()");
        }
        //#endif
        if (closed) {
            throw new SQLException("Connection closed", "08003");
        }
        try {
            qConn.rollbackTransaction();
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        }
    }
    
    /**
     * Set the state of the <code>autoCommit</code> flag. 
     *
     * @param autoCommit the new <code>autoCommit</code> state.
     */
    public void setAutoCommit(boolean autoCommit) throws SQLException {
        //#ifdef DEBUG
        if (trace.bit(1)) {
            Debug.println("Connection.setAutoCommit(" + autoCommit + ")");
        }
        //#endif
        if (closed) throw new SQLException("Connection closed", "08003");
        qConn.setAutoCommit(autoCommit);
    }
    
    /**
     * QED doesn't support catalogs, so this function throws
     * a "not implemented" exception
     *
     * @exception SQLException "not implemented"
     */
    public void setCatalog(String catalog) throws SQLException {
        throw new SQLException("Not implemented");
    }
    
    /**
     * QED doesn't support read-only connections, so this function will
     * throw a "not implemented" exception if it is called with
     * <code>readOnly == true</code>
     *
     * @param readOnly had better be false
     * @exception SQLException if it's not
     */
    public void setReadOnly(boolean readOnly) throws SQLException {
        if (readOnly) {
            throw new SQLException("Read-only connections not supported");
        }
    }
    
    /**
     * QED only supports the <code>TRANSACTION_SERIALIZABLE</code>
     * isolation level, so this function will
     * throw a "not implemented" exception if it is called with
     * any other value.
     *
     * @param readOnly had better be <code>TRANSACTION_SERIALIZABLE</code>
     * @exception SQLException if it's not
     */
    public void setTransactionIsolation(int trans) throws SQLException {
        if (trans != TRANSACTION_SERIALIZABLE) {
            throw new SQLException("Transaction isolation " + trans +
                                   " not supported");
        }

    }

    //#ifndef JDK11
    /**
     * Set the type map to be used for custom type mapping of UDTS.
     * In this release of QED, this call will succeed, but type mapping
     * is not fully implemented in this release.
     *
     * @param map the new map
     */
    public void setTypeMap(Map map) throws SQLException {
        this.typeMap = map;
    }

    /**
     * Return the current type map to be used for custom type mapping of UDTS.
     * In this release of QED, this call will succeed, but type mapping
     * is not fully implemented in this release.
     *
     * @return the curren type map
     */
    public Map getTypeMap() throws SQLException {
        return typeMap;
    }

    /**
     * Return a new <code>Statement</code> object that can be used to
     * execute SQL statements on this connection
     *
     * @param resultType the desired <code>ResultSet</code> type
     * @param resultSetConcurrency the desired <code>ResultSet</code> 
     *          concurrency
     * @return a new <code>Statement</code> object
     * @exception SQLException may be thrown
     */
    public java.sql.Statement createStatement(int resultType, 
                                              int resultSetConcurrency)
        throws SQLException
    {
        if (closed) throw new SQLException("Connection closed", "08003");
        try {
            return new Statement(this, resultType, resultSetConcurrency);
        } catch (IOException e) {
            throw DbException.wrapThrowable(e);
        }
    }
    
    //#endif


    //--------------------------JDBC 3.0-----------------------------

    //#ifdef JDK14
    /**
     * Changes the holdability of <code>ResultSet</code> objects
     * created using this <code>Connection</code> object to the given
     * holdability.
     *
     * <p>QED: <code>ResultSet</code>s are always closed on commit.</p>
     *
     * @param holdability a <code>ResultSet</code> holdability constant; one of
     *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
     *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
     * @throws SQLException if a database access occurs, the given parameter
     *         is not a <code>ResultSet</code> constant indicating holdability,
     *         or the given holdability is not supported
     * @see #getHoldability
     * @see ResultSet
     * @since 1.4
     */
    public void setHoldability(int holdability) throws SQLException {
        if (holdability != ResultSet.CLOSE_CURSORS_AT_COMMIT) {
            throw new SQLException("Not implemented");
        }
    }

    /**
     * Retrieves the current holdability of <code>ResultSet</code> objects
     * created using this <code>Connection</code> object.
     *
     * <p>QED: <code>ResultSet</code>s are always closed on commit.</p>
     *
     * @return the holdability, one of
     *        <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
     *        <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
     * @throws SQLException if a database access occurs
     * @see #setHoldability
     * @see ResultSet
     * @since 1.4
     */
    public int getHoldability() throws SQLException {
        return ResultSet.CLOSE_CURSORS_AT_COMMIT;
    }

    /**
     * Creates an unnamed savepoint in the current transaction and 
     * returns the new <code>Savepoint</code> object that represents it.
     *
     * <p>QED: <code>Savepoint</code>s not supported.</p>
     *
     * @return the new <code>Savepoint</code> object
     * @exception SQLException if a database access error occurs
     *            or this <code>Connection</code> object is currently in
     *            auto-commit mode
     * @see Savepoint
     * @since 1.4
     */
    public Savepoint setSavepoint() throws SQLException {
        throw new SQLException("Not implemented");
    }

    /**
     * Creates a savepoint with the given name in the current transaction
     * and returns the new <code>Savepoint</code> object that represents it.
     *
     * <p>QED: <code>Savepoint</code>s not supported.</p>
     *
     * @param name a <code>String</code> containing the name of the savepoint
     * @return the new <code>Savepoint</code> object
     * @exception SQLException if a database access error occurs
     *            or this <code>Connection</code> object is currently in
     *            auto-commit mode
     * @see Savepoint
     * @since 1.4
     */
    public Savepoint setSavepoint(String name) throws SQLException {
        throw new SQLException("Not implemented");
    } 

    /**
     * Undoes all changes made after the given <code>Savepoint</code> object
     * was set. 
     * <P>
     * This method should be used only when auto-commit has been disabled.
     *
     * <p>QED: <code>Savepoint</code>s not supported.</p>
     *
     * @param savepoint the <code>Savepoint</code> object to roll back to
     * @exception SQLException if a database access error occurs,
     *            the <code>Savepoint</code> object is no longer valid,
     *            or this <code>Connection</code> object is currently in
     *            auto-commit mode
     * @see Savepoint
     * @see #rollback
     * @since 1.4
     */
    public void rollback(Savepoint savepoint) throws SQLException {
        throw new SQLException("Not implemented");
    }

    /**
     * Removes the given <code>Savepoint</code> object from the current 
     * transaction. Any reference to the savepoint after it have been removed 
     * will cause an <code>SQLException</code> to be thrown.
     *
     * <p>QED: <code>Savepoint</code>s not supported.</p>
     *
     * @param savepoint the <code>Savepoint</code> object to be removed
     * @exception SQLException if a database access error occurs or
     *            the given <code>Savepoint</code> object is not a valid 
     *            savepoint in the current transaction
     * @since 1.4
     */
    public void releaseSavepoint(Savepoint savepoint) throws SQLException {
        throw new SQLException("Not implemented");
    }

    /**
     * Creates a <code>Statement</code> object that will generate
     * <code>ResultSet</code> objects with the given type, concurrency,
     * and holdability.
     * This method is the same as the <code>createStatement</code> method
     * above, but it allows the default result set
     * type, concurrency, and holdability to be overridden.
     *
     * @param resultSetType one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
     *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
     *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
     * @param resultSetConcurrency one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.CONCUR_READ_ONLY</code> or
     *         <code>ResultSet.CONCUR_UPDATABLE</code>
     * @param resultSetHoldability one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
     *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
     * @return a new <code>Statement</code> object that will generate
     *         <code>ResultSet</code> objects with the given type,
     *         concurrency, and holdability
     * @exception SQLException if a database access error occurs
     *            or the given parameters are not <code>ResultSet</code> 
     *            constants indicating type, concurrency, and holdability
     * @see ResultSet
     * @since 1.4
     */
    public java.sql.Statement createStatement(int resultSetType,
                                     int resultSetConcurrency, 
                                     int resultSetHoldability)
        throws SQLException
    {
        setHoldability(resultSetHoldability);
        return createStatement(resultSetType, resultSetConcurrency);
    }

    /**
     * Creates a <code>PreparedStatement</code> object that will generate
     * <code>ResultSet</code> objects with the given type, concurrency,
     * and holdability.
     * <P>
     * This method is the same as the <code>prepareStatement</code> method
     * above, but it allows the default result set
     * type, concurrency, and holdability to be overridden.
     *
     * @param sql a <code>String</code> object that is the SQL statement to
     *            be sent to the database; may contain one or more ? IN
     *            parameters
     * @param resultSetType one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
     *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
     *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
     * @param resultSetConcurrency one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.CONCUR_READ_ONLY</code> or
     *         <code>ResultSet.CONCUR_UPDATABLE</code>
     * @param resultSetHoldability one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
     *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
     * @return a new <code>PreparedStatement</code> object, containing the
     *         pre-compiled SQL statement, that will generate
     *         <code>ResultSet</code> objects with the given type,
     *         concurrency, and holdability
     * @exception SQLException if a database access error occurs
     *            or the given parameters are not <code>ResultSet</code> 
     *            constants indicating type, concurrency, and holdability
     * @see ResultSet
     * @since 1.4
     */
    public
    java.sql.PreparedStatement prepareStatement(String sql, int resultSetType, 
                                       int resultSetConcurrency,
                                       int resultSetHoldability)
        throws SQLException {
        setHoldability(resultSetHoldability);
        return prepareStatement(sql, resultSetType, resultSetConcurrency);
    }

    /**
     * Creates a <code>CallableStatement</code> object that will generate
     * <code>ResultSet</code> objects with the given type and concurrency.
     * This method is the same as the <code>prepareCall</code> method
     * above, but it allows the default result set
     * type, result set concurrency type and holdability to be overridden.
     *
     * @param sql a <code>String</code> object that is the SQL statement to
     *            be sent to the database; may contain on or more ? parameters
     * @param resultSetType one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.TYPE_FORWARD_ONLY</code>, 
     *         <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
     *         <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
     * @param resultSetConcurrency one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.CONCUR_READ_ONLY</code> or
     *         <code>ResultSet.CONCUR_UPDATABLE</code>
     * @param resultSetHoldability one of the following <code>ResultSet</code> 
     *        constants:
     *         <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
     *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
     * @return a new <code>CallableStatement</code> object, containing the
     *         pre-compiled SQL statement, that will generate
     *         <code>ResultSet</code> objects with the given type,
     *         concurrency, and holdability
     * @exception SQLException if a database access error occurs
     *            or the given parameters are not <code>ResultSet</code> 
     *            constants indicating type, concurrency, and holdability
     * @see ResultSet
     * @since 1.4
     */
    public
    CallableStatement prepareCall(String sql, int resultSetType, 
                                  int resultSetConcurrency, 
                                  int resultSetHoldability)
        throws SQLException
    {
        setHoldability(resultSetHoldability);
        return prepareCall(sql, resultSetType, resultSetConcurrency);
    }

    /**
     * Creates a default <code>PreparedStatement</code> object that has
     * the capability to retrieve auto-generated keys. The given constant
     * tells the driver whether it should make auto-generated keys
     * available for retrieval.  This parameter is ignored if the SQL 
     * statement is not an <code>INSERT</code> statement.
     * <P>
     * <B>Note:</B> This method is optimized for handling
     * parametric SQL statements that benefit from precompilation. If
     * the driver supports precompilation,
     * the method <code>prepareStatement</code> will send
     * the statement to the database for precompilation. Some drivers
     * may not support precompilation. In this case, the statement may
     * not be sent to the database until the <code>PreparedStatement</code> 
     * object is executed.  This has no direct effect on users; however, it does
     * affect which methods throw certain SQLExceptions.
     * <P>
     * Result sets created using the returned <code>PreparedStatement</code>
     * object will by default be type <code>TYPE_FORWARD_ONLY</code>
     * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
     *
     * @param sql an SQL statement that may contain one or more '?' IN
     *        parameter placeholders
     * @param autoGeneratedKeys a flag indicating whether auto-generated keys 
     *        should be returned; one of the following <code>Statement</code>
     *        constants:
     * @param autoGeneratedKeys a flag indicating that auto-generated keys
     *          should be returned, one of
     *        <code>Statement.RETURN_GENERATED_KEYS</code> or
     *        <code>Statement.NO_GENERATED_KEYS</code>.  
     * @return a new <code>PreparedStatement</code> object, containing the
     *         pre-compiled SQL statement, that will have the capability of
     *         returning auto-generated keys
     * @exception SQLException if a database access error occurs
     *         or the given parameter is not a <code>Statement</code>
     *         constant indicating whether auto-generated keys should be
     *         returned
     * @since 1.4
     */
    public
    java.sql.PreparedStatement prepareStatement(String sql,
                                                int autoGeneratedKeys)
        throws SQLException
    {
        if (autoGeneratedKeys == Statement.RETURN_GENERATED_KEYS) {
            throw new SQLException("RETURN_GENERATED_KEYS not implemented");
        }
        return prepareStatement(sql);
    }

    /**
     * Creates a default <code>PreparedStatement</code> object capable
     * of returning the auto-generated keys designated by the given array.
     * This array contains the indexes of the columns in the target
     * table that contain the auto-generated keys that should be made
     * available. This array is ignored if the SQL 
     * statement is not an <code>INSERT</code> statement.
     * <P>
     * An SQL statement with or without IN parameters can be
     * pre-compiled and stored in a <code>PreparedStatement</code> object. This
     * object can then be used to efficiently execute this statement
     * multiple times.
     * <P>
     * <B>Note:</B> This method is optimized for handling
     * parametric SQL statements that benefit from precompilation. If
     * the driver supports precompilation,
     * the method <code>prepareStatement</code> will send
     * the statement to the database for precompilation. Some drivers
     * may not support precompilation. In this case, the statement may
     * not be sent to the database until the <code>PreparedStatement</code> 
     * object is executed.  This has no direct effect on users; however, it does
     * affect which methods throw certain SQLExceptions.
     * <P>
     * Result sets created using the returned <code>PreparedStatement</code>
     * object will by default be type <code>TYPE_FORWARD_ONLY</code>
     * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
     *
     * @param sql an SQL statement that may contain one or more '?' IN
     *        parameter placeholders
     * @param columnIndexes an array of column indexes indicating the columns
     *        that should be returned from the inserted row or rows 
     * @return a new <code>PreparedStatement</code> object, containing the
     *         pre-compiled statement, that is capable of returning the
     *         auto-generated keys designated by the given array of column
     *         indexes
     * @exception SQLException if a database access error occurs
     *
     * @since 1.4
     */
    public
    java.sql.PreparedStatement prepareStatement(String sql,
                                                int columnIndexes[])
        throws SQLException
    {
        throw new SQLException("RETURN_GENERATED_KEYS not implemented");
    }

    /**
     * Creates a default <code>PreparedStatement</code> object capable
     * of returning the auto-generated keys designated by the given array.
     * This array contains the names of the columns in the target
     * table that contain the auto-generated keys that should be returned.
     * This array is ignored if the SQL 
     * statement is not an <code>INSERT</code> statement.
     * <P>
     * An SQL statement with or without IN parameters can be
     * pre-compiled and stored in a <code>PreparedStatement</code> object. This
     * object can then be used to efficiently execute this statement
     * multiple times.
     * <P>
     * <B>Note:</B> This method is optimized for handling
     * parametric SQL statements that benefit from precompilation. If
     * the driver supports precompilation,
     * the method <code>prepareStatement</code> will send
     * the statement to the database for precompilation. Some drivers
     * may not support precompilation. In this case, the statement may
     * not be sent to the database until the <code>PreparedStatement</code> 
     * object is executed.  This has no direct effect on users; however, it does
     * affect which methods throw certain SQLExceptions.
     * <P>
     * Result sets created using the returned <code>PreparedStatement</code>
     * object will by default be type <code>TYPE_FORWARD_ONLY</code>
     * and have a concurrency level of <code>CONCUR_READ_ONLY</code>.
     *
     * @param sql an SQL statement that may contain one or more '?' IN
     *        parameter placeholders
     * @param columnNames an array of column names indicating the columns
     *        that should be returned from the inserted row or rows 
     * @return a new <code>PreparedStatement</code> object, containing the
     *         pre-compiled statement, that is capable of returning the
     *         auto-generated keys designated by the given array of column
     *         names
     * @exception SQLException if a database access error occurs
     *
     * @since 1.4
     */
    public
    java.sql.PreparedStatement prepareStatement(String sql,
                                                String columnNames[])
        throws SQLException
    {
        throw new SQLException("RETURN_GENERATED_KEYS not implemented");
    }
    //#endif
}