OfflineDataService

open class OfflineDataService : DataService

A specialization of DataService where the provider is a DataSyncProvider.

See also

CloudSyncProvider, OfflineODataProvider.
  • Construct an offline data service using an offline provider.

    Declaration

    Swift

    public init(provider: DataSyncProvider)

    Parameters

    provider

    Offline provider.

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

    See also

    download.

    Declaration

    Swift

    open func cancelDownload() throws
  • (Asynchronous) Cancel any download(s) that are currently in progress.

    See also

    download.

    Declaration

    Swift

    open func cancelDownload(completionHandler: @escaping (Result<Void, Error>) -> Void)
  • Cancel the specifed pending requests. The requests should be cancelled as a batch, which might perform better than calling PendingRequest.cancel one request at a time.

    See also

    getQueuedRequests, getFailedRequests.

    Declaration

    Swift

    open func cancelPendingRequests(_ requests: PendingRequestList? = nil) throws

    Parameters

    requests

    Pending requests to be cancelled. If not specified (or null), then all pending requests will be cancelled. If empty, then no pending requests will be cancelled.

  • (Asynchronous) Cancel the specifed pending requests. The requests should be cancelled as a batch, which might perform better than calling PendingRequest.cancel one request at a time.

    See also

    getQueuedRequests, getFailedRequests.

    Declaration

    Swift

    open func cancelPendingRequests(_ requests: PendingRequestList? = nil, completionHandler: @escaping (Result<Void, Error>) -> Void)

    Parameters

    requests

    Pending requests to be cancelled. If not specified (or 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

    open func cancelUpload() throws
  • (Asynchronous) Cancel any upload(s) that are currently in progress.

    See also

    upload.

    Declaration

    Swift

    open func cancelUpload(completionHandler: @escaping (Result<Void, Error>) -> Void)
  • Clear the syncProvider, destroying the local database. This does not communicate with the backend system.

    Declaration

    Swift

    open func clear() throws
  • (Asynchronous) Clear the syncProvider, destroying the local database. This does not communicate with the backend system.

    Declaration

    Swift

    open func clear(completionHandler: @escaping (Result<Void, Error>) -> Void)
  • Close the syncProvider, disconnecting from the local database. This does not communicate with the backend system.

    Declaration

    Swift

    open func close() throws
  • (Asynchronous) Close the syncProvider, disconnecting from the local database. This does not communicate with the backend system.

    Declaration

    Swift

    open func close(completionHandler: @escaping (Result<Void, Error>) -> Void)
  • 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.

    Declaration

    Swift

    open func createDownloadQuery(name: String, query: DataQuery, streams: Bool = false) 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.

  • (Asynchronous) 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.

    Declaration

    Swift

    open func createDownloadQuery(name: String, query: DataQuery, streams: Bool = false, completionHandler: @escaping (Result<Void, Error>) -> Void)

    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. Consider invoking this method in a background thread to avoid blocking the application’s user interface thread.

    Declaration

    Swift

    open func deleteDownloadQuery(name: String) throws

    Parameters

    name

    Query name.

  • (Asynchronous) 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. Consider invoking this method in a background thread to avoid blocking the application’s user interface thread.

    Declaration

    Swift

    open func deleteDownloadQuery(name: String, completionHandler: @escaping (Result<Void, Error>) -> Void)

    Parameters

    name

    Query name.

  • Download backend data changes into the local database.

    See also

    cancelDownload.

    Example using proxy classes

    open func downloadExample() throws -> Void {
        let service = self.healthService
        try service.download(groups: StringList.of("PatientGroup", "StaffGroup"))
    }
    

    Declaration

    Swift

    open func download(groups: StringList? = nil, options: SyncOptions? = nil) 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.

  • (Asynchronous) Download backend data changes into the local database.

    See also

    cancelDownload.

    Example using proxy classes

    open func downloadExample() throws -> Void {
        let service = self.healthService
        try service.download(groups: StringList.of("PatientGroup", "StaffGroup"))
    }
    

    Declaration

    Swift

    open func download(groups: StringList? = nil, options: SyncOptions? = nil, completionHandler: @escaping (Result<Void, Error>) -> Void)

    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.

  • Return a named download group; the group is created if it doesn’t exist already. Download groups are not remembered across application restart. Download groups should be configured before calling download or before calling open (in the case that open may perform an implicit download).

    See also

    downloadInGroup.

    Declaration

    Swift

    open func downloadGroup(_ group: String) -> DownloadGroup

    Parameters

    group

    Name of download group.

    Return Value

    A download group (preexisting or newly created).

  • Configure one or more entity sets to be downloaded in a named group, equivalent to calling getDownloadGroup(group).add(...). Download groups are used to limit the entity sets to be downloaded. This function is helpful when using generated proxy classes which provide convenient access to entity set objects (e.g. MyService.customers, MyService.orders). If you need to configure a group using entity set names (e.g. with the dynamic API), nested group names, or download query names, then call getDownloadGroup and use the returned object for configuration. Note: this function does not actually perform the download. It simply configures entity sets for later download calls.

    See also

    download, getDownloadGroup.

    Declaration

    Swift

    open func downloadInGroup(_ group: String, _ entitySets: EntitySet...)

    Parameters

    group

    Download group name.

    rest_entitySets

    A list of entity sets to be associated with the download group.

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

    Declaration

    Swift

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

    Parameters

    from

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

    Return Value

    List of matching download queries.

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

    Declaration

    Swift

    open func downloadQueries(from: EntitySet? = nil, completionHandler: @escaping (Result<DownloadQueryList, Error>) -> Void)

    Parameters

    from

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

    Return Value

    List of matching download queries.

  • Retrieve a persistent query previously created by createDownloadQuery.

    Declaration

    Swift

    open 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.

  • (Asynchronous) Retrieve a persistent query previously created by createDownloadQuery.

    Declaration

    Swift

    open func downloadQuery(name: String, completionHandler: @escaping (Result<DownloadQuery?, Error>) -> Void)

    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, and SyncEvent.time (psuedo-properties that can be referenced by the query for filtering and ordering).

    Declaration

    Swift

    open 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.

  • (Asynchronous) @return a list of the synchronization events since the local database was created.

    See also

    SyncEvent.eventID, SyncEvent.type, and SyncEvent.time (psuedo-properties that can be referenced by the query for filtering and ordering).

    Declaration

    Swift

    open func eventHistory(matching query: DataQuery?, completionHandler: @escaping (Result<SyncEventList, Error>) -> Void)

    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.

  • Declaration

    Swift

    open func failedRequests(matching query: DataQuery? = nil, headers: HTTPHeaders? = nil, options: RequestOptions? = nil) 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.

  • (Asynchronous) @return a list of the failed pending requests in the local database (matching the query, if specified).

    Declaration

    Swift

    open func failedRequests(matching query: DataQuery? = nil, headers: HTTPHeaders? = nil, options: RequestOptions? = nil, completionHandler: @escaping (Result<PendingRequestList, Error>) -> Void)

    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

    open func hasFailedRequests(matching query: DataQuery? = nil, headers: HTTPHeaders? = nil, options: RequestOptions? = nil) 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). This includes requests that have been sent to the backend system, but which failed to execute successfully.

  • Declaration

    Swift

    open func hasInitialData() throws -> Bool

    Return Value

    true if download has been explicitly or implicitly called (by open) to obtain initial data.

  • Declaration

    Swift

    open 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

    open 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

    open func hasQueuedRequests(matching query: DataQuery? = nil, headers: HTTPHeaders? = nil, options: RequestOptions? = nil) 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

    open func lastDownloadTime() throws -> GlobalDateTime?

    Return Value

    Date and time for the last download request.

  • Declaration

    Swift

    open func lastUploadTime() throws -> GlobalDateTime?

    Return Value

    Date and time for the last upload request.

  • The online provider supporting this data service.

    Declaration

    Swift

    open var onlineProvider: OnlineODataProvider { get }
  • Open the syncProvider, performing any necessary initialization such as creation of the local database. Depending on the provider implementation, the first call to open might (or might not) communicate with the backend system. If hasInitialData returns false after calling open, then download must be explicitly called to obtain initial data. If hasInitialData returns true after calling open, then initial data has already been obtained from the backend system.

    Declaration

    Swift

    open func open() throws
  • (Asynchronous) Open the syncProvider, performing any necessary initialization such as creation of the local database. Depending on the provider implementation, the first call to open might (or might not) communicate with the backend system. If hasInitialData returns false after calling open, then download must be explicitly called to obtain initial data. If hasInitialData returns true after calling open, then initial data has already been obtained from the backend system.

    Declaration

    Swift

    open func open(completionHandler: @escaping (Result<Void, Error>) -> Void)
  • In a multiple user scenario, when a new user starts using the application on a mobile device, it might have pending requests in the local database that need to be uploaded using the previous user’s identity. This function can be called before open is called to determine whether special action is needed. Calling open when there is a known previous user might result in upload and/or download being called by open.

    Declaration

    Swift

    open func previousUser() throws -> String?

    Return Value

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

  • Declaration

    Swift

    open func queuedRequests(matching query: DataQuery? = nil, headers: HTTPHeaders? = nil, options: RequestOptions? = nil) 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.

  • (Asynchronous) @return a list of the queued pending requests in the local database (matching the query, if specified). This includes requests that have never been sent to the backend system, as well as requests that were previously sent but which failed.

    Declaration

    Swift

    open func queuedRequests(matching query: DataQuery? = nil, headers: HTTPHeaders? = nil, options: RequestOptions? = nil, completionHandler: @escaping (Result<PendingRequestList, Error>) -> Void)

    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.

  • Service options for the associated online provider.

    Declaration

    Swift

    open var serviceOptions: ServiceOptions { get }
  • The synchronization provider supporting this data service.

    Declaration

    Swift

    open var syncProvider: DataSyncProvider { get }
  • Undo all pending (local) changes for entities, so they will not be subsequently uploaded. For best performance, if multiple entities are to be undone, make one call with an EntityValueList rather than multiple calls with an EntityValue.

    Declaration

    Swift

    open func undoPendingChanges(for entities: EntityValueOrList) throws

    Parameters

    entities

    An EntityValue or EntityValueList whose pending changes will be undone.

  • (Asynchronous) Undo all pending (local) changes for entities, so they will not be subsequently uploaded. For best performance, if multiple entities are to be undone, make one call with an EntityValueList rather than multiple calls with an EntityValue.

    Declaration

    Swift

    open func undoPendingChanges(for entities: EntityValueOrList, completionHandler: @escaping (Result<Void, Error>) -> Void)

    Parameters

    entities

    An EntityValue or EntityValueList whose pending changes will be undone.

  • Upload local pending changes to the backend OData service.

    See also

    cancelUpload.

    Declaration

    Swift

    open func upload(groups: StringList? = nil, options: SyncOptions? = nil) throws

    Parameters

    groups

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

    options

    Upload options, including cancellation token and progress listener.

  • (Asynchronous) Upload local pending changes to the backend OData service.

    See also

    cancelUpload.

    Declaration

    Swift

    open func upload(groups: StringList? = nil, options: SyncOptions? = nil, completionHandler: @escaping (Result<Void, Error>) -> Void)

    Parameters

    groups

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

    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

    open func uploadDatabaseFile(encryptionKey: String? = nil, note: String? = nil, options: SyncOptions? = nil) 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 database files for diagnostic purposes.

    options

    Upload options, including cancellation token and progress listener.

  • (Asynchronous) 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

    open func uploadDatabaseFile(encryptionKey: String? = nil, note: String? = nil, options: SyncOptions? = nil, completionHandler: @escaping (Result<Void, Error>) -> Void)

    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 database files for diagnostic purposes.

    options

    Upload options, including cancellation token and progress listener.