Enabling L2 & Providers

## Two different caches Every `Session`/`EntityManager` owns a **first-level cache** — the persistence context — which lives only as long as that session and guarantees one object instance per id within it. It is always on and cannot be disabled. The **second-level cache (L2)** sits behind it at `SessionFactory` scope: it is shared by every session in the JVM (and, with a clustered provider, potentially across nodes). It stores **dehydrated entity state** — an array of column-ish values plus the version — keyed by entity id, not managed object graphs. On a cache hit Hibernate builds a fresh entity instance for the current session from that state, so cached instances are never shared between sessions. Crucially, L2 is a **by-id cache**. `em.find(Product.class, 7L)`, lazy proxy initialisation, and many-to-one navigation can be served from it. An arbitrary JPQL query cannot: a query goes to the database unless the separate query cache is also enabled. ## Step 1 — the master switch `hibernate.cache.use_second_level_cache=true`. Historically this defaulted differently across bootstrap modes; treat it as required and set it explicitly. On its own it caches nothing. ## Step 2 — a provider behind a RegionFactory Hibernate defines an SPI, `org.hibernate.cache.spi.RegionFactory`, and asks it for **regions** — named key/value stores. Implementations are separate artifacts: - `hibernate-jcache` implements the SPI over **JSR-107 (JCache)**, so any JCache provider works: EhCache 3, Infinispan, Caffeine (via `caffeine-jcache`). - Infinispan also ships a **native** Hibernate region factory with clustering features beyond the JCache API. With JCache you set `hibernate.cache.region.factory_class=jcache`, put exactly one provider on the classpath (or name it with `hibernate.javax.cache.provider`), and point `hibernate.javax.cache.uri` at the provider's own config file. Hibernate then calls `cacheManager.getCache(regionName)` for each region. If that cache is not declared, modern Hibernate **fails at startup** rather than silently creating one — `hibernate.javax.cache.missing_cache_strategy` (default `fail`) also accepts `create-warn` and `create`. That default exists precisely because an auto-created, unbounded region is a memory leak waiting to happen. ## Step 3 — opting entities in Under the default shared-cache mode (`ENABLE_SELECTIVE`), an entity participates only if annotated. Two annotations are in play and they are not the same thing: - `jakarta.persistence.@Cacheable` — the portable JPA marker meaning “this entity may be cached”. - `org.hibernate.annotations.@Cache` — Hibernate's own, carrying `usage` (the concurrency strategy: read-only, read-write, nonstrict-read-write, transactional), an optional `region` name, and `includeLazy` control. Hibernate treats `@Cache` as implying cacheability, but writing both is the clear, portable habit. Without `@Cache`, the strategy falls back to `hibernate.cache.default_cache_concurrency_strategy`, which is easy to get wrong — pick it deliberately per entity. Also note what `@Cacheable` does **not** cover: `@OneToMany`/`@ManyToMany` collections are separate regions requiring their own `@Cache` on the field, and query results need the query cache. A very common bug report — “L2 is on but I still see SELECTs” — is really “my access path was a query or an uncached collection, not `find()` by id”. ## Verifying it works Set `hibernate.generate_statistics=true` and read `SessionFactory.getStatistics()`: `getSecondLevelCacheHitCount()`, miss count, and put count, ideally per region. A region with puts and no hits is pure overhead. Do not judge by SQL logs alone — the first load of every entity is always a miss, so a cold benchmark shows no benefit at all. ## Naming By default a region is named after the fully-qualified entity name (`com.acme.shop.Product`); collection regions append the field (`com.acme.shop.Product.tags`). `hibernate.cache.region_prefix` prefixes them all, which matters when several applications share one cache manager.