ArcGIS Runtime SDK for iOS

Use geodatabase transactions

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 SDK provides an API to manage your geodatabase edits using transactions, and to commit or roll them back as appropriate.

Note:

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.

  1. 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.
  2. 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).
  3. 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.
    1. Commit edits: To store all edits made in the transaction, call commitTransaction.
    2. Rollback edits: To discard all edits and end the transaction, call rollbackTransaction.
  4. Handle changes in transaction state [optional]: You can observe the InTransaction property on the geodatabase to identify when the geodatabase transactions begin and end. You might use this event to enable and disable editing controls as appropriate.

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. Attempting to start a transaction when one is already active will result in an error.

Database locking

ArcGIS Runtime SDK 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 SDK 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.

Working in a transaction

The most common use of transactions is to manage a group of edits as a single unit of work. Sometimes, however, you might want to use transactions without making edits, such as ensuring that the current set of features will be unchanged during an operation. When a transaction is active, the geodatabase is locked for editing. That means that (apart from your own edits), you can be sure that features won't be added to (or removed from) the database while you're working in the transaction.

Things you can do in a transaction:

  • Add or delete features
  • Update feature geometry
  • Update feature attributes
  • Add, delete, or update feature attachments
  • Add, delete, or update related features

Things you cannot do in a transaction:

  • Synchronize the local geodatabase with a service (geodatabase synch uses its own transaction)
  • Begin another transaction (nested transactions are not supported)

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.

Caution:

Calling commit or rollback without a current transaction will result in an exception.

Commit a transaction if all edits succeed

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.

Note:

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.

Rollback a transaction if an edit fails