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