Getting Started with Hibernate Second-Level Cache and Hazelcast with JCache

See something wrong? Edit this page.

This guide will show you how to use Hazelcast IMDG as Hibernate’s Second-Level Cache by leveraging Hibernate’s JCache (JSR 107) support.

You will have a chance to see how to integrate Hazelcast with Hibernate without using the hazelcast-hibernate integration.

What You’ll Learn

  • How to use Hazelcast’s distributed maps as entity/collection/query caches

Prerequisites

  • JDK 8+

  • Apache Maven 3.2+

Required Dependencies

First, we need to add required dependencies.

Let’s include hibernate-jcache and hibernate-core dependencies. Keep in mind that both should have the same version:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-jcache</artifactId>
    <version>${hibernate.version}</version>
</dependency>

Make sure to include the hazelcast dependency as well:

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast</artifactId>
    <version>${hazelcast.version}</version>
</dependency>

Configuring Hibernate JCache RegionFactory

Now we need to tell Hibernate to use JCache’s region factory.

For Hibernate 5.2.x, you need to add a full class name:

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

For Hibernate 5.3.x+, it’s enough to mention jcache:

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

Configuring the Cache Provider

You can choose to either use an embedded Hazelcast instance, or connect to an external server using Hazelcast Client.

EMBEDDED: For creating an embedded Hazelcast instance with an application. This instance cannot be scaled up or down unless you run or shutdown another Hibernate application with the same server config.

CLIENT: For connecting to an existing Hazelcast cluster that can scale up or down independently from your app.

  • You can learn more about the differences between client and embedded topologies here.

Now let’s configure the provider.

To use native client:

<property name="hibernate.javax.cache.provider">
   com.hazelcast.client.cache.impl.HazelcastClientCachingProvider
</property>
<property name="hibernate.javax.cache.uri">
   hazelcast-client.xml
</property>

To use embedded Hazelcast:

<property name="hibernate.javax.cache.provider">
   com.hazelcast.cache.impl.HazelcastServerCachingProvider
</property>
<property name="hibernate.javax.cache.uri">
   hazelcast.xml
</property>

Cache Configuration

Configure the cache via hazelcast.xml and the <cache> part:

<cache name="custom.cache.region.name">
    <statistics-enabled>true</statistics-enabled>
    <management-enabled>true</management-enabled>
    <eviction size="10000" max-size-policy="ENTRY_COUNT" eviction-policy="LRU" />
</cache>
To track the cache statistics on Hazelcast Management Center, you have to enable the statistics (disabled by default) for the cache configuration of the Hazelcast instance.
If client mode is used, cache configurations must be set on the server configuration (hazelcast.xml), not on the client-side (hazelcast-client.xml).
If you do not define a specific region name, the default cache configuration is going to be used. Hence it will not be visible on Hazelcast Management Center. To apply a config to all regions, you can use a wildcard for name property (e.g., name="*").

For other cache configuration properties, see cache configuration section on the documentation here. Eviction size and policy properties might be useful for this case.

Running the Application

The samples consist of three classes demonstrating various types of Hibernate caches:

  • com.hazelcast.hibernate.jcache.CollectionCache

  • com.hazelcast.hibernate.jcache.EntityCache

  • com.hazelcast.hibernate.jcache.QueryCache

All of them are running using an in-memory H2 instance and can be run using their main() methods.

Summary

We’ve configured an application to use Hibernate’s Second-Level cache with Hazelcast.

You can find the code samples for entity cache, collection cache, and query cache use cases here.