12. Caching

At runtime, Hibernate handles moving data into and out of the second-level cache in response to the operations performed by the Session, which acts as a transaction-level cache of persistent data. Once an entity becomes managed, that object is added to the internal cache of the current persistence context (EntityManager or Session). The persistence context is also called the first-level cache, and it’s enabled by default.

It is possible to configure a JVM-level (SessionFactory-level) or even a cluster cache on a class-by-class and collection-by-collection basis.

12.1. Configuring second-level caching

Hibernate can integrate with various caching providers for the purpose of caching data outside the context of a particular Session. This section defines the settings which control this behavior.

12.1.1. RegionFactory

org.hibernate.cache.spi.RegionFactory defines the integration between Hibernate and a pluggable caching provider. hibernate.cache.region.factory_class is used to declare the provider to use. Hibernate comes with built-in support for two popular caching libraries: Ehcache and Infinispan. Detailed information is provided later in this chapter.

12.1.2. Caching configuration properties

Besides specific provider configuration, there are a number of configurations options on the Hibernate side of the integration that control various caching behaviors:

• hibernate.cache.use_second_level_cache

• Enable or disable second level caching overall. Default is true, although the default region factory is NoCachingRegionFactory.

• hibernate.cache.use_query_cache

• Enable or disable second level caching of query results. Default is false.

• hibernate.cache.query_cache_factory

• Query result caching is handled by a special contract that deals with staleness-based invalidation of the results. The default implementation does not allow stale results at all. Use this for applications that would like to relax that. Names an implementation of org.hibernate.cache.spi.QueryCacheFactory

• hibernate.cache.use_minimal_puts

• Optimizes second-level cache operations to minimize writes, at the cost of more frequent reads. Providers typically set this appropriately.

• hibernate.cache.region_prefix

• Defines a name to be used as a prefix to all second-level cache region names.

• hibernate.cache.default_cache_concurrency_strategy

• In Hibernate second-level caching, all regions can be configured differently including the concurrency strategy to use when accessing that particular region. This setting allows to define a default strategy to be used. This setting is very rarely required as the pluggable providers do specify the default strategy to use. Valid values include:

  • read-only,

  • read-write,

  • nonstrict-read-write,

  • transactional

• hibernate.cache.use_structured_entries

• If true, forces Hibernate to store data in the second-level cache in a more human-friendly format. Can be useful if you’d like to be able to "browse" the data directly in your cache, but does have a performance impact.

• hibernate.cache.auto_evict_collection_cache

• Enables or disables the automatic eviction of a bidirectional association’s collection cache entry when the association is changed just from the owning side. This is disabled by default, as it has a performance impact to track this state. However if your application does not manage both sides of bidirectional association where the collection side is cached, the alternative is to have stale data in that collection cache.

• hibernate.cache.use_reference_entries

• Enable direct storage of entity references into the second level cache for read-only or immutable entities.

12.2. Configuring second-level cache mappings

The cache mappings can be configured via JPA annotations or XML descriptors or using the Hibernate-specific mapping files.

By default, entities are not part of the second level cache and we recommend you to stick to this setting. However, you can override this by setting the shared-cache-mode element in your persistence.xml file or by using the javax.persistence.sharedCache.mode property in your configuration file. The following values are possible:

• ENABLE_SELECTIVE (Default and recommended value)

• Entities are not cached unless explicitly marked as cacheable (with the @Cacheable annotation).

• DISABLE_SELECTIVE

• Entities are cached unless explicitly marked as not cacheable.

• ALL

• Entities are always cached even if marked as non cacheable.

• NONE

• No entity is cached even if marked as cacheable. This option can make sense to disable second-level cache altogether.

The cache concurrency strategy used by default can be set globally via the hibernate.cache.default_cache_concurrency_strategy configuration property. The values for this property are:

• read-only

• If your application needs to read, but not modify, instances of a persistent class, a read-only cache is the best choice. Application can still delete entities and these changes should be reflected in second-level cache, so that the cache does not provide stale entities. Implementations may use performance optimizations based on the immutability of entities.

• read-write

• If the application needs to update data, a read-write cache might be appropriate. This strategy provides consistent access to single entity, but not a serializable transaction isolation level; e.g. when TX1 reads looks up an entity and does not find it, TX2 inserts the entity into cache and TX1 looks it up again, the new entity can be read in TX1.

• nonstrict-read-write

• Similar to read-write strategy but there might be occasional stale reads upon concurrent access to an entity. The choice of this strategy might be appropriate if the application rarely updates the same data simultaneously and strict transaction isolation is not required. Implementation may use performance optimizations that make of use the relaxed consistency.

• transactional

• Provides serializable transaction isolation level.

The @Cache annotation define three attributes:

• usage

• Defines the CacheConcurrencyStrategy

• region

• Defines a cache region where entries will be stored

• include

• If lazy properties should be included in the second level cache. Default value is "all", so lazy properties are cacheable. The other possible value is "non-lazy", so lazy properties are not cacheable.

12.3. Entity cache

Example 226. Entity cache mapping

@Entity
@Cacheable
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public static class Phone {

    @Id
    @GeneratedValue
    private Long id;

    private String mobile;

    @ManyToOne
    private Person person;

    @Version
    private int version;

    public Phone() {}

    public Phone(String mobile) {
        this.mobile = mobile;
    }

    public Long getId() {
        return id;
    }

    public String getMobile() {
        return mobile;
    }

    public Person getPerson() {
        return person;
    }

    public void setPerson(Person person) {
        this.person = person;
    }
}

Hibernate stores cached entities in a dehydrated forms, which is similar to the database representation. Aside from the foreign key column values of the @ManyToOne or @OneToOne child-side associations, entity relationships are not stored in the cache,

Once an entity is stored in the second-level cache, you can avoid a database hit and load the entity from the cache alone:

Example 227. Loading entity using JPA

Person person = entityManager.find( Person.class, 1L );

Example 228. Loading entity using Hibernate native API

Person person = session.get( Person.class, 1L );

The Hibernate second-level cache can also load entities by their natural id:

Example 229. Hibernate natural id entity mapping

@Entity(name = "Person")
@Cacheable
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public static class Person {

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    private String name;

    @NaturalId
    @Column(name = "code", unique = true)
    private String code;

    public Person() {}

    public Person(String name) {
        this.name = name;
    }

    public Long getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }
}

Example 230. Loading entity using Hibernate native natural id API

Person person = session
    .byNaturalId( Person.class )
    .using( "code", "unique-code")
    .load();

12.4. Collection cache

Hibernate can also cache collections, and the @Cache annotation must be on added to the collection property.

If the collection is made of value types (basic or embeddables mapped with @ElementCollection), the collection is stored as such. If the collection contains other entities (@OneToMany or @ManyToMany), the collection cache entry will store the entity identifiers only.

Example 231. Collection cache mapping

@OneToMany(mappedBy = "person", cascade = CascadeType.ALL)
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
private List<Phone> phones = new ArrayList<>(  );

Collections are read-through, meaning they are cached upon being accessed for the first time:

Example 232. Collection cache usage

Person person = entityManager.find( Person.class, 1L );
person.getPhones().size();

Subsequent collection retrievals will use the cache instead of going to the database.

12.5. Query cache

Aside from caching entities and collections, Hibernate offers a query cache too. This is useful for frequently executed queries with fixed parameter values.

To use query caching, you will first need to enable it with the following configuration property:

Example 233. Enabling query cache

<property
    name="hibernate.cache.use_query_cache"
    value="true" />

As mentioned above, most queries do not benefit from caching or their results. So by default, individual queries are not cached even after enabling query caching. Each particular query that needs to be cached must be manually set as cacheable. This way, the query looks for existing cache results or adds the query results to the cache when being executed.

Example 234. Caching query using JPA

List<Person> persons = entityManager.createQuery(
    "select p " +
    "from Person p " +
    "where p.name = :name", Person.class)
.setParameter( "name", "John Doe")
.setHint( "org.hibernate.cacheable", "true")
.getResultList();

Example 235. Caching query using Hibernate native API

List<Person> persons = session.createQuery(
    "select p " +
    "from Person p " +
    "where p.name = :name")
.setParameter( "name", "John Doe")
.setCacheable(true)
.list();

12.5.1. Query cache regions

This setting creates two new cache regions:

• org.hibernate.cache.internal.StandardQueryCache

• Holding the cached query results

• org.hibernate.cache.spi.UpdateTimestampsCache

• Holding timestamps of the most recent updates to queryable tables. These are used to validate the results as they are served from the query cache.

If you require fine-grained control over query cache expiration policies, you can specify a named cache region for a particular query.

Example 236. Caching query in custom region using JPA

List<Person> persons = entityManager.createQuery(
        "select p " +
        "from Person p " +
        "where p.id > :id", Person.class)
        .setParameter( "id", 0L)
        .setHint( QueryHints.HINT_CACHEABLE, "true")
        .setHint( QueryHints.HINT_CACHE_REGION, "query.cache.person" )
        .getResultList();

Example 237. Caching query in custom region using Hibernate native API

List<Person> persons = session.createQuery(
    "select p " +
    "from Person p " +
    "where p.id > :id")
.setParameter( "id", 0L)
.setCacheable(true)
.setCacheRegion( "query.cache.person" )
.list();

If you want to force the query cache to refresh one of its regions (disregarding any cached results it finds there), you can use custom cache modes.

Example 238. Using custom query cache mode with JPA

List<Person> persons = entityManager.createQuery(
    "select p " +
    "from Person p " +
    "where p.id > :id", Person.class)
.setParameter( "id", 0L)
.setHint( QueryHints.HINT_CACHEABLE, "true")
.setHint( QueryHints.HINT_CACHE_REGION, "query.cache.person" )
.setHint( "javax.persistence.cache.storeMode", CacheStoreMode.REFRESH )
.getResultList();

Example 239. Using custom query cache mode with Hibernate native API

List<Person> persons = session.createQuery(
    "select p " +
    "from Person p " +
    "where p.id > :id")
.setParameter( "id", 0L)
.setCacheable(true)
.setCacheRegion( "query.cache.person" )
.setCacheMode( CacheMode.REFRESH )
.list();

12.6. Managing the cached data

Traditionally, Hibernate defined the CacheMode enumeration to describe the ways of interactions with the cached data. JPA split cache modes by storage (CacheStoreMode) and retrieval (CacheRetrieveMode).

The relationship between Hibernate and JPA cache modes can be seen in the following table:

Table 4. Cache modes relationships

Setting the cache mode can be done wither when loading entities directly or when executing a query.

Example 240. Using custom cache modes with JPA

Map<String, Object> hints = new HashMap<>(  );
hints.put( "javax.persistence.cache.retrieveMode " , CacheRetrieveMode.USE );
hints.put( "javax.persistence.cache.storeMode" , CacheStoreMode.REFRESH );
Person person = entityManager.find( Person.class, 1L , hints);

Example 241. Using custom cache modes with Hibernate native API

session.setCacheMode( CacheMode.REFRESH );
Person person = session.get( Person.class, 1L );

The custom cache modes can be set for queries as well:

Example 242. Using custom cache modes for queries with JPA

List<Person> persons = entityManager.createQuery(
    "select p from Person p", Person.class)
.setHint( QueryHints.HINT_CACHEABLE, "true")
.setHint( "javax.persistence.cache.retrieveMode " , CacheRetrieveMode.USE )
.setHint( "javax.persistence.cache.storeMode" , CacheStoreMode.REFRESH )
.getResultList();

Example 243. Using custom cache modes for queries with Hibernate native API

List<Person> persons = session.createQuery(
    "select p from Person p" )
.setCacheable( true )
.setCacheMode( CacheMode.REFRESH )
.list();

12.6.1. Evicting cache entries

Because the second level cache is bound to the EntityManagerFactory or the SessionFactory, cache eviction must be done through these two interfaces.

JPA only supports entity eviction through the javax.persistence.Cache interface:

Example 244. Evicting entities with JPA

entityManager.getEntityManagerFactory().getCache().evict( Person.class );

Hibernate is much more flexible in this regard as it offers a fine-grained control over what needs to be evicted. The org.hibernate.Cache interface defines various evicting strategies:

• entities (by their class or region)

• entities stored using the natural-id (by their class or region)

• collections (by the region, and it might take the collection owner identifier as well)

• queries (by region)

Example 245. Evicting entities with Hibernate native API

session.getSessionFactory().getCache().evictQueryRegion( "query.cache.person" );

12.7. Caching statistics

If you enable the hibernate.generate_statistics configuration property, Hibernate will expose a number of metrics via SessionFactory.getStatistics(). Hibernate can even be configured to expose these statistics via JMX.

This way, you can get access to the Statistics class which comprises all sort of second-level cache metrics.

Example 246. Caching statistics

Statistics statistics = session.getSessionFactory().getStatistics();
SecondLevelCacheStatistics secondLevelCacheStatistics =
        statistics.getSecondLevelCacheStatistics( "query.cache.person" );
long hitCount = secondLevelCacheStatistics.getHitCount();
long missCount = secondLevelCacheStatistics.getMissCount();
double hitRatio = (double) hitCount / ( hitCount + missCount );

12.8. Ehcache

12.8.1. RegionFactory

The hibernate-ehcache module defines two specific region factories: EhCacheRegionFactory and SingletonEhCacheRegionFactory.

EhCacheRegionFactory

To use the EhCacheRegionFactory, you need to specify the following configuration property:

Example 247. EhCacheRegionFactory configuration

<property
    name="hibernate.cache.region.factory_class"
    value="org.hibernate.cache.ehcache.EhCacheRegionFactory"/>

The EhCacheRegionFactory configures a net.sf.ehcache.CacheManager for each SessionFactory, so the CacheManager is not shared among multiple SessionFactory instances in the same JVM.

SingletonEhCacheRegionFactory

To use the SingletonEhCacheRegionFactory, you need to specify the following configuration property:

Example 248. SingletonEhCacheRegionFactory configuration

<property
    name="hibernate.cache.region.factory_class"
    value="org.hibernate.cache.ehcache.SingletonEhCacheRegionFactory"/>

The SingletonEhCacheRegionFactory configures a singleton net.sf.ehcache.CacheManager (see CacheManager#create()), shared among multiple SessionFactory instances in the same JVM.

12.9. Infinispan

Infinispan currently supports all cache concurrency modes, although not all combinations of configurations are compatible.

Traditionally the transactional and read-only strategy was supported on transactional invalidation caches. In version 5.0, further modes have been added:

• non-transactional invalidation caches are supported as well with read-write strategy. The actual setting of cache concurrency mode (read-write vs. transactional) is not honored, the appropriate strategy is selected based on the cache configuration (non-transactional vs. transactional).

• read-write mode is supported on non-transactional distributed/replicated caches, however, eviction should not be used in this configuration. Use of eviction can lead to consistency issues. Expiration (with reasonably long max-idle times) can be used.

• nonstrict-read-write mode is supported on non-transactional distributed/replicated caches, but the eviction should be turned off as well. In addition to that, the entities must use versioning. This mode mildly relaxes the consistency - between DB commit and end of transaction commit a stale read (see

  example

  ) may occur in another transaction. However this strategy uses less RPCs and can be more performant than the other ones.

• read-only mode is supported on both transactional and non-transactional invalidation caches and non-transactional distributed/replicated caches, but use of this mode currently does not bring any performance gains.

The available combinations are summarized in table below

Table 5. Cache concurrency strategy/cache mode compatibility table

If your second level cache is not clustered, it is possible to use local cache instead of the clustered caches in all modes as described above.

Example 249. Stale read with nonstrict-read-write strategy

A=0 (non-cached), B=0 (cached in 2LC)
TX1: write A = 1, write B = 1
TX1: start commit
TX1: commit A, B in DB
TX2: read A = 1 (from DB), read B = 0 (from 2LC) // breaks transactional atomicity
TX1: update A, B in 2LC
TX1: end commit
Tx3: read A = 1, B = 1 // reads after TX1 commit completes are consistent again

12.9.1. RegionFactory

The hibernate-infinispan module defines two specific providers: infinispan and infinispan-jndi.

InfinispanRegionFactory

If Hibernate and Infinispan are running in a standalone environment, the InfinispanRegionFactory should be configured as follows:

Example 250. InfinispanRegionFactory configuration

<property
    name="hibernate.cache.region.factory_class"
    value="org.hibernate.cache.infinispan.InfinispanRegionFactory" />

JndiInfinispanRegionFactory

If the Infinispan CacheManager is bound to JNDI, then the JndiInfinispanRegionFactory should be used as a region factory:

Example 251. JndiInfinispanRegionFactory configuration

<property
    name="hibernate.cache.region.factory_class"
    value="org.hibernate.cache.infinispan.JndiInfinispanRegionFactory" />

<property
    name="hibernate.cache.infinispan.cachemanager"
    value="java:CacheManager" />

Infinispan in JBoss AS/WildFly

When using JPA in WildFly, region factory is automatically set upon configuring hibernate.cache.use_second_level_cache=true (by default second-level cache is not used). For more information please consult WildFly documentation.

12.9.2. Configuration properties

Hibernate-infinispan module comes with default configuration in infinispan-config.xml that is suited for clustered use. If there’s only single instance accessing the DB, you can use more performant infinispan-config-local.xml by setting the hibernate.cache.infinispan.cfg property. If you require further tuning of the cache, you can provide your own configuration. Caches that are not specified in the provided configuration will default to infinispan-config.xml (if the provided configuration uses clustering) or infinispan-config-local.xml. It is not possible to specify the configuration this way in WildFly.

Example 252. Use custom Infinispan configuration

<property
    name="hibernate.cache.infinispan.cfg"
    value="my-infinispan-configuration.xml" />

Cache configuration can differ for each type of data stored in the cache. In order to override the cache configuration template, use property hibernate.cache.infinispan._data-type_.cfg where _data-type_ can be one of:

• entity

• Entities indexed by @Id or @EmbeddedId attribute.

• immutable-entity

• Entities tagged with @Immutable annotation or set as mutable=false in mapping file.

• naturalid

• Entities indexed by their @NaturalId attribute.

• collection

• All collections.

• timestamps

• Mapping entity type → last modification timestamp. Used for query caching.

• query

• Mapping query → query result.

• pending-puts

• Auxiliary caches for regions using invalidation mode caches.

For specifying cache template for specific region, use region name instead of the _data-type_:

Example 253. Use custom cache template

<property
    name="hibernate.cache.infinispan.entities.cfg"
    value="custom-entities" />
<property
    name="hibernate.cache.infinispan.query.cfg"
    value="custom-query-cache" />
<property
    name="hibernate.cache.infinispan.com.example.MyEntity.cfg"
    value="my-entities" />
<property
    name="hibernate.cache.infinispan.com.example.MyEntity.someCollection.cfg"
    value="my-entities-some-collection" />

Some options in the cache configuration can also be overridden directly through properties. These are:

• hibernate.cache.infinispan._something_.eviction.strategy

• Available options are NONE, LRU and LIRS.

• hibernate.cache.infinispan._something_.eviction.max_entries

• Maximum number of entries in the cache.

• hibernate.cache.infinispan._something_.expiration.lifespan

• Lifespan of entry from insert into cache (in milliseconds)

• hibernate.cache.infinispan._something_.expiration.max_idle

• Lifespan of entry from last read/modification (in milliseconds)

• hibernate.cache.infinispan._something_.expiration.wake_up_interval

• Period of thread checking expired entries.

• hibernate.cache.infinispan.statistics

• Globally enables/disable Infinispan statistics collection, and their exposure via JMX.

Configuring Query and Timestamps caches

Since version 5.0 it is possible to configure query caches as non-transactional. Consistency guarantees are not changed and writes to the query cache should be faster.

The query cache is configured so that queries are only cached locally . Alternatively, you can configure query caching to use replication by selecting the "replicated-query" as query cache name. However, replication for query cache only makes sense if, and only if, all of this conditions are true:

• Performing the query is quite expensive.

• The same query is very likely to be repeatedly executed on different cluster nodes.

• The query is unlikely to be invalidated out of the cache

In default configuration, timestamps cache is asynchronously replicated. This means that a cached query on remote node can provide stale results for a brief time window before the remote timestamps cache is updated. However, requiring synchronous RPC would result in severe performance degradation.

Further, but possibly outdated information can be found in Infinispan documentation.