GeodatabaseSyncTask Class

  • GeodatabaseSyncTask
  • class Esri::ArcGISRuntime::GeodatabaseSyncTask

    A task to download or sync a sync-enabled mobile geodatabase. More...

    Header: #include <GeodatabaseSyncTask.h>
    Since: Esri::ArcGISRuntime 100.0
    Inherits: Esri::ArcGISRuntime::Object, Esri::ArcGISRuntime::ApiKeyResource, Esri::ArcGISRuntime::Loadable, and Esri::ArcGISRuntime::RemoteResource

    Public Functions

    GeodatabaseSyncTask(const QUrl &url, QObject *parent = nullptr)
    GeodatabaseSyncTask(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)
    virtual ~GeodatabaseSyncTask() override
    QFuture<Esri::ArcGISRuntime::GenerateGeodatabaseParameters> createDefaultGenerateGeodatabaseParametersAsync(const Esri::ArcGISRuntime::Geometry &extent)
    QFuture<Esri::ArcGISRuntime::SyncGeodatabaseParameters> createDefaultSyncGeodatabaseParametersAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)
    QFuture<Esri::ArcGISRuntime::SyncGeodatabaseParameters> createDefaultSyncGeodatabaseParametersAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, Esri::ArcGISRuntime::SyncDirection syncDirection)
    Esri::ArcGISRuntime::ArcGISFeatureServiceInfo featureServiceInfo() const
    Esri::ArcGISRuntime::GenerateGeodatabaseJob *generateGeodatabase(const Esri::ArcGISRuntime::GenerateGeodatabaseParameters &parameters, const QString &pathToGeodatabaseFile)
    QFuture<void> registerSyncEnabledGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)
    Esri::ArcGISRuntime::SyncGeodatabaseJob *syncGeodatabase(const Esri::ArcGISRuntime::SyncGeodatabaseParameters &parameters, Esri::ArcGISRuntime::Geodatabase *geodatabase)
    Esri::ArcGISRuntime::SyncGeodatabaseJob *syncGeodatabase(Esri::ArcGISRuntime::SyncDirection syncDirection, bool rollbackOnFailure, Esri::ArcGISRuntime::Geodatabase *geodatabase)
    QFuture<void> unregisterGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)
    QFuture<void> unregisterGeodatabaseAsync(const QUuid &syncId)

    Reimplemented Public Functions

    virtual QString apiKey() const override
    virtual void cancelLoad() override
    virtual Esri::ArcGISRuntime::Credential *credential() const override
    virtual void load() override
    virtual Esri::ArcGISRuntime::Error loadError() const override
    virtual Esri::ArcGISRuntime::LoadStatus loadStatus() const override
    virtual Esri::ArcGISRuntime::RequestConfiguration requestConfiguration() const override
    virtual void retryLoad() override
    virtual void setApiKey(const QString &apiKey) override
    virtual void setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration) override
    virtual QUrl url() const override

    Signals

    void doneLoading(const Esri::ArcGISRuntime::Error &loadError)
    void loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)

    Static Public Members

    QFuture<bool> exportDeltaAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, const QString &outputPath)
    QFuture<QList<Esri::ArcGISRuntime::SyncLayerResult *>> importDeltaAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, const QString &inputPath, QObject *parent)
    Esri::ArcGISRuntime::GeodatabaseSyncTask *instance()

    Detailed Description

    Mobile geodatabases are designed for querying and viewing feature data when your app is offline. In addition, while offline your app can edit a geodatabase locally and later sync changes with the service, assuming that the associated service supports sync. While offline, the mobile geodatabase keeps track of local edits. When those edits are synchronized with the service, local edits are sent to the service and changes made on the service in the meantime by other processes are received into the mobile geodatabase.

    You can create a mobile geodatabase on your device by downloading it from a sync-enabled ArcGIS feature service. If the geodatabase is sync-enabled, you can sync it with the sync-enabled service from which it was created (its associated service) by registering the mobile geodatabase with the service. The GeodatabaseSyncTask supports creating a geodatabase via downloading from a service, and syncing a sync-enabled geodatabase with its associated service.

    Another option is to provision a copy of a sync-enabled mobile geodatabase onto your device by loading it onto your device's file system. Register this geodatabase with the associated service, which gives the geodatabase copy its own replica ID. This identifies the geodatabase copy differently from the original geodatabase, and making the copy sync-able with the service.

    GeodatabaseSyncTask also allows you to unregister a geodatabase, which permanently prevents sync of that mobile geodatabase with its associated service. Unregistered geodatabases cannot be re-registered.

    The associated service may be hosted in the cloud on ArcGIS Online or on-premises with ArcGIS Server. Your app must have network access to the service in order to download or sync with the service.

    Member Function Documentation

    [explicit] GeodatabaseSyncTask::GeodatabaseSyncTask(const QUrl &url, QObject *parent = nullptr)

    Constructs a GeodatabaseSyncTask with a URL.

    • url - The URL of the sync-enabled ArcGIS feature service.
    • parent - The parent object for this GeodatabaseSyncTask (optional).

    GeodatabaseSyncTask::GeodatabaseSyncTask(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)

    Constructs a GeodatabaseSyncTask with a URL and a credential.

    • url - The URL of the sync-enabled ArcGIS feature service.
    • credential - The credential.
    • parent - The parent object for this GeodatabaseSyncTask (optional).

    [override virtual] GeodatabaseSyncTask::~GeodatabaseSyncTask()

    Destructor.

    [override virtual] QString GeodatabaseSyncTask::apiKey() const

    Reimplements: ApiKeyResource::apiKey() const.

    Returns the API key. See ApiKeyResource.

    See also setApiKey().

    [override virtual] void GeodatabaseSyncTask::cancelLoad()

    Reimplements: Loadable::cancelLoad().

    See Loadable.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::GenerateGeodatabaseParameters> GeodatabaseSyncTask::createDefaultGenerateGeodatabaseParametersAsync(const Esri::ArcGISRuntime::Geometry &extent)

    Default parameters for a generate geodatabase.

    • extent - The extent of the data to be included in the generated geodatabase. Must be non-null.

    This will populate the parameters with values matching what the service supports. For example if the service does not support SyncModel::Layer then SyncModel::Geodatabase will be used All layers from the service will be included. The output spatial reference will be the spatial reference of the given extent. Attachments are included by default.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::SyncGeodatabaseParameters> GeodatabaseSyncTask::createDefaultSyncGeodatabaseParametersAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)

    Default parameters for a sync geodatabase.

    • geodatabase - a geodatabase to sync.

    This will populate the parameters with values matching what the sync task's feature service and the geodatabase supports. For a geodatabase with SyncModel::Layer then all geodatabase layers will be included. If the service is read-only then the sync direction will be SyncDirection::Download. Otherwise the sync direction will be SyncDirection::Bidirectional.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::SyncGeodatabaseParameters> GeodatabaseSyncTask::createDefaultSyncGeodatabaseParametersAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, Esri::ArcGISRuntime::SyncDirection syncDirection)

    Default parameters for a sync geodatabase using the given sync direction.

    • geodatabase - a geodatabase to sync.
    • syncDirection - the sync direction to use.

    This will populate the parameters with values matching what the sync task's feature service and the geodatabase supports. For a geodatabase with SyncModel::Layer then all geodatabase layers will be included. A service is editable if it has capabilities that include any of create, update or delete. In this case both SyncDirection::Bidirectional and SyncDirection::Upload are supported sync directions. Alternatively, a service that does not have create, update or delete capability is considered read-only and only SyncDirection::Download will be supported. If the given sync direction is not compatible with the sync task's feature service or the geodatabase is not sync enabled, the returned task will fail.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [override virtual] Esri::ArcGISRuntime::Credential *GeodatabaseSyncTask::credential() const

    Reimplements: RemoteResource::credential() const.

    Returns the security credential used to access the service.

    Only applicable if using an service that is secured.

    [signal] void GeodatabaseSyncTask::doneLoading(const Esri::ArcGISRuntime::Error &loadError)

    Signal emitted when this object is done loading.

    • loadError - Details about any error that may have occurred.

    Note: If there is a load error it will also be emitted on the errorOccurred signal.

    See also Loadable and Object.

    [static, since Esri::ArcGISRuntime 200.2] QFuture<bool> GeodatabaseSyncTask::exportDeltaAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, const QString &outputPath)

    An upload delta geodatabase file containing all the changes since the last sync.

    • geodatabase - The geodatabase to generate a delta from.
    • outputPath - The path and filename to save the generated delta to.

    A delta geodatabase contains the changes that have occurred since a mobile replica Geodatabase was last synchronized with the feature service. See https://developers.arcgis.com/rest/services-reference/enterprise/synchronize-replica.htm for an overview of the delta files used in synchronization. An "upload" delta geodatabase contains the local edits, performed on the user's device, to be sent to the originating feature service.

    When you run this task, any local edits in the Geodatabase will be exported to the specified output path. The output path should include the full path and file name (ending in ".geodatabase") for the export.

    The delta file created by this method is not sent to the server and has no impact on any subsequent sync job. You can call this method repeatedly without affecting the state of the local geodatabase.

    You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase:

    The QFuture returned by this method has a Boolean result that indicates whether or not a delta geodatabase was created.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    See also SyncGeodatabaseParameters::isKeepGeodatabaseDeltas.

    Esri::ArcGISRuntime::ArcGISFeatureServiceInfo GeodatabaseSyncTask::featureServiceInfo() const

    Returns metadata about the service.

    Esri::ArcGISRuntime::GenerateGeodatabaseJob *GeodatabaseSyncTask::generateGeodatabase(const Esri::ArcGISRuntime::GenerateGeodatabaseParameters &parameters, const QString &pathToGeodatabaseFile)

    Returns a job to generate a mobile geodatabase from an ArcGIS Feature service.

    • parameters - Parameters specifying what information to include in the geodatabase.
    • pathToGeodatabaseFile - Where to save the geodatabase on the local file system.

    The result of the job will be of type Geodatabase.

    The pathToGeodatabaseFile can specify a path for the downloaded geodatabase, including the desired name and the .geodatabase file extension. Or, pathToGeodatabaseFile can be a filename only, in which case the file extension is added and the geodatabase is stored in the user's Documents folder.

    A GenerateGeodatabaseJob representing the progress on the server is returned.

    The returned job is in the JobStatus::NotStarted state. Start it by calling Job::start().

    The job should be deleted after completion.

    See also Job.

    [static, since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::SyncLayerResult *>> GeodatabaseSyncTask::importDeltaAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase, const QString &inputPath, QObject *parent)

    Imports a geodatabase delta and applies it to the given geodatabase.

    • geodatabase - The geodatabase to apply a delta to.
    • inputPath - The path and filename to import the delta from.
    • parent - A mandatory QObject parent. Since this method is static, results will have no parent by default.

    A delta geodatabase contains the changes that have occurred since a mobile replica Geodatabase was last-synchronized with the feature service. See https://developers.arcgis.com/rest/services-reference/enterprise/synchronize-replica.htm for an overview of the delta files used in synchronization. A "download" delta geodatabase contains the online edits that will be imported to the local geodatabase.

    The task returned by this method returns an array of SyncLayerResult.

    You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase, which are:

    If you want the result to have no parent, pass nullptr as the parent. Be sure to manage the memory of the result or it will leak.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [static, since Esri::ArcGISRuntime 100.3] Esri::ArcGISRuntime::GeodatabaseSyncTask *GeodatabaseSyncTask::instance()

    Returns an instance of the GeodatabaseSyncTask singleton.

    The instance is used to connect to the Object::errorOccurred, and importDeltaCompleted signals. You do not need to obtain the instance to call the static methods on the GeodatabaseSyncTask.

    This function was introduced in Esri::ArcGISRuntime 100.3.

    [override virtual] void GeodatabaseSyncTask::load()

    Reimplements: Loadable::load().

    See Loadable.

    [override virtual] Esri::ArcGISRuntime::Error GeodatabaseSyncTask::loadError() const

    Reimplements: Loadable::loadError() const.

    See Loadable.

    [override virtual] Esri::ArcGISRuntime::LoadStatus GeodatabaseSyncTask::loadStatus() const

    Reimplements: Loadable::loadStatus() const.

    See Loadable.

    [signal] void GeodatabaseSyncTask::loadStatusChanged(Esri::ArcGISRuntime::LoadStatus loadStatus)

    Signal emitted when the load status changes for this object.

    See also Loadable.

    [since Esri::ArcGISRuntime 200.2] QFuture<void> GeodatabaseSyncTask::registerSyncEnabledGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)

    Registers a copy of a sync enabled geodatabase with a service to allow the copy to sync changes.

    • geodatabase - a geodatabase to register.

    This method is typically used as part of services pattern workflow, sometimes known as a pre-planned workflow. A sync enabled geodatabase is generated centrally and not modified or synced. Copies of this original geodatabase are distributed and loaded onto each user's device. The copy must first be registered with the service to allow the server to identify changes in subsequent sync operations. One of the main benefits of this workflow is a reduction in server load to generate geodatabases for many clients. It is important not to sync the copy before registering to ensure the server can maintain consistent state on each copy. This operation is not the opposite of unregisterGeodatabaseAsync which is used to remove a geodatabase from the service prior to deletion.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [override virtual, since Esri::ArcGISRuntime 100.1] Esri::ArcGISRuntime::RequestConfiguration GeodatabaseSyncTask::requestConfiguration() const

    Reimplements: RemoteResource::requestConfiguration() const.

    Returns the RequestConfiguration in use by this task.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also setRequestConfiguration().

    [override virtual] void GeodatabaseSyncTask::retryLoad()

    Reimplements: Loadable::retryLoad().

    See Loadable.

    [override virtual] void GeodatabaseSyncTask::setApiKey(const QString &apiKey)

    Reimplements: ApiKeyResource::setApiKey(const QString &apiKey).

    Sets the API key to apiKey. See ApiKeyResource.

    See also apiKey().

    [override virtual, since Esri::ArcGISRuntime 100.1] void GeodatabaseSyncTask::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration)

    Reimplements: RemoteResource::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration).

    Sets configuration parameters used for network requests sent by this task to requestConfiguration.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also requestConfiguration().

    Esri::ArcGISRuntime::SyncGeodatabaseJob *GeodatabaseSyncTask::syncGeodatabase(const Esri::ArcGISRuntime::SyncGeodatabaseParameters &parameters, Esri::ArcGISRuntime::Geodatabase *geodatabase)

    Returns a job to synchronize a geodatabase back to a service.

    • parameters - Parameters to use to sync the geodatabase.
    • geodatabase - The geodatabase to sync.

    For a successfully completed job the job's result returns an array of SyncLayerResult, typically the array is empty. If individual edits failed then the result array provides these errors grouped by each table using SyncLayerResult instances which in turn contain each edit error.

    You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase, which are:

    See also Job.

    [since Esri::ArcGISRuntime 100.3] Esri::ArcGISRuntime::SyncGeodatabaseJob *GeodatabaseSyncTask::syncGeodatabase(Esri::ArcGISRuntime::SyncDirection syncDirection, bool rollbackOnFailure, Esri::ArcGISRuntime::Geodatabase *geodatabase)

    Returns a job to sync a mobile geodatabase with its originating ArcGIS Feature service using the given sync direction and rollback on failure Boolean value.

    • syncDirection - The preferred sync direction.
    • rollbackOnFailure - Whether to roll back edits when a failure occurs.
    • geodatabase - The geodatabase to sync with the service.

    The result of the job will be a list of SyncLayerResult objects. This list will be empty for a successfully completed job. If individual edits failed then the result provides these errors grouped by each table using SyncLayerResult instances. These contain information for each edit error as a FeatureEditResult.

    If rollbackOnFailure is false, then failed edits are skipped. Other edits are still applied. This property only applies to edits uploaded by the client to the server. It does not apply to edits imported by client from the server.

    If the given sync direction is not compatible with the sync task's feature service, the returned job will fail.

    You should not execute more than one sync on a particular geodatabase at the same time. This includes any operations that export or import deltas from the local Geodatabase:

    A SyncGeodatabaseJob representing the progress on the server is returned. The returned job is in the JobStatus::NotStarted state. Start it by calling Job::start().

    The job should be deleted after completion.

    This function was introduced in Esri::ArcGISRuntime 100.3.

    See also Job.

    [since Esri.ArcGISRuntime 200.2] QFuture<void> GeodatabaseSyncTask::unregisterGeodatabaseAsync(Esri::ArcGISRuntime::Geodatabase *geodatabase)

    Unregisters a geodatabase from a service removing the services replica id.

    • geodatabase - a geodatabase to unregister.

    After unregistering a geodatabase it can no longer be synced back to the service. This is often used prior to deleting a local geodatabase. This operation is not related to registerSyncEnabledGeodatabaseAsync, which is for registering copies of a sync enabled geodatabase.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri.ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<void> GeodatabaseSyncTask::unregisterGeodatabaseAsync(const QUuid &syncId)

    Unregisters a geodatabase from a service removing the service's replica id. This overload uses the geodatabase's sync ID rather than a reference to the geodatabase itself.

    • syncId - sync ID of geodatabase to unregister.

    This method is used to unregister a geodatabase from a service using the sync ID. This is commonly used to enable cleanup of the service after the local geodatabase has already been deleted. See Geodatabase::syncId. After unregistering a geodatabase it can no longer be synced back to the service. This operation is not related to registerSyncEnabledGeodatabaseAsync, which is for registering copies of a sync enabled geodatabase.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [override virtual] QUrl GeodatabaseSyncTask::url() const

    Reimplements: RemoteResource::url() const.

    Returns the URL to a sync-enabled ArcGIS Feature service.

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.