Instant Sync and Document State on Android
Over the course of its lifetime, any
InstantPdfDocument will go through several states. This article covers those states and their transitions in detail.
Lifecycle of an Instant Document
Each document descriptor is initially created with a document state of
CLEAN, meaning the document data is up to date. You can create, read, update, and delete (CRUD) annotations in this document. Making changes to annotations will result in the document descriptor being
DIRTY, which begets a sync.
As written elsewhere, all syncing is two-way: You cannot decide to just fetch or just push data! Instead, syncing always means that any local changes are sent to the server, which then decides a new truth. The server replies with the necessary changes for your local copy to know this new truth, which is then applied locally. For details about the state transitions this entails, please refer to the section on the sync cycle below.
When you are no longer interested in the local data backing a document, you can tell it to
removeLocalStorage. As the name implies, this will delete all local data. In addition, any ongoing network activity will be canceled immediately. Calling this method while the document is pushing changes to the server is possible, but it’s generally not recommended. When
removeLocalStorage returns, the document will be in an
INVALID state and all future interactions will fail.
Because every document is managed by the
InstantClient that created it, it cannot be used without a client. So when a client is invalidated, all documents managed by this client become
INVALID. The other — albeit unlikely — case where a document can enter this state is when Instant detects that its backing data has become corrupted. In this dire situation, there is little you can do apart from calling
The Sync Cycle
When a document descriptor starts syncing, it notifies all registered document listeners by calling
onSyncStarted. It then begins to cycle through several states until all local changes have been synced and the newest server truth has been applied, or until an error occurs. Depending upon the initial document state, this is accompanied by a change to either
SENDING_CHANGES if there were local changes, or
RECEIVING_CHANGES if there were not. When it begins receiving the new server truth,
onDocumentStateChanged is called and the document state switches to
RECEIVING_CHANGES until this truth has been applied to the local database.
Depending on various factors, this can take any amount of time. It is therefore possible that new local changes will have been made when Instant applies the newest server truth. If there are no local changes after applying the new server truth, the sync cycle completes by calling
onSyncFinished and updating the document state to
CLEAN. If, on the other hand, there are unsynced local changes, the sync cycle will continue,
onDocumentStateChanged will be called, and the document state will be updated to
Errors during Sync
If an error occurs while a sync cycle is running, the cycle terminates immediately, and an
onSyncError is called. If the local database contains changes that have not yet been confirmed by the server, the document state is updated to
DIRTY. Otherwise, the state is updated to
In the case of network errors, Instant will retry the sync operation using an exponential, jittered, backoff strategy. In case of authentication failures — such as when the authentication token expires — no such reattempts will be made. Instead, a sync will be started after you make a successful call to