DataSyncProvider

public protocol DataSyncProvider : DataServiceProvider

A provider interface for data services which can synchronize data between a local database and a backend system.

  • Cancel any download(s) that are currently in progress.

    See also

    download.

    Declaration

    Swift

    func cancelDownload() throws

  • Cancel the specifed pending requests.

    See also

    getQueuedRequests, getFailedRequests.

    Declaration

    Swift

    func cancelPendingRequests(_ requests: PendingRequestList?) throws

    Parameters

    requests

    Pending requests to be cancelled. If null, then all pending requests will be cancelled. If empty, then no pending requests will be cancelled.

  • Cancel any upload(s) that are currently in progress.

    See also

    upload.

    Declaration

    Swift

    func cancelUpload() throws

  • Clear this provider. This will close the local database, and then delete the database file(s). If the application has other active threads which may try to use the database while it is being cleared, the deletion of the database file(s) might fail.

    Declaration

    Swift

    func clear() throws

  • Close this provider. This will close any connection to the local database held by the current thread. If the application has other active threads which may try to use the database while it is being closed, it might remain open after this call has completed.

    Declaration

    Swift

    func close() throws

  • Create a persistent query to specify criteria for downloading entities for an entity set. This query is persisted across application restarts. Multiple download queries can be defined for the same entity set (e.g. with different filters).

    See also

    DataQuery.entitySet, deleteDownloadQuery, getDownloadQuery, getDownloadQueries, OfflineDataService.downloadQueriesCanOverlap, OfflineDataService.noDefaultEntityDownload, OfflineDataService.noDefaultStreamDownload.

    Declaration

    Swift

    func createDownloadQuery(name: String, query: DataQuery, streams: Bool) throws

    Parameters

    name

    Query name. Must be unique.
    query

    Data query. Use DataQuery.from to specify the query’s entity set.
    streams

    If true, then enable downloading of associated streams.

  • Delete a persistent query previously created by createDownloadQuery, along with any previously downloaded associated entities. Note: if there is a large number of previously downloaded associated entities, deletion of the download query might be time-consuming.

    Declaration

    Swift

    func deleteDownloadQuery(name: String) throws

    Parameters

    name

    Query name.

  • Download backend data changes into the local database.

    Declaration

    Swift

    func download(groups: StringList, options: SyncOptions) throws

    Parameters

    groups

    If null or empty, then data will be downloaded from all entity sets. If non-empty, then it specifies groups to be downloaded.
    options

    Download options, including cancellation token and progress listener.

  • Retrieve all of the persistent queries previously created by createDownloadQuery for a specified entity set.

    Declaration

    Swift

    func downloadQueries(from: EntitySet?) throws -> DownloadQueryList

    Parameters

    from

    Entity set. If not specified, then download queries for all entity sets are returned.

    Return Value

    List of matching queries.

  • Retrieve a persistent query previously created by createDownloadQuery.

    Declaration

    Swift

    func downloadQuery(name: String) throws -> DownloadQuery?

    Parameters

    name

    Query name.

    Return Value

    The download query, or nil if no query exists with the specified name.

  • See also

    SyncEvent.eventID, SyncEvent.type, SyncEvent.time, SyncEvent.details.

    Declaration

    Swift

    func eventHistory(matching query: DataQuery?) throws -> SyncEventList

    Parameters

    query

    If specified, then DataQuery.queryFilter will be used for event filtering and DataQuery.sortItems will be used for result ordering. If not specified (or null), all synchronization events will be returned.

    Return Value

    a list of the synchronization events since the local database was created.

  • Declaration

    Swift

    func failedRequests(matching query: DataQuery?, headers: HTTPHeaders?, options: RequestOptions?) throws -> PendingRequestList

    Parameters

    query

    If specified, then DataQuery.entitySet and DataQuery.queryFilter will be used for request filtering and DataQuery.sortItems will be used for result ordering. If not specified (or null), all failed requests will be returned.
    headers

    If specified, then the returned pending requests will be further filtered to include only those with matching headers.
    options

    If specified, then the returned pending requests will be further filtered to include only those with matching options (RequestOptions.changeSet, RequestOptions.customTag, RequestOptions.uploadGroup).

    Return Value

    List of failed requests.

  • Declaration

    Swift

    func hasFailedRequests(matching query: DataQuery?, headers: HTTPHeaders?, options: RequestOptions?) throws -> Bool

    Parameters

    query

    If specified, then DataQuery.entitySet and DataQuery.queryFilter will be used for request filtering.
    headers

    If specified, then the returned pending requests will be further filtered to include only those with matching headers.
    options

    If specified, then the returned pending requests will be further filtered to include only those with matching options (RequestOptions.changeSet, RequestOptions.customTag, RequestOptions.uploadGroup).

    Return Value

    true if there are any failed requests in the local database (matching the query, if specified).

  • Declaration

    Swift

    func hasInitialData() throws -> Bool

    Return Value

    true if a download has previously been successfully executed to obtain initial data for the local database.

  • Determine if this provider has detected metadata changes (during a previous download) that require re-downloading of previously downloaded entity sets. For example, if an additional property has been added to an entity type, and the relevent data needs to be re-downloaded to obtain values for the added property. Note: When metadata changes, the changes might not take full effect until an application restart.

    Declaration

    Swift

    func hasMetadataChanges() throws -> Bool

    Return Value

    true if this provider has detected metadata changes.

  • Declaration

    Swift

    func hasPendingDownload() throws -> Bool

    Return Value

    true if a download is currently in progress or if the previous download did not terminate normally (i.e. it failed or was cancelled).

  • Declaration

    Swift

    func hasPendingUpload() throws -> Bool

    Return Value

    true if an upload is currently in progress or if the previous upload did not terminate normally (i.e. it failed or was cancelled).

  • Declaration

    Swift

    func hasQueuedRequests(matching query: DataQuery?, headers: HTTPHeaders?, options: RequestOptions?) throws -> Bool

    Parameters

    query

    If specified, then DataQuery.entitySet and DataQuery.queryFilter will be used for request filtering.
    headers

    If specified, then the returned pending requests will be further filtered to include only those with matching headers.
    options

    If specified, then the returned pending requests will be further filtered to include only those with matching options (RequestOptions.changeSet, RequestOptions.customTag, RequestOptions.uploadGroup).

    Return Value

    true if there are any queued requests in the local database (matching the query, if specified).

  • Declaration

    Swift

    func lastDownloadTime() throws -> GlobalDateTime?

    Return Value

    Date and time for the last download request.

  • Declaration

    Swift

    func lastUploadTime() throws -> GlobalDateTime?

    Return Value

    Date and time for the last upload request.

  • Load previously saved download time estimates from file.

    See also

    OperationProgress, ProgressListener, EntitySet.estimatedDeltaDownloadTime, EntitySet.estimatedInitialDownloadTime, EntitySet.estimatedStreamDownloadTime.

    Declaration

    Swift

    func loadTimeEstimates(file: String, mustExist: Bool) throws

    Parameters

    file

    Time estimates file.
    mustExist

    Specify true if the file must exist. Existing in-memory time estimates remain unchanged if this parameter is false and the file does not exist.

  • Metadata change listener. When metadata changes, the changes might not take full effect until an application restart. It is therefore advisable to restart the application process when the metadata has changed.

    Declaration

    Swift

    var metadataListener: MetadataListener? { get set }

  • Provider for online access to the backend system.

    Declaration

    Swift

    var onlineProvider: OnlineODataProvider { get }

  • For internal use by proxy services.

    Declaration

    Swift

    var onlineSetup: Bool { get set }

  • Open this provider. This will create the local database if it doesn’t exist already. This might also communicate with the backend system (but only the first time it is called, if metadata is not available locally).

    Declaration

    Swift

    func open() throws

  • Declaration

    Swift

    func previousUser() throws -> String?

    Return Value

    the previous user of the local database (if any).

  • Progress listener for download and upload.

    Declaration

    Swift

    var progressListener: ProgressListener? { get set }

  • Declaration

    Swift

    func queuedRequests(matching query: DataQuery?, headers: HTTPHeaders?, options: RequestOptions?) throws -> PendingRequestList

    Parameters

    query

    If specified, then DataQuery.entitySet and DataQuery.queryFilter will be used for request filtering and DataQuery.sortItems will be used for result ordering. If not specified (or null), all queued requests will be returned.
    headers

    If specified, then the returned pending requests will be further filtered to include only those with matching headers.
    options

    If specified, then the returned pending requests will be further filtered to include only those with matching options (RequestOptions.changeSet, RequestOptions.customTag, RequestOptions.uploadGroup).

    Return Value

    List of queued requests.

  • Save download time estimates to file. Should be called after a download operation.

    See also

    OperationProgress, ProgressListener, EntitySet.estimatedDeltaDownloadTime, EntitySet.estimatedInitialDownloadTime, EntitySet.estimatedStreamDownloadTime.

    Declaration

    Swift

    func saveTimeEstimates(file: String) throws

    Parameters

    file

    Time estimates file.

  • Undo all pending (local) changes for entities, so they will not be subsequently uploaded.

    Declaration

    Swift

    func undoPendingChanges(for entities: EntityValueList) throws

    Parameters

    entities

    A list of entities whose pending changes will be undone.

  • Upload data changes for all uploadable entity sets.

    Declaration

    Swift

    func upload(groups: StringList, options: SyncOptions) throws

    Parameters

    groups

    If empty, then data will be uploaded from all entity sets. If non-empty, then it specifies groups to be included.
    options

    Upload options, including cancellation token and progress listener.

  • Upload a copy of the local database file (or files) to the backend server (or an intermediary server) for diagnostic purposes. Note: if the local database is encrypted, and encryptionKey is null, this operation might fail (depending on the provider). Note: if the local database is not encrypted, and encryptionKey is non-null, this operation might fail (depending on the provider).

    Declaration

    Swift

    func uploadDatabaseFile(encryptionKey: String?, note: String?, options: SyncOptions) throws

    Parameters

    encryptionKey

    Encryption key for the uploaded database, which may differ from the encryption key of the local database (if any).
    note

    Associated note for trusted users who have access to uploaded databases for diagnostic purposes.
    options

    Upload options, including cancellation token and progress listener.