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

OfflineDataServiceAsync

open class OfflineDataServiceAsync : DataServiceAsync

An specialization of {@link com.sap.cloud.mobile.kotlin.odata.DataService} where the {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#provider OfflineDataServiceAsync.provider} is a {@link com.sap.cloud.mobile.kotlin.odata.DataSyncProvider}, using the async/await style of asynchronous operations.

Constructors

constructor(provider: DataSyncProvider)

Construct an offline data service using an offline provider.

Properties

onlineProvider

open val onlineProvider: OnlineODataProvider

serviceOptions

open val serviceOptions: ServiceOptions

syncProvider

open val syncProvider: DataSyncProvider

transferExecutor

var transferExecutor: Executor

The executor for async transfers (e.g. upload / download). By default, this will be a parallel executor.

Functions

asyncTransfer

fun asyncTransfer(block: () -> Unit)

Invoke an upload or download asynchronously.

cancelDownload

open suspend fun cancelDownload()

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

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

cancelPendingRequests

open suspend fun cancelPendingRequests()

See cancelPendingRequests_(PendingRequestList?).

open suspend 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.OfflineDataServiceAsync#getQueuedRequests_(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) OfflineDataServiceAsync.getQueuedRequests}, {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#getFailedRequests_(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) OfflineDataServiceAsync.getFailedRequests}.

cancelUpload

open suspend fun cancelUpload()

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

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

clear

open suspend fun clear()

Clear the {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#syncProvider OfflineDataServiceAsync.syncProvider}, destroying the local database. This does not communicate with the backend system.

open suspend fun close()

Close the {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#syncProvider OfflineDataServiceAsync.syncProvider}, disconnecting from the local database. This does not communicate with the backend system.

createDownloadQuery

open suspend fun createDownloadQuery(name: String, query: DataQuery)

See createDownloadQuery_(String, DataQuery, Boolean).

open suspend 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.OfflineDataServiceAsync#deleteDownloadQuery_(kotlin.String) OfflineDataServiceAsync.deleteDownloadQuery}, {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#getDownloadQuery_(kotlin.String) OfflineDataServiceAsync.getDownloadQuery}, {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#getDownloadQueries_(com.sap.cloud.mobile.kotlin.odata.EntitySet?) OfflineDataServiceAsync.getDownloadQueries}.

deleteDownloadQuery

open suspend fun deleteDownloadQuery(name: String)

Delete a persistent query previously created by {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#createDownloadQuery_(kotlin.String, com.sap.cloud.mobile.kotlin.odata.DataQuery, kotlin.Boolean) OfflineDataServiceAsync.createDownloadQuery}, along with any previously downloaded associated entities. Note: if there is a large number of previously downloaded associated entities, deletion of the download query might be time-consuming. Consider invoking this method in a background thread to avoid blocking the application's user interface thread.

download

open suspend fun download()

open suspend fun download(groups: StringList?)

See download_(StringList?, SyncOptions?).

open suspend fun download(groups: StringList?, options: SyncOptions?)

Download backend data changes into the local database.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#cancelDownload_() OfflineDataServiceAsync.cancelDownload}.

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.OfflineDataServiceAsync#getDownloadGroup(kotlin.String) OfflineDataServiceAsync.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.OfflineDataServiceAsync#getDownloadGroup(kotlin.String) OfflineDataServiceAsync.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.OfflineDataServiceAsync#download_(com.sap.cloud.mobile.kotlin.odata.StringList?, com.sap.cloud.mobile.kotlin.odata.SyncOptions?) OfflineDataServiceAsync.download}, {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#getDownloadGroup(kotlin.String) OfflineDataServiceAsync.getDownloadGroup}.

getDownloadGroup

open 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.OfflineDataServiceAsync#download_(com.sap.cloud.mobile.kotlin.odata.StringList?, com.sap.cloud.mobile.kotlin.odata.SyncOptions?) OfflineDataServiceAsync.download} or before calling {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#open_() OfflineDataServiceAsync.open} (in the case that {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#open_() OfflineDataServiceAsync.open} may perform an implicit {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#download_(com.sap.cloud.mobile.kotlin.odata.StringList?, com.sap.cloud.mobile.kotlin.odata.SyncOptions?) OfflineDataServiceAsync.download}).

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#downloadInGroup(kotlin.String, com.sap.cloud.mobile.kotlin.odata.EntitySet...) OfflineDataServiceAsync.downloadInGroup}.

getDownloadQueries

open suspend fun getDownloadQueries(): DownloadQueryList

See getDownloadQueries_(EntitySet?).

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

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

getDownloadQuery

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

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

getEventHistory

open suspend 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}, and {@link com.sap.cloud.mobile.kotlin.odata.SyncEvent#time SyncEvent.time} (psuedo-properties that can be referenced by the query for filtering and ordering).

getFailedRequests

open suspend fun getFailedRequests(): PendingRequestList

open suspend fun getFailedRequests(query: DataQuery?): PendingRequestList

open suspend fun getFailedRequests(query: DataQuery?, headers: HttpHeaders?): PendingRequestList

See getFailedRequests_(DataQuery?, HttpHeaders?, RequestOptions?).

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

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#hasFailedRequests(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) OfflineDataServiceAsync.hasFailedRequests}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#changeSet PendingRequest.changeSet}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#customTag PendingRequest.customTag}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#firstSent PendingRequest.firstSent}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#lastSent PendingRequest.lastSent}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpMethod PendingRequest.httpMethod}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpStatus PendingRequest.httpStatus}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestID PendingRequest.requestID}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestURL PendingRequest.requestURL}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#uploadGroup PendingRequest.uploadGroup}.

getPreviousUser

open fun getPreviousUser(): String?

In a multiple user scenario, when a new user starts using the application on a mobile device, it might have pending requests in the local database that need to be uploaded using the previous user's identity. This function can be called before {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#open_() OfflineDataServiceAsync.open} is called to determine whether special action is needed. Calling {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#open_() OfflineDataServiceAsync.open} when there is a known previous user might result in {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#upload_(com.sap.cloud.mobile.kotlin.odata.StringList?, com.sap.cloud.mobile.kotlin.odata.SyncOptions?) OfflineDataServiceAsync.upload} and/or {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#download_(com.sap.cloud.mobile.kotlin.odata.StringList?, com.sap.cloud.mobile.kotlin.odata.SyncOptions?) OfflineDataServiceAsync.download} being called by {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#open_() OfflineDataServiceAsync.open}.

getQueuedRequests

open suspend fun getQueuedRequests(): PendingRequestList

open suspend fun getQueuedRequests(query: DataQuery?): PendingRequestList

open suspend fun getQueuedRequests(query: DataQuery?, headers: HttpHeaders?): PendingRequestList

See getQueuedRequests_(DataQuery?, HttpHeaders?, RequestOptions?).

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

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#hasQueuedRequests(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) OfflineDataServiceAsync.hasQueuedRequests}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#changeSet PendingRequest.changeSet}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#customTag PendingRequest.customTag}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#firstSent PendingRequest.firstSent}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#lastSent PendingRequest.lastSent}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpMethod PendingRequest.httpMethod}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpStatus PendingRequest.httpStatus}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestID PendingRequest.requestID}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestURL PendingRequest.requestURL}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#uploadGroup PendingRequest.uploadGroup}.

hasFailedRequests

open fun hasFailedRequests(): Boolean

open fun hasFailedRequests(query: DataQuery?): Boolean

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

See hasFailedRequests(DataQuery?, HttpHeaders?, RequestOptions?).

open 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). This includes requests that have been sent to the backend system, but which failed to execute successfully.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#getFailedRequests_(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) OfflineDataServiceAsync.getFailedRequests}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#changeSet PendingRequest.changeSet}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#customTag PendingRequest.customTag}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#firstSent PendingRequest.firstSent}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpMethod PendingRequest.httpMethod}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpStatus PendingRequest.httpStatus}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestID PendingRequest.requestID}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestURL PendingRequest.requestURL}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#uploadGroup PendingRequest.uploadGroup}.

hasInitialData

open fun hasInitialData(): Boolean

Return true if {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#download_(com.sap.cloud.mobile.kotlin.odata.StringList?, com.sap.cloud.mobile.kotlin.odata.SyncOptions?) OfflineDataServiceAsync.download} has been explicitly or implicitly called (by {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#open_() OfflineDataServiceAsync.open}) to obtain initial data.

hasPendingDownload

open fun hasPendingDownload(): Boolean

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

hasPendingUpload

open fun hasPendingUpload(): Boolean

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

hasQueuedRequests

open fun hasQueuedRequests(): Boolean

open fun hasQueuedRequests(query: DataQuery?): Boolean

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

See hasQueuedRequests(DataQuery?, HttpHeaders?, RequestOptions?).

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

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#getQueuedRequests_(com.sap.cloud.mobile.kotlin.odata.DataQuery?, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) OfflineDataServiceAsync.getQueuedRequests}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#changeSet PendingRequest.changeSet}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#customTag PendingRequest.customTag}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#firstSent PendingRequest.firstSent}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpMethod PendingRequest.httpMethod}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#httpStatus PendingRequest.httpStatus}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestID PendingRequest.requestID}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#requestURL PendingRequest.requestURL}, {@link com.sap.cloud.mobile.kotlin.odata.PendingRequest#uploadGroup PendingRequest.uploadGroup}.

lastDownloadTime

open fun lastDownloadTime(): GlobalDateTime?

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

lastUploadTime

open fun lastUploadTime(): GlobalDateTime?

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

open

open suspend fun open()

Open the {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#syncProvider OfflineDataServiceAsync.syncProvider}, performing any necessary initialization such as creation of the local database. Depending on the provider implementation, the first call to open might (or might not) communicate with the backend system. If {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#hasInitialData() OfflineDataServiceAsync.hasInitialData} returns false after calling open, then {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#download_(com.sap.cloud.mobile.kotlin.odata.StringList?, com.sap.cloud.mobile.kotlin.odata.SyncOptions?) OfflineDataServiceAsync.download} must be explicitly called to obtain initial data. If {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#hasInitialData() OfflineDataServiceAsync.hasInitialData} returns true after calling open, then initial data has already been obtained from the backend system.

undoPendingChanges

open suspend fun undoPendingChanges(entities: EntityValueOrList)

Undo all pending (local) changes for entities, so they will not be subsequently uploaded. For best performance, if multiple entities are to be undone, make one call with an {@link com.sap.cloud.mobile.kotlin.odata.EntityValueList} rather than multiple calls with an {@link com.sap.cloud.mobile.kotlin.odata.EntityValue}.

upload

open suspend fun upload()

open suspend fun upload(groups: StringList?)

See upload_(StringList?, SyncOptions?).

open suspend fun upload(groups: StringList?, options: SyncOptions?)

Upload local pending changes to the backend OData service.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.OfflineDataServiceAsync#cancelUpload_() OfflineDataServiceAsync.cancelUpload}.

uploadDatabaseFile

open suspend fun uploadDatabaseFile()

open suspend fun uploadDatabaseFile(encryptionKey: String?)

open suspend fun uploadDatabaseFile(encryptionKey: String?, note: String?)

See uploadDatabaseFile_(String?, String?, SyncOptions?).

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