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

DataServiceAsync

Encapsulates an OData data service.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataQuery}.

Example using proxy classes:

open fun dataServiceExample(): kotlin.Unit
{
    val provider = OnlineODataProvider("NorthwindService",
        "http://services.odata.org/V4/Northwind/Northwind.svc/");
    val service = NorthwindService(provider);
    val query = DataQuery()
        .select(Customer.customerID, Customer.companyName, Customer.contactName)
        .orderBy(Customer.companyName);
    val customers = service.getCustomers(query);
    this.showCustomers(customers);
    val customer = customers.get(0).copy();
    customer.companyName = "Created Inc.";
    service.createEntity(customer);
    customer.companyName = "Updated Inc.";
    service.updateEntity(customer);
    service.deleteEntity(customer);
}

Example using dynamic API:

open fun dataServiceExample(): kotlin.Unit
{
    val provider = OnlineODataProvider("NorthwindService",
        "http://services.odata.org/V4/Northwind/Northwind.svc/");
    val service = DataService(provider);
    service.loadMetadata();
    val customersEntitySet = service.getEntitySet("Customers");
    val customerEntityType = customersEntitySet.entityType;
    val customerIDProperty = customerEntityType.getProperty("CustomerID");
    val companyNameProperty = customerEntityType.getProperty("CompanyName");
    val contactNameProperty = customerEntityType.getProperty("ContactName");
    val query = DataQuery()
        .select(customerIDProperty, companyNameProperty, contactNameProperty)
        .from(customersEntitySet).orderBy(companyNameProperty);
    val customers = service.executeQuery(query).getEntityList();
    this.showCustomers(customers);
    val customer = customers.first().copyEntity();
    companyNameProperty.setString(customer, "Created Inc.");
    service.createEntity(customer);
    companyNameProperty.setString(customer, "Updated Inc.");
    service.updateEntity(customer);
    service.deleteEntity(customer);
}

Inheritors

OfflineDataServiceAsync

OnlineDataServiceAsync

Constructors

DataServiceAsync

constructor(provider: DataServiceProvider)

Construct a new data service using a specified provider.

Properties

actionExecutor

var actionExecutor: Executor

The executor for async actions (e.g. create / update / delete methods). By default, this will be a serial executor.

completionHandler

var completionHandler: Handler

Handler that will be used to post completion of an async action or function call. The default handler will notify the UI thread.

functionExecutor

var functionExecutor: Executor

The executor for async functions (e.g. query methods). By default, this will be a parallel executor.

hasMetadata

open val hasMetadata: Boolean

metadata

open val metadata: CsdlDocument

metadataLock

open val metadataLock: MetadataLock

name

open val name: String

provider

open val provider: DataServiceProvider

Functions

activateDraft

open suspend fun activateDraft(entity: EntityValue): EntityValue

open suspend fun activateDraft(entity: EntityValue, headers: HttpHeaders): EntityValue

See activateDraft_(EntityValue, HttpHeaders, RequestOptions).

open suspend fun activateDraft(entity: EntityValue, headers: HttpHeaders, options: RequestOptions): EntityValue

Activate a draft entity.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#makeDraftCopy_(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders, com.sap.cloud.mobile.kotlin.odata.RequestOptions) DataServiceAsync.makeDraftCopy}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#withCreate() EntityValue.withCreate}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#withUpdate() EntityValue.withUpdate}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#withDeepCreate(com.sap.cloud.mobile.kotlin.odata.PropertyPath...) EntityValue.withDeepCreate}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#withDeepUpdate(com.sap.cloud.mobile.kotlin.odata.PropertyPath...) EntityValue.withDeepUpdate}.

applyChanges

open suspend fun applyChanges(changes: ChangeSet)

open suspend fun applyChanges(changes: ChangeSet, headers: HttpHeaders?)

See applyChanges_(ChangeSet, HttpHeaders?, RequestOptions?).

open suspend fun applyChanges(changes: ChangeSet, headers: HttpHeaders?, options: RequestOptions?)

Apply the changes from a change set to the target system.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#processBatch_(com.sap.cloud.mobile.kotlin.odata.RequestBatch, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataServiceAsync.processBatch}.

asyncAction

fun asyncAction(block: () -> Unit)

Invoke a data change action asynchronously.

asyncFunction

fun asyncFunction(block: () -> Unit)

Invoke a data query function asynchronously.

checkIfCancelled

open fun checkIfCancelled(token: CancelToken?)

Check if token has been marked for cancellation. If it has, throw {@link com.sap.cloud.mobile.kotlin.odata.RequestCancelledException}.

createEntity

open suspend fun createEntity(entity: EntityValue)

open suspend fun createEntity(entity: EntityValue, headers: HttpHeaders?)

See createEntity_(EntityValue, HttpHeaders?, RequestOptions?).

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

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}, {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#createRelatedEntity_(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.Property, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataServiceAsync.createRelatedEntity}, Create Related Entities When Creating an Entity.

createLink

open suspend fun createLink(from: EntityValue, property: Property, to: EntityValue)

open suspend fun createLink(from: EntityValue, property: Property, to: EntityValue, headers: HttpHeaders?)

See createLink_(EntityValue, Property, EntityValue, HttpHeaders?, RequestOptions?).

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

Create a link from a source entity to a target entity in the target system.

createMedia

open suspend fun createMedia(entity: EntityValue, content: StreamBase)

open suspend fun createMedia(entity: EntityValue, content: StreamBase, headers: HttpHeaders?)

See createMedia_(EntityValue, StreamBase, HttpHeaders?, RequestOptions?).

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

Create a media entity with the specified content. 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.

createRelatedEntity

open suspend fun createRelatedEntity(entity: EntityValue, parent: EntityValue, property: Property)

open suspend fun createRelatedEntity(entity: EntityValue, parent: EntityValue, property: Property, headers: HttpHeaders?)

open suspend fun createRelatedEntity(entity: EntityValue, parent: EntityValue, property: Property, headers: HttpHeaders?, options: RequestOptions?)

Create an entity in the target system, related to an existing parent entity via a parent navigation property.

createRelatedMedia

open suspend fun createRelatedMedia(entity: EntityValue, content: StreamBase, parent: EntityValue, property: Property)

open suspend fun createRelatedMedia(entity: EntityValue, content: StreamBase, parent: EntityValue, property: Property, headers: HttpHeaders?)

open suspend fun createRelatedMedia(entity: EntityValue, content: StreamBase, parent: EntityValue, property: Property, headers: HttpHeaders?, options: RequestOptions?)

Create an media entity in the target system, related to a parent entity via a parent navigation property.

deleteByQuery

open suspend fun deleteByQuery(query: DataQuery)

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

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

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

Execute query to delete data from the target system.

deleteEntity

open suspend fun deleteEntity(entity: EntityValue)

open suspend fun deleteEntity(entity: EntityValue, headers: HttpHeaders?)

See deleteEntity_(EntityValue, HttpHeaders?, RequestOptions?).

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

Delete an entity from the target system.

deleteLink

open suspend fun deleteLink(from: EntityValue, property: Property)

open suspend fun deleteLink(from: EntityValue, property: Property, to: EntityValue)

open suspend fun deleteLink(from: EntityValue, property: Property, to: EntityValue, headers: HttpHeaders?)

See deleteLink_(EntityValue, Property, EntityValue, HttpHeaders?, RequestOptions?).

open suspend 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 suspend fun deleteStream(entity: EntityValue, link: StreamLink)

open suspend fun deleteStream(entity: EntityValue, link: StreamLink, headers: HttpHeaders?)

See deleteStream_(EntityValue, StreamLink, HttpHeaders?, RequestOptions?).

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

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

downloadMedia

open suspend fun downloadMedia(entity: EntityValue): ByteArray

open suspend fun downloadMedia(entity: EntityValue, headers: HttpHeaders?): ByteArray

See downloadMedia_(EntityValue, HttpHeaders?, RequestOptions?).

open suspend fun downloadMedia(entity: EntityValue, headers: HttpHeaders?, options: RequestOptions?): ByteArray

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.

downloadStream

open suspend fun downloadStream(entity: EntityValue, link: StreamLink): ByteArray

open suspend fun downloadStream(entity: EntityValue, link: StreamLink, headers: HttpHeaders?): ByteArray

See downloadStream_(EntityValue, StreamLink, HttpHeaders?, RequestOptions?).

open suspend fun downloadStream(entity: EntityValue, link: StreamLink, headers: HttpHeaders?, options: RequestOptions?): ByteArray

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.DataServiceAsync#downloadToFile_(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.StreamLink, kotlin.String, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataServiceAsync.downloadToFile}, {@link com.sap.cloud.mobile.kotlin.odata.Property#getStreamLink(com.sap.cloud.mobile.kotlin.odata.StructureBase) Property.getStreamLink}.

downloadToFile

open suspend fun downloadToFile(entity: EntityValue, link: StreamLink, file: String): ByteStream

open suspend fun downloadToFile(entity: EntityValue, link: StreamLink, file: String, headers: HttpHeaders?): ByteStream

See downloadToFile_(EntityValue, StreamLink, String, HttpHeaders?, RequestOptions?).

open suspend fun downloadToFile(entity: EntityValue, link: StreamLink, file: String, headers: HttpHeaders?, options: RequestOptions?): ByteStream

Downloading the content of a stream property from the target system into a local file. The local file name can be absolute or relative. If a relative path is provided, resolution of the relative path is platform dependent. On iOS, it is resolved against the application's Documents directory. On Android, it is resolved against the application's files directory. On other platforms, it is resolved against the current working directory.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#downloadMedia_(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataServiceAsync.downloadMedia}, {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#downloadStream_(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.StreamLink, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataServiceAsync.downloadStream}.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.ByteStream#copyToFile(kotlin.String) ByteStream.copyToFile}.

executeMethod

open suspend fun executeMethod(method: DataMethod): DataValue?

open suspend fun executeMethod(method: DataMethod, parameters: ParameterList): DataValue?

open suspend fun executeMethod(method: DataMethod, parameters: ParameterList, headers: HttpHeaders?): DataValue?

See executeMethod_(DataMethod, ParameterList, HttpHeaders?, RequestOptions?).

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

executeQuery

open suspend fun executeQuery(query: DataQuery): QueryResult

open suspend fun executeQuery(query: DataQuery, headers: HttpHeaders?): QueryResult

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

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

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

fetchMetadata

open suspend fun fetchMetadata(): CsdlDocument

open suspend fun fetchMetadata(headers: HttpHeaders?): CsdlDocument

See fetchMetadata_(HttpHeaders?, RequestOptions?).

open suspend 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.DataServiceAsync#metadata DataServiceAsync.metadata} property.

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

getDataMethod

open fun getDataMethod(name: String): DataMethod

Lookup a data method by qualified name (for function/action definitions) or by unqualified name (for function/action imports). Panic if the data method does not exist.

getEntitySet

open fun getEntitySet(name: String): EntitySet

Lookup an entity set by name. Panic if the entity set does not exist.

getSingleton

open fun getSingleton(name: String): EntitySet

Lookup a singleton by name. Panic if the singleton does not exist. Note: OData singleton entities are represented by {@link com.sap.cloud.mobile.kotlin.odata.EntitySet} objects where {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#isSingleton EntitySet.isSingleton} is true.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#metadata DataServiceAsync.metadata}.singletons, for looking up singletons that might not exist.

isClientRegistered

open fun isClientRegistered(): Boolean

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

loadEntity

open suspend fun loadEntity(entity: EntityValue)

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

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

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

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

Reload an existing entity from the target system.

loadMetadata

open suspend fun loadMetadata()

open suspend fun loadMetadata(headers: HttpHeaders?)

See loadMetadata_(HttpHeaders?, RequestOptions?).

open suspend fun loadMetadata(headers: HttpHeaders?, options: RequestOptions?)

Load service metadata into {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#provider DataServiceAsync.provider} (if not already loaded).

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

loadProperty

open suspend fun loadProperty(property: Property, into: EntityValue)

open suspend fun loadProperty(property: Property, into: EntityValue, query: DataQuery?)

open suspend fun loadProperty(property: Property, into: EntityValue, query: DataQuery?, headers: HttpHeaders?)

See loadProperty_(Property, EntityValue, DataQuery?, HttpHeaders?, RequestOptions?).

open suspend fun loadProperty(property: Property, into: EntityValue, query: DataQuery?, headers: HttpHeaders?, options: RequestOptions?)

Load the value of a property into an existing entity. This can be applied to both structural and navigation properties.

makeDraftCopy

open suspend fun makeDraftCopy(entity: EntityValue): EntityValue

open suspend fun makeDraftCopy(entity: EntityValue, headers: HttpHeaders): EntityValue

See makeDraftCopy_(EntityValue, HttpHeaders, RequestOptions).

open suspend fun makeDraftCopy(entity: EntityValue, headers: HttpHeaders, options: RequestOptions): EntityValue

Create a draft copy of an entity. If the draft copy is intended to be subsequently activated to update (edit) the original entity, use {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forUpdate() EntityValue.forUpdate} or {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forDeepUpdate(com.sap.cloud.mobile.kotlin.odata.PropertyPath...) EntityValue.forDeepUpdate} to indicate this. If the draft copy is intended to be subsequently activated to create a clone of the original entity, use {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forCreate() EntityValue.forCreate} or {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forDeepCreate(com.sap.cloud.mobile.kotlin.odata.PropertyPath...) EntityValue.forDeepCreate} to indicate this.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#activateDraft_(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders, com.sap.cloud.mobile.kotlin.odata.RequestOptions) DataServiceAsync.activateDraft}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forCreate() EntityValue.forCreate}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forUpdate() EntityValue.forUpdate}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forDeepCreate(com.sap.cloud.mobile.kotlin.odata.PropertyPath...) EntityValue.forDeepCreate}, {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#forDeepUpdate(com.sap.cloud.mobile.kotlin.odata.PropertyPath...) EntityValue.forDeepUpdate}.

notifyCompletion

fun notifyCompletion(completion: () -> Unit)

pingServer

open suspend fun pingServer()

open suspend fun pingServer(headers: HttpHeaders?)

See pingServer_(HttpHeaders?, RequestOptions?).

open suspend fun pingServer(headers: HttpHeaders?, options: RequestOptions?)

Ping the server.

processBatch

open suspend fun processBatch(batch: RequestBatch)

open suspend fun processBatch(batch: RequestBatch, headers: HttpHeaders?)

See processBatch_(RequestBatch, HttpHeaders?, RequestOptions?).

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

Execute a request batch in the target system. Note: If the request batch contains just one item, that item being a change set, the {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#applyChanges_(com.sap.cloud.mobile.kotlin.odata.ChangeSet, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataServiceAsync.applyChanges} function is recommended for conciseness.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.RequestBatch}, {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#applyChanges_(com.sap.cloud.mobile.kotlin.odata.ChangeSet, com.sap.cloud.mobile.kotlin.odata.http.HttpHeaders?, com.sap.cloud.mobile.kotlin.odata.RequestOptions?) DataServiceAsync.applyChanges}.

refreshMetadata

open suspend fun refreshMetadata()

Reload latest metadata from the backend server. If the metadata was previously loaded (or was obtained from generated proxy classes), then a compatibility check is performed. If the latest metadata is not compatible with the previous metadata, {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlException} will be thrown. If the latest metadata is compatible with the previous metadata, the latest metadata will be applied. It is generally recommended to use this function during application startup to check if the server's metadata has been updated since the client application was constructed. If an application wishes to use the data service for actions or updates, while refreshing the metadata in another thread, the code using the data service for actions or updates should perform those operations while holding a read lock on the {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#metadataLock DataServiceAsync.metadataLock}. Execution of functions or queries will automatically obtain a read lock on {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#metadataLock DataServiceAsync.metadataLock}.

Compatible metadata changes include:

Adding structural/navigation properties to complex/entity types.
Adding new types (enumeration, simple, complex, entity).
Adding new entity sets or singletons.
Adding new actions or functions.
Adding an action parameter that is nullable to the end of the parameter list.

Other additions, changes, and removals are considered incompatible by default, including:

Adding members to an enumeration type.
Changing the base type for any type.
Changing the value of an enumeration member.
Changing the type (or nullability) of any structural/navigation property.
Changing the type (or nullability) of any action/function parameter or result.
Removing the definition of a model element.
Removing members from an enumeration type.
Removing structural/navigation properties from a complex/entity type.

Addition of enumeration members can be pre-approved by a caller using the dynamic API before calling refreshMetadata (see {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlDocument#hasOpenEnumerations CsdlDocument.hasOpenEnumerations}). If an application uses generated proxy classes, then generating them with the "-open:enumerations" option will automate the necessary pre-approval. The hasOpenEnumerations flag should only be explicitly set when using the dynamic API. Explicitly setting the hasOpenEnumerations flag when using generated proxy classes (generated without the "-open:enumerations" option) could result in runtime exceptions.

Changes to model elements can be pre-approved by a caller using the dynamic API before calling refreshMetadata (see {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlDocument#canChangeAnything CsdlDocument.canChangeAnything}). Applications using generated proxy classes should not pre-approve such changes, as they are likely to result in application instability. For example, if a property's data type is changed, it could result in runtime exceptions since proxy class properties have a pre-determined type that is embedded into the application's compiled code.

Removal of model elements can be pre-approved by the caller before calling refreshMetadata (see {@link com.sap.cloud.mobile.kotlin.odata.csdl.CsdlDocument#canRemoveAnything CsdlDocument.canRemoveAnything}), or preferably by setting the canBeRemoved flag on model elements that the application is prepared for the removal of. Application developers should take care not to pre-approve the removal of model elements unless the application is coded to check at runtime for the possible removal of those elements. The allowance for removals is intended to support "newer" versions of client applications communicating with "older" service implementations but in the general case may require the application to have some embedded knowledge of the changes that were made to the service metadata between the older and newer service implementations. If a newer client application makes unconditional use of a model element that did not exist in an older service implementation, then the non-existence of that model element after calling refreshMetadata could result in runtime exceptions.

If refreshMetadata succeeds, then any added model elements will have isExtension == true, and any removed model elements will have isRemoved == true. Changed model elements will not be distinguishable.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.Property#isExtension Property.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.StructureType#extensionProperties StructureType.extensionProperties}, {@link com.sap.cloud.mobile.kotlin.odata.StructureType#isExtension StructureType.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.SimpleType#isExtension SimpleType.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.EnumType#isExtension EnumType.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.DataMethod#isExtension DataMethod.isExtension}, {@link com.sap.cloud.mobile.kotlin.odata.EntitySet#isExtension EntitySet.isExtension}.

registerClient

open suspend fun registerClient()

See registerClient_(EntityValue?).

open suspend fun registerClient(client: EntityValue?)

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

saveEntity

open suspend fun saveEntity(entity: EntityValue)

open suspend fun saveEntity(entity: EntityValue, headers: HttpHeaders?)

See saveEntity_(EntityValue, HttpHeaders?, RequestOptions?).

open suspend fun saveEntity(entity: EntityValue, headers: HttpHeaders?, options: RequestOptions?)

Create (if {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#isNew EntityValue.isNew}) or update (if existing) an entity in the target system.

unloadMetadata

open suspend fun unloadMetadata()

Unload service metadata {@link com.sap.cloud.mobile.kotlin.odata.DataServiceAsync#provider DataServiceAsync.provider} (if previously loaded).

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

unregisterClient

open suspend fun unregisterClient()

See unregisterClient_(Boolean).

open suspend fun unregisterClient(deleteFromServer: Boolean)

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

updateEntity

open suspend fun updateEntity(entity: EntityValue)

open suspend fun updateEntity(entity: EntityValue, headers: HttpHeaders?)

See updateEntity_(EntityValue, HttpHeaders?, RequestOptions?).

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

Update an entity in the target system.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.EntityValue#withDeepUpdate(com.sap.cloud.mobile.kotlin.odata.PropertyPath...) EntityValue.withDeepUpdate}, Update Related Entities When Updating an Entity.

updateLink

open suspend fun updateLink(from: EntityValue, property: Property, to: EntityValue)

open suspend fun updateLink(from: EntityValue, property: Property, to: EntityValue, headers: HttpHeaders?)

See updateLink_(EntityValue, Property, EntityValue, HttpHeaders?, RequestOptions?).

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

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

uploadMedia

open suspend fun uploadMedia(entity: EntityValue, content: StreamBase)

open suspend fun uploadMedia(entity: EntityValue, content: StreamBase, headers: HttpHeaders?)

See uploadMedia_(EntityValue, StreamBase, HttpHeaders?, RequestOptions?).

open suspend 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 suspend fun uploadStream(entity: EntityValue, link: StreamLink, content: StreamBase)

open suspend fun uploadStream(entity: EntityValue, link: StreamLink, content: StreamBase, headers: HttpHeaders?)

See uploadStream_(EntityValue, StreamLink, StreamBase, HttpHeaders?, RequestOptions?).

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