CloudSyncProvider

open class CloudSyncProvider : ObjectBase, DataSyncProvider

A data service provider that synchronizes data between a local SQL database on a mobile client device and a remote OData service. Occasional download and upload calls may be used to synchronize data changes when the mobile client device is online. The local SQL database can subsequently be queried and updated through the associated SQLDatabaseProvider when the mobile client device is offline. The remote OData service can be cloud-based or on-premise, but will typically be accessed via a cloud-based intermediary which enables connectivity between the mobile client device and the remote OData service. Connectivity between the mobile client device and the remote OData service can be achieved through the associated OnlineODataProvider via SAP Mobile Services and/or SAP BTP Connectivity. The OData service should be enabled for OData change tracking, so that download calls can efficiently obtain only the changed data. If the OData service does not support change tracking, then Mobile Back-End Tools can be used to enable change tracking, either by using a delta-enabled cache database, or by using a delta-enabled existing database. Mobile Back-end Tools can also be used to provide an OData service with a delta-enabled cache database, wrapping a non-OData backend system which is accessible using HTTPS (for REST APIs or SOAP services), JDBC (for SQL databases), or SAP Java Connector (for ABAP systems). The EntitySet.downloadWithoutDeltaLinks property can be set to true to enable client-side change tracking, however this is only appropriate for application prototyping or for production scenarios with a limited amount of data to be downloaded. Client applications should wrap this provider with a DataService (or OfflineDataService) for convenient consumption, including the use of async methods and proxy classes.

See also

open, client-side download queries, server-side download queries, OfflineDataService.downloadWithoutDeltaLinks, OfflineDataService.downloadQueriesCanOverlap, OfflineDataService.noDefaultEntityDownload, OfflineDataService.noDefaultStreamDownload.

Example using proxy classes

open func setupService() throws -> Void {
    let onlineProvider = OnlineODataProvider(serviceName: "HealthService",
        serviceRoot: "http://health.example.com:8080")
    let localDatabase = SQLDatabaseProvider(serviceName: "HealthDB",
        databaseURL: "sqlite:~/health.db")
    let offlineProvider = CloudSyncProvider(onlineProvider: onlineProvider,
        offlineStore: localDatabase)
    offlineProvider.encryptionKey = self.dbEncryptionKey()
    offlineProvider.createIndex(HealthService.patients, Patient.dateOfBirth,
        Patient.lastName)
    self.healthService = HealthService(provider: offlineProvider)
    try self.healthService.open()
}

Example using dynamic API

open func setupService() throws -> Void {
    let onlineProvider = OnlineODataProvider(serviceName: "HealthService",
        serviceRoot: "http://health.example.com:8080")
    let localDatabase = SQLDatabaseProvider(serviceName: "HealthDB",
        databaseURL: "sqlite:~/health.db")
    let offlineProvider = CloudSyncProvider(onlineProvider: onlineProvider,
        offlineStore: localDatabase)
    offlineProvider.encryptionKey = self.dbEncryptionKey()
    offlineProvider.createDynamicIndex("Patients", "dateOfBirth")
    self.healthService = OfflineDataService(provider: offlineProvider)
    try self.healthService.open()
}
  • For internal use by proxy services.

    Declaration

    Swift

    final public var onlineSetup: Bool
  • Construct an offline OData provider.

    Declaration

    Swift

    public init(onlineProvider: OnlineODataProvider, offlineStore: SQLDatabaseProvider? = nil)

    Parameters

    onlineProvider

    For backend system interactions.

    offlineStore

    For local database interactions.

  • Enable automatic download as part of initial open call. Defaults to false. Automatic initial download will only occur if this property is enabled and hasInitialData would return false.

    Declaration

    Swift

    public final var autoInitialDownload: Bool { get set }
  • If autoRefreshMetadata results in detection of changed metadata for entity sets, should those entity sets be automatically refreshed on the next download, even if not included in the download groups parameter? Defaults to true.

    See also

    autoRefreshInterval, autoRefreshMetadata, metadataListener, hasMetadataChanges, changedEntitySets.

    Declaration

    Swift

    public final var autoRefreshEntities: Bool { get set }
  • Frequency of automatic metadata fetches (if enabled). Defaults to one day.

    See also

    autoRefreshMetadata, autoRefreshEntities, metadataListener, hasMetadataChanges.

    Declaration

    Swift

    public final var autoRefreshInterval: DayTimeDuration { get set }
  • Should the latest metadata be occasionally fetched from the backend service (during download), in case it has changed. Defaults to true.

    See also

    autoRefreshInterval, autoRefreshEntities, metadataListener, hasMetadataChanges.

    Declaration

    Swift

    public final var autoRefreshMetadata: Bool { get set }
  • Maximum amount of time that waitForCompletion should wait for background request completion. Defaults to 20 seconds.

    Declaration

    Swift

    public final var backgroundWaitSeconds: Int { get set }
  • If the backend supports entity download for offline operation, should it be done with batch requests? Defaults to true.

    Declaration

    Swift

    public final var batchEntityDownloads: Bool { get set }
  • If the backend supports entity upload for offline operation, should it be done with batch requests? Defaults to true.

    Declaration

    Swift

    public final var batchEntityUploads: Bool { get set }
  • If the backend supports stream download for offline operation, should it be done with batch requests? Defaults to true.

    Declaration

    Swift

    public final var batchStreamDownloads: Bool { get set }
  • If the backend supports stream upload for offline operation, should it be done with batch requests? Defaults to true.

    Declaration

    Swift

    public final var batchStreamUploads: Bool { get set }
  • Cancel any download(s) that are currently in progress.

    See also

    download.

    Declaration

    Swift

    open func cancelDownload() throws
  • Cancel the specifed pending requests.

    See also

    getQueuedRequests, getFailedRequests.

    Declaration

    Swift

    open 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

    open func cancelUpload() throws
  • If hasMetadataChanges would return true, then return a list of the entity sets that need to be re-downloaded.

    Declaration

    Swift

    open func changedEntitySets() throws -> EntitySetList

    Return Value

    List of entity sets that have metadata changes.

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

    Declaration

    Swift

    open 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

    open func close() throws
  • Can pending delete requests be combined with prior create / update requests (that have not yet been uploaded) by cancelling the prior pending requests? Defaults to true. For example, if an entity is created and then deleted locally, the combining of delete requests would result in no requests being uploaded to the server.

    Declaration

    Swift

    public final var combineLocalDeletes: Bool { get set }
  • Can pending update requests be combined with prior create / update requests (that have not yet been uploaded) by altering the prior pending requests? Defaults to true. For example, if an entity is created and then updated locally, the combining of update requests would result in a single create request being uploaded to the server.

    Declaration

    Swift

    public final var combineLocalUpdates: Bool { get set }
  • 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) 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.

  • Define a database index for an entity set. Must not be called after the local database has been opened. Actual creation of the index is deferred until the local database is opened. This function differs from createIndex by accepting string-typed parameters. It is applicable even when metadata is not yet available.

    See also

    open, EntitySet.indexes, createIndex.

    Example using dynamic API

    open func setupService() throws -> Void {
        let onlineProvider = OnlineODataProvider(serviceName: "HealthService",
            serviceRoot: "http://health.example.com:8080")
        let localDatabase = SQLDatabaseProvider(serviceName: "HealthDB",
            databaseURL: "sqlite:~/health.db")
        let offlineProvider = CloudSyncProvider(onlineProvider: onlineProvider,
            offlineStore: localDatabase)
        offlineProvider.encryptionKey = self.dbEncryptionKey()
        offlineProvider.createDynamicIndex("Patients", "dateOfBirth")
        self.healthService = OfflineDataService(provider: offlineProvider)
        try self.healthService.open()
    }
    

    Declaration

    Swift

    open func createDynamicIndex(_ entitySet: String, _ item: String, _ items: String...)

    Parameters

    entitySet

    Name of entity set for which index will be created.

    item

    First item to be indexed. This is a property name (e.g. “Quantity”) or property path (e.g. “Address/City”).

    rest_items

    Optional additional items for a composite index.

  • Create an entity in the target system. Automatically calls CsdlDocument.resolveEntity to ensure that EntityValue.entitySet is available.

    Throws

    DataServiceException if the entity set hasn’t been explicitly provided before calling createEntity and there isn’t a unique entity set for the entity type.

    See also

    EntityValue.ofType, EntityValue.inSet.

    Declaration

    Swift

    open func createEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    entity

    Entity to be created.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Define a database index for an entity set. Must not be called after the local database has been opened (explicitly or implicitly). Actual creation of the index is deferred until the local database is opened (explicitly or implicitly).

    See also

    open, EntitySet.indexes, createDynamicIndex.

    Example using proxy classes

    open func setupService() throws -> Void {
        let onlineProvider = OnlineODataProvider(serviceName: "HealthService",
            serviceRoot: "http://health.example.com:8080")
        let localDatabase = SQLDatabaseProvider(serviceName: "HealthDB",
            databaseURL: "sqlite:~/health.db")
        let offlineProvider = CloudSyncProvider(onlineProvider: onlineProvider,
            offlineStore: localDatabase)
        offlineProvider.encryptionKey = self.dbEncryptionKey()
        offlineProvider.createIndex(HealthService.patients, Patient.dateOfBirth,
            Patient.lastName)
        self.healthService = HealthService(provider: offlineProvider)
        try self.healthService.open()
    }
    

    Declaration

    Swift

    open func createIndex(_ entitySet: EntitySet, _ item: PropertyPath, _ items: PropertyPath...)

    Parameters

    entitySet

    Entity set for which index will be created.

    item

    First item to be indexed (Property or DataPath).

    rest_items

    Optional additional items for a composite index.

  • Create a link from a source entity to a target entity.

    Declaration

    Swift

    open func createLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    from

    Source entity for the link to be created.

    property

    Source navigation property for the link to be created.

    to

    Target entity for the link to be created.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Create a media entity with the specified content in the target system. If the entity has non-stream structural properties in addition to the key properties and media content, such as label in the examples below, then this function will send two requests to the server: a first request to upload (POST) the media stream, and a second request (PATCH/PUT) to update the non-stream properties. It is not currently supported to make these two calls atomic. Caution: Having too many threads simultaneously creating streams may result in out-of-memory conditions on memory-constrained devices.

    Declaration

    Swift

    open func createMedia(entity: EntityValue, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    entity

    Entity to be created.

    content

    Initial content. Must be a ByteStream or CharStream. Will be closed before this function returns.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Execute query to delete data from the target system.

    Declaration

    Swift

    open func deleteByQuery(_ query: DataQuery, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    query

    Data query specifying the information to be deleted.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • 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

    open func deleteDownloadQuery(name: String) throws

    Parameters

    name

    Query name.

  • Delete an entity from the target system.

    Declaration

    Swift

    open func deleteEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    entity

    Entity to be deleted.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Delete a link from a source entity to a target entity.

    Declaration

    Swift

    open func deleteLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    from

    Source entity for the link to be deleted.

    property

    Source navigation property for the link to be deleted.

    to

    Target entity for the link to be deleted.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Delete the content of a stream property from the target system.

    Declaration

    Swift

    open func deleteStream(entity: EntityValue, link: StreamLink, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    entity

    Entity containing the stream property whose content is to be deleted.

    headers

    Request-specific headers.

    options

    Request-specific options.

    link

    Stream link for the stream to be deleted.

  • Download backend data changes into the local database.

    Declaration

    Swift

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

  • Enable background download (for execution environments where it is applicable, otherwise ignored). Defaults to false. When using background downloads, it is preferable to also enable batchEntityDownloads and batchStreamDownloads (where supported by the backend service). Using DownloadMode.parallel or DownloadMode.sequence might result in many separate background download requests, and the operating system might then apply rate limiting which would reduce overall download performance as compared to not using background downloads. For the same reason, it is preferable if the backend system can be configured avoid returning next links by returning entire (possibly large) query results. The best case for background downloads (from the client’s perspective) is a single batch request from the client, with a corresponding single (possibly large) response streamed from server to client. This might entail extra memory utilization at the server, or recoding the server to more efficiently support streaming of responses.

    See also

    uploadInBackground.

    Declaration

    Swift

    public final var downloadInBackground: Bool { get set }
  • Obtain a stream for downloading the content of a media entity from the target system. Caution: streams are often used for large content that may not fit (all at once) in available application memory. Having too many threads simultaneously downloading streams, or using ByteStream.readAndClose, may result in out-of-memory conditions on memory-constrained devices.

    Declaration

    Swift

    open func downloadMedia(entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws -> ByteStream

    Parameters

    entity

    Entity whose content is to be downloaded.

    headers

    Request-specific headers.

    options

    Request-specific options.

    Return Value

    A stream for downloading the content of a media entity. This must be closed by the caller, or else a resource leak may occur.

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

  • Obtain a stream for downloading the content of a stream property from the target system. Caution: streams are often used for large content that may not fit (all at once) in available application memory. Having too many threads simultaneously downloading streams, or using ByteStream.readAndClose, may result in out-of-memory conditions on memory-constrained devices.

    See also

    Property.getStreamLink.

    Declaration

    Swift

    open func downloadStream(entity: EntityValue, link: StreamLink, headers: HTTPHeaders, options: RequestOptions) throws -> ByteStream

    Parameters

    entity

    Entity containing the stream property whose content is to be downloaded.

    link

    Stream link for the stream to be downloaded.

    headers

    Request-specific headers.

    options

    Request-specific options.

    Return Value

    A stream for downloading the content of a stream property. This must be closed by the caller, or else a resource leak may occur.

  • Should bind operations be emulated by setting foreign keys? Defaults to false. This may be useful for estalishing relationships when the backend system does not support bind operations. Requires the metadata to have appropriate ReferentialConstraint elements.

    See also

    EntityValue.bindEntity, EntityValue.unbindEntity.

    Declaration

    Swift

    public final var emulateBindOperations: Bool { get set }
  • Should link operations be emulated by setting foreign keys? Defaults to false. This may be useful for estalishing relationships when the backend system does not support link operations. Requires the metadata to have appropriate ReferentialConstraint elements.

    See also

    DataService.createLink, DataService.updateLink, DataService.deleteLink.

    Declaration

    Swift

    public final var emulateLinkOperations: Bool { get set }
  • Encryption key for offlineStore. If an encryption key is required for the offline store, this property must be set before calling open.

    Declaration

    Swift

    open var encryptionKey: String? { get set }
  • If the backend supports entity download for offline operation, should it be done with multiple threads in parallel? Defaults to 10 threads. Configure a lower number to reduce memory utilization of clients and servers (such a change may also reduce entity download performance). Configure a higher number to improve entity download performance by reducing network latency (such a change may also increase memory utilization).

    Declaration

    Swift

    public final var entityDownloadThreads: Int { get set }
  • 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.

  • Execute a data method (action or function) in the target system. Actions may have backend side-effects. Functions should not have backend side-effects.

    Throws

    DataServiceException or DataNetworkException if an error occurs during action invocation.

    Declaration

    Swift

    open func executeMethod(_ method: DataMethod, parameters: ParameterList, headers: HTTPHeaders, options: RequestOptions) throws -> DataValue?

    Parameters

    method

    Data method.

    parameters

    Method parameters.

    headers

    Request-specific headers.

    options

    Request-specific options.

    Return Value

    The method result, or nil if the method has no result.

  • Execute a data query to get data from the target system.

    Declaration

    Swift

    open func executeQuery(_ query: DataQuery, headers: HTTPHeaders, options: RequestOptions) throws -> QueryResult

    Parameters

    query

    Data query specifying the information to be returned.

    headers

    Request-specific headers.

    options

    Request-specific options.

    Return Value

    The query result.

  • Declaration

    Swift

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

  • Fetch latest service metadata and return it, but don’t change the metadata property.

    See also

    loadMetadata.

    Declaration

    Swift

    open func fetchMetadata(headers: HTTPHeaders, options: RequestOptions) throws -> CSDLDocument

    Parameters

    headers

    Optional request-specific headers.

    options

    Optional request-specific options.

    Return Value

    Latest service metadata.

  • Declaration

    Swift

    open 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

    open func hasInitialData() throws -> Bool

    Return Value

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

  • Has service metadata been loaded.

    See also

    loadMetadata.

    Declaration

    Swift

    open var hasMetadata: Bool { get }
  • 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

    changedEntitySets, download, 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).

  • Declaration

    Swift

    open 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

    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.

  • Reload an existing entity from the target system.

    Example using proxy classes

    open func loadEntityExample() throws -> Void {
        let service = self.service
        let customer = Customer()
        customer.customerID = "ALFKI"
        try service.loadEntity(customer)
        self.showCustomer(customer)
    }
    

    Example using dynamic API

    open func loadEntityExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customerEntityType = customersEntitySet.entityType
        let customerIDProperty = customerEntityType.property(withName: "CustomerID")
        let customer = EntityValue.ofType(customerEntityType)
        customerIDProperty.setStringValue(in: customer, to: "ALFKI")
        try service.loadEntity(customer)
        self.showCustomer(customer)
    }
    

    Declaration

    Swift

    open func loadEntity(_ entity: EntityValue, query: DataQuery? = nil, headers: HTTPHeaders = HTTPHeaders.empty, options: RequestOptions = RequestOptions.none) throws

    Parameters

    entity

    Previously loaded entity, whose properties will be modified to reflect the loaded state.

    query

    Optional data query, to specify loading criteria (especially for navigation properties).

    headers

    Optional request-specific headers.

    options

    Optional request-specific options.

  • Load service metadata (if not already loaded).

    See also

    metadata, hasMetadata.

    Declaration

    Swift

    open func loadMetadata(headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    headers

    Optional request-specific headers.

    options

    Optional request-specific options.

  • Declaration

    Swift

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

  • Service metadata.

    See also

    loadMetadata.

    Declaration

    Swift

    open var metadata: CSDLDocument { get set }
  • 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

    public final var metadataListener: MetadataListener? { get set }
  • Provider for acessing the local database.

    Declaration

    Swift

    open var offlineStore: SQLDatabaseProvider { get }
  • Provider for accessing the backend system.

    Declaration

    Swift

    open var onlineProvider: OnlineODataProvider { get }
  • 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

    open func open() throws
  • Set this to false to disable persistence of downloaded entities. Defaults to true. Useful in benchmarking, to separate downloading/parsing from local persistence.

    Declaration

    Swift

    public final var persistDownloadedEntities: Bool { get set }
  • Set this to false to disable persistence of downloaded streams. Defaults to true. Useful in benchmarking, to separate downloading/parsing from local persistence.

    Declaration

    Swift

    public final var persistDownloadedStreams: Bool { get set }
  • Ping the server.

    Declaration

    Swift

    open func pingServer(headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    headers

    Optional request-specific headers.

    options

    Optional request-specific options.

  • Should download prefer compact responses such as Compact JSON encoding? Defaults to true.

    Declaration

    Swift

    public final var preferCompactResponses: Bool { get set }
  • Should traceWithData show pretty-printed JSON/XML content? Defaults to false.

    Declaration

    Swift

    open var prettyTracing: Bool { get set }
  • Declaration

    Swift

    open func previousUser() throws -> String?

    Return Value

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

  • Execute a request batch in the target system.

    Declaration

    Swift

    open func processBatch(_ batch: RequestBatch, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    batch

    The request batch.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Progress listener for download and upload.

    See also

    loadTimeEstimates, saveTimeEstimates.

    Declaration

    Swift

    public final var progressListener: ProgressListener? { get set }
  • Declaration

    Swift

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

    Declaration

    Swift

    open func saveTimeEstimates(file: String) throws

    Parameters

    file

    Time estimates file.

  • Should upload send Repeatable Requests? Defaults to true.

    Declaration

    Swift

    public final var sendRepeatableRequests: Bool { get set }
  • Service name.

    Declaration

    Swift

    open var serviceName: String { get }
  • If the backend supports stream download for offline operation, should it be done with multiple threads in parallel? Defaults to 10 threads. Configure a lower number to reduce memory utilization of clients and servers (such a change may also reduce stream download performance). Configure a higher number to improve stream download performance by reducing network latency (such a change may also increase memory utilization).

    Declaration

    Swift

    public final var streamDownloadThreads: Int { get set }
  • Should upload throw an exception if one or more requests has a service failure due to an HTTP response with a non-successful HTTP status code? Note: if a request fails due to any condition where an HTTP response status code cannot be obtained (e.g. a network failure), an upload call will always throw an exception. Defaults to true.

    Declaration

    Swift

    public final var throwUploadFailures: Bool { get set }
  • Should all requests for this data service be traced? Defaults to false.

    Declaration

    Swift

    open var traceRequests: Bool { get set }
  • If traceRequests is also true, should all requests for this data service be traced with data? Defaults to false. Note that care must be taken when enabling tracing with data, as the resulting log files may contain sensitive information. On the other hand, tracing with data may sometimes be invaluable for troubleshooting purposes.

    Declaration

    Swift

    open var traceWithData: Bool { get set }
  • Undo all pending (local) changes for entities, so they will not be subsequently uploaded.

    Declaration

    Swift

    open func undoPendingChanges(for entities: EntityValueList) throws

    Parameters

    entities

    A list of entities whose pending changes will be undone.

  • Unload service metadata (if previously loaded).

    See also

    metadata, hasMetadata.0

    Declaration

    Swift

    open func unloadMetadata() throws
  • Update an entity in the target system.

    Declaration

    Swift

    open func updateEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    entity

    Entity to be updated.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Update a link from a source entity to a target entity.

    Declaration

    Swift

    open func updateLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    from

    Source entity for the link to be updated.

    property

    Source navigation property for the link to be updated. This must be a one-to-one navigation property.

    to

    Target entity for the link to be updated.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Upload data changes for all uploadable entity sets.

    Declaration

    Swift

    open 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

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

  • Enable background upload (for execution environments where it is applicable, otherwise ignored). Defaults to false. When using background uploads, it is preferable to also enable batchEntityUploads and batchStreamUploads (where supported by the backend service).

    Declaration

    Swift

    public final var uploadInBackground: Bool { get set }
  • If the backend supports request upload for offline operation, how many bytes (maximum) should be uploaded per iteration? Defaults to 5,000,000 bytes. Configure a lower number to reduce memory utilization of clients and servers (such a change may also reduce request upload performance). Configure a higher number to improve request upload performance by reducing network latency (such a change may also increase memory utilization).

    Declaration

    Swift

    public final var uploadIterationSize: Int { get set }
  • Upload content for a media entity to the target system Caution: Having too many threads simultaneously uploading streams may result in out-of-memory conditions on memory-constrained devices. Note: this function cannot be used to create a media entity. See DataService.createMedia.

    Declaration

    Swift

    open func uploadMedia(entity: EntityValue, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    entity

    Entity whose content is to be uploaded.

    content

    Upload stream content. Will be closed before this function returns.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • Upload content for a stream property to the target system. Caution: Having too many threads simultaneously uploading streams may result in out-of-memory conditions on memory-constrained devices.

    See also

    Property.getStreamLink.

    Declaration

    Swift

    open func uploadStream(entity: EntityValue, link: StreamLink, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws

    Parameters

    entity

    Entity containing the stream property whose content is to be uploaded.

    link

    Stream link for the stream to be uploaded.

    content

    Upload stream content. Will be closed before this function returns.

    headers

    Request-specific headers.

    options

    Request-specific options.

  • If the backend supports request upload for offline operation, should it be done with multiple threads in parallel? Defaults to 10 threads. Configure a lower number to reduce memory utilization of clients and servers (such a change may also reduce request upload performance). Configure a higher number to improve request upload performance by reducing network latency (such a change may also increase memory utilization).

    Declaration

    Swift

    public final var uploadWorkerThreads: Int { get set }
  • If a background download or upload session completes, the application may need to wait for local processing of the background request results, before notifying a completion handler. When using background download/upload, call this function from the application delegate’s handleEventsForBackgroundURLSession callback.

    Declaration

    Swift

    open func waitForCompletion(sessionIdentifier: String, completionHandler: @escaping () -> Void)