Class NativeDB

java.lang.Object
org.sqlite.core.DB
org.sqlite.core.NativeDB
All Implemented Interfaces:
Codes

public final class NativeDB extends DB
This class provides a thin JNI layer over the SQLite3 C API.
  • Field Details

    • logger

      private static final Logger logger
    • DEFAULT_BACKUP_BUSY_SLEEP_TIME_MILLIS

      private static final int DEFAULT_BACKUP_BUSY_SLEEP_TIME_MILLIS
      See Also:
    • DEFAULT_BACKUP_NUM_BUSY_BEFORE_FAIL

      private static final int DEFAULT_BACKUP_NUM_BUSY_BEFORE_FAIL
      See Also:
    • DEFAULT_PAGES_PER_BACKUP_STEP

      private static final int DEFAULT_PAGES_PER_BACKUP_STEP
      See Also:
    • pointer

      private long pointer
      SQLite connection handle.
    • isLoaded

      private static boolean isLoaded
    • loadSucceeded

      private static boolean loadSucceeded
    • busyHandler

      private long busyHandler
      busy handler pointer to JNI global busyhandler reference.
    • commitListener

      private long commitListener
    • updateListener

      private long updateListener
    • progressHandler

      private long progressHandler
      handler pointer to JNI global progressHandler reference.
  • Constructor Details

  • Method Details

    • load

      public static boolean load() throws Exception
      Loads the SQLite interface backend.
      Returns:
      True if the SQLite JDBC driver is successfully loaded; false otherwise.
      Throws:
      Exception
    • _open

      protected void _open(String file, int openFlags) throws SQLException
      Description copied from class: DB
      Creates an SQLite interface to a database with the provided open flags.
      Specified by:
      _open in class DB
      Parameters:
      file - The database to open.
      openFlags - File opening configurations (https://www.sqlite.org/c3ref/c_open_autoproxy.html)
      Throws:
      SQLException
      See Also:
    • _open_utf8

      void _open_utf8(byte[] fileUtf8, int openFlags) throws SQLException
      Throws:
      SQLException
    • _close

      protected void _close() throws SQLException
      Description copied from class: DB
      Closes the SQLite interface to a database.
      Specified by:
      _close in class DB
      Throws:
      SQLException
      See Also:
    • _exec

      public int _exec(String sql) throws SQLException
      Description copied from class: DB
      Complies, evaluates, executes and commits an SQL statement.
      Specified by:
      _exec in class DB
      Parameters:
      sql - An SQL statement.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • _exec_utf8

      int _exec_utf8(byte[] sqlUtf8) throws SQLException
      Throws:
      SQLException
    • shared_cache

      public int shared_cache(boolean enable)
      Description copied from class: DB
      Enables or disables the sharing of the database cache and schema data structures between connections to the same database.
      Specified by:
      shared_cache in class DB
      Parameters:
      enable - True to enable; false otherwise.
      Returns:
      Result Codes
      See Also:
    • enable_load_extension

      public int enable_load_extension(boolean enable)
      Description copied from class: DB
      Enables or disables loading of SQLite extensions.
      Specified by:
      enable_load_extension in class DB
      Parameters:
      enable - True to enable; false otherwise.
      Returns:
      Result Codes
      See Also:
    • interrupt

      public void interrupt()
      Description copied from class: DB
      Aborts any pending operation and returns at its earliest opportunity.
      Specified by:
      interrupt in class DB
      See Also:
    • busy_timeout

      public void busy_timeout(int ms)
      Description copied from class: DB
      Sets a busy handler that sleeps for a specified amount of time when a table is locked.
      Specified by:
      busy_timeout in class DB
      Parameters:
      ms - Time to sleep in milliseconds.
      See Also:
    • busy_handler

      public void busy_handler(BusyHandler busyHandler)
      Description copied from class: DB
      Sets a busy handler that sleeps for a specified amount of time when a table is locked.
      Specified by:
      busy_handler in class DB
      Parameters:
      busyHandler -
      See Also:
    • prepare

      protected SafeStmtPtr prepare(String sql) throws SQLException
      Description copied from class: DB
      Complies an SQL statement.
      Specified by:
      prepare in class DB
      Parameters:
      sql - An SQL statement.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • prepare_utf8

      long prepare_utf8(byte[] sqlUtf8) throws SQLException
      Throws:
      SQLException
    • errmsg

      String errmsg()
      Description copied from class: DB
      Return English-language text that describes the error as either UTF-8 or UTF-16.
      Specified by:
      errmsg in class DB
      Returns:
      Error description in English.
      See Also:
    • errmsg_utf8

      ByteBuffer errmsg_utf8()
    • libversion

      public String libversion()
      Description copied from class: DB
      Returns the value for SQLITE_VERSION, SQLITE_VERSION_NUMBER, and SQLITE_SOURCE_ID C preprocessor macros that are associated with the library.
      Specified by:
      libversion in class DB
      Returns:
      Compile-time SQLite version information.
      See Also:
    • libversion_utf8

      ByteBuffer libversion_utf8()
    • changes

      public long changes()
      Specified by:
      changes in class DB
      Returns:
      Number of rows that were changed, inserted or deleted by the last SQL statement
      See Also:
    • total_changes

      public long total_changes()
      Specified by:
      total_changes in class DB
      Returns:
      Number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened.
      See Also:
    • finalize

      protected int finalize(long stmt)
      Description copied from class: DB
      Destroys a prepared statement.
      Specified by:
      finalize in class DB
      Parameters:
      stmt - Pointer to the statement pointer.
      Returns:
      Result Codes
      See Also:
    • step

      public int step(long stmt)
      Description copied from class: DB
      Evaluates a statement.
      Specified by:
      step in class DB
      Parameters:
      stmt - Pointer to the statement.
      Returns:
      Result Codes
      See Also:
    • reset

      public int reset(long stmt)
      Description copied from class: DB
      Sets a prepared statement object back to its initial state, ready to be re-executed.
      Specified by:
      reset in class DB
      Parameters:
      stmt - Pointer to the statement.
      Returns:
      Result Codes
      See Also:
    • clear_bindings

      public int clear_bindings(long stmt)
      Description copied from class: DB
      Reset all bindings on a prepared statement (reset all host parameters to NULL).
      Specified by:
      clear_bindings in class DB
      Parameters:
      stmt - Pointer to the statement.
      Returns:
      Result Codes
      See Also:
    • bind_parameter_count

      int bind_parameter_count(long stmt)
      Specified by:
      bind_parameter_count in class DB
      Parameters:
      stmt - Pointer to the statement.
      Returns:
      Number of parameters in a prepared SQL.
      See Also:
    • column_count

      public int column_count(long stmt)
      Specified by:
      column_count in class DB
      Parameters:
      stmt - Pointer to the statement.
      Returns:
      Number of columns in the result set returned by the prepared statement.
      See Also:
    • column_type

      public int column_type(long stmt, int col)
      Specified by:
      column_type in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      Datatype code for the initial data type of the result column.
      See Also:
    • column_decltype

      public String column_decltype(long stmt, int col)
      Specified by:
      column_decltype in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      Declared type of the table column for prepared statement.
      See Also:
    • column_decltype_utf8

      ByteBuffer column_decltype_utf8(long stmt, int col)
    • column_table_name

      public String column_table_name(long stmt, int col)
      Specified by:
      column_table_name in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      Original text of column name which is the declared in the CREATE TABLE statement.
      See Also:
    • column_table_name_utf8

      ByteBuffer column_table_name_utf8(long stmt, int col)
    • column_name

      public String column_name(long stmt, int col)
      Specified by:
      column_name in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - The number of column.
      Returns:
      Name assigned to a particular column in the result set of a SELECT statement.
      See Also:
    • column_name_utf8

      ByteBuffer column_name_utf8(long stmt, int col)
    • column_text

      public String column_text(long stmt, int col)
      Specified by:
      column_text in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      Value of the column as text data type in the result set of a SELECT statement.
      See Also:
    • column_text_utf8

      ByteBuffer column_text_utf8(long stmt, int col)
    • column_blob

      public byte[] column_blob(long stmt, int col)
      Specified by:
      column_blob in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      BLOB value of the column in the result set of a SELECT statement
      See Also:
    • column_double

      public double column_double(long stmt, int col)
      Specified by:
      column_double in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      DOUBLE value of the column in the result set of a SELECT statement
      See Also:
    • column_long

      public long column_long(long stmt, int col)
      Specified by:
      column_long in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      LONG value of the column in the result set of a SELECT statement.
      See Also:
    • column_int

      public int column_int(long stmt, int col)
      Specified by:
      column_int in class DB
      Parameters:
      stmt - Pointer to the statement.
      col - Number of column.
      Returns:
      INT value of column in the result set of a SELECT statement.
      See Also:
    • bind_null

      int bind_null(long stmt, int pos)
      Description copied from class: DB
      Binds NULL value to prepared statements with the pointer to the statement object and the index of the SQL parameter to be set to NULL.
      Specified by:
      bind_null in class DB
      Parameters:
      stmt - Pointer to the statement.
      pos - The index of the SQL parameter to be set to NULL.
      Returns:
      Result Codes
      See Also:
    • bind_int

      int bind_int(long stmt, int pos, int v)
      Description copied from class: DB
      Binds int value to prepared statements with the pointer to the statement object, the index of the SQL parameter to be set and the value to bind to the parameter.
      Specified by:
      bind_int in class DB
      Parameters:
      stmt - Pointer to the statement.
      pos - The index of the SQL parameter to be set.
      v - Value to bind to the parameter.
      Returns:
      Result Codes
      See Also:
    • bind_long

      int bind_long(long stmt, int pos, long v)
      Description copied from class: DB
      Binds long value to prepared statements with the pointer to the statement object, the index of the SQL parameter to be set and the value to bind to the parameter.
      Specified by:
      bind_long in class DB
      Parameters:
      stmt - Pointer to the statement.
      pos - The index of the SQL parameter to be set.
      v - Value to bind to the parameter.
      Returns:
      Result Codes
      See Also:
    • bind_double

      int bind_double(long stmt, int pos, double v)
      Description copied from class: DB
      Binds double value to prepared statements with the pointer to the statement object, the index of the SQL parameter to be set and the value to bind to the parameter.
      Specified by:
      bind_double in class DB
      Parameters:
      stmt - Pointer to the statement.
      pos - Index of the SQL parameter to be set.
      v - Value to bind to the parameter.
      Returns:
      Result Codes
      See Also:
    • bind_text

      int bind_text(long stmt, int pos, String v)
      Description copied from class: DB
      Binds text value to prepared statements with the pointer to the statement object, the index of the SQL parameter to be set and the value to bind to the parameter.
      Specified by:
      bind_text in class DB
      Parameters:
      stmt - Pointer to the statement.
      pos - Index of the SQL parameter to be set.
      v - value to bind to the parameter.
      Returns:
      Result Codes
      See Also:
    • bind_text_utf8

      int bind_text_utf8(long stmt, int pos, byte[] vUtf8)
    • bind_blob

      int bind_blob(long stmt, int pos, byte[] v)
      Description copied from class: DB
      Binds blob value to prepared statements with the pointer to the statement object, the index of the SQL parameter to be set and the value to bind to the parameter.
      Specified by:
      bind_blob in class DB
      Parameters:
      stmt - Pointer to the statement.
      pos - Index of the SQL parameter to be set.
      v - Value to bind to the parameter.
      Returns:
      Result Codes
      See Also:
    • result_null

      public void result_null(long context)
      Description copied from class: DB
      Sets the result of an SQL function as NULL with the pointer to the SQLite database context.
      Specified by:
      result_null in class DB
      Parameters:
      context - Pointer to the SQLite database context.
      See Also:
    • result_text

      public void result_text(long context, String val)
      Description copied from class: DB
      Sets the result of an SQL function as text data type with the pointer to the SQLite database context and the the result value of String.
      Specified by:
      result_text in class DB
      Parameters:
      context - Pointer to the SQLite database context.
      val - Result value of an SQL function.
      See Also:
    • result_text_utf8

      void result_text_utf8(long context, byte[] valUtf8)
    • result_blob

      public void result_blob(long context, byte[] val)
      Description copied from class: DB
      Sets the result of an SQL function as blob data type with the pointer to the SQLite database context and the the result value of byte array.
      Specified by:
      result_blob in class DB
      Parameters:
      context - Pointer to the SQLite database context.
      val - Result value of an SQL function.
      See Also:
    • result_double

      public void result_double(long context, double val)
      Description copied from class: DB
      Sets the result of an SQL function as double data type with the pointer to the SQLite database context and the the result value of double.
      Specified by:
      result_double in class DB
      Parameters:
      context - Pointer to the SQLite database context.
      val - Result value of an SQL function.
      See Also:
    • result_long

      public void result_long(long context, long val)
      Description copied from class: DB
      Sets the result of an SQL function as long data type with the pointer to the SQLite database context and the the result value of long.
      Specified by:
      result_long in class DB
      Parameters:
      context - Pointer to the SQLite database context.
      val - Result value of an SQL function.
      See Also:
    • result_int

      public void result_int(long context, int val)
      Description copied from class: DB
      Sets the result of an SQL function as int data type with the pointer to the SQLite database context and the the result value of int.
      Specified by:
      result_int in class DB
      Parameters:
      context - Pointer to the SQLite database context.
      val - Result value of an SQL function.
      See Also:
    • result_error

      public void result_error(long context, String err)
      Description copied from class: DB
      Sets the result of an SQL function as an error with the pointer to the SQLite database context and the the error of String.
      Specified by:
      result_error in class DB
      Parameters:
      context - Pointer to the SQLite database context.
      err - Error result of an SQL function.
      See Also:
    • result_error_utf8

      void result_error_utf8(long context, byte[] errUtf8)
    • value_text

      public String value_text(Function f, int arg)
      Specified by:
      value_text in class DB
      Parameters:
      f - SQLite function object.
      arg - Pointer to the parameter of the SQLite function or aggregate.
      Returns:
      Parameter value of the given SQLite function or aggregate in text data type.
      See Also:
    • value_text_utf8

      ByteBuffer value_text_utf8(Function f, int argUtf8)
    • value_blob

      public byte[] value_blob(Function f, int arg)
      Specified by:
      value_blob in class DB
      Parameters:
      f - SQLite function object.
      arg - Pointer to the parameter of the SQLite function or aggregate.
      Returns:
      Parameter value of the given SQLite function or aggregate in blob data type.
      See Also:
    • value_double

      public double value_double(Function f, int arg)
      Specified by:
      value_double in class DB
      Parameters:
      f - SQLite function object.
      arg - Pointer to the parameter of the SQLite function or aggregate.
      Returns:
      Parameter value of the given SQLite function or aggregate in double data type
      See Also:
    • value_long

      public long value_long(Function f, int arg)
      Specified by:
      value_long in class DB
      Parameters:
      f - SQLite function object.
      arg - Pointer to the parameter of the SQLite function or aggregate.
      Returns:
      Parameter value of the given SQLite function or aggregate in long data type.
      See Also:
    • value_int

      public int value_int(Function f, int arg)
      Description copied from class: DB
      Accesses the parameter values on the function or aggregate in int data type with the function object and the parameter value.
      Specified by:
      value_int in class DB
      Parameters:
      f - SQLite function object.
      arg - Pointer to the parameter of the SQLite function or aggregate.
      Returns:
      Parameter value of the given SQLite function or aggregate.
      See Also:
    • value_type

      public int value_type(Function f, int arg)
      Specified by:
      value_type in class DB
      Parameters:
      f - SQLite function object.
      arg - Pointer to the parameter of the SQLite function or aggregate.
      Returns:
      Parameter datatype of the function or aggregate in int data type.
      See Also:
    • create_function

      public int create_function(String name, Function func, int nArgs, int flags) throws SQLException
      Description copied from class: DB
      Create a user defined function with given function name and the function object.
      Specified by:
      create_function in class DB
      Parameters:
      name - The function name to be created.
      func - SQLite function object.
      flags - Extra flags to use when creating the function, such as Function.FLAG_DETERMINISTIC
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • create_function_utf8

      int create_function_utf8(byte[] nameUtf8, Function func, int nArgs, int flags)
    • destroy_function

      public int destroy_function(String name) throws SQLException
      Description copied from class: DB
      De-registers a user defined function
      Specified by:
      destroy_function in class DB
      Parameters:
      name - Name of the function to de-registered.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • destroy_function_utf8

      int destroy_function_utf8(byte[] nameUtf8)
    • create_collation

      public int create_collation(String name, Collation coll) throws SQLException
      Description copied from class: DB
      Create a user defined collation with given collation name and the collation object.
      Specified by:
      create_collation in class DB
      Parameters:
      name - The collation name to be created.
      coll - SQLite collation object.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • create_collation_utf8

      int create_collation_utf8(byte[] nameUtf8, Collation coll)
    • destroy_collation

      public int destroy_collation(String name) throws SQLException
      Description copied from class: DB
      Create a user defined collation with given collation name and the collation object.
      Specified by:
      destroy_collation in class DB
      Parameters:
      name - The collation name to be created.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • destroy_collation_utf8

      int destroy_collation_utf8(byte[] nameUtf8)
    • limit

      public int limit(int id, int value) throws SQLException
      Specified by:
      limit in class DB
      Parameters:
      id - The id of the limit.
      value - The new value of the limit.
      Returns:
      The prior value of the limit
      Throws:
      SQLException
      See Also:
    • nameToUtf8ByteArray

      private byte[] nameToUtf8ByteArray(String nameType, String name) throws SQLException
      Throws:
      SQLException
    • backup

      public int backup(String dbName, String destFileName, DB.ProgressObserver observer) throws SQLException
      Specified by:
      backup in class DB
      Parameters:
      dbName - Database name to be backed up.
      destFileName - Target backup file name.
      observer - ProgressObserver object.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • backup

      public int backup(String dbName, String destFileName, DB.ProgressObserver observer, int sleepTimeMillis, int nTimeouts, int pagesPerStep) throws SQLException
      Specified by:
      backup in class DB
      Parameters:
      dbName - Database name to be backed up.
      destFileName - Target backup file name.
      observer - ProgressObserver object.
      sleepTimeMillis - time to wait during a backup/restore operation if sqlite3_backup_step returns SQLITE_BUSY before continuing
      nTimeouts - the number of times sqlite3_backup_step can return SQLITE_BUSY before failing
      pagesPerStep - the number of pages to copy in each sqlite3_backup_step. If this is negative, the entire DB is copied at once.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • backup

      int backup(byte[] dbNameUtf8, byte[] destFileNameUtf8, DB.ProgressObserver observer, int sleepTimeMillis, int nTimeouts, int pagesPerStep) throws SQLException
      Throws:
      SQLException
    • restore

      public int restore(String dbName, String sourceFileName, DB.ProgressObserver observer) throws SQLException
      Specified by:
      restore in class DB
      Parameters:
      dbName - Database name for restoring data.
      sourceFileName - Source file name.
      observer - ProgressObserver object.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • restore

      public int restore(String dbName, String sourceFileName, DB.ProgressObserver observer, int sleepTimeMillis, int nTimeouts, int pagesPerStep) throws SQLException
      Specified by:
      restore in class DB
      Parameters:
      dbName - the name of the db to restore
      sourceFileName - the filename of the source db to restore
      observer - ProgressObserver object.
      sleepTimeMillis - time to wait during a backup/restore operation if sqlite3_backup_step returns SQLITE_BUSY before continuing
      nTimeouts - the number of times sqlite3_backup_step can return SQLITE_BUSY before failing
      pagesPerStep - the number of pages to copy in each sqlite3_backup_step. If this is negative, the entire DB is copied at once.
      Returns:
      Result Codes
      Throws:
      SQLException
      See Also:
    • restore

      int restore(byte[] dbNameUtf8, byte[] sourceFileName, DB.ProgressObserver observer, int sleepTimeMillis, int nTimeouts, int pagesPerStep) throws SQLException
      Throws:
      SQLException
    • column_metadata

      boolean[][] column_metadata(long stmt)
      Provides metadata for table columns.
      Specified by:
      column_metadata in class DB
      Parameters:
      stmt - Pointer to the statement.
      Returns:
      Column attribute array.
      index[col][0] = true if column constrained NOT NULL;
      index[col][1] = true if column is part of the primary key;
      index[col][2] = true if column is auto-increment.
      See Also:
    • set_commit_listener

      void set_commit_listener(boolean enabled)
      Specified by:
      set_commit_listener in class DB
    • set_update_listener

      void set_update_listener(boolean enabled)
      Specified by:
      set_update_listener in class DB
    • throwex

      static void throwex(String msg) throws SQLException
      Throws an SQLException. Called from native code
      Parameters:
      msg - Message for the SQLException.
      Throws:
      SQLException - the generated SQLException
    • stringToUtf8ByteArray

      static byte[] stringToUtf8ByteArray(String str)
    • utf8ByteBufferToString

      static String utf8ByteBufferToString(ByteBuffer buffer)
    • register_progress_handler

      public void register_progress_handler(int vmCalls, ProgressHandler progressHandler) throws SQLException
      Description copied from class: DB
      Progress handler
      Specified by:
      register_progress_handler in class DB
      Throws:
      SQLException
    • clear_progress_handler

      public void clear_progress_handler() throws SQLException
      Specified by:
      clear_progress_handler in class DB
      Throws:
      SQLException
    • getBusyHandler

      long getBusyHandler()
      Getter for native pointer to validate memory is properly cleaned up in unit tests
      Returns:
      a native pointer to validate memory is properly cleaned up in unit tests
    • getCommitListener

      long getCommitListener()
      Getter for native pointer to validate memory is properly cleaned up in unit tests
      Returns:
      a native pointer to validate memory is properly cleaned up in unit tests
    • getUpdateListener

      long getUpdateListener()
      Getter for native pointer to validate memory is properly cleaned up in unit tests
      Returns:
      a native pointer to validate memory is properly cleaned up in unit tests
    • getProgressHandler

      long getProgressHandler()
      Getter for native pointer to validate memory is properly cleaned up in unit tests
      Returns:
      a native pointer to validate memory is properly cleaned up in unit tests
    • serialize

      public byte[] serialize(String schema) throws SQLException
      Specified by:
      serialize in class DB
      Throws:
      SQLException
    • deserialize

      public void deserialize(String schema, byte[] buff) throws SQLException
      Specified by:
      deserialize in class DB
      Throws:
      SQLException