Outdated render cache

Nutrient uses an internal render cache for speeding up page access times. Whether you are using PdfFragment or PdfActivity or you render pages manually using a PdfDocument, pages will be served from the internal cache, if 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, for a specific cache key, there is already a rendered image inside the cache, it is directly served without rerendering.

Cache key generation

The cache key of a page is a combination of the document UID and the page index. 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 creates a hash of that.

💡 Tip: You can inspect the UID of your PdfDocument instance by logging the return value of document.getUid().

What causes the cache to become Stale?

While Nutrient tries to detect changes to a document to avoid a stale cache, there is a set of scenarios in which you have to manually tell Nutrient to invalidate its caches. In most situations, an outdated or stale render cache will cause page display issues, such as flickering of the displayed page or wrong thumbnail images in the thumbnail bar.

Typical operations that will cause an outdated render cache include:

• Reusing the same URI or file path for loading different documents.

• External changes to a previously opened PDF document — for example, adding annotations to it.

• Externally replacing a PDF document — for example, restoring an older version of the PDF.

• Deactivating auto-save and manually saving the PdfDocument instance.

• Having a DataProvider that reuses the same UID for different documents.

ℹ️ Note: When performing any of the listed operations, Nutrient won’t be able to detect file changes. In these cases, a manual cache invalidation should be performed.

Manual cache invalidation

You can invalidate the cache, which forces a rerendering of pages, by using one of the following methods:

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

• PSPDFKit#clearCaches() will invalidate the entire render cache for all documents. Use this sparingly, as misuse might cause slow render access times.