Package net.zetetic.database.sqlcipher

Class SQLiteConnection

  • All Implemented Interfaces:
    android.os.CancellationSignal.OnCancelListener 
    
public final class SQLiteConnection
 implements CancellationSignal.OnCancelListener

    Represents a SQLite database connection. Each connection wraps an instance of a native sqlite3 object.

    When database connection pooling is enabled, there can be multiple active connections to the same database. Otherwise there is typically only one connection per database.

    When the SQLite WAL feature is enabled, multiple readers and one writer can concurrently access the database. Without WAL, readers and writers are mutually exclusive.

    Connection objects are not thread-safe. They are acquired as needed to perform a database operation and are then returned to the pool. At any given time, a connection is either owned and used by a SQLiteSession object or the SQLiteConnectionPool. Those classes are responsible for serializing operations to guard against concurrent use of a connection.

    The guarantee of having a single owner allows this class to be implemented without locks and greatly simplifies resource management.

    The connection object object owns *all* of the SQLite related native objects that are associated with the connection. What's more, there are no other objects in the system that are capable of obtaining handles to those native objects. Consequently, when the connection is closed, we do not have to worry about what other components might have references to its associated SQLite state -- there are none.

    Encapsulation is what ensures that the connection object's lifecycle does not become a tortured mess of finalizers and reference queues.

    This class must tolerate reentrant execution of SQLite operations because triggers may call custom SQLite functions that perform additional queries.

    • Constructor Detail

    • Method Detail

      • getConnectionId

         int getConnectionId()

        Gets the unique id of this connection.

        Returns:

        The connection id.

      • isPrimaryConnection

         boolean isPrimaryConnection()

        Returns true if this is the primary database connection.

        Returns:

        True if this is the primary database connection.

      • prepare

         void prepare(String sql, SQLiteStatementInfo outStatementInfo)

        Prepares a statement for execution but does not bind its parameters or execute it.

        This method can be used to check for syntax errors during compilation prior to execution of the statement. If the outStatementInfo argument is not null, the provided SQLiteStatementInfo object is populated with information about the statement.

        A prepared statement makes no reference to the arguments that may eventually be bound to it, consequently it it possible to cache certain prepared statements such as SELECT or INSERT/UPDATE statements. If the statement is cacheable, then it will be stored in the cache for later.

        To take advantage of this behavior as an optimization, the connection pool provides a method to acquire a connection that already has a given SQL statement in its prepared statement cache so that it is ready for execution.

        Parameters:
        sql - The SQL statement to prepare.
        outStatementInfo - The SQLiteStatementInfo object to populate with information about the statement, or null if none.

      • execute

         void execute(String sql, Array<Object> bindArgs, CancellationSignal cancellationSignal)

        Executes a statement that does not return a result.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.

      • executeForLong

         long executeForLong(String sql, Array<Object> bindArgs, CancellationSignal cancellationSignal)

        Executes a statement that returns a single long result.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.
        Returns:

        The value of the first column in the first row of the result set as a long, or zero if none.

      • executeForString

         String executeForString(String sql, Array<Object> bindArgs, CancellationSignal cancellationSignal)

        Executes a statement that returns a single String result.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.
        Returns:

        The value of the first column in the first row of the result set as a String, or null if none.

      • executeForBlobFileDescriptor

         ParcelFileDescriptor executeForBlobFileDescriptor(String sql, Array<Object> bindArgs, CancellationSignal cancellationSignal)

        Executes a statement that returns a single BLOB result as a file descriptor to a shared memory region.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.
        Returns:

        The file descriptor for a shared memory region that contains the value of the first column in the first row of the result set as a BLOB, or null if none.

      • executeRaw

         void executeRaw(String sql, Array<Object> bindArgs, CancellationSignal cancellationSignal)

        Executes a statement that returns a count of the number of rows that were changed. Use for UPDATE or DELETE SQL statements.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.
        Returns:

        The number of rows that were changed.

      • executeForChangedRowCount

         int executeForChangedRowCount(String sql, Array<Object> bindArgs, CancellationSignal cancellationSignal)

        Executes a statement that returns a count of the number of rows that were changed. Use for UPDATE or DELETE SQL statements.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.
        Returns:

        The number of rows that were changed.

      • executeForLastInsertedRowId

         long executeForLastInsertedRowId(String sql, Array<Object> bindArgs, CancellationSignal cancellationSignal)

        Executes a statement that returns the row id of the last row inserted by the statement. Use for INSERT SQL statements.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.
        Returns:

        The row id of the last row that was inserted, or 0 if none.

      • executeForCursorWindow

         int executeForCursorWindow(String sql, Array<Object> bindArgs, CursorWindow window, int startPos, int requiredPos, boolean countAllRows, CancellationSignal cancellationSignal)

        Executes a statement and populates the specified CursorWindow with a range of results. Returns the number of rows that were counted during query execution.

        Parameters:
        sql - The SQL statement to execute.
        bindArgs - The arguments to bind, or null if none.
        window - The cursor window to clear and fill.
        startPos - The start position for filling the window.
        requiredPos - The position of a row that MUST be in the window.
        countAllRows - True to count all rows that the query would return regagless of whether they fit in the window.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.
        Returns:

        The number of rows that were counted during query execution. Might not be all rows in the result set unless countAllRows is true.

      • dump

         void dump(Printer printer, boolean verbose)

        Dumps debugging information about this connection.

        Parameters:
        printer - The printer to receive the dump, not null.
        verbose - True to dump more verbose information.