Hibernate.orgCommunity Documentation

Chapter 6. Caching

Table of Contents

6.1. The query cache
6.1.1. Query cache regions
6.2. Second-level cache providers
6.2.1. Configuring your cache providers
6.2.2. Caching strategies
6.2.3. Second-level cache providers for Hibernate
6.3. Managing the cache
6.3.1. Moving items into and out of the cache

If you have queries that run over and over, with the same parameters, query caching provides performance gains.

Caching introduces overhead in the area of transactional processing. For example, if you cache results of a query against an object, Hibernate needs to keep track of whether any changes have been committed against the object, and invalidate the cache accordingly. In addition, the benefit from caching query results is limited, and highly dependent on the usage patterns of your application. For these reasons, Hibernate disables the query cache by default.

The query cache does not cache the state of the actual entities in the cache. It caches identifier values and results of value type. Therefore, always use the query cache in conjunction with the second-level cache for those entities which should be cached as part of a query result cache.

Hibernate is compatible with several second-level cache providers. None of the providers support all of Hibernate's possible caching strategies. Section 6.2.3, “Second-level cache providers for Hibernate” lists the providers, along with their interfaces and supported caching strategies. For definitions of caching strategies, see Section 6.2.2, “Caching strategies”.

You can configure your cache providers using either annotations or mapping files.

Entities.  By default, entities are not part of the second-level cache, and their use is not recommended. If you absolutely must use entities, set the shared-cache-mode element in persistence.xml, or use property javax.persistence.sharedCache.mode in your configuration. Use one of the values in Table 6.1, “Possible values for Shared Cache Mode”.

Set the global default cache concurrency strategy The cache concurrency strategy with the hibernate.cache.default_cache_concurrency_strategy configuration property. See Section 6.2.2, “Caching strategies” for possible values.


When possible, define the cache concurrency strategy per entity rather than globally. Use the @org.hibernate.annotations.Cache annotation.

Example 6.3. Configuring cache providers using mapping files


Just as in the Example 6.2, “Configuring cache providers using annotations”, you can provide attributes in the mapping file. There are some specific differences in the syntax for the attributes in a mapping file.


The caching strategy. This attribute is required, and can be any of the following values.

  • transactional

  • read-write

  • nonstrict-read-write

  • read-only


The name of the second-level cache region. This optional attribute defaults to the class or collection role name.


Whether properties of the entity mapped with lazy=true can be cached when attribute-level lazy fetching is enabled. Defaults to all and can also be non-lazy.

Instead of <cache>, you can use <class-cache> and <collection-cache> elements in hibernate.cfg.xml.


A read-only cache is good for data that needs to be read often but not modified. It is simple, performs well, and is safe to use in a clustered environment.

nonstrict read-write

Some applications only rarely need to modify data. This is the case if two transactions are unlikely to try to update the same item simultaneously. In this case, you do not need strict transaction isolation, and a nonstrict-read-write cache might be appropriate. If the cache is used in a JTA environment, you must specify hibernate.transaction.manager_lookup_class. In other environments, ensore that the transaction is complete before you call Session.close() or Session.disconnect().


A read-write cache is appropriate for an application which needs to update data regularly. Do not use a read-write strategy if you need serializable transaction isolation. In a JTA environment, specify a strategy for obtaining the JTA TransactionManager by setting the property hibernate.transaction.manager_lookup_class. In non-JTA environments, be sure the transaction is complete before you call Session.close() or Session.disconnect().


To use the read-write strategy in a clustered environment, the underlying cache implementation must support locking. The build-in cache providers do not support locking.


The transactional cache strategy provides support for transactional cache providers such as JBoss TreeCache. You can only use such a cache in a JTA environment, and you must first specify hibernate.transaction.manager_lookup_class.

Actions that add an item to internal cache of the Session

Saving or updating an item
  • save()

  • update()

  • saveOrUpdate()

Retrieving an item
  • load()

  • get()

  • list()

  • iterate()

  • scroll()

Syncing or removing a cached item.  The state of an object is synchronized with the database when you call method flush(). To avoid this synchronization, you can remove the object and all collections from the first-level cache with the evict() method. To remove all items from the Session cache, use method Session.clear().

Determining whether an item belongs to the Session cache.  The Session provides a contains() method to determine if an instance belongs to the session cache.