Free GigaSpaces Distributed Cache for Hibernate Users

To get a free distributed cache for your Hibernate database integration, all you need to do is replace your existing Hibernate cache provider, typically EhCache, with the free GigaSpaces Community Edition, in 6 easy steps.

NOTE: GigaSpaces fully supports the Spring Framework, and can be plugged in very easily without changing your existing code.

For more detailed information, see GigaSpaces for Hibernate ORM Users in the GigaSpaces Wiki Online Help.

1. Download the GigaSpaces Community Edition

GigaSpaces Community Edition is a fully-functional version of GigaSpaces which permits unlimited clients but only one server node.

See the Product FAQ for product and license information, or
Visit the Download Page

NOTE: If you need more than one server node, download and evaluate GigaSpaces eXtreme Application Platform or XAP - Enterprise Data Grid.

2. Install GigaSpaces

If you need help, refer to the GigaSpaces installation instructions.

3. Switch Your Hibernate Cache Provider to GigaSpaces

This procedure is different if you are managing your Hibernate configuration using Spring (refer to the Spring documentation, ORM Data Access, section 12.2.2), or directly using hibernate.properties or hibernate.cfg.xml. Please read the relevant section below.

Spring Configuration

Edit your SessionFactory Setup. This is the section inside your Spring Application Context File that controls the relevant Hibernate configuration (refer to the Spring documentation, ORM Data Access, section 12.2.2).

Add or modify the following properties under <property name="hibernateProperties">:

Set hibernate.cache.provider_class to org.openspaces.hibernate.cache.SimpleMapCacheProvider:

<prop key="hibernate.cache.provider_class">
    org.openspaces.hibernate.cache.SimpleMapCacheProvider</prop>

Set hibernate.cache.use_second_level_cache to true:

<prop key="hibernate.cache.use_second_level_cache">true</prop>

Set gigaspace.hibernate.cache.url to /./space:

<prop key="gigaspace.hibernate.cache.url">/./space</prop>

Direct Configuration using `hibernate.properties`

Edit your hibernate.properties file. Add or modify the following properties in the Second-Level Cache section:

Set hibernate.cache.provider_class to org.openspaces.hibernate.cache.SimpleMapCacheProvider:

hibernate.cache.provider_class org.openspaces.hibernate.cache.SimpleMapCacheProvider

Set hibernate.cache.use_second_level_cache to true:

hibernate.cache.use_second_level_cache true

Set gigaspace.hibernate.cache.url to /./space:

gigaspace.hibernate.cache.url /./space

Direct Configuration using `hibernate.cfg.xml`

Edit your hibernate.cfg.xml file. Add or modify the following properties under <session-factory>:

Set hibernate.cache.provider_class to org.openspaces.hibernate.cache.SimpleMapCacheProvider:

<property name="hibernate.cache.provider_class">
    org.openspaces.hibernate.cache.SimpleMapCacheProvider</property>

Set hibernate.cache.use_second_level_cache to true:

<property name="hibernate.cache.use_second_level_cache">true</property>

Set gigaspace.hibernate.cache.url to /./space:

<property name="gigaspace.hibernate.cache.url">/./space</property>

4. Set Cache Usage in Mapping Resource File

Set or add cache usage (the cache concurrency strategy) in your mapping resource file (*.hbm.xml files) to read-only, read-write or nonstrict-read-write:

<class name="your.class.name" table="YourTableName">
     <cache usage="nonstrict-read-write"/>

Alternatively, use the <class-cache> and <collection-cache> elements in your hibernate configuration file.

5. Add Required JARs to Your Application

Make sure you include the following GigaSpaces JARs in your application classpath:

<GigaSpaces Root>\lib\JSpaces.jar;
<GigaSpaces Root>\lib\ServiceGrid\gs-boot.jar;
<GigaSpaces Root>\lib\jini\jsk-lib.jar;
<GigaSpaces Root>\lib\jini\jsk-platform.jar;
<GigaSpaces Root>\lib\openspaces\openspaces.jar;
<GigaSpaces Roor>\lib\common\commons-logging.jar;
<GigaSpaces Roor>\lib\spring\spring.jar;
<GigaSpaces Roor>\lib\spring\jta.jar;
<GigaSpaces Roor>\lib\spring\cglib-nodep-2.1_3.jar;

You must also include the following JARs from the Hibernate distribution package:

jdbc2_0-stdext.jar; dom4j-1.6.1.jar; commons-collections-2.1.1.jar; asm.jar; asm-attrs.jar;
antlr-2.7.6rc1.jar; ejb3-persistence.jar; hibernate3.jar; hibernate-annotations.jar; 
hibernate-commons-annotations.jar

6. Working With a Distributed Cache Topology

GigaSpaces cache provides the following distributed topologies (these are only the most common, many other topologies are supported):

Master-Local Cache Topology - each application has a lightweight, embedded cache, which is initially empty. The first time data is read, it is loaded from a master cache to the local cache (lazy load); the next time the same data is read, it is loaded quickly from the local cache. Later on data is either updated from the master or evicted from the cache.

Partitioned Master-Local Cache Topology (*) - data is split between two spaces (partitions) according to an index field defined in the data. An algorithm, defined in the load-balancing policy, maps values of the index field to specific partitions.

Embedded Replicated Cache Topology (*) - two or more space instances with replication between them, allowing two or more applications to work with their own dedicated data store, while working on the same data as the other applications.

(*) The Partitioned and Embedded Replicated topologies require GigaSpaces eXtreme Application Platform (see Product Info or Download Page) or GigaSpaces XAP Enterprise Data Grid (see Product Info or Download Page) for multiple server nodes. You may evaluate both products for a period of 30 days.

Using the Master-Local Cache Topology

Set your gigaspaces.hibernate.cache.url property to

jini://*/*/dataGrid?useLocalCache&amp;groups=gigaspaces-6.0XAP

Copy <GigaSpaces Root>\lib\hibernate\hibernate3.jar and <GigaSpaces Root>\lib\common\commons-logging.jar into the <GigaSpaces Root>\lib\ext folder.
Copy dom4j.jar from Hibernate distribution package into the <GigaSpaces Root>\lib\ext foler.
Run <GigaSpaces Root>\bin\gs-all.bat (.sh) to start a GigaSpaces container manager (GSM) and a container (GSC) for the master GigaSpaces space.

Wait to see the following output in both GSM and GSC console windows:

INFO [org.jini.rio.cybernode]: Registered to a ProvisionManager

Run <GigaSpaces root>\bin\gs.bat pudeploy ..\deploy\templates\datagrid to deploy the master space

Wait to see the following output (below the output shown in the previous step) in both GSM and GSC console windows:

FINE [org.jini.rio.monitor.services]: [..\deploy\templates\datagrid:
    ..\deploy\templates\datagrid.PU] service provisioned, .....

Run your application.

Using the Partitioned Master-Local Cache Topology (Requires GigaSpaces XAP/EDG)

Configure your gigaspaces.hibernate.cache.url property to:

jini://*/*/dataGrid?useLocalCache&amp;groups=gigaspaces-6.0XAP

Copy <GigaSpaces Root>\lib\hibernate\hibernate3.jar and <GigaSpaces Root>\lib\common\commons-logging.jar into the <GigaSpaces Root>\lib\ext folder.
Copy dom4j.jar from Hibernate distribution package into the <GigaSpaces Root>\lib\ext folder.
Run <GigaSpaces Root>\bin\gsm.bat (.sh) to start a container manager (GSM).
Run <GigaSpaces Root>\bin\gsc.bat (.sh) to start a container (GSC) for the master space.
Run <GigaSpaces Root>\bin\gsc.bat (.sh) to start an additional container (GSC).

Wait to see the following output in the two GSC output windows:

INFO [org.jini.rio.cybernode]: Registered to a ProvisionManager

Run <GigaSpaces Root>\bin\gs pudeploy -cluster schema=partitioned total_members=2,0 ../deploy/templates/datagrid to run a cluster of two partitioned master spaces.

Wait to see the following output in the first GSC console window:

FINE [org.jini.rio.cybernode]: /datagrid.PU [1]: advertised

and the following output in the second GSC console window:

FINE [org.jini.rio.cybernode]: /datagrid.PU [2]: advertised

Run your application.

Using the Embedded Replicated Cache Topology (Requires GigaSpaces XAP/EDG)

In your first application, configure the gigaspaces.hibernate.cache.url property to the following (as one long line):

/./space?cluster_schema=sync_replicated&amp;total_members=2&amp;
    id=1&amp;groups=gigaspaces-6.0XAP

Run your first application.
In your second application, configure your gigaspaces.hibernate.cache.url property to the following (as one long line):

/./space?cluster_schema=sync_replicated&amp;total_members=2&amp;
    id=2&amp;groups=gigaspaces-6.0XAP

Run your second application.

YOU'RE DONE!

OPTIONAL: Adding the GigaSpaces In-Memory Data Grid

If you need to scale up your database, you can use GigaSpaces as an In-Memory Data Grid. Your application communicates with the Data Grid using the Spring-based Open Spaces framework (or alternatively, using the simple JavaSpaces or Map interfaces). On the back-end, GigaSpaces persists the data to your existing database using your existing Hibernate O/R mapping.

NOTE: Adding the GigaSpaces Data Grid requires GigaSpaces eXtreme Application Platform (see Product Info or Download Page) or GigaSpaces XAP Enterprise Data Grid (see Product Info or Download Page) for multiple server nodes. You may evaluate both products for a period of 30 days.

Benefits

Database scalability through partitioning and data distribution - enables higher data volumes and higher throughput with low latency.
Better decoupling between your application and the database - no need to hard-wire Hibernate and database concepts into your code and runtime environment.
Event-driven model enables notifications when data is modified.
Database access can be synchronous or asynchronous - the Mirror Service allows data to be persisted to the database asynchronously, without a performance penalty.

How to Add the GigaSpaces In-Memory Data Grid

NOTE: The instructions below assume you are managing your Hibernate configuration using Spring. Refer to the Spring documentation to learn how to do this.

If you haven't done so already, download the GigaSpaces eXtreme Application Platform (see Product Info or Download Page) or GigaSpaces XAP Enterprise Data Grid (see Product Info or Download Page). You may evaluate both products for a period of 30 days. (You cannot use the Community Edition for this purpose, because a Data Grid requires more than one GigaSpaces server node.)
Install GigaSpaces. If you need help, refer to the GigaSpaces installation instructions.
Edit your SessionFactory Setup. This is the section in your Spring Application Context File that controls the relevant Hibernate configuration (refer to the Spring documentation, ORM Data Access, section 12.2.2).
Add or modify the following properties under <property name="hibernateProperties">:
- Set hibernate.cache.provider_class to org.hibernate.cache.NoCacheProvider (no cache provider):
- Set hibernate.cache.use_second_level_cache to false:
- Add the following bean definition to your application context:

<bean id="hibernateDataSource" class="com.gigaspaces.datasource.hibernate.HibernateDataSource">
    <property name="sessionFactory" ref="sessionFactory"/>
</bean>

<os-core:space id="space" url="/./space" schema="persistent" 
external-data-source="hibernateDataSource" />

Modify your application to handle data using GigaSpaces' Spring-based Open Spaces framework, instead of the Hibernate API. Keep in mind that GigaSpaces will continue to persist data to your existing database using your existing O/R mapping.
- To learn how to do this, refer to the Open Spaces section in the GigaSpaces Online Help.
- If you prefer to access GigaSpaces directly using one of the supported APIs, refer to the JavaSpaces or Map sections in the GigaSpaces Online Help.
Deploy the GigaSpaces Data Grid in the topology of your choice. A partitioned topology is particularly useful for scaling up to increase the throughput of your database.
- To learn how to do this, refer to Data Grid Topologies in the GigaSpaces Online Help. For more information, refer to the XAP Enterprise Data Grid Help Portal.
Choose how GigaSpaces should access the database:
- If you want data to be synchronously read and written to the database by the Data Grid, refer to the Read-Through and Write-Through section in the GigaSpaces Online Help.
- If you want data to be asynchronously mirrored between the Data Grid and and the database, refer to the Mirror Service section in the GigaSpaces Online Help.
Launch your application. The application writes and reads data to/from the GigaSpaces In-Memory Data Grid; the data is persisted in the background to your existing database using Hibernate.