/* * 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. *

* 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. *

*

* Each entry in the array is a Pair of *

    *
  1. bind arg position number
  2. *
  3. the value to be bound to the bindarg
  4. *
*

* It is lazily initialized in the above bind methods * and it is cleared in {@link #clearBindings()} method. *

* It is protected (in multi-threaded environment) by {@link SQLiteProgram}.this */ /* package */ HashMap 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(); } 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. * *

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(); }