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.

Be aware that caches are not aware of changes made to the persistent store by other applications. They can, however, be configured to regularly expire cached data.

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.

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 the Java caching standard JCache and also two popular caching libraries: Ehcache and Infinispan. Detailed information is provided later in this chapter.

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.

hibernate.cache.keys_factory

When storing entries into second-level cache as key-value pair, the identifiers can be wrapped into tuples <entity type, tenant, identifier> to guarantee uniqueness in case that second-level cache stores all entities in single space. These tuples are then used as keys in the cache. When the second-level cache implementation (incl. its configuration) guarantees that different entity types are stored separately and multi-tenancy is not used, you can omit this wrapping to achieve better performance. Currently, this property is only supported when Infinispan is configured as the second-level cache implementation. Valid values are:

default (wraps identitifers in the tuple)
simple (uses identifiers as keys without any wrapping)
fully qualified class name that implements org.hibernate.cache.spi.CacheKeysFactory

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 non-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. Implementations may use performance optimizations that make use of the relaxed consistency guarantee.
transactional: Provides serializable transaction isolation level.

Rather than using a global cache concurrency strategy, it is recommended to define this setting on a per entity basis. Use the @org.hibernate.annotations.Cache annotation for that.

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. The default value is all so lazy properties are cacheable. The other possible value is non-lazy so lazy properties are not cacheable.

Entity inheritance and second-level cache mapping

When using inheritance, the JPA @Cacheable and the Hibernate-specific @Cache annotations should be declared at the root-entity level only. That being said, it is not possible to customize the base class @Cacheable or @Cache definition in subclasses.

Although the JPA 2.1 specification says that the @Cacheable annotation could be overwritten by a subclass:

The value of the Cacheable annotation is inherited by subclasses; it can be overridden by specifying Cacheable on a subclass.

— Section 11.1.7 of the JPA 2.1 Specification

Hibernate requires that a given entity hierarchy share the same caching semantics.

The reasons why Hibernate requires that all entities belonging to an inheritance tree share the same caching definition can be summed as follows:

from a performance perspective, adding an additional check on a per entity type level would slow the bootstrap process.
providing different caching semantics for subclasses would violate the Liskov substitution principle.

Assuming we have a base class, Payment and a subclass CreditCardPayment. If the Payment is not cacheable and the CreditCardPayment is cached, what should happen when executing the following code snippet:
```
Payment payment = entityManager.find(Payment.class, creditCardPaymentId);
CreditCardPayment creditCardPayment = (CreditCardPayment) CreditCardPayment;
```
In this particular case, the second level cache key is formed of the entity class name and the identifier:
```
keyToLoad = {org.hibernate.engine.spi.EntityKey@4712}
 identifier = {java.lang.Long@4716} "2"
 persister = {org.hibernate.persister.entity.SingleTableEntityPersister@4629}
  "SingleTableEntityPersister(org.hibernate.userguide.model.Payment)"
```
Should Hibernate load the CreditCardPayment from the cache as indicated by the actual entity type, or it should not use the cache since the Payment is not supposed to be cached?

Because of all these intricacies, Hibernate only considers the base class @Cacheable and @Cache definition.

Entity cache

Example 1. Entity cache mapping

@Entity(name = "Phone")
@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 form, 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 2. Loading entity using JPA

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

Example 3. 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 4. 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 5. Loading entity using Hibernate native natural id API

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

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

The collection cache is not write-through so any modification will trigger a collection cache entry invalidation. On a subsequent access, the collection will be loaded from the database and re-cached.

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.

Caching of query results introduces some overhead in terms of your applications normal transactional processing. For example, if you cache results of a query against Person, Hibernate will need to keep track of when those results should be invalidated because changes have been committed against any Person entity.

That, coupled with the fact that most applications simply gain no benefit from caching query results, leads Hibernate to disable caching of query results by default.

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

Example 8. 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 9. 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 10. 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();

The query cache does not cache the state of the actual entities in the cache; it caches only identifier values and results of value type.

Just as with collection caching, the query cache should always be used in conjunction with the second-level cache for those entities expected to be cached as part of a query result cache.

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 configure your underlying cache implementation to use expiration, it’s very important that the timeout of the underlying cache region for the UpdateTimestampsCache is set to a higher value than the timeouts of any of the query caches.

In fact, we recommend that the UpdateTimestampsCache region is not configured for expiration (time-based) or eviction (size/memory-based) at all. Note that an LRU (Least Recently Used) cache eviction policy is never appropriate for this particular cache region.

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

Example 11. 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 12. 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 13. 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 14. 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();

When using CacheStoreMode.REFRESH or CacheMode.REFRESH in conjunction with the region you have defined for the given query, Hibernate will selectively force the results cached in that particular region to be refreshed.

This is particularly useful in cases where underlying data may have been updated via a separate process and is a far more efficient alternative to bulk eviction of the region via SessionFactory eviction which looks as follows:

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

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 1. Cache modes relationships
Hibernate	JPA	Description
`CacheMode.NORMAL`	`CacheStoreMode.USE` and `CacheRetrieveMode.USE`	Default. Reads/writes data from/into cache
`CacheMode.REFRESH`	`CacheStoreMode.REFRESH` and `CacheRetrieveMode.BYPASS`	Doesn’t read from cache, but writes to the cache upon loading from the database
`CacheMode.PUT`	`CacheStoreMode.USE` and `CacheRetrieveMode.BYPASS`	Doesn’t read from cache, but writes to the cache as it reads from the database
`CacheMode.GET`	`CacheStoreMode.BYPASS` and `CacheRetrieveMode.USE`	Read from the cache, but doesn’t write to cache
`CacheMode.IGNORE`	`CacheStoreMode.BYPASS` and `CacheRetrieveMode.BYPASS`	Doesn’t read/write data from/into cache

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

Example 15. 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 16. 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 17. 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 18. 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();

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 19. Evicting entities with JPA

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

Hibernate is much more flexible in this regard as it offers 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 20. Evicting entities with Hibernate native API

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

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 21. 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 );

JCache

Use of the build-in integration for JCache requires that the hibernate-jcache module jar (and all of its dependencies) are on the classpath. In addition a JCache implementation needs to be added as well. A list of compatible implementations can be found on the JCP website. An alternative source of compatible implementations can be found through the JSR-107 test zoo.

RegionFactory

The hibernate-jcache module defines the following region factory: JCacheRegionFactory.

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

Example 22. JCacheRegionFactory configuration

<property
    name="hibernate.cache.region.factory_class"
    value="org.hibernate.cache.jcache.JCacheRegionFactory"/>

The JCacheRegionFactory configures a javax.cache.CacheManager.

JCache `CacheManager`

JCache mandates that CacheManagers sharing the same URI and class loader be unique in JVM.

If you do not specify additional properties, the JCacheRegionFactory will load the default JCache provider and create the default CacheManager. Also, Caches will be created using the default javax.cache.configuration.MutableConfiguration.

In order to control which provider to use and specify configuration for the CacheManager and Caches you can use the following two properties:

Example 23. JCache configuration

<property
    name="hibernate.javax.cache.provider"
    value="org.ehcache.jsr107.EhcacheCachingProvider"/>
<property
    name="hibernate.javax.cache.uri"
    value="file:/path/to/ehcache.xml"/>

Only by specifying the second property hibernate.javax.cache.uri will you be able to have a CacheManager per SessionFactory.

Ehcache

This integration covers Ehcache 2.x, in order to use Ehcache 3.x as second level cache, refer to the JCache integration.

Use of the build-in integration for Ehcache requires that the hibernate-ehcache module jar (and all of its dependencies) are on the classpath.

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 24. 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 25. 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.

Ehcache documentation recommends using multiple non-singleton CacheManager(s) when there are multiple Hibernate SessionFactory instances running in the same JVM.

Infinispan

Use of the build-in integration for Infinispan requires that the hibernate-infinispan module jar (and all of its dependencies) are on the classpath.

How to configure Infinispan to be the second level cache provider varies slightly depending on the deployment scenario:

Single Node Local

In standalone library mode, a JPA/Hibernate application runs inside a Java SE application or inside containers that don’t offer Infinispan integration.

Enabling Infinispan second level cache provider inside a JPA/Hibernate application that runs in single node is very straightforward. First, make sure the Hibernate Infinispan cache provider (and its dependencies) are available in the classpath, then modify the persistence.xml to include these properties:

<!-- Use Infinispan second level cache provider -->
<property name="hibernate.cache.region.factory_class"
          value="org.hibernate.cache.infinispan.InfinispanRegionFactory"/>

<!-- Optional: Force using local configuration when only using a single node.
     Otherwise a clustered configuration is loaded. -->
<property name="hibernate.cache.infinispan.cfg"
          value="org/hibernate/cache/infinispan/builder/infinispan-configs-local.xml"/>

Plugging in Infinispan as second-level cache provider requires at the bare minimum that hibernate.cache.region.factory_class is set to an Infinispan region factory implementation. Normally, this is org.hibernate.cache.infinispan.InfinispanRegionFactory but other region factories are possible in alternative scenarios (see Alternative Region Factory section for more info).

By default, the Infinispan second-level cache provider uses an Infinispan configuration that’s designed for clustered environments. However, since this section is focused on running Infinispan second-level cache provider in a single node, an Infinispan configuration designed for local environments is recommended. To enable that configuration, set hibernate.cache.infinispan.cfg to org/hibernate/cache/infinispan/builder/infinispan-configs-local.xml value.

The next section focuses on analysing how the default local configuration works. Changing Infinispan configuration options can be done following the instructions in Configuration Properties section.

Default Local Configuration

Infinispan second-level cache provider comes with a configuration designed for local, single node, environments. These are the characteristics of such configuration:

Entities, collections, queries and timestamps are stored in non-transactional local caches.
Entities and collections query caches are configured with the following eviction settings. You can change these settings on a per entity or collection basis or per individual entity or collection type. More information in the Advanced Configuration section below.
- Eviction wake up interval is 5 seconds.
- Max number of entries are 10,000
- Max idle time before expiration is 100 seconds
- Default eviction algorithm is LRU, least recently used.
No eviction/expiration is configured for timestamp caches, nor it’s allowed.

Local Cache Strategies

Before version 5.0, Infinispan only supported transactional and read-only strategies.

Starting with version 5.0, all cache strategies are supported: transactional, read-write, nonstrict-read-write and read-only.

Multi Node Cluster

When running a JPA/Hibernate in a multi-node environment and enabling Infinispan second-level cache, it is necessary to cluster the second-level cache so that cache consistency can be guaranteed. Clustering the Infinispan second-level cache provider is as simple as adding the following properties:

<!-- Use Infinispan second level cache provider -->
<property name="hibernate.cache.region.factory_class"
          value="org.hibernate.cache.infinispan.InfinispanRegionFactory"/>

As with the standalone local mode, at the bare minimum the region factory has to be configured to point to an Infinispan region factory implementation.

However, the default Infinispan configuration used by the second-level cache provider is already configured to work in a cluster environment, so no need to add any extra properties.

The next section focuses on analysing how the default cluster configuration works. Changing Infinispan configuration options can be done following the instructions in Configuration Properties section.

Default Cluster Configuration

Infinispan second-level cache provider default configuration is designed for multi-node clustered environments. The aim of this section is to explain the default settings for each of the different global data type caches (entity, collection, query and timestamps), why these were chosen and what are the available alternatives. These are the characteristics of such configuration:

For all entities and collections, whenever a new entity or collection is read from database and needs to be cached, it’s only cached locally in order to reduce intra-cluster traffic. This option can be changed so that entities/collections are cached cluster wide, by switching the entity/collection cache to be replicated or distributed. How to change this option is explained in the Configuration Properties section.
All entities and collections are configured to use a synchronous invalidation as clustering mode. This means that when an entity is updated, the updated cache will send a message to the other members of the cluster telling them that the entity has been modified. Upon receipt of this message, the other nodes will remove this data from their local cache, if it was stored there. This option can be changed so that both local and remote nodes contain the updates by configuring entities or collections to use a replicated or distributed cache. With replicated caches all nodes would contain the update, whereas with distributed caches only a subset of the nodes. How to change this option is explained in the Configuration Properties section.
All entities and collections have initial state transfer disabled since there’s no need for it.
Entities and collections are configured with the following eviction settings. You can change these settings on a per entity or collection basis or per individual entity or collection type. More information in the Configuration Properties section below.
- Eviction wake up interval is 5 seconds.
- Max number of entries are 10,000
- Max idle time before expiration is 100 seconds
- Default eviction algorithm is LRU, least recently used.
Assuming that query caching has been enabled for the persistence unit (see query cache section), 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 (Note: Hibernate must aggressively invalidate query results from the cache any time any instance of one of the entity types targeted by the query. All such query results are invalidated, even if the change made to the specific entity instance would not have affected the query result)
query cache uses the same eviction/expiration settings as for entities/collections.
query cache has initial state transfer disabled . It is not recommended that this is enabled.
The timestamps cache is configured with asynchronous replication as clustering mode. Local or invalidated cluster modes are not allowed, since all cluster nodes must store all timestamps. As a result, no eviction/expiration is allowed for timestamp caches either.

Asynchronous replication was selected as default for timestamps cache for performance reasons. A side effect of this choice is that when an entity/collection is updated, for a very brief period of time stale queries might be returned. It’s important to note that due to how Infinispan deals with asynchronous replication, stale queries might be found even query is done right after an entity/collection update on same node. The reason why asynchronous replication works this way is because there’s a single node that’s owner for a given key, and that enables changes to be applied in the same order in all nodes. Without it, it could happen that an older value could replace a newer value in certain nodes.

Hibernate must aggressively invalidate query results from the cache any time any instance of one of the entity types is modified. All cached query results referencing given entity type are invalidated, even if the change made to the specific entity instance would not have affected the query result. The timestamps cache plays here an important role - it contains last modification timestamp for each entity type. After a cached query results is loaded, its timestamp is compared to all timestamps of the entity types that are referenced in the query and if any of these is higher, the cached query result is discarded and the query is executed against DB.

Cluster Cache Strategies

Before version 5.0, Infinispan only supported transactional and read-only strategies on top of transactional invalidation caches.

Since version 5.0, Infinispan currently supports all cache concurrency modes in cluster mode, although not all combinations of configurations are compatible:

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 2. Cache concurrency strategy/cache mode compatibility table
Concurrency strategy	Cache transactions	Cache mode	Eviction
transactional	transactional	invalidation	yes
read-write	non-transactional	invalidation	yes
read-write	non-transactional	distributed/replicated	no
nonstrict-read-write	non-transactional	distributed/replicated	no

Changing caches to behave different to the default behaviour explained in previous section is explained in Configuration Properties section.

Example 26. 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

Alternative RegionFactory

In standalone environments or managed environments with no Infinispan integration, org.hibernate.cache.infinispan.InfinispanRegionFactory should be the choice for region factory implementation. However, it might be sometimes desirable for the Infinispan cache manager to be shared between different JPA/Hibernate applications, for example to share intra-cluster communications channels. In this case, the Infinispan cache manager could be bound into JNDI and the JPA/Hibernate applications could use an alternative region factory implementation:

Example 27. JndiInfinispanRegionFactory configuration

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

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

Inside Wildfly

In WildFly, Infinispan is the default second level cache provider for JPA/Hibernate. 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).

You can find details about its configuration in the JPA reference guide, in particular, in the second level cache section.

The default second-level cache configurations used by Wildfly match the configurations explained above both for local and clustered environments. So, an Infinispan based second-level cache should behave exactly the same standalone and within containers that provide Infinispan second-level cache as default for JPA/Hibernate.

Remember that if deploying to Wildfly or Application Server, the way some Infinispan second level cache provider configuration is defined changes slightly because the properties must include deployment and persistence information. Check the Configuration section for more details.

Configuration properties

As explained above, Infinispan second-level cache provider comes with default configuration in infinispan-config.xml that is suited for clustered use. If there’s only single JVM 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. Cache configuration changes in Wildfly should be done either modifying the cache configurations inside the application server configuration, or creating new caches with the desired tweaks and plugging them accordingly. See examples below on how entity/collection specific configurations can be applied.

Example 28. Use custom Infinispan configuration

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

If the cache is configured as transactional, InfinispanRegionFactory automatically sets transaction manager so that the TM used by Infinispan is the same as TM used by Hibernate.

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 29. 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" />

Use custom cache template in Wildfly

When applying entity/collection level changes inside JPA applications deployed in Wildfly, it is necessary to specify deployment name and persistence unit name:

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

Cache configurations are used only as a template for the cache created for given region (usually each entity hierarchy or collection has its own region). It is not possible to use the same cache for different regions.

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.

Example:

<property name="hibernate.cache.infinispan.entity.eviction.strategy"
   value= "LRU"/>
<property name="hibernate.cache.infinispan.entity.eviction.wake_up_interval"
   value= "2000"/>
<property name="hibernate.cache.infinispan.entity.eviction.max_entries"
   value= "5000"/>
<property name="hibernate.cache.infinispan.entity.expiration.lifespan"
   value= "60000"/>
<property name="hibernate.cache.infinispan.entity.expiration.max_idle"
   value= "30000"/>

With the above configuration, you’re overriding whatever eviction/expiration settings were defined for the default entity cache name in the Infinispan cache configuration used, regardless of whether it’s the default one or user defined. More specifically, we’re defining the following:

All entities to use LRU eviction strategy
The eviction thread to wake up every 2 seconds (2000 milliseconds)
The maximum number of entities for each entity type to be 5000 entries
The lifespan of each entity instance to be 1 minute (600000 milliseconds).
The maximum idle time for each entity instance to be 30 seconds (30000 milliseconds).

You can also override eviction/expiration settings on a per entity/collection type basis in such way that the overriden settings only afftect that particular entity (i.e. com.acme.Person) or collection type (i.e. com.acme.Person.addresses). Example:

<property name="hibernate.cache.infinispan.com.acme.Person.eviction.strategy"
   value= "LIRS"/>

Inside of Wildfly, same as with the entity/collection configuration override, eviction/expiration settings would also require deployment name and persistence unit information:

<property name="hibernate.cache.infinispan._war_or_ear_name_._unit_name_.com.acme.Person.eviction.strategy"
   value= "LIRS"/>
<property name="hibernate.cache.infinispan._war_or_ear_name_._unit_name_.com.acme.Person.expiration.lifespan"
   value= "65000"/>

In versions prior to 5.1, hibernate.cache.infinispan.something.expiration.wake_up_interval was called hibernate.cache.infinispan.something.eviction.wake_up_interval. Eviction settings are checked upon each cache insert, it is expiration that needs to be triggered periodically. The old property still works, but its use is deprecated.

Property hibernate.cache.infinispan.use_synchronization that allowed to register Infinispan as XA resource in the transaction has been deprecated in 5.0 and is not honored anymore. Infinispan 2LC must register as synchronizations on transactional caches. Also, non-transactional cache modes hook into the current JTA/JDBC transaction as synchronizations.

Remote Infinispan Caching

Lately, several questions ( here and here ) have appeared in the Infinispan user forums asking whether it’d be possible to have an Infinispan second level cache that instead of living in the same JVM as the Hibernate code, it resides in a remote server, i.e. an Infinispan Hot Rod server. It’s important to understand that trying to set up second level cache in this way is generally not a good idea for the following reasons:

The purpose of a JPA/Hibernate second level cache is to store entities/collections recently retrieved from database or to maintain results of recent queries. So, part of the aim of the second level cache is to have data accessible locally rather than having to go to the database to retrieve it everytime this is needed. Hence, if you decide to set the second level cache to be remote as well, you’re losing one of the key advantages of the second level cache: the fact that the cache is local to the code that requires it.
Setting a remote second level cache can have a negative impact in the overall performance of your application because it means that cache misses require accessing a remote location to verify whether a particular entity/collection/query is cached. With a local second level cache however, these misses are resolved locally and so they are much faster to execute than with a remote second level cache.

There are however some edge cases where it might make sense to have a remote second level cache, for example:

You are having memory issues in the JVM where JPA/Hibernate code and the second level cache is running. Off loading the second level cache to remote Hot Rod servers could be an interesting way to separate systems and allow you find the culprit of the memory issues more easily.
Your application layer cannot be clustered but you still want to run multiple application layer nodes. In this case, you can’t have multiple local second level cache instances running because they won’t be able to invalidate each other for example when data in the second level cache is updated. In this case, having a remote second level cache could be a way out to make sure your second level cache is always in a consistent state, will all nodes in the application layer pointing to it.
Rather than having the second level cache in a remote server, you want to simply keep the cache in a separate VM still within the same machine. In this case you would still have the additional overhead of talking across to another JVM, but it wouldn’t have the latency of across a network.

The benefit of doing this is that:
- Size the cache separate from the application, since the cache and the application server have very different memory profiles. One has lots of short lived objects, and the other could have lots of long lived objects.
- To pin the cache and the application server onto different CPU cores (using numactl ), and even pin them to different physically memory based on the NUMA nodes.

Caching

Configuring second-level caching

RegionFactory

Caching configuration properties

Configuring second-level cache mappings

Entity inheritance and second-level cache mapping

Entity cache

Collection cache

Query cache

Query cache regions

Managing the cached data

Evicting cache entries

Caching statistics

JCache

RegionFactory

JCache CacheManager

Ehcache

RegionFactory

EhCacheRegionFactory

SingletonEhCacheRegionFactory

Infinispan

Single Node Local

Default Local Configuration

Local Cache Strategies

Multi Node Cluster

Default Cluster Configuration

Cluster Cache Strategies

Alternative RegionFactory

Inside Wildfly

Configuration properties

Remote Infinispan Caching

JCache `CacheManager`

`EhCacheRegionFactory`

`SingletonEhCacheRegionFactory`