kotlin-odata/com.sap.cloud.mobile.kotlin.odata/CloudSyncProvider

CloudSyncProvider

open class CloudSyncProvider : DataSyncProvider, ClientRegistrationProvider

A data service provider that synchronizes data between a local SQL database on a mobile client device and a remote OData service. Occasional {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download} and {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#upload(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.upload} calls may be used to synchronize data changes when the mobile client device is online. The local SQL database will subsequently be queried and updated via the associated {@link com.sap.cloud.mobile.kotlin.odata.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 by the associated {@link com.sap.cloud.mobile.kotlin.odata.OnlineODataProvider} via SAP Mobile Services and/or SAP BTP Connectivity. The OData service should be enabled for OData change tracking, so that {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.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 {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#downloadWithoutDeltaLinks 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 {@link com.sap.cloud.mobile.kotlin.odata.DataService} (or {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataService}) for convenient consumption, including the use of async methods and proxy classes.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#open() CloudSyncProvider.open}, client-side download queries, server-side download queries, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#downloadWithoutDeltaLinks(com.sap.cloud.mobile.kotlin.odata.EntitySet...) CloudSyncProvider.downloadWithoutDeltaLinks}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#downloadQueriesCanOverlap(com.sap.cloud.mobile.kotlin.odata.EntitySet...) CloudSyncProvider.downloadQueriesCanOverlap}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#noDefaultEntityDownload(com.sap.cloud.mobile.kotlin.odata.EntitySet...) CloudSyncProvider.noDefaultEntityDownload}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#noDefaultStreamDownload(com.sap.cloud.mobile.kotlin.odata.EntitySet...) CloudSyncProvider.noDefaultStreamDownload}.

Example using proxy classes:

open fun setupService(): kotlin.Unit
{
    val online = OnlineODataProvider("HealthService",
        "http://health.example.com:8080");
    val database = SQLDatabaseProvider("HealthDB", "jdbc:h2:~/health.h2");
    val offline = CloudSyncProvider(online, database);
    offline.encryptionKey = this.dbEncryptionKey();
    offline.createIndex(HealthService.patients, Patient.dateOfBirth,
        Patient.lastName);
    val service = HealthService(offline);
    service.downloadInGroup("PatientGroup", HealthService.patients,
        HealthService.appointments);
    service.downloadInGroup("StaffGroup", HealthService.doctors,
        HealthService.nurses);
    this.healthService = service;
}

Example using dynamic API:

open fun setupService(): kotlin.Unit
{
    val onlineProvider = OnlineODataProvider("HealthService",
        "http://health.example.com:8080");
    val localDatabase = SQLDatabaseProvider("HealthDB", "jdbc:h2:~/health.h2");
    val offlineProvider = CloudSyncProvider(onlineProvider, localDatabase);
    offlineProvider.encryptionKey = this.dbEncryptionKey();
    offlineProvider.createDynamicIndex("Patients", "dateOfBirth");
    this.healthService = OfflineDataService(offlineProvider);
    this.healthService.open();
}

Constructors

CloudSyncProvider

constructor(onlineProvider: OnlineODataProvider)

See CloudSyncProvider(OnlineODataProvider, SQLDatabaseProvider?).

constructor(onlineProvider: OnlineODataProvider, offlineStore: SQLDatabaseProvider?)

Construct an offline OData provider.

Types

Companion

object Companion

Properties

autoInitialDownload

var autoInitialDownload: Boolean

autoRefreshEntities

var autoRefreshEntities: Boolean

autoRefreshInterval

var autoRefreshInterval: DayTimeDuration

autoRefreshMetadata

var autoRefreshMetadata: Boolean

autoRegisterClient

var autoRegisterClient: Boolean

autoSaveEstimates

var autoSaveEstimates: Boolean

batchEntityDownloads

var batchEntityDownloads: Boolean

batchEntityUploads

var batchEntityUploads: Boolean

batchStreamDownloads

var batchStreamDownloads: Boolean

batchStreamUploads

var batchStreamUploads: Boolean

clientMetadataFile

var clientMetadataFile: String?

combineLocalDeletes

var combineLocalDeletes: Boolean

combineLocalUpdates

var combineLocalUpdates: Boolean

currentUser

var currentUser: String?

downloadInBackground

var downloadInBackground: Boolean

downloadQueueCapacity

var downloadQueueCapacity: Int

emulateBindOperations

var emulateBindOperations: Boolean

emulateLinkOperations

var emulateLinkOperations: Boolean

enableStatementBatching

var enableStatementBatching: Boolean

encryptionKey

open var encryptionKey: String?

entityDownloadThreads

var entityDownloadThreads: Int

forceDownloadOnUserSwitch

var forceDownloadOnUserSwitch: Boolean

forceUploadOnUserSwitch

var forceUploadOnUserSwitch: Boolean

hasMetadata

open override val hasMetadata: Boolean

logErrorStackTraces

var logErrorStackTraces: Boolean

metadata

open override var metadata: CsdlDocument

metadataListener

var metadataListener: MetadataListener?

offlineStore

open val offlineStore: SQLDatabaseProvider

onlineProvider

open override val onlineProvider: OnlineODataProvider

onlineSetup

open override var onlineSetup: Boolean

persistDownloadedEntities

var persistDownloadedEntities: Boolean

persistDownloadedStreams

var persistDownloadedStreams: Boolean

preferCompactResponses

var preferCompactResponses: Boolean

prettyTracing

open var prettyTracing: Boolean

progressListener

var progressListener: ProgressListener?

sendRepeatableRequests

var sendRepeatableRequests: Boolean

serviceName

open override val serviceName: String

streamDownloadThreads

var streamDownloadThreads: Int

throwUploadFailures

var throwUploadFailures: Boolean

timeEstimatesFile

var timeEstimatesFile: String?

traceRequests

open var traceRequests: Boolean

traceUploadFailures

var traceUploadFailures: Boolean

traceWithData

open var traceWithData: Boolean

uploadInBackground

var uploadInBackground: Boolean

uploadIterationSize

var uploadIterationSize: Int

uploadWorkerThreads

var uploadWorkerThreads: Int

Functions

cancelDownload

open override fun cancelDownload()

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

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download}.

cancelPendingRequests

open override fun cancelPendingRequests(requests: PendingRequestList?)

Cancel the specifed pending requests. The requests should be cancelled as a batch, which might perform better than calling {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#cancel() PendingRequest.cancel} one request at a time.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getQueuedRequests(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) CloudSyncProvider.getQueuedRequests}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getFailedRequests(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) CloudSyncProvider.getFailedRequests}.

cancelUpload

open override fun cancelUpload()

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

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#upload(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.upload}.

changedEntitySets

open fun changedEntitySets(): EntitySetList

If {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#hasMetadataChanges() CloudSyncProvider.hasMetadataChanges} would return true, then return a list of the entity sets that need to be re-downloaded.

clear

open override fun clear()

Clear this provider. This will {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#close() CloudSyncProvider.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.

open override fun close()

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.

createDownloadQuery

open override fun createDownloadQuery(name: String, query: DataQuery, streams: Boolean)

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:: {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#entitySet DataQuery.entitySet}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#deleteDownloadQuery(kotlin.String) CloudSyncProvider.deleteDownloadQuery}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadQuery(kotlin.String) CloudSyncProvider.getDownloadQuery}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadQueries(com.sap.cloud.mobile.kotlin.odata.EntitySet?) CloudSyncProvider.getDownloadQueries}.

createDynamicIndex

open fun createDynamicIndex(entitySet: String, item: String, vararg items: String)

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 {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createIndex(com.sap.cloud.mobile.kotlin.odata.EntitySet, com.sap.cloud.mobile.kotlin.odata.PropertyPath, com.sap.cloud.mobile.kotlin.odata.PropertyPath...) CloudSyncProvider.createIndex} by accepting string-typed parameters. It is applicable even when {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#metadata CloudSyncProvider.metadata} is not yet available.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#open() CloudSyncProvider.open}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#indexes EntitySet.indexes}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createIndex(com.sap.cloud.mobile.kotlin.odata.EntitySet, com.sap.cloud.mobile.kotlin.odata.PropertyPath, com.sap.cloud.mobile.kotlin.odata.PropertyPath...) CloudSyncProvider.createIndex}.

createEntity

open override fun createEntity(entity: EntityValue, headers: HttpHeaders, options: RequestOptions)

Create an entity in the target system. Automatically calls {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlDocument#resolveEntity(com.sap.cloud.mobile.kotlin.odata.EntityValue) CsdlDocument.resolveEntity} to ensure that {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#entitySet EntityValue.entitySet} is available.

Throws:: {@link com.sap.cloud.mobile.kotlin.odata.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:: {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#ofType(com.sap.cloud.mobile.kotlin.odata.EntityType, com.sap.cloud.mobile.kotlin.odata.core.SparseIndexMap?) EntityValue.ofType}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#inSet(com.sap.cloud.mobile.kotlin.odata.EntitySet) EntityValue.inSet}.

createIndex

open fun createIndex(entitySet: EntitySet, item: PropertyPath, vararg items: PropertyPath)

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:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#open() CloudSyncProvider.open}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#indexes EntitySet.indexes}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createDynamicIndex(kotlin.String, kotlin.String, kotlin.String...) CloudSyncProvider.createDynamicIndex}.

createLink

open override fun createLink(from: EntityValue, property: Property, to: EntityValue, headers: HttpHeaders, options: RequestOptions)

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

createMedia

open override fun createMedia(entity: EntityValue, content: StreamBase, headers: HttpHeaders, options: RequestOptions)

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.

deleteByQuery

open override fun deleteByQuery(query: DataQuery, headers: HttpHeaders, options: RequestOptions)

Execute query to delete data from the target system.

deleteDownloadQuery

open override fun deleteDownloadQuery(name: String)

Delete a persistent query previously created by {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createDownloadQuery(kotlin.String, com.sap.cloud.mobile.kotlin.odata.DataQuery, kotlin.Boolean) CloudSyncProvider.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.

deleteEntity

open override fun deleteEntity(entity: EntityValue, headers: HttpHeaders, options: RequestOptions)

Delete an entity from the target system.

deleteLink

open override fun deleteLink(from: EntityValue, property: Property, to: EntityValue, headers: HttpHeaders, options: RequestOptions)

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

deleteStream

open override fun deleteStream(entity: EntityValue, link: StreamLink, headers: HttpHeaders, options: RequestOptions)

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

download

open override fun download(groups: StringList, options: SyncOptions)

Download backend data changes into the local database.

downloadInGroup

open fun downloadInGroup(group: String, vararg entitySets: EntitySet)

Configure one or more entity sets to be downloaded in a named group, equivalent to calling {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadGroup(kotlin.String) CloudSyncProvider.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 {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadGroup(kotlin.String) CloudSyncProvider.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.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadGroup(kotlin.String) CloudSyncProvider.getDownloadGroup}.

downloadInPhase

open fun downloadInPhase(phase: Int, vararg entitySets: EntitySet)

Configure one or more entity sets to be downloaded in a numbered phase, equivalent to calling {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadPhase(kotlin.Int) CloudSyncProvider.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 {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadPhase(kotlin.Int) CloudSyncProvider.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.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadPhase(kotlin.Int) CloudSyncProvider.getDownloadPhase}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#setDownloadMode(kotlin.Int, com.sap.cloud.mobile.kotlin.odata.DownloadMode) CloudSyncProvider.setDownloadMode}.

downloadMedia

open override fun downloadMedia(entity: EntityValue, headers: HttpHeaders, options: RequestOptions): ByteStream

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 {@link com.sap.cloud.mobile.kotlin.odata.ByteStream#readAndClose() ByteStream.readAndClose}, may result in out-of-memory conditions on memory-constrained devices.

downloadQueriesCanOverlap

open fun downloadQueriesCanOverlap(vararg entitySets: EntitySet)

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 {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#filter(com.sap.cloud.mobile.kotlin.odata.QueryFilter) 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:: {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#downloadQueriesCanOverlap EntitySet.downloadQueriesCanOverlap}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createDownloadQuery(kotlin.String, com.sap.cloud.mobile.kotlin.odata.DataQuery, kotlin.Boolean) CloudSyncProvider.createDownloadQuery}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#deleteDownloadQuery(kotlin.String) CloudSyncProvider.deleteDownloadQuery}.

downloadStream

open override fun downloadStream(entity: EntityValue, link: StreamLink, headers: HttpHeaders, options: RequestOptions): ByteStream

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 {@link com.sap.cloud.mobile.kotlin.odata.ByteStream#readAndClose() ByteStream.readAndClose}, may result in out-of-memory conditions on memory-constrained devices.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.Property#getStreamLink(com.sap.cloud.mobile.kotlin.odata.StructureBase) Property.getStreamLink}.

downloadWithoutDeltaLinks

open fun downloadWithoutDeltaLinks(vararg entitySets: EntitySet)

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:: {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#downloadWithoutDeltaLinks EntitySet.downloadWithoutDeltaLinks}.

executeMethod

open override fun executeMethod(method: DataMethod, parameters: ParameterList, headers: HttpHeaders, options: RequestOptions): DataValue?

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:: {@link com.sap.cloud.mobile.kotlin.odata.DataServiceException} or {@link com.sap.cloud.mobile.kotlin.odata.DataNetworkException} if an error occurs during action invocation.

executeQuery

open override fun executeQuery(query: DataQuery, headers: HttpHeaders, options: RequestOptions): QueryResult

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

fetchMetadata

open override fun fetchMetadata(headers: HttpHeaders, options: RequestOptions): CsdlDocument

Fetch latest service metadata and return it, but don't change the {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#metadata CloudSyncProvider.metadata} property.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#loadMetadata(com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders, com.sap.cloud.mobile.kotlin.odata.RequestOptions) CloudSyncProvider.loadMetadata}.

getDownloadGroup

open override fun getDownloadGroup(group: String): DownloadGroup

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 {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#open() CloudSyncProvider.open}.

getDownloadPhase

open fun getDownloadPhase(phase: Int): DownloadPhase

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 {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#open() CloudSyncProvider.open}.

getDownloadQueries

open fun getDownloadQueries(): DownloadQueryList

See getDownloadQueries(EntitySet?).

open override fun getDownloadQueries(from: EntitySet?): DownloadQueryList

Retrieve all of the persistent queries previously created by {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createDownloadQuery(kotlin.String, com.sap.cloud.mobile.kotlin.odata.DataQuery, kotlin.Boolean) CloudSyncProvider.createDownloadQuery} for a specified entity set.

getDownloadQuery

open override fun getDownloadQuery(name: String): DownloadQuery?

Retrieve a persistent query previously created by {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createDownloadQuery(kotlin.String, com.sap.cloud.mobile.kotlin.odata.DataQuery, kotlin.Boolean) CloudSyncProvider.createDownloadQuery}.

getEventHistory

open override fun getEventHistory(query: DataQuery?): SyncEventList

Return a list of the synchronization events since the local database was created.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.SyncEvent#eventID SyncEvent.eventID}, {@link com.sap.cloud.mobile.kotlin.odata.SyncEvent#type SyncEvent.type}, {@link com.sap.cloud.mobile.kotlin.odata.SyncEvent#time SyncEvent.time}, {@link com.sap.cloud.mobile.kotlin.odata.SyncEvent#details SyncEvent.details}.

getFailedRequests

open override fun getFailedRequests(query: DataQuery?, headers: HttpHeaders?, options: RequestOptions?): PendingRequestList

Return a list of the failed pending 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.

getPreviousUser

open override fun getPreviousUser(): String?

Return (nullable) The {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#currentUser CloudSyncProvider.currentUser} after {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#open() CloudSyncProvider.open} was last called.

getQueuedRequests

open override fun getQueuedRequests(query: DataQuery?, headers: HttpHeaders?, options: RequestOptions?): PendingRequestList

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.

hasFailedRequests

open override fun hasFailedRequests(query: DataQuery?, headers: HttpHeaders?, options: RequestOptions?): Boolean

Return true if there are any failed requests in the local database (matching the query, if specified).

hasInitialData

open override fun hasInitialData(): Boolean

Return true if a {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download} has previously been successfully executed to obtain initial data for the local database.

hasMetadataChanges

open fun hasMetadataChanges(): Boolean

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:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#changedEntitySets() CloudSyncProvider.changedEntitySets}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#metadataListener CloudSyncProvider.metadataListener}.

hasPendingDownload

open override fun hasPendingDownload(): Boolean

Return true if a {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download} is currently in progress or if the previous download did not terminate normally (i.e. it failed or was cancelled).

hasPendingUpload

open override fun hasPendingUpload(): Boolean

Return true if an {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#upload(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.upload} is currently in progress or if the previous upload did not terminate normally (i.e. it failed or was cancelled).

hasQueuedRequests

open override fun hasQueuedRequests(query: DataQuery?, headers: HttpHeaders?, options: RequestOptions?): Boolean

Return true if there are any queued requests in the local database (matching the query, if specified).

isClientRegistered

open override fun isClientRegistered(): Boolean

Checks locally whether a previous {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#registerClient(com.sap.cloud.mobile.kotlin.odata.EntityValue?) CloudSyncProvider.registerClient} call successfuly created a client registration for the remote OData service.

lastDownloadTime

open override fun lastDownloadTime(): GlobalDateTime?

Return (nullable) Date and time for the last {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download} request.

lastUploadTime

open override fun lastUploadTime(): GlobalDateTime?

Return (nullable) Date and time for the last {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#upload(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.upload} request.

loadEntity

open fun loadEntity(entity: EntityValue)

open fun loadEntity(entity: EntityValue, query: DataQuery?)

open fun loadEntity(entity: EntityValue, query: DataQuery?, headers: HttpHeaders)

See loadEntity(EntityValue, DataQuery?, HttpHeaders, RequestOptions).

open fun loadEntity(entity: EntityValue, query: DataQuery?, headers: HttpHeaders, options: RequestOptions)

Reload an existing entity from the target system.

loadMetadata

open override fun loadMetadata(headers: HttpHeaders, options: RequestOptions)

Load service metadata (if not already loaded).

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#metadata CloudSyncProvider.metadata}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#hasMetadata CloudSyncProvider.hasMetadata}.

loadTimeEstimates

open fun loadTimeEstimates(file: String)

See loadTimeEstimates(String, Boolean).

open fun loadTimeEstimates(file: String, mustExist: Boolean)

Load previously saved download time estimates from file.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OperationProgress}, {@link com.sap.cloud.mobile.kotlin.odata.ProgressListener}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#estimatedDeltaDownloadTime EntitySet.estimatedDeltaDownloadTime}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#estimatedInitialDownloadTime EntitySet.estimatedInitialDownloadTime}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#estimatedStreamDownloadTime EntitySet.estimatedStreamDownloadTime}.

noDefaultEntityDownload

open fun noDefaultEntityDownload(vararg entitySets: EntitySet)

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 {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#createDownloadQuery(kotlin.String, com.sap.cloud.mobile.kotlin.odata.DataQuery, kotlin.Boolean) CloudSyncProvider.createDownloadQuery}.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#downloadEntitiesByDefault EntitySet.downloadEntitiesByDefault}.

noDefaultStreamDownload

open fun noDefaultStreamDownload(vararg entitySets: EntitySet)

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

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#downloadStreamsByDefault EntitySet.downloadStreamsByDefault}.

open

open override fun open()

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 {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#forceUploadOnUserSwitch CloudSyncProvider.forceUploadOnUserSwitch} and/or {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#forceDownloadOnUserSwitch CloudSyncProvider.forceDownloadOnUserSwitch} is enabled).

pingServer

open override fun pingServer(headers: HttpHeaders, options: RequestOptions)

Ping the server.

processBatch

open override fun processBatch(batch: RequestBatch, headers: HttpHeaders, options: RequestOptions)

Execute a request batch in the target system.

registerClient

open override fun registerClient(client: EntityValue?)

If {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#isClientRegistered() CloudSyncProvider.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 {@link com.sap.cloud.mobile.kotlin.odata.ServiceOptions#clientInstanceID 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, {@link com.sap.cloud.mobile.kotlin.odata.ServiceOptions#clientInstanceID 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.

saveTimeEstimates

open fun saveTimeEstimates(file: String)

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

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OperationProgress}, {@link com.sap.cloud.mobile.kotlin.odata.ProgressListener}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#estimatedDeltaDownloadTime EntitySet.estimatedDeltaDownloadTime}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#estimatedInitialDownloadTime EntitySet.estimatedInitialDownloadTime}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#estimatedStreamDownloadTime EntitySet.estimatedStreamDownloadTime}.

setDownloadMode

open fun setDownloadMode(phase: Int, mode: DownloadMode)

Configure the mode (any, batch, parallel or sequence) for a specified {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#download(com.sap.cloud.mobile.kotlin.odata.StringList, com.sap.cloud.mobile.kotlin.odata.SyncOptions) CloudSyncProvider.download} phase. Selecting mode any means that the effective mode is determined by other configuration settings (e.g. for batches or threads).

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#getDownloadPhase(kotlin.Int) CloudSyncProvider.getDownloadPhase}.

undoPendingChanges

open override fun undoPendingChanges(entities: EntityValueList)

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

unloadMetadata

open override fun unloadMetadata()

Unload service metadata (if previously loaded).

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#metadata CloudSyncProvider.metadata}, {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#hasMetadata CloudSyncProvider.hasMetadata}.0

unregisterClient

open override fun unregisterClient(deleteFromServer: Boolean)

Forget any client registration previously established by {@link com.sap.cloud.mobile.kotlin.odata.CloudSyncProvider#registerClient(com.sap.cloud.mobile.kotlin.odata.EntityValue?) CloudSyncProvider.registerClient}. Also attempts to make a call to the server to delete the associated entity, if the deleteFromServer parameter is true.

updateEntity

open override fun updateEntity(entity: EntityValue, headers: HttpHeaders, options: RequestOptions)

Update an entity in the target system.

updateLink

open override fun updateLink(from: EntityValue, property: Property, to: EntityValue, headers: HttpHeaders, options: RequestOptions)

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

upload

open override fun upload(groups: StringList, options: SyncOptions)

Upload data changes for all uploadable entity sets.

uploadDatabaseFile

open override fun uploadDatabaseFile(encryptionKey: String?, note: String?, options: SyncOptions)

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

uploadMedia

open override fun uploadMedia(entity: EntityValue, content: StreamBase, headers: HttpHeaders, options: RequestOptions)

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 {@link com.sap.cloud.mobile.kotlin.odata.DataService#createMedia(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.StreamBase, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataService.createMedia}.

uploadStream

open override fun uploadStream(entity: EntityValue, link: StreamLink, content: StreamBase, headers: HttpHeaders, options: RequestOptions)

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:: {@link com.sap.cloud.mobile.kotlin.odata.Property#getStreamLink(com.sap.cloud.mobile.kotlin.odata.StructureBase) Property.getStreamLink}.