FileDocCategorySizeDatePackage
SQLiteProgram.javaAPI DocAndroid 1.5 API8567Wed May 06 22:41:54 BST 2009android.database.sqlite

SQLiteProgram

public abstract class SQLiteProgram extends SQLiteClosable
A base class for compiled SQLite programs.

Fields Summary
private static final String
TAG
protected SQLiteDatabase
mDatabase
The database this program is compiled against.
protected int
nHandle
Native linkage, do not modify. This comes from the database and should not be modified in here or in the native code.
protected int
nStatement
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.
private StackTraceElement[]
mStackTraceElements
Used to find out where a cursor was allocated in case it never got released.
Constructors Summary
SQLiteProgram(SQLiteDatabase db, String sql)

    
 
    /* package */     
        if (SQLiteDebug.DEBUG_SQL_STATEMENTS) {
            mStackTraceElements = new Exception().getStackTrace();
        }
        
        mDatabase = db;
        db.acquireReference();
        db.addSQLiteClosable(this);
        this.nHandle = db.mNativeHandle;
        compile(sql, false);
Methods Summary
public voidbindBlob(int index, byte[] 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

        if (value == null) {
            throw new IllegalArgumentException("the bind value at index " + index + " is null");
        }
        acquireReference();
        try {
            native_bind_blob(index, value);
        } finally {
            releaseReference();
        }
public voidbindDouble(int index, double 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

        acquireReference();
        try {
            native_bind_double(index, value);
        } finally {
            releaseReference();
        }
public voidbindLong(int index, long value)
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

        acquireReference();
        try {
            native_bind_long(index, value);
        } finally {
            releaseReference();
        }
public voidbindNull(int index)
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

        acquireReference();
        try {
            native_bind_null(index);
        } finally {
            releaseReference();
        }
public voidbindString(int index, java.lang.String 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

        if (value == null) {
            throw new IllegalArgumentException("the bind value at index " + index + " is null");
        }
        acquireReference();
        try {
            native_bind_string(index, value);
        } finally {
            releaseReference();
        }
public voidclearBindings()
Clears all existing bindings. Unset bindings are treated as NULL.

        acquireReference();
        try {
            native_clear_bindings();
        } finally {
            releaseReference();
        }
public voidclose()
Release this program's resources, making it invalid.

        mDatabase.lock();
        try {
            releaseReference();
        } finally {
            mDatabase.unlock();
        }
protected voidcompile(java.lang.String sql, boolean forceCompilation)
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.

Note: this method acquires the database lock.

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

        // 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();
            }        
        }
protected voidfinalize()
Make sure that the native resource is cleaned up.

        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();
        }
public final intgetUniqueId()
Returns a unique identifier for this program.

return
a unique identifier for this program

        return nStatement;
protected final native voidnative_bind_blob(int index, byte[] value)

protected final native voidnative_bind_double(int index, double value)
protected final native voidnative_bind_long(int index, long value)
protected final native voidnative_bind_null(int index)
protected final native voidnative_bind_string(int index, java.lang.String value)
private final native voidnative_clear_bindings()
protected final native voidnative_compile(java.lang.String sql)
Compiles SQL into a SQLite program.


The database lock must be held when calling this method.
param
sql The SQL to compile.
protected final native voidnative_finalize()
protected voidonAllReferencesReleased()
        // Note that native_finalize() checks to make sure that nStatement is
        // non-null before destroying it.
        native_finalize();
        mDatabase.releaseReference();
        mDatabase.removeSQLiteClosable(this);
    
protected voidonAllReferencesReleasedFromContainer()
        // Note that native_finalize() checks to make sure that nStatement is
        // non-null before destroying it.
        native_finalize();
        mDatabase.releaseReference();