41  * at most one read-write transaction is performed at a time.  When WAL is not
51  * has its own session object and therefore its own transaction state independent
64  * There are two kinds of transaction: implicit transactions and explicit
67  * An implicit transaction is created whenever a database operation is requested
68  * and there is no explicit transaction currently in progress.  An implicit transaction
72  * An explicit transaction is started by calling {@link #beginTransaction} and
73  * specifying the desired transaction mode.  Once an explicit transaction has begun,
74  * all subsequent database operations will be performed as part of that transaction.
75  * To end an explicit transaction, first call {@link #setTransactionSuccessful} if the
76  * transaction was successful, then call {@link #end}.  If the transaction was
79  * Explicit transactions can also be nested.  A nested explicit transaction is
82  * If any nested transaction is not marked successful, then the entire transaction
84  * when the outermost transaction is ended.
86  * To improve concurrency, an explicit transaction can be yielded by calling
88  * then yielding ends the current transaction, commits its changes, releases the
90  * new transaction with the same properties as the original one.
93  * When a transaction is started, the client can provide a {@link SQLiteTransactionListener}
94  * to listen for notifications of transaction-related events.
98  * // First, begin the transaction.
104  *     // As the very last step before ending the transaction, mark it successful.
107  *     // Finally, end the transaction.
108  *     // This statement will commit the transaction if it was marked successful or
119  * as needed to perform each requested database transaction.  If all connections
124  * of a single (implicit or explicit) database transaction, then releases it.
133  * a database connection for the entire duration of a database transaction,
140  * run may cause the application UI to become unresponsive.  Even if the transaction
143  * a transaction runs.
175      * In a deferred transaction, no locks are acquired on the database
185      * Because the lock is only acquired when needed in a deferred transaction,
189      * Corresponds to the SQLite <code>BEGIN DEFERRED</code> transaction mode.
197      * When an immediate transaction begins, the session acquires a
203      * Corresponds to the SQLite <code>BEGIN IMMEDIATE</code> transaction mode.
211      * When an exclusive transaction begins, the session acquires an
217      * Corresponds to the SQLite <code>BEGIN EXCLUSIVE</code> transaction mode.
236      * Returns true if the session has a transaction in progress.
238      * @return True if the session has a transaction in progress.
245      * Returns true if the session has a nested transaction in progress.
247      * @return True if the session has a nested transaction in progress.
263      * Begins a transaction.
265      * Transactions may nest.  If the transaction is not in progress,
266      * then a database connection is obtained and a new transaction is started.
267      * Otherwise, a nested transaction is started.
270      * to {@link #endTransaction}.  To mark a transaction as successful,
272      * If the transaction is not successful, or if any of its nested
273      * transactions were not successful, then the entire transaction will
274      * be rolled back when the outermost transaction is ended.
277      * @param transactionMode The transaction mode.  One of: {@link #TRANSACTION_MODE_DEFERRED},
279      * Ignored when creating a nested transaction.
280      * @param transactionListener The transaction listener, or null if none.
286      * called for the current transaction.
313             // Set up the transaction such that we can back out safely
345             Transaction transaction = obtainTransaction(transactionMode, transactionListener);
346             transaction.mParent = mTransactionStack;
347             mTransactionStack = transaction;
356      * Marks the current transaction as having completed successfully.
359      * {@link #endTransaction} to indicate that the changes made by the transaction should be
361      * when the transaction is ended.
364      * @throws IllegalStateException if there is no current transaction, or if
365      * {@link #setTransactionSuccessful} has already been called for the current transaction.
378      * Ends the current transaction and commits or rolls back changes.
380      * If this is the outermost transaction (not nested within any other
381      * transaction), then the changes are committed if {@link #setTransactionSuccessful}
389      * @throws IllegalStateException if there is no current transaction.
452      * Temporarily ends a transaction to let other threads have use of
453      * the database.  Begins a new transaction after a specified delay.
456      * then the current transaction is committed and the database
457      * connection is released.  After a short delay, a new transaction
460      * The transaction is assumed to be successful so far.  Do not call
462      * This method will fail if the transaction has already been marked
468      * a transaction in progress.  When this method returns, there will
469      * still be a transaction in progress, either the same one as before
470      * or a new one if the transaction was actually yielded.
472      * This method should not be called when there is a nested transaction
473      * in progress because it is not possible to yield a nested transaction.
475      * a nested transaction will throw {@link IllegalStateException}, otherwise
478      * If there is no nested transaction in progress but a previous nested
479      * transaction failed, then the transaction is not yielded (because it
486      * delay beyond the time it will take to begin a new transaction.
488      * transaction is in progress, a nested transaction is in progress, or when
489      * the transaction has already been marked successful, throws {@link IllegalStateException}.
491      * @return True if the transaction was actually yielded.
494      * there is no current transaction, there is a nested transaction in progress or
495      * if {@link #setTransactionSuccessful} has already been called for the current transaction.
846      * "COMMIT" and "ROLLBACK" to ensure that transaction state invariants are
916                     + "there is no current transaction.");
923                     + "the transaction has already been marked successful.  The only "
931                     + "a nested transaction is in progress.");
936         Transaction transaction = mTransactionPool;
937         if (transaction != null) {
938             mTransactionPool = transaction.mParent;
939             transaction.mParent = null;
940             transaction.mMarkedSuccessful = false;
941             transaction.mChildFailed = false;
943             transaction = new Transaction();
945         transaction.mMode = mode;
946         transaction.mListener = listener;
947         return transaction;
950     private void recycleTransaction(Transaction transaction) {
951         transaction.mParent = mTransactionPool;
952         transaction.mListener = null;
953         mTransactionPool = transaction;

Indexes created Fri Mar 13 02:32:08 CET 2015