Administration guide > Configure the deployment environment > Configuring cache integration

JPA cache configuration properties

WebSphere eXtreme Scale includes level 2 cache plug-ins for both OpenJPA and Hibernate Java™ Persistence API (JPA) providers.

You can configure the JPA cache plug-in with the following properties, all of which are optional.


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.


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.


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.


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.


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.


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 file and placing this file in the class path. For more information about evictors, see Evictionthe information about evictors in the Product Overview. For more information about the server properties file, see Server properties filethe Administration Guide.


Valid values: greater than or equal to 1 Specifies the maximum number of replicas to be use for the cache. This value only applies to the EMBEDDED type. This number should be equal to or greater than the number of Java virtual machines in a system. The default value is 47.

The NumberOfPartitions, ReplicaMode, ReplicaReadEnabled, and MaxNumberOfReplicas properties are ObjectGrid deployment factors. The NumberOfPartitions, ReplicaMode, and ReplicaReadEnabled apply to the EMBEDDED_PARTITION type. Both ReplicaMode and MaxNumberOfReplicas apply to the EMBEDDED type.


The embedded ObjectGrid types use the configuration properties previously described to configure and deploy a set of ObjectGrid container servers and a catalog service when necessary. The life cycle of the containers is bound to the JPA application and is collocated within the application class path. When an application is started, the plug-in automatically detects or starts a catalog service, starts a container, and connects to the catalog service. The plug-in then communicates with the ObjectGrid container and its peers that are running in other application server processes using the client connection.

Each JPA entity has an independent backing map assigned using the class name of the entity. Each BackingMap has the following attributes.

When you are using the EMBEDDED or EMBEDDED_PARTITION ObjectGridType value in a Java SE environment, use the System.exit(0) method at the end of the program to stop the embedded eXtreme Scale server. Otherwise, the program seems to become unresponsive.

ObjectGridType value defaults

The ObjectGridType value specifies the topology in which the ObjectGrid cache is deployed. The default and best performing type is EMBEDDED. The following sections describe the default properties for each of the ObjectGridType values.

EMBEDDED ObjectGrid JPA cache topology defaults

When you are using the EMBEDDED ObjectGrid type, the following default property values are used if you do not specify any values in the configuration:

You should specify a unique ObjectGridName value to avoid naming conflicts. The MaxNumberOfReplicas value should be equal to or greater than the total number of Java virtual machines in the system.

REMOTE ObjectGrid cache topology

The REMOTE ObjectGrid type does not require any property settings because the ObjectGrid and deployment policy is defined separately from the JPA application. The JPA cache plug-in remotely connects to an existing remote ObjectGrid.

Because all interaction with the ObjectGrid is remote, this topology has the slowest performance among all ObjectGrid types.

Catalog service considerations and configuration

When you are running in an EMBEDDED or EMBEDDED_PARTITION topology, the JPA cache plug-in automatically starts a single catalog service within one of the application processes if needed. In a production environment, you should create a catalog service domain. For more information about defining a catalog service, see High-availability catalog service.

If you are running inside a WebSphere Application Server process, the JPA cache plug-in automatically connects to the catalog service or catalog service domain that is defined for the WebSphere Application Server cell. For more information about defining a catalog service domain, see Start the catalog service in a stand-alone environment.

If you are not running the servers inside a WebSphere Application Server process, the catalog service domain hosts and ports are specified using properties file named This file must be stored in the class path of the application and have the catalogServiceEndPoints property defined. The catalog service grid is started independently from the application processes and must be started before the application processes are started.

The format of the file follows:


Parent topic:

Configure cache integration

Related tasks

Configure JPA loaders

Configure a JPA time-based data updater

Configure HTTP session managers

Configure the dynamic cache provider for WebSphere eXtreme Scale


Search Tips   |   Advanced Search