A transaction manages a series of geodatabase edits as a single unit of work. If all edits in a transaction are successful, it can be committed and saved to the geodatabase. If a transaction encounters errors and must be canceled, it is rolled back to discard all edits. ArcGIS Runtime provides an API to manage your geodatabase edits using transactions and to commit or roll them back as appropriate.
While the use of transactions is available for editing local geodatabases, it is not required. If it works better for your workflow, you can continue to make edits directly to your data without the use of transactions.
The following steps describe a general workflow for using transactions to manage local geodatabase edits.
- Start a transaction: You can start a transaction by calling beginTransaction on the geodatabase that contains the data you want to edit. The transaction stays active until you end it either by committing or rolling back. Use inTransaction to check whether or not the geodatabase has a current transaction.
- Make edits: Add or delete features, update feature geometry and attributes, edit feature attachments and related features, and so on. All edits you make will be included in the current transaction. You can include individual edits as well as bulk edits (inserting a set of features, for example). You cannot synchronize the local geodatabase with a service (geodatabase sync uses its own transaction). You cannot begin another transaction (nested transactions are not supported).
- End the transaction: End a transaction by committing or rolling back edits. If you want to make additional edits and manage them in a transaction, you need to call beginTransaction to start a new one.
- Commit edits: To store all edits made in the transaction, call commitTransaction.
- Rollback edits: To discard all edits and end the transaction, call rollbackTransaction.
- Handle changes in transaction state (optional): You can handle the inTransactionChanged signal to observe the inTransaction property to see when transactions begin and end. You might use this information to enable and disable editing controls as appropriate.
ArcGIS Runtime uses the immediate transaction mode supported by SQLite. When you begin a transaction, the geodatabase will be locked for writing. Others can read the geodatabase, but they will not be able to write or to see your uncommitted edits. The immediate transaction mode allows only one transaction at a time, so attempting to begin a transaction when one is active will result in an error. Use the inTransaction property on the geodatabase to see if there is a current transaction.
ArcGIS Runtime starts a transaction internally when synchronizing geodatabase edits to a service. Therefore, if you attempt to begin a transaction during synchronization, you will receive an error that states a transaction is already in progress. Likewise, if you attempt to synchronize the database inside your own transaction, you will receive the same error.
Commit or rollback to end a transaction
A geodatabase transaction stays active until you end it by calling commitTransaction or rollbackTransaction. All edits made between the beginTransaction call that started the transaction and this call are part of the transaction. commitTransaction saves all edits in the transaction to the geodatabase and ends the transaction. rollbackTransaction discards all edits in the transaction and ends the transaction.
Calling commit or rollback without a current transaction will result in an exception.
Transactions allow you to manage a set of edits as a single unit. This may be required when working with edits that must either succeed or fail as a group. This is similar to a financial transaction, where you might want to deposit a check and withdraw part of it. If the check cannot be deposited, you should not attempt to make the withdrawal. Similarly, if any edit that's part of a geodatabase transaction fails, you can rollback all edits.
ArcGIS Runtime internally manages some operations within a transaction. Synchronizing a geodatabase with a service or making bulk edits (inserting a set of features, for example) are both handled in a transaction that will be rolled back if any of the edits fail.
If you're unexpectedly disconnected from the database, any active transaction will be rolled back. If the app crashes, or the user closes the app without saving edits, for example, the transaction will be rolled back and the edits discarded.