core/java/android/database/sqlite/SQLiteProgram.java

/*
 * Copyright (C) 2006 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.database.sqlite;

import android.util.Log;

/**
 * A base class for compiled SQLite programs.
 */
public abstract class SQLiteProgram extends SQLiteClosable {
    static final String TAG = "SQLiteProgram";

    /** The database this program is compiled against. */
    protected SQLiteDatabase mDatabase;

    /**
     * Native linkage, do not modify. This comes from the database and should not be modified
     * in here or in the native code.
     */
    protected int nHandle = 0;

    /**
     * Native linkage, do not modify. When non-0 this holds a reference to a valid
     * sqlite3_statement object. It is only updated by the native code, but may be
     * checked in this class when the database lock is held to determine if there
     * is a valid native-side program or not.
     */
    protected int nStatement = 0;

    /**
     * Used to find out where a cursor was allocated in case it never got
     * released.
     */
    private StackTraceElement[] mStackTraceElements;    
 
    /* package */ SQLiteProgram(SQLiteDatabase db, String sql) {
        if (SQLiteDebug.DEBUG_SQL_STATEMENTS) {
            mStackTraceElements = new Exception().getStackTrace();
        }
        
        mDatabase = db;
        db.acquireReference();
        db.addSQLiteClosable(this);
        this.nHandle = db.mNativeHandle;
        compile(sql, false);
    }    
    
    @Override
    protected void onAllReferencesReleased() {
        // Note that native_finalize() checks to make sure that nStatement is
        // non-null before destroying it.
        native_finalize();
        mDatabase.releaseReference();
        mDatabase.removeSQLiteClosable(this);
    }
    
    @Override
    protected void onAllReferencesReleasedFromContainer(){
        // Note that native_finalize() checks to make sure that nStatement is
        // non-null before destroying it.
        native_finalize();
        mDatabase.releaseReference();        
    }

    /**
     * Returns a unique identifier for this program.
     * 
     * @return a unique identifier for this program
     */
    public final int getUniqueId() {
        return nStatement;
    }

    /**
     * Compiles the given SQL into a SQLite byte code program using sqlite3_prepare_v2(). If
     * this method has been called previously without a call to close and forCompilation is set
     * to false the previous compilation will be used. Setting forceCompilation to true will
     * always re-compile the program and should be done if you pass differing SQL strings to this
     * method.
     *
     * <P>Note: this method acquires the database lock.</P>
     *
     * @param sql the SQL string to compile
     * @param forceCompilation forces the SQL to be recompiled in the event that there is an
     *  existing compiled SQL program already around
     */
    protected void compile(String sql, boolean forceCompilation) {
        // Only compile if we don't have a valid statement already or the caller has
        // explicitly requested a recompile. 
        if (nStatement == 0 || forceCompilation) {
            mDatabase.lock();
            try {
                // Note that the native_compile() takes care of destroying any previously
                // existing programs before it compiles.
                acquireReference();                
                native_compile(sql);
            } finally {
                releaseReference();
                mDatabase.unlock();
            }        
        }
    } 
  
    /**
     * Bind a NULL value to this statement. The value remains bound until
     * {@link #clearBindings} is called.
     *
     * @param index The 1-based index to the parameter to bind null to
     */
    public void bindNull(int index) {
        acquireReference();
        try {
            native_bind_null(index);
        } finally {
            releaseReference();
        }
    }

    /**
     * Bind a long value to this statement. The value remains bound until
     * {@link #clearBindings} is called.
     *
     * @param index The 1-based index to the parameter to bind
     * @param value The value to bind
     */
    public void bindLong(int index, long value) {
        acquireReference();
        try {
            native_bind_long(index, value);
        } finally {
            releaseReference();
        }
    }

    /**
     * Bind a double value to this statement. The value remains bound until
     * {@link #clearBindings} is called.
     *
     * @param index The 1-based index to the parameter to bind
     * @param value The value to bind
     */
    public void bindDouble(int index, double value) {
        acquireReference();
        try {
            native_bind_double(index, value);
        } finally {
            releaseReference();
        }
    }

    /**
     * Bind a String value to this statement. The value remains bound until
     * {@link #clearBindings} is called.
     *
     * @param index The 1-based index to the parameter to bind
     * @param value The value to bind
     */
    public void bindString(int index, String value) {
        if (value == null) {
            throw new IllegalArgumentException("the bind value at index " + index + " is null");
        }
        acquireReference();
        try {
            native_bind_string(index, value);
        } finally {
            releaseReference();
        }
    }

    /**
     * Bind a byte array value to this statement. The value remains bound until
     * {@link #clearBindings} is called.
     *
     * @param index The 1-based index to the parameter to bind
     * @param value The value to bind
     */
    public void bindBlob(int index, byte[] value) {
        if (value == null) {
            throw new IllegalArgumentException("the bind value at index " + index + " is null");
        }
        acquireReference();
        try {
            native_bind_blob(index, value);
        } finally {
            releaseReference();
        }
    }

    /**
     * Clears all existing bindings. Unset bindings are treated as NULL.
     */
    public void clearBindings() {
        acquireReference();
        try {
            native_clear_bindings();
        } finally {
            releaseReference();
        }
    }

    /**
     * Release this program's resources, making it invalid.
     */
    public void close() {
        mDatabase.lock();
        try {
            releaseReference();
        } finally {
            mDatabase.unlock();
        }        
    }
    
    /**
     * Make sure that the native resource is cleaned up.
     */
    @Override
    protected void finalize() {
        if (nStatement != 0) {
            if (SQLiteDebug.DEBUG_SQL_STATEMENTS) {
                String message = "Finalizing " + this +  
                    " that has not been closed";

                Log.d(TAG, message + "\nThis cursor was created in:");
                for (StackTraceElement ste : mStackTraceElements) {
                    Log.d(TAG, "      " + ste);
                }
            }
            // when in finalize() it is already removed from weakhashmap
            // so it is safe to not removed itself from db
            onAllReferencesReleasedFromContainer();
        }
    }

    /**
     * Compiles SQL into a SQLite program.
     * 
     * <P>The database lock must be held when calling this method.
     * @param sql The SQL to compile.
     */
    protected final native void native_compile(String sql);
    protected final native void native_finalize();

    protected final native void native_bind_null(int index);
    protected final native void native_bind_long(int index, long value);
    protected final native void native_bind_double(int index, double value);
    protected final native void native_bind_string(int index, String value);
    protected final native void native_bind_blob(int index, byte[] value);
    private final native void native_clear_bindings();
}