OfflineDataService
open class OfflineDataService : DataService
A specialization of DataService
where the provider
is a DataSyncProvider
.
-
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).
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).
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 callingopen
(in the case thatopen
may perform an implicitdownload
).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 callgetDownloadGroup
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
, andSyncEvent.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 andDataQuery.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
, andSyncEvent.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 andDataQuery.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
andDataQuery.queryFilter
will be used for request filtering andDataQuery.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
andDataQuery.queryFilter
will be used for request filtering andDataQuery.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
andDataQuery.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 thequery
, 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
ifdownload
has been explicitly or implicitly called (byopen
) to obtain initial data. -
Declaration
Swift
open func hasPendingDownload() throws -> Bool
Return Value
true
if adownload
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 anupload
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
andDataQuery.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 thequery
, 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. IfhasInitialData
returnsfalse
after callingopen
, thendownload
must be explicitly called to obtain initial data. IfhasInitialData
returnstrue
after callingopen
, 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. IfhasInitialData
returnsfalse
after callingopen
, thendownload
must be explicitly called to obtain initial data. IfhasInitialData
returnstrue
after callingopen
, 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. Callingopen
when there is a known previous user might result inupload
and/ordownload
being called byopen
.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
andDataQuery.queryFilter
will be used for request filtering andDataQuery.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
andDataQuery.queryFilter
will be used for request filtering andDataQuery.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 anEntityValueList
rather than multiple calls with anEntityValue
.Declaration
Swift
open func undoPendingChanges(for entities: EntityValueOrList) throws
Parameters
entities
An
EntityValue
orEntityValueList
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 anEntityValueList
rather than multiple calls with anEntityValue
.Declaration
Swift
open func undoPendingChanges(for entities: EntityValueOrList, completionHandler: @escaping (Result<Void, Error>) -> Void)
Parameters
entities
An
EntityValue
orEntityValueList
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, andencryptionKey
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, andencryptionKey
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.