JPA cache configuration properties for Hibernate Version 4.0

WebSphere® eXtreme Scale includes L2 cache plug-ins for Hibernate Version 4.0 Java™ Persistence API (JPA) provider. To configure the L2 cache plug-in, you must update properties in the persistence.xml file.

Tip: The JPA L2 cache plug-in requires an application that uses the JPA APIs. If you want to use WebSphere eXtreme Scale APIs to access a JPA data source, use the JPA loader. For more information, see Configuring JPA loaders.

Hibernate 4.0 properties location

You can configure these properties individually in the persistence.xml file.

<property name="wxs.<name_of_property>"
 value="<value>"/>

You can set the properties on the DataCache or QueryCache, for example:

<property name="wxs.objectgrid_name"
 value="BasicObjectGrid"/>

Properties

You can configure the Hibernate Version 4.0 JPA cache plug-in with the following properties. The default values are used if you do not specify a value in the configuration.

wxs.objectgrid_name

Specifies the unique ObjectGrid name. The default value is the defined persistence unit name. If the persistence unit name is not available from the JPA provider, a generated name is used.

wxs.objectgrid_type

Specifies the type of ObjectGrid.

Valid values:

EMBEDDED: The default and recommended configuration type. Its default settings include: wxs.number_of_partitions=1, wxs.replica_mode=SYNC, wxs.replica_read_enabled=true and wxs.max_number_of_replicas=47. Use the wxs.replica_mode parameter to set the replication mode and the wxs.max_number_of_replicas parameter to set the maximum number of replicas. If a system has more than 47 Java virtual machines, set the wxs.max_number_of_replicas value to be equal to the number of Java virtual machines.
EMBEDDED_PARTITION: The type to use when the system needs to cache a large amount of data in a distributed system. The default number of partitions is 47, with a replica mode of NONE. In a small environment that has only a few Java virtual machines, set the wxs.number_of_partitions value to be equal to or less than the number of Java virtual machines. You can specify the wxs.replica_mode, wxs.number_of_partitions and wxs.replica_read_enabled values to tune the system.
REMOTE: The cache tries to connect to a remote, distributed ObjectGrid from the catalog service.

wxs.max_number_of_replicas

Specifies the maximum number of replicas to be used for the cache. This value applies to the EMBEDDED type only. This number must be equal to or greater than the number of Java virtual machines in your environment. The default value is 47.

Valid values: Greater than or equal to 1

wxs.max_used_memory

Valid values: TRUE or FALSE

Enables eviction of cache entries when memory becomes constrained. The default value is TRUE and evicts data when the JVM heap utilization threshold exceeds 70 percent. You can modify the default JVM heap utilization threshold percentage by setting the memoryThresholdPercentage property in the objectGridServer.properties file and placing this file in the class path. For more information about evictors, see Plug-ins for evicting cache objectsthe information about evictors in the Product Overview. For more information about the server properties file, see Server properties file.

wxs.number_of_partitions

Valid values: Greater than or equal to 1

Specifies the number of partitions to be used for the cache. This property applies when the wxs.objectgrid_type value is set to EMBEDDED_PARTITION. The default value is 47. For the EMBEDDED type, the wxs.number_of_partitions value is always 1.

wxs.placement_scope

Indicates the granularity of a single instance of a map set.

Valid values:

DOMAIN_SCOPE: (Default) Places one primary shard for each partition on a container server within the catalog service domain. Replica shards for each partition are placed on the other container servers within the catalog service domain.
CONTAINER_SCOPE: Places a primary shard on each container server in the catalog service domain.

wxs.placement_scope_topology

Defines the linking topology of the container servers within the catalog service domain. This value is only used when the wxs.placement_scope value is set to something other than DOMAIN_SCOPE.

Valid values:

HUB: (Default) If the hub topology is selected, then a single data grid is selected to be the hub. Every other data grid connects to the hub. This topology is fairly scalable because the spokes have a single connection. The hub can become a bottleneck and temporary single point of failure. The hub is relocated to another container server when it fails. The advantage to this configuration is more complex arbitration code can be written that allows a single point, the hub, to handle all collisions.
RING: If the ring topology is selected, each data grid is linked with two other data grids. The ordering of the links is not guaranteed. However, each container that starts is likely linked to the first container and last container to be added to the ring. This topology is the most scalable, but only two links can fail before being temporarily cut off. If the container servers fail, links are established among the survivors after the failure has been discovered.

wxs.replica_mode

Valid values: SYNC/ASYNC/NONE

Specifies the method that is used to copy the cache to the replicas. This property applies when you have the wxs.objectgrid_type value set to EMBEDDED or EMBEDDED_PARTITION. The default value is NONE for the EMBEDDED_PARTITION type and SYNC for the EMBEDDED type. If the wxs.replica_mode value is set to NONE for the EMBEDDED wxs.objectgrid_type, the EMBEDDED type still uses a wxs.replica_mode of SYNC.

wxs.replica_read_enabled

Valid values: TRUE or FALSE

When enabled, clients read from replicas. This property applies to the EMBEDDED_PARTITION type. The default value is FALSE for the EMBEDDED_PARTITION type. The EMBEDDED type always sets the wxs.replica_read_enabled value to TRUE.

wxs.write_behind

For Hibernate providers only: When wxs.write_behind is enabled, updates are temporarily stored in a JVM-scoped data storage until either the wxs.write_behind_interval or wxs.write_behind_max_batch_size conditions are met.

Attention: Unless wxs.write_behind is enabled, the other write-behind configuration settings are disregarded.

Important: Take care when using the wxs.write_behind function. Write-behind configurations introduce longer latency of data synchronization across all JVMs and a higher chance of lost updates. In a system that has write-behind configuration enabled with four or more JVMs, the update performed on one JVM has an approximate 15-second delay before the update becomes available to other JVMs. If any two JVMs update the same entry, the one that flushes the update first loses its update.

Valid values: TRUE or FALSE

Default value: FALSE

wxs.write_behind_interval

For Hibernate providers only: Specifies the time interval in milliseconds to flush updates to the cache.

Valid values: Greater than or equal to 1

Default value: 5000 (5 seconds)

wxs.write_behind_pool_size

For Hibernate providers only: Specifies the maximum size of the thread pool used in flushing updates to the cache.

Valid values: Greater than or equal to1

Default value: 5

wxs.write_behind_max_batch_size

For Hibernate providers only: Specifies the maximum batch size per region cache in flushing updates to the cache. For example, if the size is set to 1000, and the updates stored in the write-behind storage of a region cache exceeds 1000 entries, the updates are flushed to the cache, even if the specified wxs.write_behind_interval condition is not met. Updates flush to the cache either approximately at the number of seconds specified by the wxs.write_behind_interval value or whenever the size of write behind storage of each region cache exceeds 1000 entries. Note, in the case of the wxs.write_behind_max_batch_size condition being met; only the region cache that meets this condition flushes its updates in write-behind storage to cache. A region cache usually corresponds to an entity or a query.

Valid values: Greater than or equal to 1

Default value: 1000