public final class SQLiteConnection extends Object implements CancellationSignal.OnCancelListener
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.
Modifier and Type | Method and Description |
---|---|
void |
dump(Printer printer,
boolean verbose)
Dumps debugging information about this connection.
|
void |
execute(String sql,
Object[] bindArgs,
CancellationSignal cancellationSignal)
Executes a statement that does not return a result.
|
ParcelFileDescriptor |
executeForBlobFileDescriptor(String sql,
Object[] bindArgs,
CancellationSignal cancellationSignal)
Executes a statement that returns a single BLOB result as a
file descriptor to a shared memory region.
|
int |
executeForChangedRowCount(String sql,
Object[] bindArgs,
CancellationSignal cancellationSignal)
Executes a statement that returns a count of the number of rows
that were changed.
|
int |
executeForCursorWindow(String sql,
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. |
long |
executeForLastInsertedRowId(String sql,
Object[] bindArgs,
CancellationSignal cancellationSignal)
Executes a statement that returns the row id of the last row inserted
by the statement.
|
long |
executeForLong(String sql,
Object[] bindArgs,
CancellationSignal cancellationSignal)
Executes a statement that returns a single
long result. |
String |
executeForString(String sql,
Object[] bindArgs,
CancellationSignal cancellationSignal)
Executes a statement that returns a single
String result. |
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
int |
getConnectionId()
Gets the unique id of this connection.
|
boolean |
isPrimaryConnection()
Returns true if this is the primary database connection.
|
void |
onCancel()
Called when
CancellationSignal.cancel() is invoked. |
void |
prepare(String sql,
SQLiteStatementInfo outStatementInfo)
Prepares a statement for execution but does not bind its parameters or execute it.
|
String |
toString()
Returns a string representation of the object.
|
protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
public int getConnectionId()
public boolean isPrimaryConnection()
public void prepare(String sql, SQLiteStatementInfo outStatementInfo)
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.
sql
- The SQL statement to prepare.outStatementInfo
- The SQLiteStatementInfo
object to populate
with information about the statement, or null if none.SQLiteException
- if an error occurs, such as a syntax error.public void execute(String sql, Object[] bindArgs, CancellationSignal cancellationSignal)
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.SQLiteException
- if an error occurs, such as a syntax error
or invalid number of bind arguments.OperationCanceledException
- if the operation was canceled.public long executeForLong(String sql, Object[] bindArgs, CancellationSignal cancellationSignal)
long
result.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.long
, or zero if none.SQLiteException
- if an error occurs, such as a syntax error
or invalid number of bind arguments.OperationCanceledException
- if the operation was canceled.public String executeForString(String sql, Object[] bindArgs, CancellationSignal cancellationSignal)
String
result.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.String
, or null if none.SQLiteException
- if an error occurs, such as a syntax error
or invalid number of bind arguments.OperationCanceledException
- if the operation was canceled.public ParcelFileDescriptor executeForBlobFileDescriptor(String sql, Object[] bindArgs, CancellationSignal cancellationSignal)
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.SQLiteException
- if an error occurs, such as a syntax error
or invalid number of bind arguments.OperationCanceledException
- if the operation was canceled.public int executeForChangedRowCount(String sql, Object[] bindArgs, CancellationSignal cancellationSignal)
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.SQLiteException
- if an error occurs, such as a syntax error
or invalid number of bind arguments.OperationCanceledException
- if the operation was canceled.public long executeForLastInsertedRowId(String sql, Object[] bindArgs, CancellationSignal cancellationSignal)
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.SQLiteException
- if an error occurs, such as a syntax error
or invalid number of bind arguments.OperationCanceledException
- if the operation was canceled.public int executeForCursorWindow(String sql, Object[] bindArgs, CursorWindow window, int startPos, int requiredPos, boolean countAllRows, CancellationSignal cancellationSignal)
CursorWindow
with a range of results. Returns the number of rows that were counted
during query execution.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 filled
so that it does. Must be greater than or equal to startPos
.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.countAllRows
is true.SQLiteException
- if an error occurs, such as a syntax error
or invalid number of bind arguments.OperationCanceledException
- if the operation was canceled.public void onCancel()
CancellationSignal.OnCancelListener
CancellationSignal.cancel()
is invoked.onCancel
in interface CancellationSignal.OnCancelListener
public void dump(Printer printer, boolean verbose)
printer
- The printer to receive the dump, not null.verbose
- True to dump more verbose information.public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())