CloudSyncProvider

For internal use by proxy services.

Construct an offline OData provider.

Enable automatic download as part of initial open call. Defaults to true. 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 false.

If the backend requires client registration, should this provider automate it. Defaults to true.

Should loadTimeEstimates be called on the first call to download after application startup, and saveTimeEstimates be called after each download? 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. The requests should be cancelled as a batch, which might perform better than calling PendingRequest.cancel one request at a time.

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.

When using the dynamic API, you can set this (before calling open) to the name of a client-side file with supplementary metadata. Client-only types (e.g. TypeDefinition, ComplexType, EnumType, EntityType, EntitySet) can be annotated using the “Offline.ClientOnly” annotation. Local draft entity sets (for backend-defined entity types) can be annotated using the “Offline.LocalDraft” annotation. When using proxy classes, rather than setting this property, use the “-X:definitions ” option for proxy generation.

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 proxy classes

open func setupService() throws -> Void {
    let online = OnlineODataProvider(serviceName: "HealthService", serviceRoot: "http://health.example.com:8080")
    let database = SQLDatabaseProvider(serviceName: "HealthDB", databaseURL: "sqlite:~/health.db")
    let offline = CloudSyncProvider(onlineProvider: online,
        offlineStore: database)
    offline.encryptionKey = self.dbEncryptionKey()
    offline.createIndex(HealthService.patients, Patient.dateOfBirth,
        Patient.lastName)
    let service = HealthService(provider: offline)
    service.downloadInGroup("PatientGroup", HealthService.patients,
        HealthService.appointments)
    service.downloadInGroup("StaffGroup", HealthService.doctors,
        HealthService.nurses)
    self.healthService = service
}

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 online = OnlineODataProvider(serviceName: "HealthService", serviceRoot: "http://health.example.com:8080")
    let database = SQLDatabaseProvider(serviceName: "HealthDB", databaseURL: "sqlite:~/health.db")
    let offline = CloudSyncProvider(onlineProvider: online,
        offlineStore: database)
    offline.encryptionKey = self.dbEncryptionKey()
    offline.createIndex(HealthService.patients, Patient.dateOfBirth,
        Patient.lastName)
    let service = HealthService(provider: offline)
    service.downloadInGroup("PatientGroup", HealthService.patients,
        HealthService.appointments)
    service.downloadInGroup("StaffGroup", HealthService.doctors,
        HealthService.nurses)
    self.healthService = service
}

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.

Current user name for open. Set this before calling open. Note: setting this property does not have any affect on authentication of HTTP requests issued by upload and download. The associated onlineProvider needs to be appropriately configured for authentication.

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.

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

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.

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

Configure one or more entity sets to be downloaded in a numbered phase, equivalent to calling getDownloadPhase(phase).add(entitySets). Download phases are used to order the entity sets to be downloaded. This method 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 phase using entity set names (e.g. with the dynamic API), nested group names, or download query names, then call getDownloadPhase 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.

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.

Return a numbered download phase; the phase is created if it doesn’t exist already. Download phases are not remembered across application restart. Download phases should be configured before calling open.

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

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.

Retrieve a persistent query previously created by createDownloadQuery.

The maximum number of download batches that are waiting to be persisted. Defaults to 100.

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.

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.

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.

Enable database-level statement batching during download. Defaults to false. This might result in fallbacks (with warning messages) when duplicates are detected, but should result in better download performance when there is a large amount of data to be downloaded.

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.

If currentUser doesn’t match getPreviousUser when open is called, should open implicitly call download? Defaults to false. If this flag is true and forceUploadOnUserSwitch is also true, then upload will be called before download.

If currentUser doesn’t match getPreviousUser when open is called, should open implicitly call upload? Defaults to false. If this flag is true and forceDownloadOnUserSwitch is also true, then upload will be called before download.

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.

Checks locally whether a previous registerClient call successfuly created a client registration for the remote OData service.

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.

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.

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

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 or if forceUploadOnUserSwitch and/or forceDownloadOnUserSwitch is enabled).

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.

If isClientRegistered would return false, create a new client registration and record its key (ClientID property of type GUID) in local file ~/ClientRegistration/<ServiceName>.json. Otherwise just load the previously locally-saved registration ID into the ServiceOptions.clientInstanceID. The server’s metadata is expected to include a ClientRegistrationSet entity set with entity type ClientRegistration, a key property named ClientID of type long (Edm.Int64), and a property named ClientGUID of type guid (Edm.Guid). If a new registration is successfully created, ServiceOptions.clientInstanceID is set, and will subsequently be used to populate the Client-Instance-ID HTTP header for all OData calls. The purpose of creating such a client registration is to enable the server to associate various resources with the current instance of the current client application. A “current instance” can survive multiple restarts of the client application so long as the same Client-Instance-ID header value is provided for each OData call to the remote service. This is particularly useful for offline applications which rely on server-side OData change tracking implementations that store per-client server-side state to facilitate change tracking.

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

Should upload send Repeatable Requests? Defaults to true.

Service name.

Configure the mode (any, batch, parallel or sequence) for a specified download phase. Selecting mode any means that the effective mode is determined by other configuration settings (e.g. for batches or threads).

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? Defaults to false. 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 should always throw an exception.

Name to be used for time estimates file if autoSaveEstimates is true.

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

Should upload trace upload failures if one or more requests has a service failure due to an HTTP response with a non-successful HTTP status code? Defaults to false. 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 should always log an error (but without request details). Enabling tracing of upload failures can result in sensitive data being included in the log.

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

Forget any client registration previously established by registerClient. Also attempts to make a call to the server to delete the associated entity, if the deleteFromServer parameter is true.

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.