LuciadCPillar offers support for persisting model changes, making a distinction between in-memory changes and the saving of feature data to a file or a database, for example.
When an IFeatureModelIFeatureModelIFeatureModel has a back end with a higher latency for storing changes,
such as one that involves writing to a file or database, it’s better for performance if you don’t instantly write each update
to the model’s
back end. Such an IFeatureModelIFeatureModelIFeatureModel can make use of the persistence API.
Using this API, you can save the updates to the back end at a lower frequency. It allows for many updates to be
condensed and batched in a single save operation.
|
The behavior of the |
Using feature models with save support
An IFeatureModelIFeatureModelIFeatureModel with support for saving offers a
FeatureModelPersistenceManagerFeatureModelPersistenceManagerFeatureModelPersistenceManager with methods to save and
discard changes, and to view in-memory changes that haven’t been saved yet. To build up the list of changes that can be saved,
in-memory updatesin-memory updatesin-memory updates are passed to the
IFeatureModelUpdaterIFeatureModelUpdaterIFeatureModelUpdater.
To actually save something to the IFeatureModel’sIFeatureModel’sIFeatureModel’s back end, you must
call IFeatureModel::getPersistenceManager()IFeatureModel::getPersistenceManager()IFeatureModel::getPersistenceManager() to
get the FeatureModelPersistenceManagerFeatureModelPersistenceManagerFeatureModelPersistenceManager and call its
saveChanges()saveChanges()saveChanges() method.
Check the result of the saveChanges() method to see if the save action was successful, or if something went wrong and you got an
errorerrorerror. In the case of errors, you can check if they’re general errors, such as a failure to
connect to the database or file permission issues, or errors specific to a FeatureFeatureFeature.
It’s assumed that a discarddiscarddiscard doesn’t fail. It shouldn’t change the state of the back end, but does change the in-memory state of the model because all
the
pending changes will be reverted.
getChanges()getChanges()getChanges() returns a
condensed list of FeatureChangesFeatureChangesFeatureChanges. This means that even if the same
FeatureFeatureFeature is changed more than once, only one feature change is returned for that
feature. The returned change describes the difference between the back end and the current state. This also means that each
updated feature
appears at most once in the list.
Usage example
For an example of how to use the persistence API, see the GeoPackage editing tutorial.
Implementing save support for a feature model
When you’re implementing an IFeatureModelIFeatureModelIFeatureModel that requires save support, you
must be able to return a FeatureModelPersistenceManagerFeatureModelPersistenceManagerFeatureModelPersistenceManager
in the IFeatureModel::getPersistenceManager()IFeatureModel::getPersistenceManager()IFeatureModel::getPersistenceManager() method.
You can create a FeatureModelPersistenceManagerFeatureModelPersistenceManagerFeatureModelPersistenceManager using the
BuilderBuilderBuilder. It requires an
IFeatureSaveSupportIFeatureSaveSupportIFeatureSaveSupport implementation tailored to your feature model implementation.
Calls to the FeatureModelPersistenceManagerFeatureModelPersistenceManagerFeatureModelPersistenceManager
will be passed on to the corresponding IFeatureSaveSupportIFeatureSaveSupportIFeatureSaveSupport method.
Keep these things in mind when implementing the save capability:
-
IFeatureModel::query()IFeatureModel::query()IFeatureModel::query()andModel::queryBoundsModel::queryBoundsModel::queryBoundsneed to work on the current state of the model, which can be partially in the back end, and partially in memory. If a feature in the back end has an updated version in memory, make sure that only the version in memory gets considered. -
You must send any changes to the model’s state need to the
IFeatureModelObserversIFeatureModelObserversIFeatureModelObservers -
If the back end puts restrictions on
featuresfeaturesfeatures, consider validating them in yourIFeatureModelUpdaterIFeatureModelUpdaterIFeatureModelUpdaterimplementation, and dispatch failures on theIFeatureUpdaterCallbackIFeatureUpdaterCallbackIFeatureUpdaterCallback, to avoid saving problems later on.