Outdated render cache

Nutrient uses an internal render cache for speeding up page access times. Whether you use PdfFragment or PdfActivity or render pages manually with a PdfDocument, Nutrient serves pages from the internal cache when available. Nutrient will keep track of changes to the document and will invalidate the render cache if necessary.

How caching works

In most situations, Nutrient Android SDK uses an in-memory cache of page renderings. When using the cache (which is the default), Nutrient will generate a unique cache key for every page it renders. If the cache already holds a rendered image for a specific cache key, Nutrient serves it directly without rerendering.

Cache key generation

The cache key of a page is based on the document unique identifier (UID) and the page index. Persisted page cache entries also account for the document data. Replacing a file or data-provider-backed document with different PDF data doesn’t normally reuse old rendered pages. The document UID can be retrieved by calling document.getUid() and is generated in different ways based on the source of the document:

• If the document is loaded from a DataProvider, Nutrient will retrieve the UID using the data provider’s getUid() method.
• If the document is loaded from a local file path, a hash of the path is used.
• For compound documents, Nutrient combines the UID and file paths of all compound document sources and hashes the result.

What causes the cache to become stale?

Nutrient tries to detect document changes to avoid a stale cache, but some scenarios require you to invalidate its caches manually. An outdated render cache usually causes page display issues, such as flickering pages or wrong thumbnail images in the thumbnail bar.

Typical operations that can still cause an outdated render cache include:

• External changes to a previously opened PDF document — for example, adding annotations to it while the document is open.
• Deactivating autosave and manually saving the PdfDocument instance.
• Having a DataProvider that reuses a UID across documents or serves changed bytes without exposing them as changed document data.

Manual cache invalidation

Use one of the following methods to invalidate the cache and force a rerendering of pages:

• PdfDocument#invalidateCacheForPage() can be called to invalidate the cache for a single page of a given document.
• PdfDocument#invalidateCache() will invalidate the render cache for an entire document, including all of its pages.
• Nutrient#clearCaches() will invalidate the entire render cache for all documents. Use this sparingly, as misuse might cause slow render access times.