Troubleshooting Client-only Entities Errors

When an Offline OData application with client-only entities encounters errors, enabling the debug logging for Offline OData can help to identify the possible root cause, and existing troubleshooting technologies, such as Troubleshooting with ILOData can also be used to assist debugging. Some unexpected errors may occur if the metadata document is changed incompatibly.

Incompatible Metadata Change

The compatible metadata change is listed in the DataService.refreshMetadata API. For Offline OData application with client-only entity, the metadata changes may come from either the client-only metadata or the back-end metadata. The forcePurgeClientOnlyDataOnMetadataChange Offline OData parameter can be enabled if the metadata is changed incompatibly. This option will try to purge the client only entities and upgrade the database schema according to the new metadata in the offline store.

Java

OfflineODataParameters parameters = new OfflineODataParameters();
parameters.setEnableClientOnlyMetadata(true);

// Enable this option to try to work around an incompatible metadata change error.
parameters.setForcePurgeClientOnlyDataOnMetadataChange(true);

Kotlin

var offlineODataParameters = OfflineODataParameters().apply {
    isEnableClientOnlyMetadata = true

    // Enable this option to try to work around an incompatible metadata change error.
    isForcePurgeClientOnlyDataOnMetadataChange = true
}

Swift

let offlineParameters = OfflineODataParameters()
offlineParameters.enableClientOnlyMetadata = true

// Enable this option to try to work around an incompatible metadata change error.
offlineParameters.forcePurgeClientOnlyDataOnMetadataChange = true

Purge Client-only Entities

The number of client-only entities may keep growing over time and impact performance. While querying and deleting the stale client-only entities one by one would work, it is not the best approach. Use the OfflineODataProvider.purgeClientOnlyData API to discard all client-only data, including local draft.

Java

offlineODataProvider.purgeClientOnlyData();

Kotlin

offlineODataProvider.purgeClientOnlyData()

Swift

offlineODataProvider.purgeClientOnlyData()

Turn Off The Client-only Entity Feature

If the enableClientOnlyMetadata parameter is turned from on to off, Offline OData will try to purge client-only entities and delete the database schema for client-only metadata in the offline store.

Java

OfflineODataParameters parameters = new OfflineODataParameters();
parameters.setEnableClientOnlyMetadata(false);

Kotlin

var offlineODataParameters = OfflineODataParameters().apply {
    isEnableClientOnlyMetadata = false
}

Swift

let offlineParameters = OfflineODataParameters()
offlineParameters.enableClientOnlyMetadata = false

Mulit-user And Client-only Entities

When using client-only entities for multi users, the default behavior during switching users is to purge the client-only entities, given that the temporary client-only data belongs to the previous user. The client-only entities can be shared between users by setting forcePurgeClientOnlyDataOnUserSwitch to false.

Java

OfflineODataParameters parameters = new OfflineODataParameters();
parameters.setEnableClientOnlyMetadata(true);

//parameters.setForcePurgeClientOnlyDataOnUserSwitch(true);
//Set forcePurgeClientOnlyDataOnUserSwitch to false to share the client-only data between users
parameters.setForcePurgeClientOnlyDataOnUserSwitch(false);

Kotlin

var offlineODataParameters = OfflineODataParameters().apply {
    isEnableClientOnlyMetadata = true

    // isForcePurgeClientOnlyDataOnUserSwitch = true
    // Set forcePurgeClientOnlyDataOnUserSwitch to false to share the client-only data between users
    isForcePurgeClientOnlyDataOnUserSwitch = false
}

Swift

let offlineParameters = OfflineODataParameters()
offlineParameters.enableClientOnlyMetadata = true

//offlineParameters.forcePurgeClientOnlyDataOnUserSwitch = true
//Set forcePurgeClientOnlyDataOnUserSwitch to false to share the client-only data between users
offlineParameters.forcePurgeClientOnlyDataOnUserSwitch = false

---

Last update: June 15, 2023