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.database.DatabaseUtils;
import android.database.Cursor;

import java.util.HashMap;

/**
 * A base class for compiled SQLite programs.
 *<p>
 * SQLiteProgram is NOT internally synchronized so code using a SQLiteProgram from multiple
 * threads should perform its own synchronization when using the SQLiteProgram.
 */
public abstract class SQLiteProgram extends SQLiteClosable {

    private static final String TAG = "SQLiteProgram";

    /** The database this program is compiled against.
     * @deprecated do not use this
     */
    @Deprecated
    protected SQLiteDatabase mDatabase;

    /** The SQL used to create this query */
    /* package */ final String mSql;

    /**
     * Native linkage, do not modify. This comes from the database and should not be modified
     * in here or in the native code.
     * @deprecated do not use this
     */
    @Deprecated
    protected int nHandle;

    /**
     * the SQLiteCompiledSql object for the given sql statement.
     */
    /* package */ SQLiteCompiledSql mCompiledSql;

    /**
     * SQLiteCompiledSql statement id is populated with the corresponding object from the above
     * member. This member is used by the native_bind_* methods
     * @deprecated do not use this
     */
    @Deprecated
    protected int nStatement;

    /**
     * In the case of {@link SQLiteStatement}, this member stores the bindargs passed
     * to the following methods, instead of actually doing the binding.
     * <ul>
     *   <li>{@link #bindBlob(int, byte[])}</li>
     *   <li>{@link #bindDouble(int, double)}</li>
     *   <li>{@link #bindLong(int, long)}</li>
     *   <li>{@link #bindNull(int)}</li>
     *   <li>{@link #bindString(int, String)}</li>
     * </ul>
     * <p>
     * Each entry in the array is a Pair of
     * <ol>
     *   <li>bind arg position number</li>
     *   <li>the value to be bound to the bindarg</li>
     * </ol>
     * <p>
     * It is lazily initialized in the above bind methods
     * and it is cleared in {@link #clearBindings()} method.
     * <p>
     * It is protected (in multi-threaded environment) by {@link SQLiteProgram}.this
     */
    /* package */ HashMap<Integer, Object> mBindArgs = null;
    /* package */ final int mStatementType;
    /* package */ static final int STATEMENT_CACHEABLE = 16;
    /* package */ static final int STATEMENT_DONT_PREPARE = 32;
    /* package */ static final int STATEMENT_USE_POOLED_CONN = 64;
    /* package */ static final int STATEMENT_TYPE_MASK = 0x0f;

    /* package */ SQLiteProgram(SQLiteDatabase db, String sql) {
        this(db, sql, null, true);
    }

    /* package */ SQLiteProgram(SQLiteDatabase db, String sql, Object[] bindArgs,
            boolean compileFlag) {
        mSql = sql.trim();
        int n = DatabaseUtils.getSqlStatementType(mSql);
        switch (n) {
            case DatabaseUtils.STATEMENT_UPDATE:
                mStatementType = n | STATEMENT_CACHEABLE;
                break;
            case DatabaseUtils.STATEMENT_SELECT:
                mStatementType = n | STATEMENT_CACHEABLE | STATEMENT_USE_POOLED_CONN;
                break;
            case DatabaseUtils.STATEMENT_BEGIN:
            case DatabaseUtils.STATEMENT_COMMIT:
            case DatabaseUtils.STATEMENT_ABORT:
                mStatementType = n | STATEMENT_DONT_PREPARE;
                break;
            default:
                mStatementType = n;
        }
        db.acquireReference();
        db.addSQLiteClosable(this);
        mDatabase = db;
        nHandle = db.mNativeHandle;
        if (bindArgs != null) {
            int size = bindArgs.length;
            for (int i = 0; i < size; i++) {
                this.addToBindArgs(i + 1, bindArgs[i]);
            }
        }
        if (compileFlag) {
            compileAndbindAllArgs();
        }
    }

    private void compileSql() {
        // only cache CRUD statements
        if ((mStatementType & STATEMENT_CACHEABLE) == 0) {
            mCompiledSql = new SQLiteCompiledSql(mDatabase, mSql);
            nStatement = mCompiledSql.nStatement;
            // since it is not in the cache, no need to acquire() it.
            return;
        }

        mCompiledSql = mDatabase.getCompiledStatementForSql(mSql);
        if (mCompiledSql == null) {
            // create a new compiled-sql obj
            mCompiledSql = new SQLiteCompiledSql(mDatabase, mSql);

            // add it to the cache of compiled-sqls
            // but before adding it and thus making it available for anyone else to use it,
            // make sure it is acquired by me.
            mCompiledSql.acquire();
            mDatabase.addToCompiledQueries(mSql, mCompiledSql);
        } else {
            // it is already in compiled-sql cache.
            // try to acquire the object.
            if (!mCompiledSql.acquire()) {
                int last = mCompiledSql.nStatement;
                // the SQLiteCompiledSql in cache is in use by some other SQLiteProgram object.
                // we can't have two different SQLiteProgam objects can't share the same
                // CompiledSql object. create a new one.
                // finalize it when I am done with it in "this" object.
                mCompiledSql = new SQLiteCompiledSql(mDatabase, mSql);
                // since it is not in the cache, no need to acquire() it.
            }
        }
        nStatement = mCompiledSql.nStatement;
    }

    @Override
    protected void onAllReferencesReleased() {
        release();
        mDatabase.removeSQLiteClosable(this);
        mDatabase.releaseReference();
    }

    @Override
    protected void onAllReferencesReleasedFromContainer() {
        release();
        mDatabase.releaseReference();
    }

    /* package */ void release() {
        if (mCompiledSql == null) {
            return;
        }
        mDatabase.releaseCompiledSqlObj(mSql, mCompiledSql);
        mCompiledSql = null;
        nStatement = 0;
    }

    /**
     * Returns a unique identifier for this program.
     *
     * @return a unique identifier for this program
     * @deprecated do not use this method. it is not guaranteed to be the same across executions of
     * the SQL statement contained in this object.
     */
    @Deprecated
    public final int getUniqueId() {
      return -1;
    }

    /**
     * used only for testing purposes
     */
    /* package */ int getSqlStatementId() {
      synchronized(this) {
        return (mCompiledSql == null) ? 0 : nStatement;
      }
    }

    /* package */ String getSqlString() {
        return mSql;
    }

    /**
     * @deprecated This method is deprecated and must not be used.
     *
     * @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
     */
    @Deprecated
    protected void compile(String sql, boolean forceCompilation) {
        // TODO is there a need for this?
    }

    private void bind(int type, int index, Object value) {
        mDatabase.verifyDbIsOpen();
        addToBindArgs(index, (type == Cursor.FIELD_TYPE_NULL) ? null : value);
        if (nStatement > 0) {
            // bind only if the SQL statement is compiled
            acquireReference();
            try {
                switch (type) {
                    case Cursor.FIELD_TYPE_NULL:
                        native_bind_null(index);
                        break;
                    case Cursor.FIELD_TYPE_BLOB:
                        native_bind_blob(index, (byte[]) value);
                        break;
                    case Cursor.FIELD_TYPE_FLOAT:
                        native_bind_double(index, (Double) value);
                        break;
                    case Cursor.FIELD_TYPE_INTEGER:
                        native_bind_long(index, (Long) value);
                        break;
                    case Cursor.FIELD_TYPE_STRING:
                    default:
                        native_bind_string(index, (String) value);
                        break;
                }
            } finally {
                releaseReference();
            }
        }
    }

    /**
     * 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) {
        bind(Cursor.FIELD_TYPE_NULL, index, null);
    }

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

    /**
     * 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) {
        bind(Cursor.FIELD_TYPE_FLOAT, index, value);
    }

    /**
     * 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");
        }
        bind(Cursor.FIELD_TYPE_STRING, index, value);
    }

    /**
     * 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");
        }
        bind(Cursor.FIELD_TYPE_BLOB, index, value);
    }

    /**
     * Clears all existing bindings. Unset bindings are treated as NULL.
     */
    public void clearBindings() {
        mBindArgs = null;
        if (this.nStatement == 0) {
            return;
        }
        mDatabase.verifyDbIsOpen();
        acquireReference();
        try {
            native_clear_bindings();
        } finally {
            releaseReference();
        }
    }

    /**
     * Release this program's resources, making it invalid.
     */
    public void close() {
        mBindArgs = null;
        if (nHandle == 0 || !mDatabase.isOpen()) {
            return;
        }
        releaseReference();
    }

    private void addToBindArgs(int index, Object value) {
        if (mBindArgs == null) {
            mBindArgs = new HashMap<Integer, Object>();
        }
        mBindArgs.put(index, value);
    }

    /* package */ void compileAndbindAllArgs() {
        if ((mStatementType & STATEMENT_DONT_PREPARE) > 0) {
            if (mBindArgs != null) {
                throw new IllegalArgumentException("Can't pass bindargs for this sql :" + mSql);
            }
            // no need to prepare this SQL statement
            return;
        }
        if (nStatement == 0) {
            // SQL statement is not compiled yet. compile it now.
            compileSql();
        }
        if (mBindArgs == null) {
            return;
        }
        for (int index : mBindArgs.keySet()) {
            Object value = mBindArgs.get(index);
            if (value == null) {
                native_bind_null(index);
            } else if (value instanceof Double || value instanceof Float) {
                native_bind_double(index, ((Number) value).doubleValue());
            } else if (value instanceof Number) {
                native_bind_long(index, ((Number) value).longValue());
            } else if (value instanceof Boolean) {
                Boolean bool = (Boolean)value;
                native_bind_long(index, (bool) ? 1 : 0);
                if (bool) {
                    native_bind_long(index, 1);
                } else {
                    native_bind_long(index, 0);
                }
            } else if (value instanceof byte[]){
                native_bind_blob(index, (byte[]) value);
            } else {
                native_bind_string(index, value.toString());
            }
        }
    }

    /**
     * Given an array of String bindArgs, this method binds all of them in one single call.
     *
     * @param bindArgs the String array of bind args.
     */
    public void bindAllArgsAsStrings(String[] bindArgs) {
        if (bindArgs == null) {
            return;
        }
        int size = bindArgs.length;
        for (int i = 0; i < size; i++) {
            bindString(i + 1, bindArgs[i]);
        }
    }

    /* package */ synchronized final void setNativeHandle(int nHandle) {
        this.nHandle = nHandle;
    }

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

    /**
     * @deprecated This method is deprecated and must not be used.
     */
    @Deprecated
    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();
}