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:
    Cache, CacheConcurrencyStrategy, CacheSettings.CACHE_REGION_FACTORY, CacheSettings.USE_SECOND_LEVEL_CACHE

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      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.

    • Method Detail

      • 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.