LATEST VERSION: 8.2.6 - CHANGELOG
Pivotal GemFire® v8.2

Changing Pivotal GemFire Default Configuration (Hibernate Cache Module)

Changing Pivotal GemFire Default Configuration (Hibernate Cache Module)

To edit GemFire configuration information (such as how members locate each other), you can add GemFire properties to Hibernate's hibernate.cfg.xml file.

When adding properties, use the following syntax:

<property name="gemfire.PROPERTY_NAME">PROPERTY_VALUE</property>

In the preceding code snippet, PROPERTY_NAME is the property name and PROPERTY_VALUE is the property value. The list of configurable system properties include any of the properties that can be specified in GemFire's gemfire.properties file. The property changes associated with the most common configurations are described below.

Changing the GemFire Topology

By default, the topology is set for a peer-to-peer configuration rather than a client/server configuration. To use the peer-to-peer configuration, you don't have to make any changes. If you want to change the configuration to a client/server topology, edit the Hibernate configuration file:

<property name="gemfire.cache-topology">client-server</property>

Since the Hibernate process operates as a GemFire client in this configuration, you must manually launch a GemFire cache server. You can do this with the following script (which should be installed into the bin subdirectory wherever GemFire is located):

In Unix: 
  prompt$ ./cacheserver.sh start
  
In Windows:
  prompt> cacheserver.bat start
Note: When running the cache server, make sure the Hibernate jar and the GemFire modules jar are in the classpath, along with any dependencies. You can use the CLASSPATH environment variable or you can set the -classpath <classpath> command line argument when launching the cache server.
Without making any further configuration changes, the client and server attempt to locate each other on the same system using a default port (40404). Though useful for testing purposes, you would not normally deploy a client/server configuration in this way. Refer to "Using GemFire Locators with a Client/Server Configuration" for information on creating and using Locators, which provide both discovery and load balancing services.

Changing Peer-to-Peer Region Attributes

You can change the region attributes from within the hibernate.cfg.xml file using the same region shortcuts specified in Region Shortcuts and Custom Named Region Attributes.
<property name="gemfire.default-region-attributes-id">
  REGION_ATTRIBUTE
</property> 

In this example, REGION_ATTRIBUTE can be any of the pre-defined region shortcuts. By default, this is REPLICATE_HEAP_LRU. Other available region shortcuts include: REPLICATE, REPLICATE_PERSISTENT, PARTITION, PARTITION_PERSISTENT, PARTITION_REDUNDANT, PARTITION_REDUNDANT_PERSISTENT. If you plan to configure a region for persistence, refer to Turning On Persistence.

You can also control the region type on a per-entity basis using the following code:

<property name="gemfire.region-attributes-for: com.foo.Bar">
  REGION_ATTRIBUTE
</property> 

In this example, com.foo.Bar is the name of your class and REGION_ATTRIBUTE can be one of the region shortcuts.

Using a Different Multicast Port with a Peer-to-Peer Configuration

For a GemFire peer-to-peer member to communicate on a different multicast port than the default (10334), use the mcast-port property.

<property name="gemfire.mcast-port">10445</property> 
This example uses port 10445 as the multicast port.

Using GemFire Locators with a Peer-to-Peer Configuration

By default, GemFire peers discover each other using multicast communication on a known port (as specified by the mcast-port property). Alternatively, you can configure member discovery using one or more dedicated locators. A locator provides both discovery and load balancing services.

To run GemFire with one or more locators instead of a multicast port, use the locators property.

<property name="gemfire.locators">host1[port1],host2[port2]</property> 

In this example, host1 and host2 are the hostnames (or IP addresses) for each of the locators; port1 and port2 are the ports for each of the locators.

Although this code will tell the peer to look for a locator, it does not automatically start the locator. To launch a locator automatically within the same application as the one running the Hibernate process, use this code, with your hostname (or IP address) and port settings:

<property name="gemfire.start-locator">host[port]</property> 

Alternatively, you can start a locator in a separate process using the gemfire command-line tool found in the bin subdirectory wherever GemFire is located.

In Unix:
  ./gemfire.sh start-locator -port=10334
  
In Windows:
  gemfire.bat start-locator -port=10334

This example starts a locator that listens on port 10334.

Changing Region Names

By default, the GemFire Hibernate module puts entities in a region whose name is the fully qualified path of the entity. The module uses these region names to eagerly prefetch related entities. Therefore, we recommend that you do not change the default names of the regions that are created by Hibernate.

Changing Client/Server Region Attributes

When using a client/server configuration, the default region attribute for the GemFire servers is a PARTITION region. This means that the data is partitioned across the pool of GemFire servers. You can modify this behavior using the same instructions specified in Changing Peer-to-Peer Region Attributes.

In addition to the region attribute of the servers, you can also modify the region attributes for the GemFire client, which is the process running Hibernate. By default this region is set to PROXY. This means that the client will not cache data.

You can change the client region attributes from within the hibernate.cfg.xml file using the same client region shortcuts specified in Region Shortcuts and Custom Named Region Attributes.

<property name="gemfire.default-client-region-attributes-id">
  CLIENT_REGION_ATTRIBUTE
</property> 

In this example, CLIENT_REGION_ATTRIBUTE can be any of the pre-defined region shortcuts. By default, this is PROXY. If you would like the client to keep a local cache of recently used data, change the region to CACHING_PROXY.

You can also control the client region type on a per-entity basis using the following code:

<property name="gemfire.client-region-attributes-for: com.foo.Bar">
  CLIENT_REGION_ATTRIBUTE
</property> 

In this example, com.foo.Bar is the name of your class and CLIENT_REGION_ATTRIBUTE can be one of the client region shortcuts.

Using GemFire Locators with a Client/Server Configuration

By default, GemFire clients and servers discover each other on a pre-defined port (40404) on the localhost. This is not typically the way you would deploy a client/server configuration. A preferred solution is to use one or more dedicated locators. A locator provides both discovery and load balancing services.

To run GemFire with one or more locators, use the locators property.

<property name="gemfire.locators">host1[port1],host2[port2]</property> 

In this example, host1 and host2 are the hostnames (or IP addresses) for each of the locators; port1 and port2 are the ports for each of the locators.

Although this code will tell the client to look for a locator, it does not automatically start the locator. You can start a locator using the gemfire command-line tool found in the bin subdirectory wherever GemFire is located.

In Unix:
  ./gemfire.sh start-locator -port=10334
  
In Windows:
  gemfire.bat start-locator -port=10334

This example starts a locator that listens on port 10334.

You also need to tell the GemFire server to use a locator when you launch the server. You can do this through a command-line argument when you start up the server with the script provided in the bin subdirectory wherever GemFire is located:

In Unix: 
  prompt$ ./cacheserver.sh start locators=hostname[port]
  
In Windows:
  prompt> cacheserver.bat start locators=hostname[port]

If you are running more than one locator, use a comma-separated list of locators. Refer to Running GemFire Server Processes for more information on using this script.

Note: When running the cache server, make sure the Hibernate jar and the GemFire modules jar are in the classpath, along with any dependencies. You can use the CLASSPATH environment variable or you can set the -classpath <classpath> command line argument when launching the cache server.

Turning On Persistence

If you change the region type to any one of the persistent modes (such as PARTITION_PERSISTENT and REPLICATE_PERSISTENT), cache data will get stored into the current working directory. To change this location, supply disk storage information in GemFire's cache.xml configuration file. For example:

<cache>
  <!-- define a disk store with a couple of directories. -->
  <!-- All data logs are stored here -->
 <disk-store name="CacheDataRepository">
  <disk-dirs>
    <disk-dir>c:\cache_data</disk-dir>
    <disk-dir dir-size="20480">d:\cache_data</disk-dir>
  </disk-dirs>
 </disk-store>

 <!-- now change the predefined region attributes to use this disk store --> 
 <region-attributes id="MYAPP_PARTITION_PERSISTENT" 
      ref-id="PARTITION_PERSISTENT">
   <disk-store>CacheDataRepository</disk-store>
 </region-attributes>
</cache> 

This example creates a 20480 MB data repository in the d:\cache_data subdirectory. It also defines a region attribute called MYAPP_PARTITION_PERSISTENT, which is derived from the PARTITION_PERSISTENT region definition.

You must also change Hibernate's hibernate.cfg.xml file to point to this xml file and to reference this particular region definition:

<property name="gemfire.default-region-attributes-id">  
  MYAPP_PARTITION_PERSISTENT
</property> 
<property name="gemfire.cache-xml-file">
  c:\gemfire_cache.xml
</property> 

Caching Query Results

In a Hibernate application, the caching of query results is recommended for queries that are run frequently with the same parameters. However, most applications using Hibernate do not benefit from query results caching because Hibernate will invalidate cached results when even a single entity involved in the query is updated. For example, suppose that a query on the Person entity is cached. As soon as any instance of Person is updated, created or deleted, Hibernate will invalidate this query because it cannot predict the impact of the change on the cached query results. Therefore, the GemFire Hibernate Cache Module does not distribute query results to other GemFire member caches. The query results are always cached only in the GemFire cache local to the Hibernate session.

Remapping the Hibernate EnumType with the GemFire EnumType

Due to an issue with Hibernate in a client-server topology, application classes must be present on the GemFire cache server when a Hibernate application uses annotations. If you do not want to place the application classes on the GemFire cache server, you can modify the Hibernate configuration to use the com.gemstone.gemfire.modules.hibernate.EnumType in place of org.hibernate.type.EnumType.

To configure Hibernate to use the GemFire EnumType, modify hibernate.cfg.xml to add a property for the mapping. For example:
<property name="myEnum">
    <type name="com.gemstone.gemfire.modules.hibernate.EnumType">
    <param name="enumClass">com.mycompany.MyEnum</param>
   </type>
</property>