JPA cache configuration properties for both OpenJPA and Hibernate Version 3.0

WebSphere® eXtreme Scale includes level 2 cache plug-ins for both OpenJPA and Hibernate Java™ Persistence API (JPA) providers. 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.

Properties location

You can configure these properties in the persistence.xml file. The syntax for specifying the properties in this file varies depending if you are using OpenJPA or Hibernate Version 3.0:

Default topology and properties

The following default property values are used if you do not specify any values in the configuration:

Properties

You can configure JPA cache plug-ins with the following properties.

ObjectGridName
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.
ObjectGridType
Specifies the type of ObjectGrid.

Valid values:

EMBEDDED
The default and recommended configuration type. Its default settings include: NumberOfPartitions=1, ReplicaMode=SYNC, ReplicaReadEnabled=true and MaxNumberOfReplicas=47. Use the ReplicaMode parameter to set the replication mode and the MaxNumberOfReplicas parameter to set the maximum number of replicas. If a system has more than 47 Java virtual machines, set the MaxNumberOfReplicas 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 system that has only a few Java virtual machines, set the NumberOfPartitions value to be equal or less than the number of Java virtual machines. You can specify the ReplicaMode, NumberOfPartitions, and ReplicaReadEnabled values to tune the system.
REMOTE
The cache tries to connect to a remote, distributed ObjectGrid from the catalog service.
MaxNumberOfReplicas
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 a system. The default value is 47.

Valid values: greater than or equal to 1

MaxUsedMemory

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.
NumberOfPartitions

Valid values: greater than or equal to 1

Specifies the number of partitions to be used for the cache. This property applies when the ObjectGridType value is set to EMBEDDED_PARTITION. The default value is 47. For the EMBEDDED type, the NumberOfPartitions value is always 1.
PlacementScope
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.
PlacementScopeTopology
Defines the linking topology of the container servers within the catalog service domain. This value is only used when the PlacementScope 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.
ReplicaMode

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 ObjectGridType 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 ReplicaMode value is set to NONE for the EMBEDDED ObjectGridType, the EMBEDDED type still uses a ReplicaMode of SYNC.
ReplicaReadEnabled

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 ReplicaReadEnabled value to TRUE.
writeBehind

For Hibernate providers only: When writeBehind is enabled, updates are temporarily stored in a JVM scope data storage until either the writeBehindInterval or writeBehindMaxBatchSize conditions are met.

Attention: Unless writeBehind is enabled, the other write behind configuration settings are disregarded.
Important: Take care when using the 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

writeBehindInterval

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)

writeBehindPoolSize

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 to 1

Default value: 5

writeBehindMaxBatchSize

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 the specified writeBehindInterval condition is not met. Updates flush to the cache either approximately at the number of seconds specified by the writeBehindInterval value or whenever the size of write behind storage of each region cache exceeds 1000 entries. Note, in the case of the writeBehindMaxBatchSize condition 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