SQLite
Class Database

java.lang.Object
  SQLite.Database

public class Database

extends Object

Main class wrapping an SQLite database.

Field Summary

protected int	error_code Internal last error code for exec() methods.
protected long	handle Internal handle for the native SQLite API.

Constructor Summary

Database()

Method Summary

private static void	_backup(Backup b, Database dest, String destName, Database src, String srcName)
private void	_busy_handler(BusyHandler bh)
private void	_busy_timeout(int ms)
private long	_changes()
private void	_close()
private static boolean	_complete(String sql)
private void	_create_aggregate(String name, int nargs, Function f)
private void	_create_function(String name, int nargs, Function f)
private int	_db_status(int op, int[] info, boolean flag)
protected static boolean	_enable_shared_cache(boolean onoff) Enable/disable shared cache mode (SQLite 3.x only).
private String	_errmsg()
private void	_exec(String sql, Callback cb)
private void	_exec(String sql, Callback cb, String[] args)
private void	_finalize()
private void	_function_type(String name, int type)
private void	_interrupt()
private void	_key(byte[] ekey)
private long	_last_insert_rowid()
private void	_open_aux_file(String filename)
private void	_open_blob(String db, String table, String column, long row, boolean rw, Blob blob) Internal SQLite open blob method.
private void	_open(String filename, int mode)
private void	_open4(String filename, int mode, String vfs, boolean ver2)
private void	_profile(Profile pr)
private void	_progress_handler(int n, ProgressHandler p)
private void	_rekey(byte[] ekey)
private void	_set_authorizer(Authorizer auth)
private void	_set_encoding(String enc)
private static int	_status(int op, int[] info, boolean flag)
private void	_trace(Trace tr)
Backup	backup(Database dest, String destName, String srcName) Initiate a database backup, SQLite 3.x only.
void	busy_handler(BusyHandler bh) Establish a busy callback method which gets called when an SQLite table is locked.
void	busy_timeout(int ms) Set the timeout for waiting for an SQLite table to become unlocked.
long	changes() Return the number of changed rows for the last statement.
void	close() Close the underlying SQLite database file.
Vm	compile(String sql) Compile and return SQLite VM for SQL statement.
Vm	compile(String sql, String[] args) Compile and return SQLite VM for SQL statement.
static boolean	complete(String sql) See if an SQL statement is complete.
void	create_aggregate(String name, int nargs, Function f) Create aggregate function.
void	create_function(String name, int nargs, Function f) Create regular function.
int	db_status(int op, int[] info, boolean flag) Return information on SQLite connection status.
String	dbversion() Return SQLite version number as string.
String	error_message() Return last error message of SQLite3 engine.
static String	error_string(int error_code) Return error string given SQLite error code (SQLite2).
void	exec(String sql, Callback cb) Execute an SQL statement and invoke callback methods for each row of the result set.
void	exec(String sql, Callback cb, String[] args) Execute an SQL statement and invoke callback methods for each row of the result set.
protected void	finalize() Destructor for object.
void	function_type(String name, int type) Set function return type.
TableResult	get_table(String sql) Convenience method to retrieve an entire result set into memory.
TableResult	get_table(String sql, int maxrows) Convenience method to retrieve an entire result set into memory.
TableResult	get_table(String sql, int maxrows, String[] args) Convenience method to retrieve an entire result set into memory.
TableResult	get_table(String sql, String[] args) Convenience method to retrieve an entire result set into memory.
void	get_table(String sql, String[] args, TableResult tbl) Convenience method to retrieve an entire result set into memory.
private static void	internal_init() Internal native initializer.
void	interrupt() Abort the current SQLite operation.
boolean	is3() Check type of open database.
static double	julian_from_long(long ms) Make julian date value from java.lang.Date
void	key(byte[] ekey) Specify key for encrypted database.
void	key(String skey) Specify key for encrypted database.
int	last_error() Return the code of the last error occurred in any of the exec() methods.
long	last_insert_rowid() Return the row identifier of the last inserted row.
static long	long_from_julian(double d) Make long value from julian date for java.lang.Date
static long	long_from_julian(String s) Make long value from julian date for java.lang.Date
void	open_aux_file(String filename) Open SQLite auxiliary database file for temporary tables.
Blob	open_blob(String db, String table, String column, long row, boolean rw) Open an SQLite3 blob.
void	open(String filename, int mode) Open an SQLite database file.
void	open(String filename, int mode, String vfs) Open an SQLite database file.
void	open(String filename, int mode, String vfs, boolean ver2) Open an SQLite database file.
Stmt	prepare(String sql) Prepare and return SQLite3 statement for SQL.
void	profile(Profile pr) Set profile function.
void	progress_handler(int n, ProgressHandler p) Establish a progress callback method which gets called after N SQLite VM opcodes.
void	rekey(byte[] ekey) Change the key of a encrypted database.
void	rekey(String skey) Change the key of a encrypted database.
void	set_authorizer(Authorizer auth) Set authorizer function.
void	set_encoding(String enc) Set character encoding.
protected void	set_last_error(int error_code) Internal: set error code.
static int	status(int op, int[] info, boolean flag) Return information on SQLite runtime status.
private void	stmt_prepare(String sql, Stmt stmt) Internal SQLite3 prepare method.
void	trace(Trace tr) Set trace function.
static String	version() Return SQLite version number as string.
private void	vm_compile_args(String sql, Vm vm, String[] args) Internal compile method, SQLite 3.0 only.
private void	vm_compile(String sql, Vm vm) Internal compile method.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

Constructor Detail

Database

public Database()

Method Detail

_backup

private static void _backup(Backup b,
                            Database dest,
                            String destName,
                            Database src,
                            String srcName)
                     throws Exception

Throws:

Exception

_busy_handler

private void _busy_handler(BusyHandler bh)

_busy_timeout

private void _busy_timeout(int ms)

_changes

private long _changes()

_close

private void _close()
             throws Exception

Throws:

Exception

_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)

_db_status

private int _db_status(int op,
                       int[] info,
                       boolean flag)

_enable_shared_cache

protected static boolean _enable_shared_cache(boolean onoff)

Enable/disable shared cache mode (SQLite 3.x only).

Parameters:

onoff - boolean to enable or disable shared cache

Returns:

boolean when true, function supported/succeeded

_errmsg

private String _errmsg()

_exec

private void _exec(String sql,
                   Callback cb)
            throws Exception

Throws:

Exception

_exec

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

Throws:

Exception

_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_aux_file

private void _open_aux_file(String filename)
                     throws Exception

Throws:

Exception

_open_blob

private void _open_blob(String db,
                        String table,
                        String column,
                        long row,
                        boolean rw,
                        Blob blob)
                 throws Exception

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

Throws:

Exception - indicating SQLite error

_open

private void _open(String filename,
                   int mode)
            throws Exception

Throws:

Exception

_open4

private void _open4(String filename,
                    int mode,
                    String vfs,
                    boolean ver2)
             throws Exception

Throws:

Exception

_profile

private void _profile(Profile pr)

_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)
                    throws Exception

Throws:

Exception

_status

private static int _status(int op,
                           int[] info,
                           boolean flag)

_trace

private void _trace(Trace tr)

backup

public Backup backup(Database dest,
                     String destName,
                     String srcName)
              throws Exception

Initiate a database backup, SQLite 3.x only.

Parameters:

dest - destination database

destName - schema of destination database to be backed up

srcName - schema of source database

Returns:

Backup object to perform the backup operation

Throws:

Exception - indicating SQLite error

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.

Returns:

number of changed rows

close

public void close()
           throws Exception

Close the underlying SQLite database file.

Throws:

Exception - indicating SQLite error

compile

public Vm compile(String sql)
           throws Exception

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

Throws:

Exception - indicating SQLite error

compile

public Vm compile(String sql,
                  String[] args)
           throws Exception

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

Throws:

Exception - indicating SQLite error

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

Returns:

true if string is a complete SQL statement

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

db_status

public int db_status(int op,
                     int[] info,
                     boolean flag)

Return information on SQLite connection status. Only available in SQLite 3.6 and above, otherwise a no-op.

Parameters:

op - operation code

info - output buffer, must be able to hold two values (current/highwater)

flag - reset flag

Returns:

SQLite error code

dbversion

public String dbversion()

Return SQLite version number as string. If the database is not open, the string "unknown" is returned.

Returns:

version string

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)
          throws Exception

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

Throws:

Exception - indicating SQLite error

exec

public void exec(String sql,
                 Callback cb,
                 String[] args)
          throws Exception

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

Throws:

Exception - indicating SQLite error

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)
                      throws Exception

Convenience method to retrieve an entire result set into memory.

Parameters:

sql - the SQL statement to be executed

Returns:

result set

Throws:

Exception - indicating SQLite error

get_table

public TableResult get_table(String sql,
                             int maxrows)
                      throws Exception

Convenience method to retrieve an entire result set into memory.

Parameters:

sql - the SQL statement to be executed

maxrows - the max. number of rows to retrieve

Returns:

result set

Throws:

Exception - indicating SQLite error

get_table

public TableResult get_table(String sql,
                             int maxrows,
                             String[] args)
                      throws Exception

Convenience method to retrieve an entire result set into memory.

Parameters:

sql - the SQL statement to be executed

maxrows - the max. number of rows to retrieve

args - arguments for the SQL statement, '%q' substitution

Returns:

result set

Throws:

Exception - indicating SQLite error

get_table

public TableResult get_table(String sql,
                             String[] args)
                      throws Exception

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

Throws:

Exception - indicating SQLite error

get_table

public void get_table(String sql,
                      String[] args,
                      TableResult tbl)
               throws Exception

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

Throws:

Exception - indicating SQLite error

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)
         throws Exception

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

Throws:

Exception - indicating SQLite error

key

public void key(String skey)
         throws Exception

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

Throws:

Exception - indicating SQLite error

last_error

public int last_error()

Return the code of the last error occurred 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.

Returns:

rowid of 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)
                             throws Exception

Make long value from julian date for java.lang.Date

Parameters:

s - string (double value) (julian date in SQLite3 format)

Returns:

long

Throws:

Exception - indicating SQLite error

open_aux_file

public void open_aux_file(String filename)
                   throws Exception

Open SQLite auxiliary database file for temporary tables.

Parameters:

filename - the name of the auxiliary file or null

Throws:

Exception - indicating SQLite error

open_blob

public Blob open_blob(String db,
                      String table,
                      String column,
                      long row,
                      boolean rw)
               throws Exception

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

Throws:

Exception - indicating SQLite error

open

public void open(String filename,
                 int mode)
          throws Exception

Open an SQLite database file.

Parameters:

filename - the name of the database file

mode - open mode (e.g. SQLITE_OPEN_READONLY)

Throws:

Exception - indicating SQLite error

open

public void open(String filename,
                 int mode,
                 String vfs)
          throws Exception

Open an SQLite database file.

Parameters:

filename - the name of the database file

mode - open mode (e.g. SQLITE_OPEN_READONLY)

vfs - VFS name (for SQLite ≥ 3.5)

Throws:

Exception - indicating SQLite error

open

public void open(String filename,
                 int mode,
                 String vfs,
                 boolean ver2)
          throws Exception

Open an SQLite database file.

Parameters:

filename - the name of the database file

mode - open mode (e.g. SQLITE_OPEN_READONLY)

vfs - VFS name (for SQLite ≥ 3.5)

ver2 - flag to force version on create (false = SQLite3, true = SQLite2)

Throws:

Exception - indicating SQLite error

prepare

public Stmt prepare(String sql)
             throws Exception

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

Throws:

Exception - indicating SQLite error

profile

public void profile(Profile pr)

Set profile function. Only available in SQLite 3.6 and above, otherwise a no-op.

Parameters:

pr - the trace function

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)
           throws Exception

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

Throws:

Exception - indicating SQLite error

rekey

public void rekey(String skey)
           throws Exception

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

Throws:

Exception - indicating SQLite error

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)
                  throws Exception

Set character encoding.

Parameters:

enc - name of encoding

Throws:

Exception - indicating SQLite error

set_last_error

protected void set_last_error(int error_code)

Internal: set error code.

Parameters:

error_code - new error code

status

public static int status(int op,
                         int[] info,
                         boolean flag)

Return information on SQLite runtime status. Only available in SQLite 3.6 and above, otherwise a no-op.

Parameters:

op - operation code

info - output buffer, must be able to hold two values (current/highwater)

flag - reset flag

Returns:

SQLite error code

stmt_prepare

private void stmt_prepare(String sql,
                          Stmt stmt)
                   throws Exception

Internal SQLite3 prepare method.

Parameters:

sql - SQL statement

stmt - Stmt object

Throws:

Exception - indicating SQLite error

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.

Returns:

version string

vm_compile_args

private void vm_compile_args(String sql,
                             Vm vm,
                             String[] args)
                      throws Exception

Internal compile method, SQLite 3.0 only.

Parameters:

sql - SQL statement

args - arguments for the SQL statement, '%q' substitution

vm - Vm object

Throws:

Exception - indicating SQLite error

vm_compile

private void vm_compile(String sql,
                        Vm vm)
                 throws Exception

Internal compile method.

Parameters:

sql - SQL statement

vm - Vm object

Throws:

Exception - indicating SQLite error