Overview

This section discusses client applications that:

• Use the JavaSpace API to read and write Entry object data to and from a space and a database, or that use the Map API to read and write POJO object data to and from a space and a database.
• Use the Hibernate CacheLoader/Store driver provided with the product for the read/write connection from space to database. This driver implements the generic CacheLoader/Store Interface and does not require any user implementation. Read and write to the database is performed by Hibernate.

With this configuration, JavaSpaces API can still specify object data to read by template or by SQLQuery. However, RegExQuery templates are not supported.
Some typical uses of this configuration are described in this section.
In addition, migrating a legacy Hibernate API application to JavaSpace API is discussed.

To enable logging for CacheLoader\Store, edit the <GigaSpaces Root>\config\gs_logging.properties file and set the persistent level to CONFIG or FINER. For more details, refer to the Settings & Configuration section.

Hibernate CacheLoader/Store Driver

The Hibernate Service

Hibernate is an Object-Relational Mapping (ORM) persistence and query service for the Java language. It is free, open-source software that is distributed under the LGPL. It provides an easy to use framework for mapping an object-oriented domain model to a traditional relational database. Hibernate allows you to express queries in its own portable SQL extension (HQL), as well as in native SQL, or with an object-oriented Criteria and Example API.

The Hibernate CacheLoader/Store driver is an implementation of the generic CacheLoader/Store Interface that automatically activates a full Hibernate session to perform read/write functionality to a database. Both JavaSpace API and Map API space read/write operations interface seamlessly with it.

Legacy Hibernate Installations

The Hibernate CacheLoader/Store driver is especially suited for users with legacy Hibernate installations. It lets you preserve your Hibernate domain classes and HBM mapping configuration file investment while allowing you to take advantage of the SBA data exchange , data caching , data collaboration , messaging , clustering , high-availability, notifications, and SQL query capabilities.

Read-Through - Hibernate CacheLoader

The figure above illustrates how a client application reads or takes a single entry from the space that matches a given template or SQL Query where the actual data is loaded from a database. In this case the Hibernate CacheLoader is called. The JavaSpaces API is used as an example.
The operation proceeds in two stages:

1. The client application calls the JavaSpace read or take API methods, passing a template or SQL Query as first parameter. Non null-valued and null-valued templates are supported.
   The client application call could look like:

   Person person = (Person)JavaSpace.read(new Person("john","doe", null), null, timeout);

2. The client API initiates data lookup in the space for a matching Entry. The first Entry found from the class or its sub-classes instances that matches the template or SQL Query is returned (note that Entries under a transaction cannot be returned). If no such Entry is found, the space calls the Hibernate Cache Loader, which gets the required data from the database. The first object satisfying the template is stored in the space and returned to the client.

RegExQuery templates are not supported.

Write-Through - the Hibernate Cache Store

The figure above illustrates how a client application writes a single Entry object to the space and persists the data in a database. The space writes the Entry data into the database using the Hibernate CacheStore plug-in. The JavaSpace API is used as an example.
The operation proceeds in two stages:

1. The client application calls the JavaSpace.write method or the IJSpaces.update method, passing the Entry object as first parameter.
   The client application call would look like, for example:

   Lease lease = JavaSpace.write(person, null, FOREVER);

2. The JavaSpace API writes the Entry object data as a space Entry, and calls the Hibernate CacheStore.store() passing the Entry object data to the Hibernate session. The Hibernate CacheStore verifies whether the data already exists within the database and performs either an insert or an update database operation, transforming the space Entry into the corresponding record format.

GigaSpaces version 5.1 supports the FOREVER lease time only for write operations when using the Hibernate CacheStore.

Avoid using SQL reserved words such as COUNT, SELECT, WHERE etc. with space Entries Class field names when using the Hibernate CacheLoader/Store.

Migrating Legacy Hibernate API Applications to JavaSpaces API

To benefit from data caching and other capabilities, it is worthwhile to migrate a legacy application that uses the Hibernate API, to either the GigaSpaces Map API or the JavaSpaces API. In such cases, these applications can benefit from the ability to scale when using the GigaSpaces Data Grid. This is achieved by partitioning the data across different spaces running on different machines, and having the business logic also running with each partition. This allows the space and the business logic to run in same memory address, eliminating remote calls when accessing the data.

The following tables show the correspondence between the Hibernate basic API methods to GigaSpaces Map/JavaSpaces API methods.

org.hibernate.Session to IJSpace Mapping

org.hibernate.Session to IMap Mapping

Hibernate CacheLoader/Store Usage Considerations

Database Changes are Not Reflected at the Space

Application accessing the database directly performing insert, updates or data removal operations are not propagated to space – the space is unaware of the operations conducted within the database. You may use database triggers or database replication facilities to update the space with such changes.

More information about updating the space with database changes by application accessing the database directly can be retrieved from the GigaSpaces support team.

Hibernate CacheLoader and the Mirror Service

The Hibernate CacheStore updates the database with new space objects, updated objects or objects that have been removed before the space provide acknowledge to the client – this means the client operation against the space cannot be completed until the database has been fully updated. This impose serious performance impact when performing space destructive operations (write, take, or update; put or remove with the map API). To minimize the performance impact you can perform all relevant database operations in asynchronous manner without impacting the "run time" space operation. All run time destructive operation are replicated in asynchronous manner to a space that is dedicated to perform the database operations in bulk mode – the mirror space. You can control the replication event execution duration interval and replication batch size via the mirror service settings.

To perform data load into the run time space in lazy manner the run time space should be configured to use the Hibernate CacheLoader. This will allow the application to retrieve the required data from the database in case it cannot be found as part of the space. Data from the space can be evicted based on maximum space cached object amount, based on space JVM heap size or based on Entry lease time (this will be supported in future version). The run time space and the Mirror Service sharing the same database server.

Data Consistency Across Space and Database

When the space interacts with the database, the space maintains a consistent view across the space and the database, in case of a database operation failure, i.e., an operation in the space is reverted and the relevant com.j_spaces.core.sadapter.SAException is thrown back into the client, when the HibernateCacheLoader/Store fails to interact with the database. When the HibernateCacheLoader/Store fails to interact with the database, the operation in the space is reverted and the relevant com.j_spaces.core.sadapter.SAException is thrown back into the client.

Transaction Support

All client operations conducted with a transaction are delegated into the database via one database transaction using the HibernateCacheStore.(List<BulkEntry> bulk) implementation when the commit is called.

Extending the Hibernate CacheLoader/Store

You can extend the existing Hibernate CacheLoader/Store and add your own business logic on top of it.

Configuration Files and Space Classpath

• you should define the location of the hibernate.cfg.xml using the space-config.persistent.StorageAdapterURL property.
• The hbm files should be part of the GigaSpaces space classpath.
• Domain classes should be part of the space classpath.

Space Entry and Hibernate Object Mapping

When using an Entry class with the HibernateClassLoader/Store, the space checks for an Entry fields list, when performing client space operations and when performing data load from the database. Both of these operations must represent the same Entry field list.

When loading data from the database, the Entry fields list is determined by the getter and setter methods.

When performing space operations, the Entry fields list is determined based on the public fields.

A public field for an Entry class that does not have getter or setter methods, is not recognized by Hibernate, so it isn't persistent. This will cause inconsistency when reading back from the database into the space, and an UnusableEntryException will be thrown. In this case you should have the field as private or have a getter or setter for it.

Be Careful When Extending Entry Classes Extending a base class that has setter and getter methods for non-existing Entry class fields is not supported. You may extend Entry classes, but make sure the setter and getter methods and their corresponding fields are in the same class.

Initial Load

When a space running in persistent mode (i.e. using HibernateCacheLoader or HibernateCacheStore implementation) is started, the space trying to load data from its underlying data source.

The amount of data to be loaded is 50% of the space cache max size. To disable this initial load phase you should configure the initial_load value to be 0.

Space configuration schema tag:

<space-config>
	<engine>
    	<initial_load>0</initial_load>
	</engine>
</space-config>

XPATH property:

space-config.engine.initial_load=0

The space schema file does not have the above tag by default. You should add it into the correct location.

Libraries and their Location

The following libraries are required when using GigaSpaces Hibernate CacheLoader/Store:

• ant-antlr-1.6.5.jar
• antlr-2.7.6rc1.jar
• asm-attrs.jar
• asm.jar
• cglib-2.1.3.jar
• commons-collections-2.1.1.jar
• commons-logging-1.0.4.jar
• dom4j-1.6.1.jar
• ehcache-1.1.jar
• hibernate3.jar
• jdbc2_0-stdext.jar
• jta.jar

These libraries can be found in the <GigaSpaces Root>/examples/Advanced/Data_Grid/Database-Integration/lib folder.