OfflineDataServiceAsync

@available(swift 5.5)
open class OfflineDataServiceAsync : DataServiceAsync

An specialization of DataService where the provider is a DataSyncProvider, using the async/await style of asynchronous operations.

  • Construct an offline data service using an offline provider.

    Declaration

    Swift

    public init(provider: DataSyncProvider)

    Parameters

    provider

    Offline provider.

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

    See also

    download.

    Declaration

    Swift

    open func cancelDownload() async throws

  • (Asynchronous) Cancel the specifed pending requests.

    See also

    getQueuedRequests, getFailedRequests.

    Declaration

    Swift

    open func cancelPendingRequests(_ requests: PendingRequestList? = nil) async 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 any upload(s) that are currently in progress.

    See also

    upload.

    Declaration

    Swift

    open func cancelUpload() async throws

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

    Declaration

    Swift

    open func clear() async throws

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

    Declaration

    Swift

    open func close() async throws

  • (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, OfflineDataService.downloadQueriesCanOverlap, OfflineDataService.noDefaultEntityDownload, OfflineDataService.noDefaultStreamDownload.

    Declaration

    Swift

    open func createDownloadQuery(name: String, query: DataQuery, streams: Bool = false) async 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. Defaults to false, but may be overridden by EntitySet.downloadStreamsByDefault.

  • (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) async throws

    Parameters

    name

    Query name.

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

    See also

    cancelDownload, progressListener.

    Declaration

    Swift

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

  • Configure one or more entity sets to be downloaded in a named group, by setting EntitySet.downloadGroup for all of the specified entity sets. Download groups are used to limit (select) the entity sets to be downloaded. Note: this function does not actually perform the download. It simply configures entity sets for later download calls.

    See also

    download (groups parameter).

    Declaration

    Swift

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

    Parameters

    group

    Download group name.
    rest_entitySets

    A list of entity sets whose EntitySet.downloadGroup will be set.

  • Configure one or more entity sets to be downloaded in a numbered phase and specified mode, by setting EntitySet.downloadPhase and EntitySet.downloadMode for all of the specified entity sets. Also the EntitySet.downloadOrder for the respective entity sets will be set from 1 to the number of entity sets, in the order indicated by the entitySets parameter. Download phases are used to order (sort) the entity sets to be downloaded. Note: this function does not actually perform the download. It simply configures entity sets for later download calls.

    See also

    download.

    Declaration

    Swift

    open func downloadInPhase(_ phase: Int, _ mode: DownloadMode, _ entitySets: EntitySet...)

    Parameters

    phase

    Download phase number, which should be greater than zero. If a zero or negative value is provided, then download will be disabled for the specified entity sets.
    mode

    Download mode.
    rest_entitySets

    A list of entity sets whose EntitySet.downloadPhase and EntitySet.downloadOrder will be set. If this list is empty, all entity sets will be configured with the specified phase and mode.

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

    Declaration

    Swift

    open func downloadQueries(from: EntitySet? = nil) async 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.

  • Configure one or more entity sets to allow overlapping results when multiple download queries are used per entity set. By default (for optimal performance), it is assumed that multiple download queries for the same entity set will have non-overlapping query results, e.g. by the appropriate use of DataQuery.filter for each download query. Allowing for overlapping results requires the provider to track downloaded keys, but ensures that deleting a download query will result in deletion of downloaded entities only when they are not related to one or more other download queries.

    See also

    EntitySet.downloadQueriesCanOverlap, createDownloadQuery, deleteDownloadQuery.

    Declaration

    Swift

    open func downloadQueriesCanOverlap(_ entitySets: EntitySet...)

    Parameters

    rest_entitySets

    A list of entity sets whose downloadQueriesCanOverlap property will be set to true. If this list is empty, all entity sets will be configured to allow overlapping download query results.

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

    Declaration

    Swift

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

    Parameters

    name

    Query name.

    Return Value

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

  • Configure one or more entity sets to enable downloads without delta links. If this property is set to true, then download requests to the backend service are expected to return all relevant data (as opposed to returning just changed data), in which case the effective changes will be determined on the client side, and applied to the local database as needed. For large data sets, client-side change determination can result in high client-side CPU, memory, and network utilization. It is recommended to use delta-enabled backend services when working with large data sets, instead of setting this property to true. If you are considering setting this property to true, please evaluate the client-side resource utilization, and consider the alternative option of delta-enabling the backend system.

    See also

    SAP Mobile Services - Mobile Back-End Tools

    See also

    EntitySet.downloadWithoutDeltaLinks.

    Declaration

    Swift

    open func downloadWithoutDeltaLinks(_ entitySets: EntitySet...)

    Parameters

    rest_entitySets

    A list of entity sets whose downloadWithoutDeltaLinks property will be set to true. If this list is empty, all entity sets will be configured to enable downloads without delta links.

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

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

    See also

    hasFailedRequests, PendingRequest.changeSet, PendingRequest.customTag, PendingRequest.firstSent, PendingRequest.httpMethod, PendingRequest.httpStatus, PendingRequest.requestID, PendingRequest.requestURL, PendingRequest.uploadGroup.

    Declaration

    Swift

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

  • See also

    getFailedRequests, PendingRequest.changeSet, PendingRequest.customTag, PendingRequest.firstSent, PendingRequest.httpMethod, PendingRequest.httpStatus, PendingRequest.requestID, PendingRequest.requestURL, PendingRequest.uploadGroup.

    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.

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

    See also

    metadataListener.

    Declaration

    Swift

    open func hasMetadataChanges() throws -> Bool

    Return Value

    true if this provider has detected metadata changes.

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

  • See also

    getQueuedRequests, PendingRequest.changeSet, PendingRequest.customTag, PendingRequest.firstSent, PendingRequest.httpMethod, PendingRequest.httpStatus, PendingRequest.requestID, PendingRequest.requestURL, PendingRequest.uploadGroup.

    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.

  • Load previously saved download time estimates from file.

    See also

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

    Declaration

    Swift

    open func loadTimeEstimates(file: String, mustExist: Bool = false) 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. Defaults to false.

  • 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

    open var metadataListener: MetadataListener? { get set }

  • Disable download-by-default for the entities of an entity set. This indicates that entity data should only be downloaded if explicitly enabled by use of createDownloadQuery.

    See also

    EntitySet.downloadEntitiesByDefault.

    Declaration

    Swift

    open func noDefaultEntityDownload(_ entitySets: EntitySet...)

    Parameters

    rest_entitySets

    A list of entity sets whose downloadEntitiesByDefault property will be set to false. If this list is empty, all entity sets will be configured to disable default entity download.

  • Disable download-by-default for the streams of an entity set.

    See also

    EntitySet.downloadStreamsByDefault.

    Declaration

    Swift

    open func noDefaultStreamDownload(_ entitySets: EntitySet...)

    Parameters

    rest_entitySets

    A list of entity sets whose downloadStreamsByDefault property will be set to false. If this list is empty, all entity sets will be configured to disable default stream download.

  • The online provider supporting this data service.

    Declaration

    Swift

    open var onlineProvider: OnlineODataProvider { get }

  • (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() async throws

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

  • Progress listener for download and upload.

    Declaration

    Swift

    open var progressListener: ProgressListener? { get set }

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

    See also

    hasQueuedRequests, PendingRequest.changeSet, PendingRequest.customTag, PendingRequest.firstSent, PendingRequest.httpMethod, PendingRequest.httpStatus, PendingRequest.requestID, PendingRequest.requestURL, PendingRequest.uploadGroup.

    Declaration

    Swift

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

    open func saveTimeEstimates(file: String) throws

    Parameters

    file

    Time estimates file.

  • 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 }

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

    Declaration

    Swift

    open func undoPendingChanges(for entities: EntityValueOrList) async throws

    Parameters

    entities

    An EntityValue or EntityValueList whose pending changes will be undone.

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

    See also

    cancelUpload, progressListener.

    Declaration

    Swift

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