Auto saving PDF files on Android

Nutrient saves annotations at specific events. For details, refer to the saving triggers guide. A restart, depleted battery, or app crash before saving completes can cause data loss.

Document checkpointing stores unsaved changes in the background for recovery after a crash. Automatic checkpointing requires configuration and defaults to disabled.

Understanding document checkpoints

A checkpoint contains the document’s unsaved changes, also called dirty data. Calling #saveIfModifiedAsync() writes these changes into the document. Checkpointing instead stores them in a separate file for recovery after a crash.

Each PdfDocument has a PdfDocumentCheckpointer that manages checkpoints. Retrieve it with #getCheckpointer(). Set a PdfDocumentCheckpointingStrategy through #setStrategy() to control checkpoint frequency.

Checkpointing strategies

Choose one of three checkpointing strategies:

• Manual — PdfDocumentCheckpointingStrategy.MANUAL is the default. Call PdfDocumentCheckpointer#saveCheckpointAsync() or PdfDocumentCheckpointer#saveCheckpoint() to save a checkpoint.
• Timed — PdfDocumentCheckpointingStrategy.TIMED saves at a preset interval while the document exists and has unsaved changes.
• Immediate — PdfDocumentCheckpointingStrategy.IMMEDIATE saves a checkpoint after every change.

For most apps, use PdfDocumentCheckpointingStrategy.TIMED to limit the performance impact.

Loading a saved checkpoint

Nutrient automatically loads an existing checkpoint when opening the document. Loading restores changes in memory but doesn’t save them to the document file.

Call #saveIfModifiedAsync() to save the restored changes. After saving, PdfDocumentCheckpointer deletes the checkpoint file.

Additional information

Review these storage requirements and performance considerations before enabling checkpointing.

Supported document types

Checkpointing doesn’t support PdfDocument instances with multiple data providers. Custom data providers support checkpointing if each document has a unique UID.

Assign a unique UID to each document because PdfDocumentCheckpointer includes it in the checkpoint filename. Don’t edit multiple document instances with the same UID while checkpointing is enabled. This causes undefined behavior.

Checkpoint location

Nutrient stores checkpoints in the PSPDFDocumentCheckpoints folder in app internal storage(opens in a new tab). The checkpointer deletes the previous checkpoint before saving a new one. Nutrient also removes checkpoints older than one week.

You can’t share or export checkpoints. To delete all checkpoints, call PdfDocumentCheckpointer#deleteAllCheckpoints().

Performance

Checkpointing affects saving and loading differently:

• Saving — PdfDocumentCheckpointer writes checkpoints on a background thread according to the selected strategy.
• Loading — Restoring a checkpoint can increase document loading time because Nutrient parses the document during loading.