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.


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.

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:


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


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


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


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


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


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


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.


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.


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


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


Entities are cached unless explicitly marked as non-cacheable.


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


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:


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.


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.


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.


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:


Defines the CacheConcurrencyStrategy


Defines a cache region where entries will be stored


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}

    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")
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public static class Phone {

    private Long id;

    private String mobile;

    private Person person;

    private int version;

    public Phone() {}

    public Phone(String 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")
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public static class Person {

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

    private String name;

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

    public Person() {}

    public Person(String name) { = name;

    public Long getId() {
        return id;

    public String getName() {
        return name;

    public void setName(String 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")

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

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
    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 = :name", Person.class)
.setParameter( "name", "John Doe")
.setHint( "org.hibernate.cacheable", "true")
Example 10. Caching query using Hibernate native API
List<Person> persons = session.createQuery(
    "select p " +
    "from Person p " +
    "where = :name")
.setParameter( "name", "John Doe")

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:


Holding the cached query results


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 > :id", Person.class)
        .setParameter( "id", 0L)
        .setHint( QueryHints.HINT_CACHEABLE, "true")
        .setHint( QueryHints.HINT_CACHE_REGION, "query.cache.person" )
Example 12. Caching query in custom region using Hibernate native API
List<Person> persons = session.createQuery(
    "select p " +
    "from Person p " +
    "where > :id")
.setParameter( "id", 0L)
.setCacheRegion( "query.cache.person" )

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 > :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 )
Example 14. Using custom query cache mode with Hibernate native API
List<Person> persons = session.createQuery(
    "select p " +
    "from Person p " +
    "where > :id")
.setParameter( "id", 0L)
.setCacheRegion( "query.cache.person" )
.setCacheMode( CacheMode.REFRESH )

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


CacheStoreMode.USE and CacheRetrieveMode.USE

Default. Reads/writes data from/into cache


CacheStoreMode.REFRESH and CacheRetrieveMode.BYPASS

Doesn’t read from cache, but writes to the cache upon loading from the database


CacheStoreMode.USE and CacheRetrieveMode.BYPASS

Doesn’t read from cache, but writes to the cache as it reads from the database


CacheStoreMode.BYPASS and CacheRetrieveMode.USE

Read from the cache, but doesn’t write to cache


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 )
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 )

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


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


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


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

Example 22. EhCacheRegionFactory configuration

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.


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

Example 23. SingletonEhCacheRegionFactory configuration

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.


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

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 2. Cache concurrency strategy/cache mode compatibility table
Concurrency strategy Cache transactions Cache mode Eviction

















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


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


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

Example 25. InfinispanRegionFactory configuration
    value="org.hibernate.cache.infinispan.InfinispanRegionFactory" />

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

Example 26. JndiInfinispanRegionFactory configuration
    value="org.hibernate.cache.infinispan.JndiInfinispanRegionFactory" />

    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.

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 27. Use custom Infinispan configuration
    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 where data-type can be one of:


Entities indexed by @Id or @EmbeddedId attribute.


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


Entities indexed by their @NaturalId attribute.


All collections.


Mapping entity typelast modification timestamp. Used for query caching.


Mapping queryquery result.


Auxiliary caches for regions using invalidation mode caches.

For specifying cache template for specific region, use region name instead of the data-type:

Example 28. Use custom cache template
    value="custom-entities" />
    value="custom-query-cache" />
    value="my-entities" />
    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:


Available options are NONE, LRU and LIRS.


Maximum number of entries in the cache.


Lifespan of entry from insert into cache (in milliseconds)


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


Period of thread checking expired entries.


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

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.

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

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.

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.