Hibernate Ehcache Configuration: ehcache.xml for Hibernate 7

Hibernate Ehcache configuration is the ehcache.xml file that gives every Hibernate cache region its own Ehcache cache, with a size limit and an expiry time. Hibernate decides what goes into the second level cache and names a region for each cached entity, collection and query. Ehcache 3 stores the entries, and ehcache.xml sets the size limit and the expiry of each region.

We use ehcache.xml to keep the cache of a Hibernate app inside a known memory budget and to limit how old a cached value can get. It matters most for reference data such as languages or countries, which many requests read and few requests change.

The following example declares a shared template, one entity region and the timestamps region, and then points Hibernate to the file and reads the statistics of two regions.

<config xmlns="http://www.ehcache.org/v3">
  <cache-template name="reference-data">
    <expiry>
      <ttl unit="minutes">30</ttl>
    </expiry>
    <heap unit="entries">500</heap>
  </cache-template>

  <cache alias="com.howtodoinjava.hibernate.ehcacheconfig.Language" uses-template="reference-data"/>

  <cache alias="default-update-timestamps-region">
    <expiry>
      <none/>
    </expiry>
    <heap unit="entries">100</heap>
  </cache>
</config>

.property("hibernate.javax.cache.uri", "ehcache.xml")      // read from the classpath

Statistics stats = emf.unwrap(SessionFactory.class).getStatistics();
long hits = stats.getDomainDataRegionStatistics(Language.class.getName()).getHitCount();   // 2
long misses = stats.getQueryRegionStatistics("language-queries").getMissCount();           // 1

Notice that the cache alias equals the region name character for character. When the alias does not match, Hibernate creates a separate cache without any limit, and the settings in the file are never used.

Next, we see how Hibernate names its regions and build the file step by step. After that, we cover templates, ttl and tti expiry, heap sizing, offheap storage, missing regions, concurrency strategies and per-region statistics.

1. How Hibernate Names Its Cache Regions

Hibernate 6 and later use Ehcache 3 through the JCache API. In short, we add hibernate-jcache and ehcache (classifier jakarta), and set four properties.

.property("hibernate.cache.region.factory_class", "jcache")
.property("hibernate.javax.cache.provider", "org.ehcache.jsr107.EhcacheCachingProvider")
.property("hibernate.javax.cache.uri", "ehcache.xml")
.property("hibernate.cache.use_query_cache", true)
.property("hibernate.generate_statistics", true)

A region is a named cache that Hibernate asks the provider for. Hibernate builds one region for each cached entity class and for each cached collection, plus two regions for the query cache. Ehcache looks up a <cache> element whose alias equals the region name, and in Hibernate 7.4 the default names come from the class and field names.

What we cache	Default region name	Changed with
Entity Language	com.howtodoinjava.hibernate.ehcacheconfig.Language (the class name)	@Cache(region = “…”)
Collection Language.translations	com.howtodoinjava.hibernate.ehcacheconfig.Language.translations (class name + field)	@Cache(region = “…”) on the field
Query results with HINT_CACHEABLE	default-query-results-region	HINT_CACHE_REGION on the query
Last change time of each table	default-update-timestamps-region	Cannot be renamed

Our example is the translation store of an app, where a Language (“en”, “English”) has many Translation rows such as greeting = Hello. Every page of the app reads these texts, but a translator changes them only now and then. The language keeps the default region name, whereas the translation entity moves to a short region called translations.

@Entity
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class Language {

  @Id
  @GeneratedValue
  private Long id;

  private String code;
  private String name;

  @OneToMany(mappedBy = "language")
  @Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
  private List<Translation> translations = new ArrayList<>();
}

@Entity
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE, region = "translations")
public class Translation {

  @Id
  @GeneratedValue
  private Long id;

  @Column(name = "message_key")
  private String key;

  private String text;

  @ManyToOne(fetch = FetchType.LAZY)
  private Language language;
}

The @OneToMany field needs its own @Cache, because caching the class does not cache its collections. Hibernate stores each region from the code in the cache with the same alias in ehcache.xml.

2. Ehcache Configuration Example for Hibernate 7

The example runs on Java 25, Hibernate 7.4.11.Final, Ehcache 3.12.0 and an in-memory H2 database. The complete project on GitHub prints the settings Ehcache applied to every cache along with the SQL and statistics of each step, and 22 JUnit tests check all of them (mvn compile exec:java, mvn test).

2.1. The Structure of ehcache.xml

One <config> element describes one Ehcache CacheManager. Hibernate creates that manager from the file when the EntityManagerFactory starts and closes it with the factory. Inside <config>, the file needs only a few elements.

Element	Purpose
<cache-template name=”…”>	Settings shared by several caches
<cache alias=”…”>	One cache; the alias is the Hibernate region name
uses-template=”…”	Copies all settings of a template into the cache
<expiry>	<ttl>, <tti> or <none/>
<heap unit=”entries”>	Size of the on-heap store, in entries or in kB/MB
<resources>	Several storage tiers together: <heap>, <offheap>, <disk>
<key-type>, <value-type>	Type check on keys and values; leave them out for Hibernate (see FAQ 3.2)

The complete file of the example declares every region from the table in section 1, plus the named query region language-queries.

<config xmlns="http://www.ehcache.org/v3">

  <!-- Shared settings for reference data -->
  <cache-template name="reference-data">
    <expiry>
      <ttl unit="minutes">30</ttl>
    </expiry>
    <heap unit="entries">500</heap>
  </cache-template>

  <!-- Entity region: the fully qualified class name -->
  <cache alias="com.howtodoinjava.hibernate.ehcacheconfig.Language" uses-template="reference-data"/>

  <!-- Collection region: class name + "." + field name -->
  <cache alias="com.howtodoinjava.hibernate.ehcacheconfig.Language.translations" uses-template="reference-data"/>

  <!-- Entity region renamed with @Cache(region = "translations"); overrides the template -->
  <cache alias="translations" uses-template="reference-data">
    <expiry>
      <tti unit="minutes">10</tti>
    </expiry>
    <heap unit="entries">5000</heap>
  </cache>

  <!-- Query results: the default region and a named one -->
  <cache alias="default-query-results-region">
    <expiry>
      <ttl unit="minutes">5</ttl>
    </expiry>
    <heap unit="entries">200</heap>
  </cache>
  <cache alias="language-queries" uses-template="reference-data"/>

  <!-- Last change time per table: never expire -->
  <cache alias="default-update-timestamps-region">
    <expiry>
      <none/>
    </expiry>
    <heap unit="entries">100</heap>
  </cache>
</config>

A wrong alias does not fail. Hibernate creates a separate cache, and the settings in the file are never used. For example, when a refactoring moves Language to another package, the region name changes with it, and the old alias stays in the file without any effect. So we always read the applied settings back from Ehcache once, through the JCache CacheManager that Hibernate created.

CacheManager cacheManager = ((JCacheRegionFactory) emf.unwrap(SessionFactoryImplementor.class)
    .getCache().getRegionFactory()).getCacheManager();

Eh107Configuration<Object, Object> config = cacheManager.getCache("translations").getConfiguration(Eh107Configuration.class);
CacheRuntimeConfiguration<Object, Object> runtime = config.unwrap(CacheRuntimeConfiguration.class);
ResourcePools pools = runtime.getResourcePools();       // heap=5000 entries
ExpiryPolicy<?, ?> expiry = runtime.getExpiryPolicy();  // TTI of PT10M

com.howtodoinjava.hibernate.ehcacheconfig.Language -> heap=500 entries, TTL of PT30M
com.howtodoinjava.hibernate.ehcacheconfig.Language.translations -> heap=500 entries, TTL of PT30M
default-query-results-region -> heap=200 entries, TTL of PT5M
default-update-timestamps-region -> heap=100 entries, No Expiry
language-queries -> heap=500 entries, TTL of PT30M
translations -> heap=5000 entries, TTI of PT10M

2.2. Sharing Settings With Cache Templates

Most regions of reference data need the same limits. A <cache-template> holds them once, and each cache picks them up with uses-template. Elements written inside the cache override the template. For example, translations takes the template but replaces its ttl with a tti and its heap with 5000 entries, as the last line of the output in section 2.1 shows.

A template is not a fallback for regions we forgot, so a region without a <cache> element does not use any template unless we set the JCache default template from section 2.6.

2.3. Expiry With ttl, tti and none

Expiry removes an entry after some time, so the cache picks up changes that other programs made in the database. For example, a support engineer fixes a French translation with a SQL script, and Hibernate never sees that update. With a 30 minute ttl, the app shows the old text for at most 30 minutes. Ehcache 3 has three expiry types, and each one starts the clock at a different moment.

Element	The entry expires	Good for
<ttl unit=”minutes”>30</ttl>	30 minutes after it was stored, even if it is read all the time	Data that other programs can change
<tti unit=”minutes”>10</tti>	10 minutes after the last read	Keeping hot entries and dropping unused ones
<none/>	Never; only eviction or our code removes it	default-update-timestamps-region

To test expiry, the file ehcache-expiry.xml sets a 1 second ttl on Language and a 2 second tti on translations. The pause() helper waits with LockSupport.parkNanos(), and each find() runs in a new session.

<cache alias="com.howtodoinjava.hibernate.ehcacheconfig.Language">
  <expiry>
    <ttl unit="seconds">1</ttl>
  </expiry>
  <heap unit="entries">100</heap>
</cache>

<cache alias="translations">
  <expiry>
    <tti unit="seconds">2</tti>
  </expiry>
  <heap unit="entries">100</heap>
</cache>

// the insert stored English at t=0
emf.runInTransaction(em -> em.find(Language.class, enId));   // t=1ms:    hit
pause(Duration.ofMillis(500));
emf.runInTransaction(em -> em.find(Language.class, enId));   // t=508ms:  hit
pause(Duration.ofMillis(700));
emf.runInTransaction(em -> em.find(Language.class, enId));   // t=1213ms: miss
// select l1_0.id,l1_0.code,l1_0.name from Language l1_0 where l1_0.id=?

emf.runInTransaction(em -> em.find(Translation.class, helloId));   // t=6ms:    miss, put
pause(Duration.ofMillis(1200));
emf.runInTransaction(em -> em.find(Translation.class, helloId));   // t=1208ms: hit
pause(Duration.ofMillis(1200));
emf.runInTransaction(em -> em.find(Translation.class, helloId));   // t=2410ms: hit, older than 2 s
pause(Duration.ofMillis(2200));
emf.runInTransaction(em -> em.find(Translation.class, helloId));   // t=4613ms: miss
// select t1_0.id,t1_0.message_key,t1_0.language_id,t1_0.text from Translation t1_0 where t1_0.id=?

The third translation read is a hit although the entry is 2.4 seconds old, because each read restarts the idle time.

A tti alone never refreshes an entry that is read often, so a value changed by another program can stay stale for as long as people keep reading it. For data that other programs change, we use ttl.

2.4. Sizing the Heap by Entries or by Memory

The heap tier keeps the cached values as Java objects in the JVM heap, and we size it in one of two ways.

• <heap unit=”entries”>500</heap> counts entries, which is fast and predictable.
• <heap unit=”kB”>64</heap> (or MB) measures the memory of each entry, so Ehcache walks the object graph of every value to compute its size.

Byte sizing has a cost on every put, and on Java 25 the module system blocks part of the object walk. We stored 1,000 languages in a 64 kB heap and got a warning with a stack trace.

WARN org.ehcache.sizeof.ObjectGraphWalker - The JVM is preventing Ehcache from accessing the subgraph beneath 'private final byte[] java.lang.String.value' - cache sizes may be underestimated as a result
java.lang.reflect.InaccessibleObjectException: Unable to make field private final byte[] java.lang.String.value accessible: module java.base does not "opens java.lang" to unnamed module @37e4624e

Language entries in 64 kB: 154 of 1000

We size the heap in entries for Hibernate regions. The size estimate skips the contents of every String, so a memory limit is not reliable, and the log gets a warning with a stack trace.

2.5. Eviction and the Offheap Tier

When the heap is full, Ehcache removes an entry to make room for a new one. This is called eviction, and the evicted entry is gone from the cache, so the next read of it goes to the database. The file ehcache-small-heap.xml gives the Language region a heap of 2 entries, and we store three languages.

<!-- Room for two languages only -->
<cache alias="com.howtodoinjava.hibernate.ehcacheconfig.Language">
  <heap unit="entries">2</heap>
</cache>

<!-- Two languages on the heap, the rest off the heap -->
<cache alias="translations">
  <resources>
    <heap unit="entries">2</heap>
    <offheap unit="MB">10</offheap>
  </resources>
</cache>

saveLanguages(emf);                                                      // puts=3, entries=2
boolean englishCached = emf.getCache().contains(Language.class, enId);   // false: evicted
emf.runInTransaction(em -> em.find(Language.class, enId));
// select l1_0.id,l1_0.code,l1_0.name from Language l1_0 where l1_0.id=?
// misses=1, puts=1
boolean frenchCached = emf.getCache().contains(Language.class, frId);    // false: French made room for English

Loading English stored it again and evicted French. When the heap is smaller than the data that is read often, the cache keeps evicting and reloading entries, so most reads go to the database.

The translations region adds a second tier. An <offheap> tier stores entries outside the Java heap, so they do not add to garbage collection work, and the heap keeps only some of them. With the offheap tier, all three translations stay cached.

// translations: heap=2 entries, offheap=10 mb, entries=3
Translation hello = em.find(Translation.class, helloId);       // greeting=Hello
Translation bonjour = em.find(Translation.class, bonjourId);   // greeting=Bonjour
Translation hallo = em.find(Translation.class, halloId);       // greeting=Hallo
// hits=3, misses=0, no SQL

Ehcache sets a few rules for the offheap tier, and they affect both speed and memory.

• Every value is serialized when it is stored and deserialized when it is read. Hibernate’s cache entries are Serializable, so no extra code is needed, but each read costs more than a heap read.
• A multi-tier cache always has a heap tier, and the heap must be smaller than the offheap tier.
• The offheap memory is not part of -Xmx, so we set -XX:MaxDirectMemorySize to fit the offheap size, as the Ehcache documentation recommends.

2.6. Regions Without a Cache Element

When a region is missing from ehcache.xml, Hibernate follows hibernate.javax.cache.missing_cache_strategy. The file ehcache-missing.xml declares only Language and the query regions, and leaves out translations and the collection, so we can see what each value of the setting does.

Value	Startup	Cache that is created
create-warn (default)	Logs HHH90001006 for every missing region	No size limit, no expiry
create	No log	No size limit, no expiry
fail	Stops with a CacheException	None

WARN org.hibernate.orm.cache - HHH90001006: Missing cache region [translations] was created with provider-specific default policies. Explicitly configure the region and its policies, or disable this warning by setting 'hibernate.javax.cache.missing_cache_strategy' to 'create'.

translations -> heap=9223372036854775807 entries

jakarta.persistence.PersistenceException: Unable to build Hibernate SessionFactory  [persistence unit: ehcache-config]
Caused by: org.hibernate.cache.CacheException: On-the-fly creation of JCache Cache objects is not supported [com.howtodoinjava.hibernate.ehcacheconfig.Language.translations]

The heap of Long.MAX_VALUE entries means the cache grows until the JVM runs out of memory. We set missing_cache_strategy to fail in production, so a renamed entity or a typo in an alias stops the application at startup instead of creating an unbounded cache. With fail, Hibernate names the first missing region it builds, which is either the collection or the entity.

When we prefer a fallback, Ehcache’s JCache extension applies a template to every cache created at runtime.

<config xmlns="http://www.ehcache.org/v3"
        xmlns:jsr107="http://www.ehcache.org/v3/jsr107">

  <service>
    <jsr107:defaults default-template="fallback"/>
  </service>

  <cache-template name="fallback">
    <expiry>
      <ttl unit="minutes">10</ttl>
    </expiry>
    <heap unit="entries">1000</heap>
  </cache-template>

  <cache alias="com.howtodoinjava.hibernate.ehcacheconfig.Language">
    <heap unit="entries">500</heap>
  </cache>
</config>

com.howtodoinjava.hibernate.ehcacheconfig.Language -> heap=500 entries, No Expiry
com.howtodoinjava.hibernate.ehcacheconfig.Language.translations -> heap=1000 entries, TTL of PT10M
default-query-results-region -> heap=1000 entries, TTL of PT10M
default-update-timestamps-region -> heap=1000 entries, TTL of PT10M
translations -> heap=1000 entries, TTL of PT10M

The missing regions get a limit from the template, but Hibernate still logs HHH90001006 for each of them. The timestamps region also got the 10 minute ttl, which is wrong for that region (see FAQ 3.5), so we still declare default-update-timestamps-region with <none/>.

2.7. Choosing a Concurrency Strategy per Region

The concurrency strategy in @Cache(usage = …) decides what Hibernate does with a region’s entry when a transaction inserts or changes the entity. We set it in the code, not in ehcache.xml, but it changes how many puts and misses each region sees. To compare the strategies, we cached one small Label entity with each strategy, inserted “Save”, changed it to “Save changes” and read it in a new session.

Strategy	After persist()	Update	Next find()	Use it for
READ_ONLY	Cached (1 put)	Fails: Can’t update read-only object	Miss, SELECT	Data that never changes, with @Immutable
NONSTRICT_READ_WRITE	Not cached	Allowed; the entry is removed	Miss, SELECT	Rare changes, a short stale read is acceptable
READ_WRITE	Cached (1 put)	Allowed; the entry is replaced at commit	Hit, no SQL	Data that changes; the usual choice
TRANSACTIONAL	Cached (1 put)	Allowed; replaced at commit	Hit, no SQL	JTA with a transactional provider such as Infinispan

With Ehcache, two of the strategies print a warning at startup.

WARN org.hibernate.orm.cache - HHH90001003: Read-only caching was requested for mutable entity [com.howtodoinjava.hibernate.ehcacheconfig.ReadOnlyLabel]
WARN org.hibernate.orm.cache - HHH90001008: Cache region [com.howtodoinjava.hibernate.ehcacheconfig.TransactionalLabel] has the access type 'transactional' which is not supported by [JCacheRegionFactory]. Ensure cache implementation supports JTA transactions.

Ehcache through JCache does not support TRANSACTIONAL. Hibernate accepts it with the warning, and in our test it behaved like READ_WRITE, without any JTA guarantee. For READ_ONLY, we add @Immutable to the entity, which removes the warning and makes Hibernate skip changes instead of failing. A list of supported currencies that changes only with a new release of the app is a good fit for READ_ONLY.

2.8. Reading Statistics per Region

With hibernate.generate_statistics on, the SessionFactory counts hits, misses and puts for each region separately. Global counters do not show a region with a bad configuration, so we check each one. We read English and its translations in two new sessions, and after that ran a cached JPQL query twice in the named region.

emf.runInTransaction(em -> em.find(Language.class, enId).getTranslations());   // [greeting=Hello]
// select t1_0.language_id,t1_0.id,t1_0.message_key,t1_0.text from Translation t1_0 where t1_0.language_id=?
emf.runInTransaction(em -> em.find(Language.class, enId).getTranslations());   // [greeting=Hello], no SQL

List<Language> languages = em.createQuery("select l from Language l order by l.code", Language.class)
    .setHint(HibernateHints.HINT_CACHEABLE, true)
    .setHint(HibernateHints.HINT_CACHE_REGION, "language-queries")
    .getResultList();                     // [de (German), en (English), fr (French)], twice, one SELECT

The Statistics interface has one method per region type, and each method returns a CacheRegionStatistics.

Statistics stats = emf.unwrap(SessionFactory.class).getStatistics();

String[] regions = stats.getSecondLevelCacheRegionNames();                                             // all regions in use
CacheRegionStatistics languageStats = stats.getDomainDataRegionStatistics(Language.class.getName());   // entity and collection regions
CacheRegionStatistics queryStats = stats.getQueryRegionStatistics("language-queries");                 // query result regions
CacheRegionStatistics anyStats = stats.getCacheRegionStatistics("language-queries");                   // either kind

for (String region : stats.getSecondLevelCacheRegionNames()) {
  CacheRegionStatistics s = stats.getCacheRegionStatistics(region);
  System.out.println(region + ": hits=" + s.getHitCount() + " misses=" + s.getMissCount() + " puts=" + s.getPutCount());
}

default-query-results-region: hits=0 misses=0 puts=0
com.howtodoinjava.hibernate.ehcacheconfig.Language: hits=2 misses=0 puts=0
translations: hits=1 misses=0 puts=0
language-queries: hits=1 misses=1 puts=1
com.howtodoinjava.hibernate.ehcacheconfig.Language.translations: hits=1 misses=1 puts=1

The collection region missed once and was filled by the first session. The second session found the collection and after that the “Hello” entry in translations. With Ehcache 3, four of these calls give results that need a closer look.

Call	Result with Ehcache 3
getDomainDataRegionStatistics(“default-query-results-region”)	IllegalArgumentException: Region name [default-query-results-region] referred to a query result region, not a domain data region
getElementCountInMemory()	-9223372036854775808 (Long.MIN_VALUE): JCache does not report it
getSecondLevelCacheRegionNames()	Has no default-update-timestamps-region; language-queries appears after its first use
Counting the entries of a cache	Iterate cacheManager.getCache(alias): 3 entries for three languages

3. Hibernate Ehcache Configuration FAQs

3.1. Where Does Hibernate Look for ehcache.xml?

Hibernate reads the file from the location that hibernate.javax.cache.uri names. A plain name such as ehcache.xml or ehcache-expiry.xml is read from the classpath, so the file goes into src/main/resources. For a file outside the application, we pass a file URI.

.property("hibernate.javax.cache.uri", "ehcache.xml")                    // classpath
.property("hibernate.javax.cache.uri", "file:/path/to/ehcache.xml")      // file system

Without the hibernate.javax.cache.uri property, Hibernate uses the default JCache CacheManager, where no region is declared. So Hibernate logs HHH90001006 for every region and creates each cache without a size limit.

3.2. Why Does key-type Break the Hibernate Cache?

The <key-type> check breaks because Hibernate does not store our ids and entities. Some tutorials declare <key-type>java.lang.Long</key-type> and the entity class as <value-type>, but Hibernate stores its own key objects and dehydrated entries (arrays of column values). So the type check fails when the first entry is stored.

jakarta.persistence.RollbackException: Error while committing the transaction [Unable to perform afterTransactionCompletion callback: Invalid key type, expected : java.lang.Long but was : org.hibernate.cache.internal.BasicCacheKeyImplementation]
Caused by: java.lang.ClassCastException: Invalid key type, expected : java.lang.Long but was : org.hibernate.cache.internal.BasicCacheKeyImplementation

The error comes after the database commit. The three languages were saved, but the caller gets a RollbackException, so a user who saves a form sees an error page although the data is in the database. We leave key-type and value-type out, and both default to java.lang.Object.

3.3. Does hibernate.cache.region_prefix Change the Cache Names?

Yes. With hibernate.cache.region_prefix=i18n, Hibernate asks Ehcache for i18n.com.howtodoinjava.hibernate.ehcacheconfig.Language, i18n.translations, i18n.default-update-timestamps-region and so on. The aliases in ehcache.xml must carry the prefix too, because in our test the unprefixed caches stayed unused and the prefixed ones were created without a limit. The statistics keep the names without the prefix.

// caches:     i18n.com.howtodoinjava.hibernate.ehcacheconfig.Language, i18n.translations, ...
// statistics: com.howtodoinjava.hibernate.ehcacheconfig.Language, translations, ...
CacheRegionStatistics translationStats = stats.getDomainDataRegionStatistics("translations");   // works without the prefix

A prefix is useful when two EntityManagerFactory instances share one CacheManager and have entities with the same names.

3.4. How Do Ehcache 2 Settings Map to Ehcache 3?

Hibernate 5 apps configured Ehcache 2, but Hibernate 6 removed the hibernate-ehcache module, and Ehcache 3 has a new XML format. The CacheProvider of Hibernate 3 is older still. Each old setting has an Ehcache 3 equivalent.

Ehcache 2 with Hibernate 5	Ehcache 3 with Hibernate 7
<cache name=”…” maxElementsInMemory=”10000″>	<cache alias=”…”><heap unit=”entries”>10000</heap></cache>
timeToLiveSeconds=”600″	<expiry><ttl unit=”seconds”>600</ttl></expiry>
timeToIdleSeconds=”300″	<expiry><tti unit=”seconds”>300</tti></expiry>
eternal=”true”	<expiry><none/></expiry>
overflowToDisk=”true”	A <disk> tier inside <resources>
<defaultCache>	<jsr107:defaults default-template=”…”/>
net.sf.ehcache.configurationResourceName	hibernate.javax.cache.uri
EhCacheRegionFactory	hibernate.cache.region.factory_class=jcache
<cache usage=”read-write”/> in hbm.xml	@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)

Ehcache 3 has no ttl and tti on the same cache, but a custom ExpiryPolicy class (<expiry><class>…</class></expiry>) can combine them. Old Hibernate 5 code that reads the entity with load() needs a change too, because Session in Hibernate 7 no longer has load(Class, id), so we use em.find().

3.5. Should the Timestamps Region Expire?

No. Hibernate keeps the time of the last insert, update or delete of each table in default-update-timestamps-region and compares it with the time a query result was cached. The timestamps region should have no expiry and no eviction, and if it has a timeout at all, the timeout must be longer than that of every query results region, as the Hibernate user guide recommends. If a timestamp disappears first, Hibernate can no longer tell that a table changed after a result was cached. We give the region <none/> and a heap larger than the number of cached tables.

4. Conclusion

An ehcache.xml for Hibernate has one <cache> per region, and the alias must equal the region name. Entity regions use the class name and collection regions add the field name to it, whereas the query cache uses two default regions. Templates keep the shared limits in one place, and ttl limits how stale an entry can be. We size the heap in entries and add an offheap tier for entries that do not fit.

Setting missing_cache_strategy to fail reports forgotten regions at startup, and the per-region statistics show that each cache is used.

5. References

• Hibernate ORM 7.4 User Guide: JCache
• Hibernate ORM 7.4 User Guide: JCache missing cache strategy
• Hibernate ORM 7.4 User Guide: Query cache regions
• Hibernate ORM 7.4 User Guide: Caching configuration properties
• CacheConcurrencyStrategy JavaDoc (Hibernate 7.4)
• CacheRegionStatistics JavaDoc (Hibernate 7.4)
• Cacheable JavaDoc (Jakarta Persistence 3.2)
• Ehcache 3 XML Configuration
• Ehcache 3 Expiry
• Ehcache 3 Storage Tiers
• Ehcache 3 JCache Provider and Default Templates
• HHH-14544: Ehcache default caches and performance

Happy Learning !!

Source Code on Github