Quadcap Embeddable Database

com/quadcap/jdbc/Statement.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.sql.SQLException;
import java.sql.SQLWarning;

import antlr.RecognitionException;
import antlr.TokenStreamException;

import com.quadcap.sql.Database;
import com.quadcap.sql.Session;
import com.quadcap.sql.SQLParser;
import com.quadcap.sql.Stmt;

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

/**
 * This class implements the <code>java.sql.Statement</code> interface, which
 * provides facilities for executing SQL statements on a database
 * connection, as part of that connection's transaction.
 *
 * TODO: setMaxFieldSize
 * TODO: setQueryTimeout
 * TODO: JDBC3.0: return generated keys
 *
 * @author Stan Bailes
 */
public class Statement implements java.sql.Statement {
    /*{com.quadcap.qed.Trace-vars.xml-1054}
     * <config-var>
     *   <config-name>qed.trace.Statement</config-name>
     *   <config-dflt>0</config-dflt>
     *   <config-desc>
     *   <pre>
     *     bit 0: statement lifecycle
     *     bit 1: statement execution
     *     bit 2: statement + result
     *     bit 4: params in prepared statements
     *    </pre>
     *    </config-desc>
     * </config-var>
     */
    static final ConfigNumber   trace =
    ConfigNumber.find("qed.trace.Statement", "0");

    Connection                          conn;
    com.quadcap.sql.Connection          qConn            = null;
    Session                             session          = null;
    ResultSet                           rs               = null;
    int                                 updateCount      = -1;
    protected boolean                   escapeProcessing = true;
    int                                 maxRows          = -1;

    /**
     * Create a new statement
     */
    public Statement(Connection conn) throws SQLException, IOException {
        this.conn = conn;
        this.qConn = conn.getConnection();
        this.session = qConn.createSession();
        //#ifdef DEBUG
        if (trace.bit(0)) {
            Debug.println(toString() + " created");
        }
        //#endif
    }

    /**
     * Create a new Statement with the specified result set type and
     * concurrency.
     */
    public Statement(Connection conn, int resultSetType,
                     int resultSetConcurrency)
        throws SQLException, IOException
    {
        this(conn);
        this.resultSetType = resultSetType;
        this.resultSetConcurrency = resultSetConcurrency;
    }

    /**
     * My short life is ended
     */
    public void finalize() throws Throwable {
        try {
            close();
        } catch (Throwable t) {}
        super.finalize();
    }
    
    /**
     * This QED release doesn't support batch statement execution.
     *
     * @exception SQLException "not implemented"
     */
    public void addBatch(String sql) throws SQLException {
        throw new SQLException("not implemented", "0A000");
    }
    
    /**
     * QED does not support the <code>cancel()</code> feature.
     */
    public void cancel() throws SQLException {
    }
    
    /**
     * This QED release doesn't support batch statement execution.
     *
     * @exception SQLException "not implemented"
     */
    public void clearBatch() throws SQLException {
        throw new SQLException("not implemented", "0A000");
    }
    
    /**
     * Clear any warnings associated with this <code>Statement</code>
     * object.  Since this QED release doesn't generate 
     * <code>SQLWarning</code>s, this function does nothing.
     */
    public void clearWarnings() {
    }
    
    /**
     * Close this statement object and free up any resources held by it.
     */
    public void close() {
        //#ifdef DEBUG
        if (trace.bit(0)) {
            Debug.println(toString() + ".close()");
        }
        //#endif
        if (session != null) {
            try {
                session.close();
            } catch (SQLException e) {
            } catch (IOException e) {
            } finally {
                session = null;
                qConn = null;
            }
        }
    }

    //#ifdef DEBUG
    public String toString() {
        return "Statement[" + session == null ? "" : session.toString() + "]";
    }
    //#endif

    /**
     * Execute the specified SQL statement, returning <code>true</code>
     * if the statement generates a <code>ResultSet</code> object.
     *
     * @param sql an SQL statement
     * @return true if execution of the statement results in the creation
     *  of a <code>ResultSet</code>
     * @see #getResultSet()
     * @exception SQLException may be thrown
     */
    public boolean execute(String sql) throws SQLException {
        //#ifdef DEBUG
        if (trace.bit(1)) {
            Debug.println(toString() + ".execute(" + sql + ")");
        }
        //#endif
        if (this.qConn == null || this.qConn.isClosed()) {
            throw new SQLException("Connection closed");
        }

        if (this.rs != null) {
            this.rs.close();
            this.rs = null;
        }
        this.updateCount = -1;

        session.makeTransaction();
        SQLParser p = new SQLParser(session, sql, escapeProcessing);
        String auth = qConn.getAuth();
        //#ifdef DEBUG
        String res = "";
        //#endif
        try {
            try {
                Stmt s = p.statement();
                if (s == null) {
                    throw new SQLException("Parse error", "42000");
                }
                session.doStatement(s);
                this.rs = (ResultSet)session.getResultSet(this);
                if (rs != null) {
                    //#ifdef DEBUG
                    res = "true";
                    //#endif
                    return true;
                } else {
                    this.updateCount = session.getUpdateCount();
                    //#ifdef DEBUG
                    res = String.valueOf(updateCount);
                    //#endif
                    return false;
                }
            } catch (IOException e) {
                //#ifdef DEBUG
                res = e.toString();
                //#endif
                Debug.print(e);
                session.endStatement(true);
                throw new SQLException(e.toString(), "Q0012");
            } catch (RecognitionException e) {
                //#ifdef DEBUG
                Debug.print(e);
                Debug.println("SQL: " + sql);
                res = e.toString();
                //#endif
                session.endStatement(true);
                SQLException se = new SQLException("Statment: " + sql);
                SQLException s2 = new SQLException(e.toString(), "42000");
                s2.setNextException(se);
                throw s2;
            } catch (TokenStreamException e) {
                //#ifdef DEBUG
                res = e.toString();
                //#endif
                session.endStatement(true);
                SQLException se = new SQLException("Statment: " + sql);
                SQLException s2 = new SQLException(e.toString(), "42000");
                s2.setNextException(se);
                throw s2;
            } catch (SQLException e) {
                //#ifdef DEBUG
                res = e.toString();
                //#endif
                session.endStatement(true);
                throw e;
            } catch (Throwable e) {
                //#ifdef DEBUG
                res = e.toString();
                Debug.println("Throwable: " + e);
                Debug.print(e);
                //#endif
                session.endStatement(true);
                throw new SQLException(e.toString(), "Q0013");
            }
        } catch (IOException e) {
            Debug.print(e);
            throw new SQLException(e.toString(), "Q0014");
        } finally {
            // XXX restore auth in case of createSchema
            // This is a hack. 'create schema' will temporarily set the
            // 'auth' to the schema name, and this is the first place where
            // we get a chance to restore the correct auth.
            //
            // This is made worse by the fact that names are resolved during
            // the parse phase, and could be made better if antlr parser 
            // rules allowed you to specify a 'finally' handler.

            // Also 'create schema' where the schema name is a parameter is
            // going to fail badly.
            session.getConnection().setAuth(auth, null);
            //#ifdef DEBUG
            if (trace.bit(2)) {
                Debug.println("Statement.execute(" + sql + ") = " + res);
            }
            //#endif
        }
    }
    
    /**
     * This QED release doesn't support batch statement execution.
     *
     * @exception SQLException "not implemented"
     */
    public int[] executeBatch() throws SQLException {
        throw new SQLException("not implemented", "0A000");
    }

    
    /**
     * Execute the specified SQL query statement, returning the 
     * <code>ResultSet</code> object containing the results of the
     * query.
     *
     * @param sql an SQL query statement
     * @return a <code>ResultSet</code> object containing the results of
     *          the query
     * @exception SQLException may be thrown
     */
    public java.sql.ResultSet executeQuery(String sql) throws SQLException {
        if (execute(sql)) {
            return this.rs;
        } else {
            return null;
        }
    }

    /**
     * Execute the specified SQL update statement, returning the update
     * count, meaning the number of rows updated or inserted by this
     * statement.
     *
     * @param sql an SQL update statement
     * @return the update count
     * @exception SQLException may be thrown
     */
    public int executeUpdate(String sql) throws SQLException {
        if (!execute(sql)) {
            return this.updateCount;
        } else {
            return 0;
        }
    }
    
    /**
     * Return the <code>Connection</code> object used to create this
     * <code>Statement</code> object.
     *
     * @return this statement's connection.
     */
    public java.sql.Connection getConnection() {
        return conn;
    }
    
    /**
     * In QED, the fetch size is always 1.
     *
     * @return one
     */
    public int getFetchSize() {
        return 1;
    }
    
    /**
     * QED imposes no maximum field size.
     *
     * @return zero, meaning unlimited
     */
    public int getMaxFieldSize() {
        return 0;
    }
    
    /**
     * QED imposes no limit on the number of rows in a <code>ResultSet</code>.
     *
     * @return zero, meaning unlimited
     */
    public int getMaxRows() {
        return 0;
    }
    
    /**
     * QED only returns one <code>ResultSet</code> per statement, so
     * this function always returns <code>false</code> (after closing
     * the current <code>ResultSet</code> object for this
     * <code>Statement</code>.
     *
     * @return false
     * @exception SQLException may be thrown
     */
    public boolean getMoreResults() throws SQLException {
        if (rs != null) rs.close();
        this.updateCount = -1;
        return false;
    }
    
    /**
     * QED doesn't support query timeouts, so this method always returns
     * zero.
     *
     * @return zero, meaning unlimited
     */
    public int getQueryTimeout() {
        return 0;
    }
    
    /**
     * Return the <code>ResultSet</code> generated by the last call to
     * <code>execute()</code>, unless that <code>ResultSet</code> has
     * been closed, or if there was no <code>ResultSet</code> generated
     * by the last call to <code>execute()</code>, in which case, return
     * <code>null</code>.
     *
     * @return the current <code>ResultSet</code>
     *
     */
    public java.sql.ResultSet getResultSet() {
        return rs;
    }

    /**
     * Return the update count for the last statement executed.  If no
     * records were updated, inserted, or deleted, return -1.
     *
     * @return the update count for the last <code>execute()</code>
     *  operation
     */
    public int getUpdateCount() {
        return updateCount;
    }
    
    /**
     * Since this QED release doesn't generate 
     * <code>SQLWarning</code>s, this function always returns null.
     *
     * @return null
     */
    public SQLWarning getWarnings() {
        return null;
    }
    
    /**
     * This QED release doesn't support SQL named cursors
     *
     * @exception SQLException "not implemented"
     */
    public void setCursorName(String name) throws SQLException {
        throw new SQLException("not implemented", "0A000");
    }
    
    /**
     * Enable or disable JDBC escape processing mode.
     *
     * @boolean enable <code>true</code> is the driver should perform
     *    JDBC escape processing on statement execution.
     */
    public void setEscapeProcessing(boolean enable) {
        escapeProcessing = enable;
    }
    
    /**
     * Set the default fetch direction for <code>ResultSet</code> objects
     * generated by this <code>Statement</code> object.
     */
    public void setFetchDirection(int dir) throws SQLException {
    }
    
    /**
     * QED, being an embedded driver, fetches rows only when they are
     * needed, with no performance penalty.  Thus, the fetch size is
     * always <code>one</code>, and this function has no effect.
     */
    public void setFetchSize(int x) throws SQLException {
    }
    
    /**
     * Not implemented in this release of QED
     *
     * @exception SQLException "not implemented"
     */ 
    public void setMaxFieldSize(int x) throws SQLException {
        throw new SQLException("not implemented", "0A000");
    }
    
    /**
     * Set the maximum number of rows that will be returned by this
     * ResultSet
     */ 
    public void setMaxRows(int x) throws SQLException {
        maxRows = x;
    }
    
    /**
     * Not implemented in this release of QED
     *
     * @exception SQLException "not implemented"
     */ 
    public void setQueryTimeout(int x) throws SQLException {
        throw new SQLException("not implemented", "0A000");
    }
    
    int         resultSetType       = ResultSet.TYPE_SCROLL_INSENSITIVE;
    int         resultSetConcurrency    = ResultSet.CONCUR_UPDATABLE;

    /**
     * Return the default result set concurrency for <code>ResultSet</code>
     * objects generated by this <code>Statement</code> object.
     *
     * @return the default result set concurrency
     */
    public int getResultSetConcurrency() {
        return resultSetConcurrency;
    }
    
    /**
     * Return the default result set type for <code>ResultSet</code>
     * objects generated by this <code>Statement</code> object.
     *
     * @return the default result set type
     */
    public int getResultSetType() {
        return resultSetType;
    }

    /**
     * This release of QED only supports the fetch direction:
     * <code>ResultSet.FETCH_FORWARD</code>
     *
     * @return <code>ResultSet.FETCH_FORWARD</code>
     */
    public int getFetchDirection() {
        return ResultSet.FETCH_FORWARD;
    }
        
    // JDBC 3.0 -------------------------------------------------------
    //#ifdef JDK14
    /**
     * Moves to this <code>Statement</code> object's next result, deals with
     * any current <code>ResultSet</code> object(s) according  to the
     * instructions specified by the given flag, and returns
     * <code>true</code> if the next result is a <code>ResultSet</code> object.
     *
     * <P>There are no more results when the following is true:
     * <PRE>
     *      <code>(!getMoreResults() && (getUpdateCount() == -1)</code>
     * </PRE>
     *
     * @param current one of the following <code>Statement</code>
     *        constants indicating what should happen to current 
     *        <code>ResultSet</code> objects obtained using the method
     *        <code>getResultSet</code:
     *        <code>CLOSE_CURRENT_RESULT</code>, 
     *        <code>KEEP_CURRENT_RESULT</code>, or
     *        <code>CLOSE_ALL_RESULTS</code>
     * @return <code>true</code> if the next result is a <code>ResultSet</code> 
     *         object; <code>false</code> if it is an update count or there are no 
     *         more results
     * @exception SQLException if a database access error occurs
     * @since 1.4
     * @see #execute
     */
    public boolean getMoreResults(int current) throws SQLException {
        if (current == KEEP_CURRENT_RESULT) {
            throw new SQLException("JDBC 3.0 feature KEEP_CURRENT_RESULT " +
                                   "not implemented");
        }
        return getMoreResults();
    }

    /**
     * Retrieves any auto-generated keys created as a result of executing this
     * <code>Statement</code> object. If this <code>Statement</code> object
     * did not generate any keys, an empty <code>ResultSet</code>
     * object is returned.
     *
     * @return a <code>ResultSet</code> object containing the auto-generated
     *         key(s) generated by the execution of this
     *         <code>Statement</code> object
     * @exception SQLException if a database access error occurs
     * @since 1.4
     */
    public java.sql.ResultSet getGeneratedKeys() throws SQLException {
        throw new SQLException("JDBC3.0 feature not implemented");
    }

    /**
     * Executes the given SQL statement and signals the driver with the
     * given flag about whether the
     * auto-generated keys produced by this <code>Statement</code> object
     * should be made available for retrieval. 
     *
     * @param sql must be an SQL <code>INSERT</code>, <code>UPDATE</code> or
     *        <code>DELETE</code> statement or an SQL statement that 
     *        returns nothing
     * @param autoGeneratedKeys a flag indicating whether auto-generated keys
     *        should be made available for retrieval;
     *         one of the following constants:
     *         <code>Statement.RETURN_GENERATED_KEYS</code>
     *         <code>Statement.NO_GENERATED_KEYS</code>
     * @return either the row count for <code>INSERT</code>,
     *         <code>UPDATE</code>
     *         or <code>DELETE</code> statements, or <code>0</code> for SQL 
     *         statements that return nothing
     * @exception SQLException if a database access error occurs, the given
     *            SQL statement returns a <code>ResultSet</code> object, or
     *            the given constant is not one of those allowed
     * @since 1.4
     */
    public int executeUpdate(String sql, int autoGeneratedKeys)
        throws SQLException
    {
        if (autoGeneratedKeys == RETURN_GENERATED_KEYS) {
            throw new SQLException("JDBC3.0 feature not implemented");
        }
        return executeUpdate(sql);
    }

    /**
     * Executes the given SQL statement and signals the driver that the
     * auto-generated keys indicated in the given array should be made
     * available for retrieval.  The driver will ignore the array if the
     * SQL statement is not an <code>INSERT</code> statement.
     *
     * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
     *        <code>DELETE</code> statement or an SQL statement that returns
     *        nothing, such as an SQL DDL statement
     * @param columnIndexes an array of column indexes indicating the columns
     *        that should be returned from the inserted row
     * @return either the row count for <code>INSERT</code>,
     *         <code>UPDATE</code>,
     *         or <code>DELETE</code> statements, or 0 for SQL statements 
     *         that return nothing
     * @exception SQLException if a database access error occurs or the SQL
     *            statement returns a <code>ResultSet</code> object
     * @since 1.4
     */
    public int executeUpdate(String sql, int columnIndexes[])
        throws SQLException
    {
        return executeUpdate(sql);
    }

    /**
     * Executes the given SQL statement and signals the driver that the
     * auto-generated keys indicated in the given array should be made available
     * for retrieval.  The driver will ignore the array if the SQL statement
     * is not an <code>INSERT</code> statement.
     *
     * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
     *        <code>DELETE</code> statement or an SQL statement that returns nothing
     * @param columnNames an array of the names of the columns that should be 
     *        returned from the inserted row
     * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
     *         or <code>DELETE</code> statements, or 0 for SQL statements 
     *         that return nothing
     * @exception SQLException if a database access error occurs
     *
     * @since 1.4
     */
    public int executeUpdate(String sql, String columnNames[])
        throws SQLException
    {
        return executeUpdate(sql);
    }

    /**
     * Executes the given SQL statement, which may return multiple results,
     * and signals the driver that any
     * auto-generated keys should be made available
     * for retrieval.  The driver will ignore this signal if the SQL statement
     * is not an <code>INSERT</code> statement.
     * <P>
     * In some (uncommon) situations, a single SQL statement may return
     * multiple result sets and/or update counts.  Normally you can ignore
     * this unless you are (1) executing a stored procedure that you know may
     * return multiple results or (2) you are dynamically executing an
     * unknown SQL string.  
     * <P>
     * The <code>execute</code> method executes an SQL statement and indicates the
     * form of the first result.  You must then use the methods 
     * <code>getResultSet</code> or <code>getUpdateCount</code>
     * to retrieve the result, and <code>getMoreResults</code> to
     * move to any subsequent result(s).
     *
     * @param sql any SQL statement
     * @param autoGeneratedKeys a constant indicating whether auto-generated 
     *        keys should be made available for retrieval using the method
     *        <code>getGeneratedKeys</code>; one of the following constants:
     *        <code>Statement.RETURN_GENERATED_KEYS</code> or
     *        <code>Statement.NO_GENERATED_KEYS</code>
     * @return <code>true</code> if the first result is a <code>ResultSet</code>
     *         object; <code>false</code> if it is an update count or there are
     *         no results
     * @exception SQLException if a database access error occurs
     * @see #getResultSet
     * @see #getUpdateCount
     * @see #getMoreResults
     * @see #getGeneratedKeys
     *
     * @since 1.4 
     */
    public boolean execute(String sql, int autoGeneratedKeys)
        throws SQLException
    {
        return execute(sql);
    }

    /**
     * Executes the given SQL statement, which may return multiple results,
     * and signals the driver that the
     * auto-generated keys indicated in the given array should be made available
     * for retrieval.  This array contains the indexes of the columns in the 
     * target table that contain the auto-generated keys that should be made
     * available. The driver will ignore the array if the given SQL statement
     * is not an <code>INSERT</code> statement.
     * <P>
     * Under some (uncommon) situations, a single SQL statement may return
     * multiple result sets and/or update counts.  Normally you can ignore
     * this unless you are (1) executing a stored procedure that you know may
     * return multiple results or (2) you are dynamically executing an
     * unknown SQL string.  
     * <P>
     * The <code>execute</code> method executes an SQL statement and indicates the
     * form of the first result.  You must then use the methods 
     * <code>getResultSet</code> or <code>getUpdateCount</code>
     * to retrieve the result, and <code>getMoreResults</code> to
     * move to any subsequent result(s).
     *
     * @param sql any SQL statement
     * @param columnIndexes an array of the indexes of the columns in the 
     *        inserted row that should be  made available for retrieval by a
     *        call to the method <code>getGeneratedKeys</code>
     * @return <code>true</code> if the first result is a <code>ResultSet</code> 
     *         object; <code>false</code> if it is an update count or there 
     *         are no results
     * @exception SQLException if a database access error occurs
     * @see #getResultSet
     * @see #getUpdateCount
     * @see #getMoreResults
     *
     * @since 1.4
     */
    public boolean execute(String sql, int columnIndexes[])
        throws SQLException
    {
        return execute(sql);
    }

    /**
     * Executes the given SQL statement, which may return multiple results,
     * and signals the driver that the
     * auto-generated keys indicated in the given array should be made available
     * for retrieval. This array contains the names of the columns in the 
     * target table that contain the auto-generated keys that should be made
     * available. The driver will ignore the array if the given SQL statement
     * is not an <code>INSERT</code> statement.
     * <P>
     * In some (uncommon) situations, a single SQL statement may return
     * multiple result sets and/or update counts.  Normally you can ignore
     * this unless you are (1) executing a stored procedure that you know may
     * return multiple results or (2) you are dynamically executing an
     * unknown SQL string.  
     * <P>
     * The <code>execute</code> method executes an SQL statement and indicates the
     * form of the first result.  You must then use the methods 
     * <code>getResultSet</code> or <code>getUpdateCount</code>
     * to retrieve the result, and <code>getMoreResults</code> to
     * move to any subsequent result(s).
     *
     * @param sql any SQL statement
     * @param columnNames an array of the names of the columns in the inserted
     *        row that should be made available for retrieval by a call to the
     *        method <code>getGeneratedKeys</code>
     * @return <code>true</code> if the next result is a <code>ResultSet</code> 
     *         object; <code>false</code> if it is an update count or there 
     *         are no more results
     * @exception SQLException if a database access error occurs
     * @see #getResultSet
     * @see #getUpdateCount
     * @see #getMoreResults
     * @see #getGeneratedKeys
     *
     * @since 1.4 
     */
    public boolean execute(String sql, String columnNames[])
        throws SQLException
    {
        return execute(sql);
    }

   /**
     * Retrieves the result set holdability for <code>ResultSet</code> objects
     * generated by this <code>Statement</code> object.
     *
     * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
     *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
     * @exception SQLException if a database access error occurs
     *
     * @since 1.4
     */
    public int getResultSetHoldability() throws SQLException {
        return ResultSet.CLOSE_CURSORS_AT_COMMIT;
    }
    //#endif
    
}