SQLite

Class Database

public class Database extends Object

Main class wrapping an SQLite database.
Field Summary
protected interror_code
Internal last error code for exec() methods.
protected longhandle
Internal handle for the native SQLite API.
Method Summary
voidbusy_handler(BusyHandler bh)
Establish a busy callback method which gets called when an SQLite table is locked.
voidbusy_timeout(int ms)
Set the timeout for waiting for an SQLite table to become unlocked.
longchanges()
Return the number of changed rows for the last statement.
voidclose()
Close the underlying SQLite database file.
Vmcompile(String sql)
Compile and return SQLite VM for SQL statement.
Vmcompile(String sql, String[] args)
Compile and return SQLite VM for SQL statement.
static booleancomplete(String sql)
See if an SQL statement is complete.
voidcreate_aggregate(String name, int nargs, Function f)
Create aggregate function.
voidcreate_function(String name, int nargs, Function f)
Create regular function.
Stringdbversion()
Return SQLite version number as string.
Stringerror_message()
Return last error message of SQLite3 engine.
static Stringerror_string(int error_code)
Return error string given SQLite error code (SQLite2).
voidexec(String sql, 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.

voidexec(String sql, Callback cb, String[] args)
Execute an SQL statement and invoke callback methods for each row of the result set.
protected voidfinalize()
Destructor for object.
voidfunction_type(String name, int type)
Set function return type.
TableResultget_table(String sql)
Convenience method to retrieve an entire result set into memory.
TableResultget_table(String sql, String[] args)
Convenience method to retrieve an entire result set into memory.
voidget_table(String sql, String[] args, TableResult tbl)
Convenience method to retrieve an entire result set into memory.
static voidinternal_init()
Internal native initializer.
voidinterrupt()
Abort the current SQLite operation.
booleanis3()
Check type of open database.
static doublejulian_from_long(long ms)
Make julian date value from java.lang.Date
voidkey(byte[] ekey)
Specify key for encrypted database.
voidkey(String skey)
Specify key for encrypted database.
intlast_error()
Return the code of the last error occured in any of the exec() methods.
longlast_insert_rowid()
Return the row identifier of the last inserted row.
static longlong_from_julian(double d)
Make long value from julian date for java.lang.Date
static longlong_from_julian(String s)
Make long value from julian date for java.lang.Date
voidopen(String filename, int mode)
Open an SQLite database file.
voidopen_aux_file(String filename)
Open SQLite auxiliary database file for temporary tables.
Blobopen_blob(String db, String table, String column, long row, boolean rw)
Open an SQLite3 blob.
Stmtprepare(String sql)
Prepare and return SQLite3 statement for SQL.
voidprogress_handler(int n, ProgressHandler p)
Establish a progress callback method which gets called after N SQLite VM opcodes.
voidrekey(byte[] ekey)
Change the key of a encrypted database.
voidrekey(String skey)
Change the key of a encrypted database.
voidset_authorizer(Authorizer auth)
Set authorizer function.
voidset_encoding(String enc)
Set character encoding.
protected voidset_last_error(int error_code)
Internal: set error code.
voidstmt_prepare(String sql, Stmt stmt)
Internal SQLite3 prepare method.
voidtrace(Trace tr)
Set trace function.
static Stringversion()
Return SQLite version number as string.
voidvm_compile(String sql, Vm vm)
Internal compile method.
voidvm_compile_args(String sql, Vm vm, String[] args)
Internal compile method, SQLite 3.0 only.
void_busy_handler(BusyHandler bh)
void_busy_timeout(int ms)
long_changes()
void_close()
static boolean_complete(String sql)
void_create_aggregate(String name, int nargs, Function f)
void_create_function(String name, int nargs, Function f)
String_errmsg()
void_exec(String sql, Callback cb)
void_exec(String sql, Callback cb, String[] args)
void_finalize()
void_function_type(String name, int type)
void_interrupt()
void_key(byte[] ekey)
long_last_insert_rowid()
void_open(String filename, int mode)
void_open_aux_file(String filename)
void_open_blob(String db, String table, String column, long row, boolean rw, Blob blob)
Internal SQLite open blob method.
void_progress_handler(int n, ProgressHandler p)
void_rekey(byte[] ekey)
void_set_authorizer(Authorizer auth)
void_set_encoding(String enc)
void_trace(Trace tr)

Field Detail

error_code

protected int error_code
Internal last error code for exec() methods.

handle

protected long handle
Internal handle for the native SQLite API.

Method Detail

busy_handler

public void busy_handler(BusyHandler bh)
Establish a busy callback method which gets called when an SQLite table is locked.

Parameters: bh the object implementing the busy callback method

busy_timeout

public void busy_timeout(int ms)
Set the timeout for waiting for an SQLite table to become unlocked.

Parameters: ms number of millisecond to wait

changes

public long changes()
Return the number of changed rows for the last statement.

close

public void close()
Close the underlying SQLite database file.

compile

public Vm compile(String sql)
Compile and return SQLite VM for SQL statement. Only available in SQLite 2.8.0 and above, otherwise a no-op.

Parameters: sql SQL statement to be compiled

Returns: a Vm object

compile

public Vm compile(String sql, String[] args)
Compile and return SQLite VM for SQL statement. Only available in SQLite 3.0 and above, otherwise a no-op.

Parameters: sql SQL statement to be compiled args arguments for the SQL statement, '%q' substitution

Returns: a Vm object

complete

public static boolean complete(String sql)
See if an SQL statement is complete. Returns true if the input string comprises one or more complete SQL statements.

Parameters: sql the SQL statement to be checked

create_aggregate

public void create_aggregate(String name, int nargs, Function f)
Create aggregate function.

Parameters: name the name of the new function nargs number of arguments to function f interface of function

create_function

public void create_function(String name, int nargs, Function f)
Create regular function.

Parameters: name the name of the new function nargs number of arguments to function f interface of function

dbversion

public String dbversion()
Return SQLite version number as string. If the database is not open, unknown is returned.

error_message

public String error_message()
Return last error message of SQLite3 engine.

Returns: error string or null

error_string

public static String error_string(int error_code)
Return error string given SQLite error code (SQLite2).

Parameters: error_code the error code

Returns: error string

exec

public void exec(String sql, 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.

Parameters: sql the SQL statement to be executed cb the object implementing the callback methods

exec

public void exec(String sql, Callback cb, 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.

Parameters: sql the SQL statement to be executed cb the object implementing the callback methods args arguments for the SQL statement, '%q' substitution

finalize

protected void finalize()
Destructor for object.

function_type

public void function_type(String name, int type)
Set function return type. Only available in SQLite 2.6.0 and above, otherwise a no-op.

Parameters: name the name of the function whose return type is to be set type return type code, e.g. SQLite.Constants.SQLITE_NUMERIC

get_table

public TableResult get_table(String sql)
Convenience method to retrieve an entire result set into memory.

Parameters: sql the SQL statement to be executed

Returns: result set

get_table

public TableResult get_table(String sql, String[] args)
Convenience method to retrieve an entire result set into memory.

Parameters: sql the SQL statement to be executed args arguments for the SQL statement, '%q' substitution

Returns: result set

get_table

public void get_table(String sql, String[] args, TableResult tbl)
Convenience method to retrieve an entire result set into memory.

Parameters: sql the SQL statement to be executed args arguments for the SQL statement, '%q' substitution tbl TableResult to receive result set

Returns: result set

internal_init

private static void internal_init()
Internal native initializer.

interrupt

public void interrupt()
Abort the current SQLite operation.

is3

public boolean is3()
Check type of open database.

Returns: true if SQLite3 database

julian_from_long

public static double julian_from_long(long ms)
Make julian date value from java.lang.Date

Parameters: ms millisecond value of java.lang.Date

Returns: double

key

public void key(byte[] ekey)
Specify key for encrypted database. To be called right after open() on SQLite3 databases. Not available in public releases of SQLite.

Parameters: ekey the key as byte array

key

public void key(String skey)
Specify key for encrypted database. To be called right after open() on SQLite3 databases. Not available in public releases of SQLite.

Parameters: skey the key as String

last_error

public int last_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.

Returns: SQLite error code

last_insert_rowid

public long last_insert_rowid()
Return the row identifier of the last inserted row.

long_from_julian

public static long long_from_julian(double d)
Make long value from julian date for java.lang.Date

Parameters: d double value (julian date in SQLite3 format)

Returns: long

long_from_julian

public static long long_from_julian(String s)
Make long value from julian date for java.lang.Date

Parameters: s string (double value) (julian date in SQLite3 format)

Returns: long

open

public void open(String filename, int mode)
Open an SQLite database file.

Parameters: filename the name of the database file mode open mode, currently ignored

open_aux_file

public void open_aux_file(String filename)
Open SQLite auxiliary database file for temporary tables.

Parameters: filename the name of the auxiliary file or null

open_blob

public Blob open_blob(String db, String table, String column, long row, boolean rw)
Open an SQLite3 blob. Only available in SQLite 3.4.0 and above.

Parameters: db database name table table name column column name row row identifier rw if true, open for read-write, else read-only

Returns: a Blob object

prepare

public Stmt prepare(String sql)
Prepare and return SQLite3 statement for SQL. Only available in SQLite 3.0 and above, otherwise a no-op.

Parameters: sql SQL statement to be prepared

Returns: a Stmt object

progress_handler

public void progress_handler(int n, ProgressHandler p)
Establish a progress callback method which gets called after N SQLite VM opcodes.

Parameters: n number of SQLite VM opcodes until callback is invoked p the object implementing the progress callback method

rekey

public void rekey(byte[] ekey)
Change the key of a encrypted database. The SQLite3 database must have been open()ed. Not available in public releases of SQLite.

Parameters: ekey the key as byte array

rekey

public void rekey(String skey)
Change the key of a encrypted database. The SQLite3 database must have been open()ed. Not available in public releases of SQLite.

Parameters: skey the key as String

set_authorizer

public void set_authorizer(Authorizer auth)
Set authorizer function. Only available in SQLite 2.7.6 and above, otherwise a no-op.

Parameters: auth the authorizer function

set_encoding

public void set_encoding(String enc)
Set character encoding.

Parameters: enc name of encoding

set_last_error

protected void set_last_error(int error_code)
Internal: set error code.

Parameters: error_code new error code

stmt_prepare

private void stmt_prepare(String sql, Stmt stmt)
Internal SQLite3 prepare method.

Parameters: sql SQL statement stmt Stmt object

trace

public void trace(Trace tr)
Set trace function. Only available in SQLite 2.7.6 and above, otherwise a no-op.

Parameters: tr the trace function

version

public static String version()
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.

vm_compile

private void vm_compile(String sql, Vm vm)
Internal compile method.

Parameters: sql SQL statement vm Vm object

vm_compile_args

private void vm_compile_args(String sql, Vm vm, String[] args)
Internal compile method, SQLite 3.0 only.

Parameters: sql SQL statement args arguments for the SQL statement, '%q' substitution vm Vm object

_busy_handler

private void _busy_handler(BusyHandler bh)

_busy_timeout

private void _busy_timeout(int ms)

_changes

private long _changes()

_close

private void _close()

_complete

private static boolean _complete(String sql)

_create_aggregate

private void _create_aggregate(String name, int nargs, Function f)

_create_function

private void _create_function(String name, int nargs, Function f)

_errmsg

private String _errmsg()

_exec

private void _exec(String sql, Callback cb)

_exec

private void _exec(String sql, Callback cb, String[] args)

_finalize

private void _finalize()

_function_type

private void _function_type(String name, int type)

_interrupt

private void _interrupt()

_key

private void _key(byte[] ekey)

_last_insert_rowid

private long _last_insert_rowid()

_open

private void _open(String filename, int mode)

_open_aux_file

private void _open_aux_file(String filename)

_open_blob

private void _open_blob(String db, String table, String column, long row, boolean rw, Blob blob)
Internal SQLite open blob method.

Parameters: db database name table table name column column name row row identifier rw if true, open for read-write, else read-only blob Blob object

_progress_handler

private void _progress_handler(int n, ProgressHandler p)

_rekey

private void _rekey(byte[] ekey)

_set_authorizer

private void _set_authorizer(Authorizer auth)

_set_encoding

private void _set_encoding(String enc)

_trace

private void _trace(Trace tr)
Contact: Christian Werner