org.sqlite.database.sqlite

Class SQLiteConnection

java.lang.Object

org.sqlite.database.sqlite.SQLiteConnection

All Implemented Interfaces:

android.os.CancellationSignal.OnCancelListener

public final class SQLiteConnection
extends java.lang.Object
implements android.os.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 Summary

Modifier and Type	Method and Description
void	dump(android.util.Printer printer, boolean verbose) Dumps debugging information about this connection.
void	enableLocalizedCollators()
void	execute(java.lang.String sql, java.lang.Object[] bindArgs, android.os.CancellationSignal cancellationSignal) Executes a statement that does not return a result.
android.os.ParcelFileDescriptor	executeForBlobFileDescriptor(java.lang.String sql, java.lang.Object[] bindArgs, android.os.CancellationSignal cancellationSignal) Executes a statement that returns a single BLOB result as a file descriptor to a shared memory region.
int	executeForChangedRowCount(java.lang.String sql, java.lang.Object[] bindArgs, android.os.CancellationSignal cancellationSignal) Executes a statement that returns a count of the number of rows that were changed.
int	executeForCursorWindow(java.lang.String sql, java.lang.Object[] bindArgs, android.database.CursorWindow window, int startPos, int requiredPos, boolean countAllRows, android.os.CancellationSignal cancellationSignal) Executes a statement and populates the specified CursorWindow with a range of results.
long	executeForLastInsertedRowId(java.lang.String sql, java.lang.Object[] bindArgs, android.os.CancellationSignal cancellationSignal) Executes a statement that returns the row id of the last row inserted by the statement.
long	executeForLong(java.lang.String sql, java.lang.Object[] bindArgs, android.os.CancellationSignal cancellationSignal) Executes a statement that returns a single long result.
java.lang.String	executeForString(java.lang.String sql, java.lang.Object[] bindArgs, android.os.CancellationSignal cancellationSignal) Executes a statement that returns a single String result.
protected void	finalize()
int	getConnectionId() Gets the unique id of this connection.
static boolean	hasCodec()
boolean	isPrimaryConnection() Returns true if this is the primary database connection.
void	onCancel()
void	prepare(java.lang.String sql, SQLiteStatementInfo outStatementInfo) Prepares a statement for execution but does not bind its parameters or execute it.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

hasCodec

public static boolean hasCodec()

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

enableLocalizedCollators

public void enableLocalizedCollators()

getConnectionId

public int getConnectionId()

Gets the unique id of this connection.

Returns:

The connection id.

isPrimaryConnection

public boolean isPrimaryConnection()

Returns true if this is the primary database connection.

Returns:

True if this is the primary database connection.

prepare

public void prepare(java.lang.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.

Throws:

SQLiteException - if an error occurs, such as a syntax error.

execute

public void execute(java.lang.String sql,
                    java.lang.Object[] bindArgs,
                    android.os.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.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

android.os.OperationCanceledException - if the operation was canceled.

executeForLong

public long executeForLong(java.lang.String sql,
                           java.lang.Object[] bindArgs,
                           android.os.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.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

android.os.OperationCanceledException - if the operation was canceled.

executeForString

public java.lang.String executeForString(java.lang.String sql,
                                         java.lang.Object[] bindArgs,
                                         android.os.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.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

android.os.OperationCanceledException - if the operation was canceled.

executeForBlobFileDescriptor

public android.os.ParcelFileDescriptor executeForBlobFileDescriptor(java.lang.String sql,
                                                                    java.lang.Object[] bindArgs,
                                                                    android.os.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.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

android.os.OperationCanceledException - if the operation was canceled.

executeForChangedRowCount

public int executeForChangedRowCount(java.lang.String sql,
                                     java.lang.Object[] bindArgs,
                                     android.os.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.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

android.os.OperationCanceledException - if the operation was canceled.

executeForLastInsertedRowId

public long executeForLastInsertedRowId(java.lang.String sql,
                                        java.lang.Object[] bindArgs,
                                        android.os.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.

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

android.os.OperationCanceledException - if the operation was canceled.

executeForCursorWindow

public int executeForCursorWindow(java.lang.String sql,
                                  java.lang.Object[] bindArgs,
                                  android.database.CursorWindow window,
                                  int startPos,
                                  int requiredPos,
                                  boolean countAllRows,
                                  android.os.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. 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.

Returns:

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

Throws:

SQLiteException - if an error occurs, such as a syntax error or invalid number of bind arguments.

android.os.OperationCanceledException - if the operation was canceled.

onCancel

public void onCancel()

Specified by:

onCancel in interface android.os.CancellationSignal.OnCancelListener

dump

public void dump(android.util.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.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object