Auto saving PDF files on Android

Nutrient automatically saves annotations at certain trigger events. This mechanism works well; however, there’s still the chance data will be lost if a device restarts or runs out of battery, or if your application crashes before a save completes.

With document checkpointing, Nutrient offers a checkpointing mode that works in the background, offering an effective crash recovery mechanism to restore unsaved changes. This is an advanced feature and is disabled by default, as it requires some configuration to work effectively.

ℹ️ Note: Instant stores annotations in a database and synchronizes with Document Engine as soon as a connection is available, which greatly reduces the chances of data loss if the app terminates suddenly. No checkpointing or other custom setup is needed. Read more in our offline support.

Understanding document checkpoints

A checkpoint contains all the unsaved data of a document. Let’s call this the “dirty” data. This data is temporary and is persisted into the document when #saveIfModifiedAsync() is called. With document checkpoints, this dirty data can be continually saved to a separate checkpoint file, and in the event of a crash, it can be restored to the document.

Checkpoints are managed by the PdfDocumentCheckpointer instance of your PdfDocument. To retrieve the checkpointer, call #getCheckpointer() on your document. To control the frequency at which checkpoints are written, you can set a PdfDocumentCheckpointingStrategy on the checkpointer using #setStrategy().

Checkpointing strategies

The checkpointing strategy defines the frequency at which checkpoints are created. There are three different checkpointing strategies available:

• PdfDocumentCheckpointingStrategy.MANUAL — The checkpoint has to be saved manually by calling PdfDocumentCheckpointer#saveCheckpointAsync() or PdfDocumentCheckpointer#saveCheckpoint(). This is the default.

• PdfDocumentCheckpointingStrategy.TIMED — The checkpoint will be saved at a preset interval, as long as the document exists and there are unsaved changes.

• PdfDocumentCheckpointingStrategy.IMMEDIATE — The checkpointer reacts to changes made to the document, saving a checkpoint every time a change is made.

For most use cases, PdfDocumentCheckpointingStrategy.TIMED is a good option and does not affect performance by any significant amount.

Loading a saved checkpoint

A previously saved checkpoint will be loaded automatically if found.

It is important to note that while the document will contain any previously unsaved objects saved in the checkpoint, the loaded changes are not saved to the document. To save them, you must still call #saveIfModifiedAsync(). This will cause the data from the checkpoint file to be written into the document, after which point the checkpoint will be deleted from disk by the PdfDocumentCheckpointer.

Additional information

Supported document types

PdfDocuments that are backed by more than one provider are currently not supported by document checkpoints. Documents that are not backed by a file (custom data provider) work well checkpointing, as long as certain care is taken with regard to their UID. When having checkpoints enabled on a document that uses a custom UID, it’s necessary to be sure that the UID is unique to that document, since the PdfDocumentCheckpointer uses the UID as a part of the checkpoint’s file name. Opening multiple instances of a document with the same UID and making changes to them while they have checkpointing enabled is not supported and will result in undefined behavior.

Checkpoint location

The checkpoints are stored in the PSPDFDocumentCheckpoints folder in app internal storage (more info). You do not have to manage this manually since each PdfDocumentCheckpointer will always delete the document’s previous checkpoint before saving the new one. Additionally, the directory in which the checkpoints are stored is cleaned up, with checkpoints that are older than a week being removed. The checkpoints are not shared in any way and cannot be exported. Furthermore, all the checkpoints can be deleted at any time by PdfDocumentCheckpointer#deleteAllCheckpoints().

Performance

There are two things to consider with document checkpointing in terms of performance:

• Saving — Depending on the strategy, the PdfDocumentCheckpointer saves checkpoints to the location specified above on the background thread. This should not affect your application’s performance in any meaningful way.

• Loading — When loading the checkpoints as specified above, the loading of a document may take a little longer than usual since that is when the document is parsed.