Client Reset - Java SDK
On this page
Tip
See also: Learn More About Client Resets
To learn about the causes of and strategies for handling client resets, check out the Sync Client Resets page.
The SDK reads and writes to a realm file on the device. When you use Atlas Device Sync, this local realm syncs with the application backend. Some conditions can cause the realm to be unable to sync with the backend. When this occurs, you get a client reset error.
This error means you must reset the realm file in the client application. Clients in this state may continue to run and save data locally. Until you perform the client reset, the realm does not sync with the backend.
Choose a client reset strategy to handle client reset errors. These strategies restore realm to a syncable state, but have tradeoffs:
Discard Unsynced Changes. Restore Sync by discarding local changes since the last sync. Maintains change listeners.
Manually Recover Unsynced Changes:. Move the unsyncable realm and download a new copy. Invalidates change listeners.
Both options let you write custom logic to recover local changes. Neither option can recover local changes for you.
Discard unsynced changes is a less complex alternative to manual recovery. However, this strategy cannot handle every client reset error. You must maintain a manual client reset handler as a fallback.
Discard Unsynced Changes
New in version 10.10.0.
Discard unsynced changes is a client reset strategy provided by the SDK. This strategy requires minimal code. This strategy performs a reset without closing the realm or missing notifications.
It does delete all local changes made since the last successful sync. This includes any data already written to the realm but not yet synced to the application backend. Do not use this strategy if your application cannot lose unsynced data.
Discard unsynced changes cannot handle breaking or destructive schema changes. When breaking changes occur, the SDK falls back to manual recovery mode.
To use this strategy, pass an instance of
DiscardUnsyncedChangesStrategy to the
defaultSyncClientResetStrategy()
builder method when you instantiate your App. Your
DiscardUnsyncedChangesStrategy instance must implement the following
methods:
onBeforeReset(). The SDK calls this block when it receives a client reset error from the backend. This occurs before the SDK executes the client reset strategy.onAfterReset(). The SDK calls this block after successfully executing this strategy. This block provides a frozen copy of the original realm. It also returns a live instance of the realm in a syncable state.onError(). The SDK calls this method during a breaking schema change. Behaves similarly to defaultClientResetStrategy().
The following example implements this strategy:
Discard Unsynced Changes after Breaking Schema Changes
Important
Breaking Schema Changes Require an App Schema Update
After a breaking schema change:
All clients must perform a client reset.
You must update client models affected by the breaking schema change.
The discard unsynced changes strategy cannot handle breaking changes. You
must manually handle the client reset in the onError() method. This
example manually discards unsynced changes to handle the client reset:
Manually Recover Unsynced Changes
Tip
Manual recovery replaces the deprecated
SyncSession.ClientResetHandler.
Clients using the deprecated handler can update to manual recovery
with no logic changes.
We do not recommend manual client reset recovery. It requires:
Substantial amounts of code
Schema concessions
Complex conflict resolution logic.
To learn more, see the Advanced Guide to Manual Client Reset Data Recovery.
Test Client Reset Handling
You can manually test your application's client reset handling by terminating and re-enabling Device Sync.
When you terminate and re-enable Sync, clients that have previously connected with Sync are unable to connect until after they perform a client reset. Terminating Sync deletes the metadata from the server that allows the client to synchronize. The client must download a new copy of the realm from the server. The server sends a client reset error to these clients. So, when you terminate Sync, you trigger the client reset condition.
To test client reset handling:
Write data from a client application and wait for it to synchronize.
Terminate and re-enable Device Sync.
Run the client app again. The app should get a client reset error when it tries to connect to the server.
Warning
While you iterate on client reset handling in your client application, you may need to terminate and re-enable Sync repeatedly. Terminating and re-enabling Sync renders all existing clients unable to sync until after completing a client reset. To avoid this in production, test client reset handling in a development environment.