Geodatabase transactions provide an editing pattern that allows a set of edits to be committed or rolled back as a single batch. When initiated by the user, these batched edits are known as explicit transactions. Explicit transactions are only available when editing a mobile geodatabase on the device (also called a local geodatabase). See the discussion of mobile geodatabases in the Work with data files topic to learn how to create a mobile geodatabase.
Note that editing is not supported for a mobile geodatabase created in ArcGIS Pro that contains a controller dataset, such as a utility network or parcel fabric. Feature tables in such a geodatabase are read-only.
When to use explicit transactions
Explicit transactions are useful in a variety of scenarios, such as the following.
-
A mobile worker collecting data in the field realizes they have entered several edits for the incorrect feature. If your app uses transactions for data input, the worker can roll back the set of erroneous edits and try inputting the data for the correct feature.
-
Complex data architectures, such as a representation of an electrical network, require that a single edit touches several feature tables. Using a transaction ensures that all these required table updates are saved together or fail together.
-
While adding a new subnetwork controller in a utility network, a designer might need to create features, establish associations between them, and run a trace to verify the subnetwork. All these steps can be done in an explicit transaction so that the assets and their relationships can be saved to the geodatabase together, or rolled back together (in case of an error in the design).
Make edits inside 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 Geodatabase.isInTransaction() to check whether or not the geodatabase has a current transaction.
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).
End a transaction by committing or rolling back edits. To make further further edits and manage them in a transaction, call Geodatabase.beginTransaction() to start a new one.
Commit edits
To store all edits made in the active transaction, call Geodatabase.commitTransaction(). The edits will be saved to the local geodatabase.
Rollback edits
To reject all edits made in the active transaction, call Geodatabase.rollbackTransaction(). The edits will not be saved to the local geodatabase.
If you're unexpectedly disconnected from the database, any active transaction will be automatically 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.
Handle changes in transaction state (optional)
Your app can listen for changes in the transaction state. The event you receive indicates whether a transaction is beginning or ending.
You might use this information to enable and disable editing controls as appropriate.
Synchronization vs explicit transaction
It is important to distinguish between synchronization of the local geodatabase and creating an explicit transaction on the local geodatabase.
Synchronization keeps your local geodatabase up to date with the feature service from which it was generated. Use Geodatabase.hasLocalEdits() to check if there are any new edits saved to the local geodatabase since the last time you synchronized. The method ArcGISFeatureTable.getLocalEditsAsync() returns those edits saved to the local geodatabase but not yet synchronized. Geodatabase has other methods that work with local edits as well; see GeodatabaseFeatureTable and search for LocalEdits.
An explicit transaction groups together edits that you want to treat as a unit, saving them to the local geodatabase or rolling them back. You can have multiple transactions between synchronizations.
One geodatabase transaction at a time
There can be only one transaction active in your app at a time. It is important to note that a transaction can be created in two different ways:
- Explicitly in your code by calling
Geodatabase.beginTransaction(). - Internally by Java Maps SDK when you synchronize the local geodatabase with the feature service from which it was generated.
Whether you create an explicit transaction or Java Maps SDK creates an internal transaction, you can still have only one transaction. Therefore, you should not:
- Start a new explicit transaction until you have called
commitTransaction()orrollbackTransaction()to end the current one. - Start an explicit transaction during a synchronization of the local geodatabase with the feature service.
- Synchronize the data while you still have an explicit transaction active.
The safest way to enforce these restrictions is to check the Geodatabase.isInTransaction() property before starting, committing, or rolling back an explicit transaction. Attempting to start more than one transaction at the same time will return an error stating that a transaction is already in progress.
Immediate transaction mode
Java Maps SDK uses the immediate transaction mode supported by SQLite. When you begin a transaction, the geodatabase will be locked for writing. Other processes on your device can read the geodatabase, but will not be able to write or see your uncommitted edits. Immediate transaction mode is the reason you can have only one transaction on the local geodatabase at a time.