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, 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 removeLocalStorage.

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 SENDING_CHANGES.

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 CLEAN.

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 updateAuthenticationToken.