DEVCON 2026 | 2-5 November 2026 – QEII Centre – London, UK | Register now!

Blogs

Platform

Liferay DXP 2025.Q2 Liferay DXP 2025.Q3 Liferay DXP 2025.Q4

Liferay DXP

CLUSTER

Tunning EHCACHE 3.X

With the 2025.Q2 release, Liferay introduced a breaking change on LPD-40485: Update to Ehcache 3.10 by migrating from Ehcache 2 to Ehcache 3. This change modernizes caching internals but also requires updating the cache configuration format and deployment strategy.

Texto

Daniel Martinez Cisneros

November 06, 2025

A Minute Read

This article explains:

Where to place cache configuration files
How to reference them in portal-ext.properties
Real‑world tuning examples for improving performance

Background: Ehcache in Liferay

Liferay uses two main cache layers:

Single‑VM Cache: Local in‑JVM cache used for, Optimized for standalone deployments or clusters with database‑level replication.
- EntityCache
- FinderCache
- Service and request‑level caching
Multi‑VM Cache: Distributed cache used in clustered environments for:
- Shared cache invalidation
- Consistency across nodes

Migration to Ehcache 3 (2025.Q2+)

Area	Old (Ehcache 2) < 2025.Q2	New (Ehcache 3) > 2025.Q2
Config format	Ehcache 2 XML	Ehcache 3 XML & schema
File names	`liferay-single-vm.xml`, `liferay-multi-vm.xml`	Same names, new syntax
Classes	`net.sf.ehcache.*`	`org.ehcache.*`
Expiry	`timeToIdle`, `timeToLive`	`<expiry><tti/> <ttl/></expiry>`
Heap syntax	`maxEntriesLocalHeap`	`<heap>`

Configuration File Locations

1. Place your custom config files here:

TOMCAT_HOME/webapps/ROOT/WEB-INF/classes/ehcache/

Typical structure:

/ehcache

├── liferay-single-vm-override.xml

└── liferay-multi-vm-override.xml

2. Referencing Custom Config in portal-ext.properties:

ehcache.single.vm.config.location=/ehcache/liferay-single-vm-override.xml 
ehcache.multi.vm.config.location=/ehcache/liferay-multi-vm-override.xml

Default config files location:

Located in jar file:

${LIFERAY_HOME}/osgi/portal/com.liferay.portal.cache.ehcache.impl.jar

Or in github for each version:
- liferay-multi-vm.xml: liferay-portal/modules/apps/portal-cache/portal-cache-ehcache-impl/src/main/resources/ehcache/liferay-multi-vm.xml at master · liferay/liferay-portal
- liferay-single-vm.xml: liferay-portal/modules/apps/portal-cache/portal-cache-ehcache-impl/src/main/resources/ehcache/liferay-single-vm.xml at master · liferay/liferay-portal

Example: Custom Ehcache 3 Tuning

Below are examples to optimize caching for DDMFieldAttributeImpl, a common hot cache entry in heavily customized DXP installations using Dynamic Data Mapping.

Goal

Increase heap to support large datasets
Extend idle expiration for better cache retention
Reduce DB round trips

Sample XML (Ehcache 3)

<cache alias="com.liferay.portal.kernel.dao.orm.EntityCache.com.liferay.dynamic.data.mapping.model.impl.DDMFieldAttributeImpl"> 
   <expiry> 
      <ttl>3600<\/ttl> <!-- expire after 1 hour regardless of usage -->
      <tti>600<\/tti> <!-- expire after 10 minutes idle -->
   </expiry> 
   <heap>200000</heap> 
</cache>

What these settings mean

Setting	Meaning
`heap`	max entries stored in memory
`tti`	Time‑to‑Idle (evict if not accessed for X seconds)
`ttl`	time to live
`uses-template="default"`	inherits base cache config defined in XML