Package SQLite

Class Database

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

  • Field Summary

    Fields
    Modifier and Type Field Description
    protected int error_code
    Internal last error code for exec() methods.
    protected long handle
    Internal handle for the native SQLite API.

  • Constructor Summary

    Constructors
    Constructor Description
    Database()  

  • Method Summary

    Modifier and Type Method Description
    protected static boolean _enable_shared_cache​(boolean onoff)
    Enable/disable shared cache mode (SQLite 3.x only).
    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.
    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 occured 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​(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.
    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.
    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.
    void trace​(Trace tr)
    Set trace function.
    static String version()
    Return SQLite version number as string.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • handle

      protected long handle
      Internal handle for the native SQLite API.

    • error_code

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

  • Constructor Details

    • Database

      public Database()

  • Method Details

    • 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

    • 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

    • 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

    • 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

    • finalize

      protected void finalize()
      Destructor for object.
      Overrides:
      finalize in class Object

    • close

      public void close() throws Exception
      Close the underlying SQLite database file.
      Throws:
      Exception

    • 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

    • 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

    • last_insert_rowid

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

    • interrupt

      public void interrupt()
      Abort the current SQLite operation.

    • changes

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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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.

    • dbversion

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

    • 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

    • 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

    • 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

    • 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

    • set_last_error

      protected void set_last_error​(int error_code)
      Internal: set error code.
      Parameters:
      error_code - new error code

    • 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

    • set_encoding

      public void set_encoding​(String enc) throws Exception
      Set character encoding.
      Parameters:
      enc - name of encoding
      Throws:
      Exception

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • is3

      public boolean is3()
      Check type of open database.
      Returns:
      true if SQLite3 database

    • 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

    • 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

    • 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

    • 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

    • 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

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

    • 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

    • 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