CloudSyncProvider

For internal use by proxy services.

Construct an offline OData provider.

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.

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.

Frequency of automatic metadata fetches (if enabled). Defaults to one day.

Should the latest metadata be occasionally fetched from the backend service (during download), in case it has changed. Defaults to true.

Maximum amount of time that waitForCompletion should wait for background request completion. Defaults to 20 seconds.

If the backend supports entity download for offline operation, should it be done with batch requests? Defaults to true.

If the backend supports entity upload for offline operation, should it be done with batch requests? Defaults to true.

If the backend supports stream download for offline operation, should it be done with batch requests? Defaults to true.

If the backend supports stream upload for offline operation, should it be done with batch requests? Defaults to true.

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

Cancel the specifed pending requests.

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

If hasMetadataChanges would return true, then return a list of the entity sets that need to be re-downloaded.

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.

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.

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.

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.

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

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.

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()
}

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

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

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()
}

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

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.

Execute query to delete data from the target system.

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.

Delete an entity from the target system.

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

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

Download backend data changes into the local database.

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.

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.

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

Retrieve a persistent query previously created by createDownloadQuery.

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.

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.

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.

Encryption key for offlineStore. If an encryption key is required for the offline store, this property must be set before calling open.

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

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

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

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

Has service metadata been loaded.

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.

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

Load service metadata (if not already loaded).

Load previously saved download time estimates from file.

Service metadata.

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.

Provider for acessing the local database.

Provider for accessing the backend system.

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

Set this to false to disable persistence of downloaded entities. Defaults to true. Useful in benchmarking, to separate downloading/parsing from local persistence.

Set this to false to disable persistence of downloaded streams. Defaults to true. Useful in benchmarking, to separate downloading/parsing from local persistence.

Ping the server.

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

Should traceWithData show pretty-printed JSON/XML content? Defaults to false.

Execute a request batch in the target system.

Progress listener for download and upload.

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

Should upload send Repeatable Requests? Defaults to true.

Service name.

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

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.

Should all requests for this data service be traced? Defaults to false.

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.

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

Unload service metadata (if previously loaded).

Update an entity in the target system.

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

Upload data changes for all uploadable entity sets.

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

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

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

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.

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.

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

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.