Package 

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.

    Ownership and concurrency guarantees

    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.

    Encapsulation guarantees

    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.

    Reentrance

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

    • Method Detail

      • getConnectionId

         int getConnectionId()

        Gets the unique id of this connection.

      • isPrimaryConnection

         boolean isPrimaryConnection()

        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 compilationprior to execution of the statement. If the {@code outStatementInfo} argumentis not null, the provided SQLiteStatementInfo object is populatedwith information about the statement.

        A prepared statement makes no reference to the arguments that may eventuallybe bound to it, consequently it it possible to cache certain prepared statementssuch 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 poolprovides a method to acquire a connection that already has a given SQL statementin its prepared statement cache so that it is ready for execution.

        Parameters:
        sql - The SQL statement to prepare.
        outStatementInfo - The SQLiteStatementInfo object to populatewith 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.

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

      • executeForBlobFileDescriptor

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

        Executes a statement that returns a single BLOB result as afile 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.

      • executeRaw

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

        Executes a statement that returns a count of the number of rowsthat 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.

      • executeForChangedRowCount

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

        Executes a statement that returns a count of the number of rowsthat 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.

      • executeForLastInsertedRowId

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

        Executes a statement that returns the row id of the last row insertedby 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.

      • 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 countedduring 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.If it won't fit, then the query should discard part of what it filledso that it does.
        countAllRows - True to count all rows that the query would returnregagless of whether they fit in the window.
        cancellationSignal - A signal to cancel the operation in progress, or null if none.

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