SQLite
Class Database

java.lang.Object
  extended bySQLite.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


Contact: Christian Werner