FileDocCategorySizeDatePackage
Database.javaAPI DocAndroid 1.5 API15324Wed May 06 22:41:06 BST 2009SQLite

Database

public class Database extends Object
Main class wrapping an SQLite database.

Fields Summary
protected long
handle
Internal handle for the native SQLite API.
protected int
error_code
Internal last error code for exec() methods.
Constructors Summary
Methods Summary
private native void_busy_handler(SQLite.BusyHandler bh)

private native void_busy_timeout(int ms)
private native long_changes()
private native void_close()
private static native boolean_complete(java.lang.String sql)
private native void_create_aggregate(java.lang.String name, int nargs, Function f)
private native void_create_function(java.lang.String name, int nargs, Function f)
private native java.lang.String_errmsg()
private native void_exec(java.lang.String sql, SQLite.Callback cb)
private native void_exec(java.lang.String sql, SQLite.Callback cb, java.lang.String[] args)
private native void_finalize()
private native void_function_type(java.lang.String name, int type)
private native void_interrupt()
private native long_last_insert_rowid()
private native void_open(java.lang.String filename, int mode)
private native void_open_aux_file(java.lang.String filename)
private native void_open_blob(java.lang.String db, java.lang.String table, java.lang.String column, long row, boolean rw, Blob blob)
Internal SQLite open blob method.
param
db database name
param
table table name
param
column column name
param
row row identifier
param
rw if true, open for read-write, else read-only
param
blob Blob object
private native void_progress_handler(int n, SQLite.ProgressHandler p)
private native void_set_authorizer(Authorizer auth)
private native void_set_encoding(java.lang.String enc)
private native void_trace(Trace tr)
public voidbusy_handler(SQLite.BusyHandler bh)
Establish a busy callback method which gets called when
an SQLite table is locked.
param
bh the object implementing the busy callback method
    synchronized(this) {
        _busy_handler(bh);
    }
    
public voidbusy_timeout(int ms)
Set the timeout for waiting for an SQLite table to become
unlocked.
param
ms number of millisecond to wait
    synchronized(this) {
        _busy_timeout(ms);
    }
    
public longchanges()
Return the number of changed rows for the last statement.
    synchronized(this) {
        return _changes();
    }
    
public voidclose()
Close the underlying SQLite database file.
    synchronized(this) {
        _close();
    }
    
public Vmcompile(java.lang.String sql)
Compile and return SQLite VM for SQL statement. Only available
in SQLite 2.8.0 and above, otherwise a no-op.
param
sql SQL statement to be compiled
return
a Vm object
    synchronized(this) {
        Vm vm = new Vm();
        vm_compile(sql, vm);
        return vm;
    }
    
public Vmcompile(java.lang.String sql, java.lang.String[] args)
Compile and return SQLite VM for SQL statement. Only available
in SQLite 3.0 and above, otherwise a no-op.
param
sql SQL statement to be compiled
param
args arguments for the SQL statement, '%q' substitution
return
a Vm object
    synchronized(this) {
        Vm vm = new Vm();
        vm_compile_args(sql, vm, args);
        return vm;
    }
    
public static synchronized booleancomplete(java.lang.String sql)
See if an SQL statement is complete.
Returns true if the input string comprises
one or more complete SQL statements.
param
sql the SQL statement to be checked
    return _complete(sql);
    
public voidcreate_aggregate(java.lang.String name, int nargs, Function f)
Create aggregate function.
param
name the name of the new function
param
nargs number of arguments to function
param
f interface of function
    synchronized(this) {
        _create_aggregate(name, nargs, f);
    }
    
public voidcreate_function(java.lang.String name, int nargs, Function f)
Create regular function.
param
name the name of the new function
param
nargs number of arguments to function
param
f interface of function
    synchronized(this) {
        _create_function(name, nargs, f);
    }
    
public native java.lang.Stringdbversion()
Return SQLite version number as string.
If the database is not open, unknown is returned.
public java.lang.Stringerror_message()
Return last error message of SQLite3 engine.
return
error string or null
    synchronized(this) {
        return _errmsg();
    }
    
public static native java.lang.Stringerror_string(int error_code)
Return error string given SQLite error code (SQLite2).
param
error_code the error code
return
error string
public voidexec(java.lang.String sql, SQLite.Callback cb, java.lang.String[] args)
Execute an SQL statement and invoke callback methods
for each row of the result set. Each '%q' or %Q in the
statement string is substituted by its corresponding
element in the argument vector.



Example:


String args[] = new String[1];
args[0] = "tab%";
db.exec("select * from sqlite_master where type like '%q'",
null, args);



It the method fails, an SQLite.Exception is thrown and
an error code is set, which later can be retrieved by
the last_error() method.
param
sql the SQL statement to be executed
param
cb the object implementing the callback methods
param
args arguments for the SQL statement, '%q' substitution
    synchronized(this) {
        _exec(sql, cb, args);
    }
    
public voidexec(java.lang.String sql, SQLite.Callback cb)
Execute an SQL statement and invoke callback methods
for each row of the result set.


It the method fails, an SQLite.Exception is thrown and
an error code is set, which later can be retrieved by
the last_error() method.
param
sql the SQL statement to be executed
param
cb the object implementing the callback methods
    synchronized(this) {
        _exec(sql, cb);
    }
    
protected voidfinalize()
Destructor for object.
    synchronized(this) {
        _finalize();
    }
    
public voidfunction_type(java.lang.String name, int type)
Set function return type. Only available in SQLite 2.6.0 and
above, otherwise a no-op.
param
name the name of the function whose return type is to be set
param
type return type code, e.g. SQLite.Constants.SQLITE_NUMERIC
    synchronized(this) {
        _function_type(name, type);
    }
    
public TableResultget_table(java.lang.String sql)
Convenience method to retrieve an entire result
set into memory.
param
sql the SQL statement to be executed
return
result set
    TableResult ret = new TableResult();
    if (!is3()) {
        exec(sql, ret);
    } else {
        synchronized(this) {
        /* only one statement !!! */
        Vm vm = compile(sql);
        set_last_error(vm.error_code);
        while (vm.step(ret)) {
            set_last_error(vm.error_code);
        }
        vm.finalize();
        }
    }
    return ret;
    
public TableResultget_table(java.lang.String sql, java.lang.String[] args)
Convenience method to retrieve an entire result
set into memory.
param
sql the SQL statement to be executed
param
args arguments for the SQL statement, '%q' substitution
return
result set
    TableResult ret = new TableResult();
    if (!is3()) {
        exec(sql, ret, args);
    } else {
        synchronized(this) {
        /* only one statement !!! */
        Vm vm = compile(sql, args);
        set_last_error(vm.error_code);
        while (vm.step(ret)) {
            set_last_error(vm.error_code);
        }
        vm.finalize();
        }
    }
    return ret;
    
public voidget_table(java.lang.String sql, java.lang.String[] args, TableResult tbl)
Convenience method to retrieve an entire result
set into memory.
param
sql the SQL statement to be executed
param
args arguments for the SQL statement, '%q' substitution
param
tbl TableResult to receive result set
return
result set
    tbl.clear();
    if (!is3()) {
        exec(sql, tbl, args);
    } else {
        synchronized(this) {
        /* only one statement !!! */
        Vm vm = compile(sql, args);
        while (vm.step(tbl)) {
        }
        vm.finalize();
        }
    }
    
private static native voidinternal_init()
Internal native initializer.
public voidinterrupt()
Abort the current SQLite operation.
    synchronized(this) {
        _interrupt();
    }
    
public native booleanis3()
Check type of open database.
return
true if SQLite3 database
public intlast_error()
Return the code of the last error occured in
any of the exec() methods. The value is valid
after an Exception has been reported by one of
these methods. See the Constants
class for possible values.
return
SQLite error code
    return error_code;
    
public longlast_insert_rowid()
Return the row identifier of the last inserted
row.
    synchronized(this) {
        return _last_insert_rowid();
    }
    
public voidopen(java.lang.String filename, int mode)
Open an SQLite database file.
param
filename the name of the database file
param
mode open mode, currently ignored

                            

            
    synchronized(this) {
        _open(filename, mode);
    }
    
public voidopen_aux_file(java.lang.String filename)
Open SQLite auxiliary database file for temporary
tables.
param
filename the name of the auxiliary file or null
    synchronized(this) {
        _open_aux_file(filename);
    }
    
public Blobopen_blob(java.lang.String db, java.lang.String table, java.lang.String column, long row, boolean rw)
Open an SQLite3 blob. Only available in SQLite 3.4.0 and above.
param
db database name
param
table table name
param
column column name
param
row row identifier
param
rw if true, open for read-write, else read-only
return
a Blob object
    synchronized(this) {
        Blob blob = new Blob();
        _open_blob(db, table, column, row, rw, blob);
        return blob;
    }
    
public Stmtprepare(java.lang.String sql)
Prepare and return SQLite3 statement for SQL. Only available
in SQLite 3.0 and above, otherwise a no-op.
param
sql SQL statement to be prepared
return
a Stmt object
    synchronized(this) {
        Stmt stmt = new Stmt();
        stmt_prepare(sql, stmt);
        return stmt;
    }
    
public voidprogress_handler(int n, SQLite.ProgressHandler p)
Establish a progress callback method which gets called after
N SQLite VM opcodes.
param
n number of SQLite VM opcodes until callback is invoked
param
p the object implementing the progress callback method
    synchronized(this) {
        _progress_handler(n, p);
    }
    
public voidset_authorizer(Authorizer auth)
Set authorizer function. Only available in SQLite 2.7.6 and
above, otherwise a no-op.
param
auth the authorizer function
    synchronized(this) {
        _set_authorizer(auth);
    }
    
public voidset_encoding(java.lang.String enc)
Set character encoding.
param
enc name of encoding
    synchronized(this) {
        _set_encoding(enc);
    }
    
protected voidset_last_error(int error_code)
Internal: set error code.
param
error_code new error code
    this.error_code = error_code;
    
private native voidstmt_prepare(java.lang.String sql, Stmt stmt)
Internal SQLite3 prepare method.
param
sql SQL statement
param
stmt Stmt object
public voidtrace(Trace tr)
Set trace function. Only available in SQLite 2.7.6 and above,
otherwise a no-op.
param
tr the trace function
    synchronized(this) {
        _trace(tr);
    }
    
public static native java.lang.Stringversion()
Return SQLite version number as string.
Don't rely on this when both SQLite 2 and 3 are compiled
into the native part. Use the class method in this case.
private native voidvm_compile(java.lang.String sql, Vm vm)
Internal compile method.
param
sql SQL statement
param
vm Vm object
private native voidvm_compile_args(java.lang.String sql, Vm vm, java.lang.String[] args)
Internal compile method, SQLite 3.0 only.
param
sql SQL statement
param
args arguments for the SQL statement, '%q' substitution
param
vm Vm object