Inside Liferay's Caching Layers
Almost every 'I changed something but the portal still shows the old value' problem in Liferay is a caching problem. Liferay caches aggressively at multiple independent layers, each with its own lifetime and its own invalidation rules. When data looks stale, the real question is never 'is caching on' - it always is - but 'which layer is holding the old value.' Answering that quickly requires a map of the layers.
The caching stack, top to bottom
Think of caching as a stack. A request may be answered by any layer before it reaches the database, and each layer can independently be stale.
| Layer | Caches | Typical staleness cause |
|---|---|---|
| Fragment / portlet cache | Rendered HTML output | Content changed but output cached |
| Entity cache | Individual model objects by primary key | Direct DB write bypassing the service layer |
| Finder cache | Query results (lists of IDs) | New record not reflected in a cached query |
| Hibernate cache | ORM-level objects | Second-level cache not invalidated |
| Database cache | Query and buffer pools | Outside Liferay's control |
Entity cache: objects by primary key
The entity cache stores individual model objects keyed by their primary key. When you fetch a blog entry by ID, Liferay checks this cache first. It is invalidated automatically when you update the entry through the service layer. The word automatically is doing a lot of work: if you write to the database directly with SQL, bypassing the service layer, the entity cache never learns about the change and happily serves the old object.
Finder cache: results of queries
The finder cache stores the results of finder methods - the lists of IDs returned by queries like 'all entries in this group'. This is separate from the entity cache. You can have a perfectly fresh entity cache and still get a stale list because the finder cache remembers the old set of matching IDs. Adding a record through a direct SQL insert is the classic way to leave the finder cache stale.
// Goes through the service layer:
// entity + finder caches are invalidated correctly.
_blogsEntryLocalService.updateEntry(entry);
// Direct SQL insert/update:
// caches are NOT invalidated -> stale reads.
jdbcTemplate.update(
"INSERT INTO BlogsEntry (...) VALUES (...)");Rendered output cache
Above the data layers sits caching of rendered markup - portlet output and fragment output. This can make a page appear stale even when every data cache is correct, because the HTML was rendered and stored before the data changed. Personalized or permission-filtered output complicates this: caching one user's rendered view and showing it to another is a subtle correctness bug, not just a freshness one.
Clustering multiplies the problem
In a clustered deployment each node has its own caches. Invalidating a cache on one node does not automatically clear it on the others unless cache replication or invalidation messaging is configured. A record can look updated on the node you are hitting and stale on the node your colleague is hitting. This is why 'it works for me' is a legitimate and important clue in a clustered Liferay environment.
A debugging order that works
- Reproduce with a hard refresh to rule out the browser cache first.
- Check whether the change was made through the service layer or via direct SQL.
- If the object is stale, suspect the entity cache; if a list is stale, suspect the finder cache.
- If the data is right but the page is wrong, suspect the rendered output cache.
- In a cluster, check whether the correct value appears on some nodes but not others.
Conclusion
Liferay's caching is not one cache but a layered stack: rendered output, entities, finders, ORM, and the database beneath. Each layer speeds the portal up and each can independently hold a stale value. The engineers who resolve caching issues in minutes are the ones who know the layers, know that the service layer keeps them coherent, and know that bypassing it is what breaks them. Map the layers once and you stop guessing forever.