Hibernate EhCache configuration tutorial

Caching is facility provided by ORM frameworks which help users to get fast running web application, while help framework itself to reduce number of queries made to database in a single transaction. Hibernate also provide this caching functionality, in two layers.

  • Fist level cache: This is enabled by default and works in session scope. Read more about hibernate first level cache.
  • Second level cache: This is apart from first level cache which is available to be used globally in session factory scope.

In this tutorial, I am giving an example using ehcache configuration as second level cache in hibernate.

Hibernate with EhCache

Hibernate with EhCache

Sections in this post:
How second level cache works
About EhCache
Configuring EhCache
Configuring entity objects
Query caching
Example application
Sourcecode download

How second level cache works

Lets write all the facts point by point:

  1. Whenever hibernate session try to load an entity, the very first place it look for cached copy of entity in first level cache (associated with particular hibernate session).
  2. If cached copy of entity is present in first level cache, it is returned as result of load method.
  3. If there is no cached entity in first level cache, then second level cache is looked up for cached entity.
  4. If second level cache has cached entity, it is returned as result of load method. But, before returning the entity, it is stored in first level cache also so that next invocation to load method for entity will return the entity from first level cache itself, and there will not be need to go to second level cache again.
  5. If entity is not found in first level cache and second level cache also, then database query is executed and entity is stored in both cache levels, before returning as response of load() method.
  6. Second level cache validate itself for modified entities, if modification has been done through hibernate session APIs.
  7. If some user or process make changes directly in database, the there is no way that second level cache update itself until “timeToLiveSeconds” duration has passed for that cache region. In this case, it is good idea to invalidate whole cache and let hibernate build its cache once again. You can use below code snippet to invalidate whole hibernate second level cache.

About EhCache

Terracotta Ehcache is a popular open source Java cache that can be used as a Hibernate second level cache. It can be used as a standalone second level cache, or can be configured for clustering to provide a replicated coherent second level cache.

Hibernate ships with the ehcache library. If you want any particular version of ehcache, visit the Terracotta Ehcache download site:


The maven dependency is for Ehcache 2.0 and any upgrades is:


Configuring EhCache

To configure ehcache, you need to do two steps:

  1. configure Hibernate for second level caching
  2. specify the second level cache provider

Hibernate 3.3 and above

<property key="hibernate.cache.use_second_level_cache">true</property>
<property name="hibernate.cache.region.factory_class">net.sf.ehcache.hibernate.EhCacheRegionFactory</property>

Hibernate 3.2 and below

<property key="hibernate.cache.use_second_level_cache">true</property>
<property name="hibernate.cache.region.provider_class">net.sf.ehcache.hibernate.EhCacheProvider</property>

Configuring entity objects

This may done in two ways.

1) If you are using hbm.xml files then use below configuration:

<class name="com.application.entity.DepartmentEntity" table="...">
    <cache usage="read-write"/>

2) Otherwise, if you are using annotations, use these annotations:

public class DepartmentEntity implements Serializable 

For both options, caching strategy can be of following types:

  • none : No caching will happen.
  • read-only : If your application needs to read, but not modify, instances of a persistent class, a read-only cache can be used.
  • read-write : If the application needs to update data, a read-write cache might be appropriate.
  • nonstrict-read-write : If the application only occasionally needs to update data (i.e. if it is extremely unlikely that two transactions would try to update the same item simultaneously), and strict transaction isolation is not required, a nonstrict-read-write cache might be appropriate.
  • transactional : The transactional cache strategy provides support for fully transactional cache providers such as JBoss TreeCache. Such a cache can only be used in a JTA environment and you must specify hibernate.transaction.manager_lookup_class.

Query caching

You can also enable query caching. To do so configure it in your hbm.xml:

<property key="hibernate.cache.use_query_cache">true</property>

and where queries are defined in your code, add the method call setCacheable(true) to the queries that should be cached:


By default, Ehcache will create separate cache regions for each entity that you configure for caching. You can change the defaults for these regions by adding the configuration to your ehcache.xml. To provide this configuration file, use this property in hibernate configuration:

<property name="net.sf.ehcache.configurationResourceName">/ehcache.xml</property>

And use below configuration to override the default configuration:


Please note that in ehcache.xml, if eternal=”true” then we should not write timeToIdealSeconds, timeToLiveSeconds, hibernate will take care about those values
So if you want to give values manually better use eternal=”false” always, so that we can assign values into timeToIdealSeconds, timeToLiveSeconds manually.

timeToIdealSeconds=”seconds” means, if the object in the global cache is ideal, means not using by any other class or object then it will be waited for some time we specified and deleted from the global cache if time is exceeds more than timeToIdealSeconds value.

timeToLiveSeconds=”seconds” means, the other Session or class using this object or not, i mean may be it is using by other sessions or may not, what ever the situation might be, once it competed the time specified timeToLiveSeconds, then it will be removed from the global cache by hibernate.

Example application

In our example application, I have one DepartmentEntity for which I want to enable second level cache using ehcache. Lets record the changes step by step:

1) hibernate.cfg.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        <property name="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property>
        <property name="hibernate.connection.url">jdbc:mysql://localhost:3306/hibernatedemo</property>
        <property name="hibernate.connection.password">password</property>
        <property name="hibernate.connection.username">root</property>
        <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="show_sql">true</property>
		<property name="hbm2ddl.auto">create</property>
		<property name="hibernate.cache.provider_class">org.hibernate.cache.EhCacheProvider</property>
        <mapping class="hibernate.test.dto.DepartmentEntity"></mapping>

2) DepartmentEntity.java

package hibernate.test.dto;

import java.io.Serializable;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.persistence.UniqueConstraint;

import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;

@Entity (name = "dept")
@Table(name = "DEPARTMENT", uniqueConstraints = {
		@UniqueConstraint(columnNames = "ID"),
		@UniqueConstraint(columnNames = "NAME") })
@Cache(usage=CacheConcurrencyStrategy.READ_ONLY, region="department")

public class DepartmentEntity implements Serializable {
	private static final long serialVersionUID = 1L;

	@GeneratedValue(strategy = GenerationType.IDENTITY)
	@Column(name = "ID", unique = true, nullable = false)
	private Integer id;
	@Column(name = "NAME", unique = true, nullable = false, length = 100)
	private String name;

	public Integer getId() {
		return id;

	public void setId(Integer id) {
		this.id = id;

	public String getName() {
		return name;

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

3) HibernateUtil.java

package hibernate.test;

import java.io.File;

import org.hibernate.SessionFactory;
import org.hibernate.cfg.AnnotationConfiguration;

public class HibernateUtil 
	private static final SessionFactory sessionFactory = buildSessionFactory();
    private static SessionFactory buildSessionFactory() 
            // Create the SessionFactory from hibernate.cfg.xml
            return new AnnotationConfiguration().configure(new File("hibernate.cgf.xml")).buildSessionFactory();
        catch (Throwable ex) {
            // Make sure you log the exception, as it might be swallowed
            System.err.println("Initial SessionFactory creation failed." + ex);
            throw new ExceptionInInitializerError(ex);
    public static SessionFactory getSessionFactory() {
        return sessionFactory;
    public static void shutdown() {
    	// Close caches and connection pools

4) TestHibernateEhcache.java

public class TestHibernateEhcache 
	public static void main(String[] args) 
			//Open the hibernate session
			Session session = HibernateUtil.getSessionFactory().openSession();
			//fetch the department entity from database first time
			DepartmentEntity department = (DepartmentEntity) session.load(DepartmentEntity.class, new Integer(1));
			//fetch the department entity again; Fetched from first level cache
			department = (DepartmentEntity) session.load(DepartmentEntity.class, new Integer(1));
			//Let's close the session
			//Try to get department in new session
			Session anotherSession = HibernateUtil.getSessionFactory().openSession();
			//Here entity is already in second level cache so no database query will be hit
			department = (DepartmentEntity) anotherSession.load(DepartmentEntity.class, new Integer(1));
			System.out.println(HibernateUtil.getSessionFactory().getStatistics().getEntityFetchCount()); //Prints 1
			System.out.println(HibernateUtil.getSessionFactory().getStatistics().getSecondLevelCacheHitCount()); //Prints 1
	private static void storeData()
		Session session = HibernateUtil.getSessionFactory().openSession();
		DepartmentEntity department = new DepartmentEntity();
		department.setName("Human Resource");


Hibernate: insert into DEPARTMENT (NAME) values (?)
Hibernate: select department0_.ID as ID0_0_, department0_.NAME as NAME0_0_ from DEPARTMENT department0_ where department0_.ID=?
Human Resource
Human Resource
Human Resource

In above output, first time the department is fetched from database. but next two times it is fetched from cache. Last fetch is from second level cache.

To download the sourcecode of above application, please follow below link.

Sourcecode Download

Hope you likes above article. If you got any question or suggestion, drop a comment.

Happy Learning !!




I have 7 Years of rich experience in java technology. This has only increased my hunger to learn more. In this blog, i will be writing on different topics occasionally, and would love to engage in some meaningful serious discussions with you folks.

You may also like...

30 Responses

  1. sivan says:

    ehcache or other variants are always work on 2. level cache or is it possible to configure them work on 1. level?Thanks in advance

    • Lokesh says:

      At first level, there is always hibernate default cache and you cannot even disable it. You can choose anything at only second level cache.

  2. sivan says:

    when we set or change entity and commit the transection session cache is updated.So 2. level cache is also updated or not? if so the other sessions will still use old data because they are referring first level cache before second level maybe second level cache changes trigger to all sessions update their data from 2. level context.

  3. Niraj says:

    Hi Lokesh,

    How to set ehcache for clustered environment?

  4. Manisha Pandey says:

    Hello I am just implementing Query level cache in my code using annotation and currently facing a problem ….can you please clarify that do we need to use @Cache() at the entity level if we are implementing Query Level cache only.

  5. Sandeep says:

    In attached zip file there is ehCache.xml file is not present?

    • Lokesh says:

      Look at path: hibernate-test-project / .settings / ehcache.xml

      • sandeep.pandey15@gmail.com says:

        Thanks Lokesh!

        I have create a stand alone program for ehcache. I have deleted/renamed ehcache.xml even after that i can see the cached file in java.io.tmpdir” path.

        Could you please let me know how/where to use ehcache.xml. Can i rename it/can path updated from java.io.tmpdir to any-other path.

        Appreciate your response.

  6. sunny says:

    I am applying EHCache for Hibernate4,
    This is my configuration
    In entity,i configured like this

    @Table(name = “tbl_lookup”)

    In hibernate.cfg.xml :

    Ehcache.xml :

    I have add the jars : ehcache-core-2.4.5.jar,hibernate-ehcache-4.1.0.Final.jar

    Prob : For first click it getting the objects putting into 2nd level cache(ex:SecondLevelCachePutCount -30),from next click onwards it is getting the 7 objects which are there in second level cache.Now it is updating SecondLeveCacheMissCount,SecondLevelHitCount(if we observe with JConsole).It should not go to DB again.

    Please Help me……

  7. suchithra says:

    ehcache and OSCache useful in real time projects or not?

  8. Jorge Luiz says:

    yours tutorials are so didact, keep it up Lokesh good work.

  9. Somesh says:

    very good article written in very simple and easy to understand language. also code snippets helped to understand completely.
    Thanks a lot . You rocks

  10. senthil says:

    Very good

  11. jagadish says:

    Hi Lokesh,

    Can you explain me about stale object in Hibernate?

    • Lokesh says:

      A stale persistent object is no longer valid. Its fields have default values or values left over from previous transactions and should not be used. An object can also become stale when the transaction in which it was accessed is aborted because of a deadlock or another action that caused AbortException to be signaled.

      I will cover more in any future post.

  12. Sourabh says:

    Nice tutorial eazy and crisp to understand.
    I am unable to download the sourcecode.

  13. ayoub says:

    Sorry about my bad english.

    Firstly I want to thank for all these tutorials, secondly I followed all steps mentioned above but my output was like that :

    Hibernate: insert into DEPARTMENT (NAME) values (?)
    Hibernate: select department0_.ID as ID0_0_, department0_.NAME as NAME0_0_ from DEPARTMENT department0_ where department0_.ID=?
    Human Resource
    Human Resource
    Human Resource
    the two lines :
    System.out.println(HibernateUtil.getSessionFactory().getStatistics().getSecondLevelCacheHitCount()); Print 0 instead of 1.

    would you explaining me why?

  14. sanjay says:

    where should i keep ehcache.xml file

  15. samir says:

    good tutorial

  16. Romi says:

    Doing very good job. Keep it up.

Note:- In comment box, please put your code inside [java] ... [/java] OR [xml] ... [/xml] tags otherwise it may not appear/post as intended.

Want to ask any question? Or suggest anything?