public final class SQLiteSession extends Object
Database access is always performed using a session. The session manages the lifecycle of transactions and database connections.
Sessions can be used to perform both read-only and read-write operations. There is some advantage to knowing when a session is being used for read-only purposes because the connection pool can optimize the use of the available connections to permit multiple read-only operations to execute in parallel whereas read-write operations may need to be serialized.
When Write Ahead Logging (WAL) is enabled, the database can execute simultaneous read-only and read-write transactions, provided that at most one read-write transaction is performed at a time. When WAL is not enabled, read-only transactions can execute in parallel but read-write transactions are mutually exclusive.
Session objects are not thread-safe. In fact, session objects are thread-bound.
The SQLiteDatabase
uses a thread-local variable to associate a session
with each thread for the use of that thread alone. Consequently, each thread
has its own session object and therefore its own transaction state independent
of other threads.
A thread has at most one session per database. This constraint ensures that a thread can never use more than one database connection at a time for a given database. As the number of available database connections is limited, if a single thread tried to acquire multiple connections for the same database at the same time, it might deadlock. Therefore we allow there to be only one session (so, at most one connection) per thread per database.
There are two kinds of transaction: implicit transactions and explicit transactions.
An implicit transaction is created whenever a database operation is requested and there is no explicit transaction currently in progress. An implicit transaction only lasts for the duration of the database operation in question and then it is ended. If the database operation was successful, then its changes are committed.
An explicit transaction is started by calling beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
and
specifying the desired transaction mode. Once an explicit transaction has begun,
all subsequent database operations will be performed as part of that transaction.
To end an explicit transaction, first call setTransactionSuccessful()
if the
transaction was successful, then call #end
. If the transaction was
marked successful, its changes will be committed, otherwise they will be rolled back.
Explicit transactions can also be nested. A nested explicit transaction is
started with beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
, marked successful with
setTransactionSuccessful()
and ended with endTransaction(android.os.CancellationSignal)
.
If any nested transaction is not marked successful, then the entire transaction
including all of its nested transactions will be rolled back
when the outermost transaction is ended.
To improve concurrency, an explicit transaction can be yielded by calling
yieldTransaction(long, boolean, android.os.CancellationSignal)
. If there is contention for use of the database,
then yielding ends the current transaction, commits its changes, releases the
database connection for use by another session for a little while, and starts a
new transaction with the same properties as the original one.
Changes committed by yieldTransaction(long, boolean, android.os.CancellationSignal)
cannot be rolled back.
When a transaction is started, the client can provide a SQLiteTransactionListener
to listen for notifications of transaction-related events.
Recommended usage:
// First, begin the transaction.
session.beginTransaction(SQLiteSession.TRANSACTION_MODE_DEFERRED, 0);
try {
// Then do stuff...
session.execute("INSERT INTO ...", null, 0);
// As the very last step before ending the transaction, mark it successful.
session.setTransactionSuccessful();
} finally {
// Finally, end the transaction.
// This statement will commit the transaction if it was marked successful or
// roll it back otherwise.
session.endTransaction();
}
A SQLiteDatabase
can have multiple active sessions at the same
time. Each session acquires and releases connections to the database
as needed to perform each requested database transaction. If all connections
are in use, then database transactions on some sessions will block until a
connection becomes available.
The session acquires a single database connection only for the duration of a single (implicit or explicit) database transaction, then releases it. This characteristic allows a small pool of database connections to be shared efficiently by multiple sessions as long as they are not all trying to perform database transactions at the same time.
Because there are a limited number of database connections and the session holds
a database connection for the entire duration of a database transaction,
it is important to keep transactions short. This is especially important
for read-write transactions since they may block other transactions
from executing. Consider calling yieldTransaction(long, boolean, android.os.CancellationSignal)
periodically
during long-running transactions.
Another important consideration is that transactions that take too long to run may cause the application UI to become unresponsive. Even if the transaction is executed in a background thread, the user will get bored and frustrated if the application shows no data for several seconds while a transaction runs.
Guidelines:
This class must tolerate reentrant execution of SQLite operations because triggers may call custom SQLite functions that perform additional queries.
Modifier and Type | Field and Description |
---|---|
static int |
TRANSACTION_MODE_DEFERRED
Transaction mode: Deferred.
|
static int |
TRANSACTION_MODE_EXCLUSIVE
Transaction mode: Exclusive.
|
static int |
TRANSACTION_MODE_IMMEDIATE
Transaction mode: Immediate.
|
Constructor and Description |
---|
SQLiteSession(SQLiteConnectionPool connectionPool)
Creates a session bound to the specified connection pool.
|
Modifier and Type | Method and Description |
---|---|
void |
beginTransaction(int transactionMode,
SQLiteTransactionListener transactionListener,
int connectionFlags,
CancellationSignal cancellationSignal)
Begins a transaction.
|
void |
endTransaction(CancellationSignal cancellationSignal)
Ends the current transaction and commits or rolls back changes.
|
void |
execute(String sql,
Object[] bindArgs,
int connectionFlags,
CancellationSignal cancellationSignal)
Executes a statement that does not return a result.
|
ParcelFileDescriptor |
executeForBlobFileDescriptor(String sql,
Object[] bindArgs,
int connectionFlags,
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,
int connectionFlags,
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,
int connectionFlags,
CancellationSignal cancellationSignal)
Executes a statement and populates the specified
CursorWindow
with a range of results. |
long |
executeForLastInsertedRowId(String sql,
Object[] bindArgs,
int connectionFlags,
CancellationSignal cancellationSignal)
Executes a statement that returns the row id of the last row inserted
by the statement.
|
long |
executeForLong(String sql,
Object[] bindArgs,
int connectionFlags,
CancellationSignal cancellationSignal)
Executes a statement that returns a single
long result. |
String |
executeForString(String sql,
Object[] bindArgs,
int connectionFlags,
CancellationSignal cancellationSignal)
Executes a statement that returns a single
String result. |
boolean |
hasConnection()
Returns true if the session has an active database connection.
|
boolean |
hasNestedTransaction()
Returns true if the session has a nested transaction in progress.
|
boolean |
hasTransaction()
Returns true if the session has a transaction in progress.
|
void |
prepare(String sql,
int connectionFlags,
CancellationSignal cancellationSignal,
SQLiteStatementInfo outStatementInfo)
Prepares a statement for execution but does not bind its parameters or execute it.
|
void |
setTransactionSuccessful()
Marks the current transaction as having completed successfully.
|
boolean |
yieldTransaction(long sleepAfterYieldDelayMillis,
boolean throwIfUnsafe,
CancellationSignal cancellationSignal)
Temporarily ends a transaction to let other threads have use of
the database.
|
public static final int TRANSACTION_MODE_DEFERRED
In a deferred transaction, no locks are acquired on the database
until the first operation is performed. If the first operation is
read-only, then a SHARED
lock is acquired, otherwise
a RESERVED
lock is acquired.
While holding a SHARED
lock, this session is only allowed to
read but other sessions are allowed to read or write.
While holding a RESERVED
lock, this session is allowed to read
or write but other sessions are only allowed to read.
Because the lock is only acquired when needed in a deferred transaction, it is possible for another session to write to the database first before this session has a chance to do anything.
Corresponds to the SQLite BEGIN DEFERRED
transaction mode.
public static final int TRANSACTION_MODE_IMMEDIATE
When an immediate transaction begins, the session acquires a
RESERVED
lock.
While holding a RESERVED
lock, this session is allowed to read
or write but other sessions are only allowed to read.
Corresponds to the SQLite BEGIN IMMEDIATE
transaction mode.
public static final int TRANSACTION_MODE_EXCLUSIVE
When an exclusive transaction begins, the session acquires an
EXCLUSIVE
lock.
While holding an EXCLUSIVE
lock, this session is allowed to read
or write but no other sessions are allowed to access the database.
Corresponds to the SQLite BEGIN EXCLUSIVE
transaction mode.
public SQLiteSession(SQLiteConnectionPool connectionPool)
connectionPool
- The connection pool.public boolean hasTransaction()
public boolean hasNestedTransaction()
public boolean hasConnection()
public void beginTransaction(int transactionMode, SQLiteTransactionListener transactionListener, int connectionFlags, CancellationSignal cancellationSignal)
Transactions may nest. If the transaction is not in progress, then a database connection is obtained and a new transaction is started. Otherwise, a nested transaction is started.
Each call to beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
must be matched exactly by a call
to endTransaction(android.os.CancellationSignal)
. To mark a transaction as successful,
call setTransactionSuccessful()
before calling endTransaction(android.os.CancellationSignal)
.
If the transaction is not successful, or if any of its nested
transactions were not successful, then the entire transaction will
be rolled back when the outermost transaction is ended.
transactionMode
- The transaction mode. One of: TRANSACTION_MODE_DEFERRED
,
TRANSACTION_MODE_IMMEDIATE
, or TRANSACTION_MODE_EXCLUSIVE
.
Ignored when creating a nested transaction.transactionListener
- The transaction listener, or null if none.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.cancellationSignal
- A signal to cancel the operation in progress, or null if none.IllegalStateException
- if setTransactionSuccessful()
has already been
called for the current transaction.SQLiteException
- if an error occurs.OperationCanceledException
- if the operation was canceled.setTransactionSuccessful()
,
yieldTransaction(long, boolean, android.os.CancellationSignal)
,
endTransaction(android.os.CancellationSignal)
public void setTransactionSuccessful()
This method can be called at most once between beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
and
endTransaction(android.os.CancellationSignal)
to indicate that the changes made by the transaction should be
committed. If this method is not called, the changes will be rolled back
when the transaction is ended.
IllegalStateException
- if there is no current transaction, or if
setTransactionSuccessful()
has already been called for the current transaction.beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
,
endTransaction(android.os.CancellationSignal)
public void endTransaction(CancellationSignal cancellationSignal)
If this is the outermost transaction (not nested within any other
transaction), then the changes are committed if setTransactionSuccessful()
was called or rolled back otherwise.
This method must be called exactly once for each call to beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
.
cancellationSignal
- A signal to cancel the operation in progress, or null if none.IllegalStateException
- if there is no current transaction.SQLiteException
- if an error occurs.OperationCanceledException
- if the operation was canceled.beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
,
setTransactionSuccessful()
,
yieldTransaction(long, boolean, android.os.CancellationSignal)
public boolean yieldTransaction(long sleepAfterYieldDelayMillis, boolean throwIfUnsafe, CancellationSignal cancellationSignal)
If there are other threads waiting to acquire connections, then the current transaction is committed and the database connection is released. After a short delay, a new transaction is started.
The transaction is assumed to be successful so far. Do not call
setTransactionSuccessful()
before calling this method.
This method will fail if the transaction has already been marked
successful.
The changes that were committed by a yield cannot be rolled back later.
Before this method was called, there must already have been a transaction in progress. When this method returns, there will still be a transaction in progress, either the same one as before or a new one if the transaction was actually yielded.
This method should not be called when there is a nested transaction
in progress because it is not possible to yield a nested transaction.
If throwIfNested
is true, then attempting to yield
a nested transaction will throw IllegalStateException
, otherwise
the method will return false
in that case.
If there is no nested transaction in progress but a previous nested
transaction failed, then the transaction is not yielded (because it
must be rolled back) and this method returns false
.
sleepAfterYieldDelayMillis
- A delay time to wait after yielding
the database connection to allow other threads some time to run.
If the value is less than or equal to zero, there will be no additional
delay beyond the time it will take to begin a new transaction.throwIfUnsafe
- If true, then instead of returning false when no
transaction is in progress, a nested transaction is in progress, or when
the transaction has already been marked successful, throws IllegalStateException
.cancellationSignal
- A signal to cancel the operation in progress, or null if none.IllegalStateException
- if throwIfNested
is true and
there is no current transaction, there is a nested transaction in progress or
if setTransactionSuccessful()
has already been called for the current transaction.SQLiteException
- if an error occurs.OperationCanceledException
- if the operation was canceled.beginTransaction(int, android.database.sqlite.SQLiteTransactionListener, int, android.os.CancellationSignal)
,
endTransaction(android.os.CancellationSignal)
public void prepare(String sql, int connectionFlags, CancellationSignal cancellationSignal, 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 and reused if possible.
sql
- The SQL statement to prepare.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.cancellationSignal
- A signal to cancel the operation in progress, or null if none.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.OperationCanceledException
- if the operation was canceled.public void execute(String sql, Object[] bindArgs, int connectionFlags, CancellationSignal cancellationSignal)
sql
- The SQL statement to execute.bindArgs
- The arguments to bind, or null if none.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.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, int connectionFlags, CancellationSignal cancellationSignal)
long
result.sql
- The SQL statement to execute.bindArgs
- The arguments to bind, or null if none.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.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, int connectionFlags, CancellationSignal cancellationSignal)
String
result.sql
- The SQL statement to execute.bindArgs
- The arguments to bind, or null if none.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.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, int connectionFlags, CancellationSignal cancellationSignal)
sql
- The SQL statement to execute.bindArgs
- The arguments to bind, or null if none.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.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, int connectionFlags, CancellationSignal cancellationSignal)
sql
- The SQL statement to execute.bindArgs
- The arguments to bind, or null if none.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.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, int connectionFlags, CancellationSignal cancellationSignal)
sql
- The SQL statement to execute.bindArgs
- The arguments to bind, or null if none.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.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, int connectionFlags, 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.connectionFlags
- The connection flags to use if a connection must be
acquired by this operation. Refer to SQLiteConnectionPool
.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.