Package org.hibernate

Interface Cache

All Superinterfaces:
Cache
All Known Subinterfaces:
CacheImplementor
All Known Implementing Classes:
DisabledCaching, EnabledCaching
public interface Cache extends Cache
An API for directly querying and managing the second-level 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 Cacheable or 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 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 Cache annotation also specifies a CacheConcurrencyStrategy, a policy governing access to the second-level cache by concurrent transactions. Either:

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 SelectionQuery.setCacheable(boolean), and may be assigned to a region of the second-level cache by calling 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 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".

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    containsCollection(String role, Object ownerIdentifier)
    Determine whether the cache contains an item for the collection with the given role and given identifier.
    boolean
    containsEntity(Class<?> entityClass, Object identifier)
    Determine whether the cache contains an item for the entity of the given type, and with the given identifier.
    boolean
    containsEntity(String entityName, Object identifier)
    Determine whether the cache contains an item for the entity of the type with the given name, and with the given identifier.
    boolean
    containsQuery(String regionName)
    Determine whether the given region name contains cached query results.
    default void
    evictAll()
    default void
    evictAllRegions()
    Evict all cached data from every cache region.
    void
    evictCollectionData()
    Evict all cache data from every cache region to which some collection role is assigned.
    void
    evictCollectionData(String role)
    Evict all cached data from the cache region to which the given collection role is assigned.
    void
    evictCollectionData(String role, Object ownerIdentifier)
    Evict the cached item for the collection with the given role and given identifier, if there is any such item in the cache.
    void
    evictDefaultQueryRegion()
    Evict all cached query results from the default region.
    void
    evictEntityData()
    Evict all cached data from every cache region to which any entity type is assigned.
    void
    evictEntityData(Class<?> entityClass)
    Evict all cached data from the cache region to which the given entity type is assigned.
    void
    evictEntityData(Class<?> entityClass, Object identifier)
    Evicts the cached item for the entity of the given type, and with the given identifier, if there is any such item in the cache.
    void
    evictEntityData(String entityName)
    Evict all cached data from the cache region to which the given named entity type is assigned.
    void
    evictEntityData(String entityName, Object identifier)
    Evict the cached item for the entity of the type with the given name, and with the given identifier, if there is any such item in the cache.
    void
    evictNaturalIdData()
    Evict all cached natural id mappings for every entity type.
    void
    evictNaturalIdData(Class<?> entityClass)
    Evict all cached natural id mappings for the given entity type.
    void
    evictNaturalIdData(String entityName)
    Evict all cached natural id mappings for the entity type with the given name.
    void
    evictQueryRegion(String regionName)
    Evict all cached query results from the region with the given name.
    void
    evictQueryRegions()
    Evict all cached query results from every region.
    void
    evictRegion(String regionName)
    Evict all cached data from the named cache region.
    SessionFactory
    getSessionFactory()
    The SessionFactory to which this Cache belongs.

    Methods inherited from interface jakarta.persistence.Cache

    contains, evict, evict, unwrap

  • Method Details

    • getSessionFactory

      SessionFactory getSessionFactory()
      The SessionFactory to which this Cache belongs.
      Returns:
      The SessionFactory

    • containsEntity

      boolean containsEntity(Class<?> entityClass, Object identifier)
      Determine whether the cache contains an item for the entity of the given type, and with the given identifier.
      Parameters:
      entityClass - The entity type
      identifier - The entity identifier
      Returns:
      True if the underlying cache contains corresponding data; false otherwise.

    • containsEntity

      boolean containsEntity(String entityName, Object identifier)
      Determine whether the cache contains an item for the entity of the type with the given name, and with the given identifier.
      Parameters:
      entityName - The entity name
      identifier - The entity identifier
      Returns:
      True if the underlying cache contains corresponding data; false otherwise.

    • evictEntityData

      void evictEntityData(Class<?> entityClass, Object identifier)
      Evicts the cached item for the entity of the given type, and with the given identifier, if there is any such item in the cache.
      Parameters:
      entityClass - The entity type
      identifier - The entity identifier
      Since:
      5.3

    • evictEntityData

      void evictEntityData(String entityName, Object identifier)
      Evict the cached item for the entity of the type with the given name, and with the given identifier, if there is any such item in the cache.
      Parameters:
      entityName - The entity name
      identifier - The entity identifier
      Since:
      5.3

    • evictEntityData

      void evictEntityData(Class<?> entityClass)
      Evict all cached data from the cache region to which the given entity type is assigned. Thus, every cached item for the given entity type will be evicted, along with any cached items for any other entity type assigned to the same cache region.
      Parameters:
      entityClass - The entity type
      Since:
      5.3

    • evictEntityData

      void evictEntityData(String entityName)
      Evict all cached data from the cache region to which the given named entity type is assigned. Thus, every cached item for the given entity type will be evicted, along with any cached items for any other entity type assigned to the same cache region.
      Parameters:
      entityName - The entity name
      Since:
      5.3

    • evictEntityData

      void evictEntityData()
      Evict all cached data from every cache region to which any entity type is assigned.
      Since:
      5.3

    • evictNaturalIdData

      void evictNaturalIdData(Class<?> entityClass)
      Evict all cached natural id mappings for the given entity type.
      Parameters:
      entityClass - The entity type
      Since:
      5.3

    • evictNaturalIdData

      void evictNaturalIdData(String entityName)
      Evict all cached natural id mappings for the entity type with the given name.
      Parameters:
      entityName - The entity name
      Since:
      5.3

    • evictNaturalIdData

      void evictNaturalIdData()
      Evict all cached natural id mappings for every entity type.
      Since:
      5.3

    • containsCollection

      boolean containsCollection(String role, Object ownerIdentifier)
      Determine whether the cache contains an item for the collection with the given role and given identifier.
      Parameters:
      role - The name of the collection role in the form package.OwnerEntityName.collectionPropertyName
      ownerIdentifier - The identifier of the owning entity
      Returns:
      True if the underlying cache contains corresponding data; false otherwise.

    • evictCollectionData

      void evictCollectionData(String role, Object ownerIdentifier)
      Evict the cached item for the collection with the given role and given identifier, if there is any such item in the cache.
      Parameters:
      role - The name of the collection role in the form package.OwnerEntityName.collectionPropertyName
      ownerIdentifier - The identifier of the owning entity
      Since:
      5.3

    • evictCollectionData

      void evictCollectionData(String role)
      Evict all cached data from the cache region to which the given collection role is assigned.
      Parameters:
      role - The name of the collection role in the form package.OwnerEntityName.collectionPropertyName
      Since:
      5.3

    • evictCollectionData

      void evictCollectionData()
      Evict all cache data from every cache region to which some collection role is assigned.
      Since:
      5.3

    • containsQuery

      boolean containsQuery(String regionName)
      Determine whether the given region name contains cached query results.
      Parameters:
      regionName - The name of a cache region to which some query is assigned
      Returns:
      True if the underlying cache contains corresponding data; false otherwise.

    • evictDefaultQueryRegion

      void evictDefaultQueryRegion()
      Evict all cached query results from the default region.

    • evictQueryRegion

      void evictQueryRegion(String regionName)
      Evict all cached query results from the region with the given name.
      Parameters:
      regionName - The cache name associated to the queries being cached.

    • evictQueryRegions

      void evictQueryRegions()
      Evict all cached query results from every region.

    • evictRegion

      void evictRegion(String regionName)
      Evict all cached data from the named cache region.
      Since:
      5.3

    • evictAll

      default void evictAll()
      Specified by:
      evictAll in interface Cache
      API Note:
      This operation only affects cached data for entities, in keeping with the intent of the JPA specification, which only defines caching for entity data. To evict all data from every cache region, including cached collections, natural-id mappings, and cached query results, use evictAllRegions() instead.

    • evictAllRegions

      default void evictAllRegions()
      Evict all cached data from every cache region.