public Interface Cache

Hibernate has two levels of caching:

• The first-level cache is better known as the persistence context. It's the collection of managed entity instances associated with an open Session.
• The second-level cache is shared between all sessions belonging to a given SessionFactory. It stores the state of an entity instance in a destructured format, as a tuple of persistent attribute values. The second-level cache is also used to store cached query result sets.

By nature, a second-level cache tends to undermine the ACID properties of transaction processing in a relational database. A second-level cache is often by far the easiest way to improve the performance of a system, but only at the cost of making it much more difficult to reason about concurrency. And so the cache is a potential source of bugs which are difficult to isolate and reproduce.

Therefore, only entities and collection roles explicitly annotated jakarta.persistence.Cacheable or org.hibernate.annotations.Cache are eligible for storage in the second-level cache, and so by default the state of an entity is always retrieved from the database when requested.

Hibernate segments the second-level cache into named regions, one for each mapped entity hierarchy or collection role, each with its own policies for expiry, persistence, and replication, which must be configured externally to Hibernate. An entity hierarchy or collection role may be explicitly assigned a region using the org.hibernate.annotations.Cache annotation, but, by default, the region name is just the name of the entity class or collection role.

The appropriate policies depend on the kind of data an entity represents. For example, a program might have different caching policies for "reference" data, for transactional data, and for data used for analytics. Ordinarily, the implementation of those policies is the responsibility of the cache provider and is transparent to code which makes use of a Hibernate Session. At worst, interaction with the cache may be controlled by specification of an explicit CacheMode.

Very occasionally, it's necessary or advantageous to control the cache explicitly via programmatic eviction, using, for example, evictEntityData(Class) to evict a whole cache region, or evictEntityData(Class, Object), to evict a single item.

If multiple entities or roles are mapped to the same cache region, they share policies and even the same FIFO-type expiry queue (if any). This sounds useful, but comes with the downside that evictEntityData(Class) for any one of the entities evicts all entities mapped to the same region. It's therefore much more common to have a distinct region for each entity and role.

None of the operations of this interface respect any isolation or transactional semantics associated with the underlying caches. In particular, eviction via the methods of this interface causes an immediate "hard" removal outside any current transaction and/or locking scheme.

The org.hibernate.annotations.Cache annotation also specifies a org.hibernate.annotations.CacheConcurrencyStrategy, a policy governing access to the second-level cache by concurrent transactions. Either:

• read-only access for immutable data,
• read/write access with no locking, when concurrent updates are extremely improbable,
• read/write access using soft locks when concurrent updates are possible but not common, or
• transactional access when concurrent updates are frequent.

It's important to always explicitly specify an appropriate policy, taking into account the expected patterns of data access, most importantly, the frequency of updates.

Query result sets may also be stored in the second-level cache. A query is made eligible for caching by calling org.hibernate.query.SelectionQuery#setCacheable(boolean), and may be assigned to a region of the second-level cache by calling org.hibernate.query.SelectionQuery#setCacheRegion(String). It's very important to understand that any entity instance in a query result set is cached by its id. If the entity itself is not cacheable, or if the instance is not available in the second-level cache at the time a result set is retrieved from the cache, then the state of the entity must be read from the database. This negates the benefits of caching the result set. It's therefore very important to carefully "match" the caching policies of a query and the entities it returns.

Hibernate does not itself contain a high-quality implementation of a second-level cache backend with expiry, persistence, and replication, and depends on a plug-in implementation of org.hibernate.cache.spi.RegionFactory to integrate a backend storage mechanism. Therefore, the second-level cache is completely disabled by default, unless hibernate.cache.region.factory_class is explicitly specified. For convenience, the second-level cache may also be enabled or disabled using hibernate.cache.use_second_level_cache.