WebSphere eXtreme Scale Administration Guide > Configure WebSphere eXtreme Scale > Cache integration > JPA cache plug-in > JPA cache plug-in configuration

OpenJPA cache plug-in configuration

WebSphere eXtreme Scale provides both DataCache and QueryCache implementations for OpenJPA. The OpenJPA ObjectGrid cache or ObjectGrid cache in short, is a common term for both the DataCache and QueryCache implementations.

Sets

The eXtreme Scale cache is enabled or disabled for OpenJPA by setting the openjpa.DataCache and openjpa.QueryCache configuration properties in the persistence.xml file. The syntax for setting the property follows:

<property name="openjpa.DataCache"
          value="<object_grid_datacache_class(<property>=<value>,...)"/>
<property name="openjpa.QueryCache"
          value="<object_grid_querycache_class(<property>=<value>,...)"/>

Both DataCache and QueryCache can take eXtreme Scale cache properties to configure the cache used by the persistence unit.

In addition to the eXtreme Scale cache setting, the openjpa.RemoteCommitProvider property has to be set to sjvm:

<property name="openjpa.RemoteCommitProvider" value="sjvm"/>

The timeout value specified with @DataCache annotation for each entity class is carried down to the BackingMap to which each entity is cached. However, the name value specified with @DataCache annotation is ignored by the eXtreme Scale cache. The fully qualified entity class name is the cache map name.

The pin and unpin methods of OpenJPA StoreCache and QueryCache are not supported and perform no function.

You can specify the ObjectGridName property, the ObjectGridType property, and other simple deployment policy-related properties in the property list of the ObjectGrid cache class to customize cache configuration. An example follows:

<property name="openjpa.DataCache"
          value="com.ibm.websphere.objectgrid.openjpa.ObjectGridDataCache(
          ObjectGridName=BasicTestObjectGrid,ObjectGridType=EMBEDDED, 
          maxNumberOfReplicas=4)"/>
<property name="openjpa.QueryCache"
          value="com.ibm.websphere.objectgrid.openjpa.ObjectGridQueryCache()"/>
<property name="openjpa.RemoteCommitProvider" value="sjvm"/>

DataCache and QueryCache configurations are independent of one another. You can enable either configuration. However, if both configurations are enabled, the QueryCache configuration uses the same configuration as the DataCache configuration, and its configuration properties are discarded.

Customize OpenJPA cache configuration with XML

For most scenarios, setting eXtreme Scale cache properties should be sufficient.

To further customize the ObjectGrid used by the cache, you can provide OpenJPA ObjectGrid configuration XML files in the META-INF directory similarly to the persistence.xml file. During cache initialization, the ObjectGrid cache tries to locate these XML files and process the files if they are found.

There are three types of OpenJPA ObjectGrid configuration XML files: the openjpa-objectGrid.xml (ObjectGrid configuration), openjpa-objectGridDeployment.xml (deployment policy), and openjpa-objectGrid-client-override.xml (client ObjectGrid override configuration) files. Depending on the configured ObjectGrid type, you can provide any one of these three XML files to customize the ObjectGrid.

For both the EMBEDDED and EMBEDDED_PARTITION types, you can provide any one of the three XML files to customize the ObjectGrid, deployment policy, and client ObjectGrid override configuration.

For a REMOTE ObjectGrid, the ObjectGrid cache does not create a dynamic ObjectGrid. Instead, the cache only obtains a client-side ObjectGrid from the catalog service. You can only provide the openjpa-objectGrid-client-override.xml file to customize the client ObjectGrid override configuration.

1. ObjectGrid configuration: Use the META-INF/openjpa-objectGrid.xml file. This file is used to customize ObjectGrid configuration for both the EMBEDDED and EMBEDDED_PARTITION type. With the REMOTE type, this file is ignored. By default, each entity class is mapped to its own BackingMap configuration named as an entity class name within the ObjectGrid configuration. For example, com.mycompany.Employee entity class is mapped to com.mycompany.Employee BackingMap. The default BackingMap configuration is readOnly="false", copyKey="false", lockStrategy="NONE", and copyMode="NO_COPY". You can customize some BackingMaps with the chosen configuration. You can use the ALL_ENTITY_MAPS reserved keyword to represent all maps excluding other customized maps listed in the openjpa-objectGrid.xml file. BackingMaps that are not listed in this openjpa-objectGrid.xml file use the default configuration. If customized BackingMaps do not specify the BackingMaps attribute or properties and these attributes are specified in the default configuration, the attribute values from the default configuration are applied. For example, if an entity class is annotated with timeToLive=30, the default BackingMap configuration for that entity has a timeToLive=30. If the custom openjpa-objectGrid.xml file also includes that BackingMap but does not specify timeToLive value, then the customize BackingMap has a timeToLive=30 value by default. The openjpa-objectGrid.xml file intends to override or extend the default configuration.

2. ObjectGridDeployment configuration: Use the META-INF/openjpa-objectGridDeployment.xml file. This file is used to customize deployment policy. When you are customizing deployment policy, if the openjpa-objectGridDeployment.xml file is provided, the default deployment policy is discarded. All deployment policy attribute values are from the provided openjpa-objectGridDeployment.xml file.

3. Client override ObjectGrid configuration: Use the META-INF/openjpa-objectGrid-client-override.xml file. This file is used to customize a client-side ObjectGrid. By default, the ObjectGrid cache applies a default client override ObjectGrid configuration that disables a near cache. If an application requires a near cache, it can provide this file and specify numberOfBuckets="xxx". The default client override disables the near cache by setting numberOfBuckets="0". The near cache can be active when resetting numberOfBuckets to a value greater than 0 with the openjpa-objectGrid-client-override.xml file. The way that the openjpa-objectGrid-client-override.xml file works is similar to the openjpa-objectGrid.xml file. It overrides or extends the default client ObjectGrid override configuration.

OpenJPA ObjectGrid XML file examples

OpenJPA ObjectGrid XML files should be created based on the configuration of the persistence unit.

A persistence.xml file that is an example that represents the configuration of a persistence unit follows:

persistence.xml

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  version="1.0">
 
<persistence-unit name="AnnuityGrid">
   
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.FixedAnnuity</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.EquityAnnuity</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Person</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityHolder</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact</class>
   
<class>com.ibm.wssvt.acme.annuity.common.bean.jpa.Address</class>
   
<exclude-unlisted-classes>true</exclude-unlisted-classes>

   
<properties>
   
<!-- Database setting -->


   
<!--  enable cache -->
     
<property name="openjpa.DataCache"
        value="com.ibm.websphere.objectgrid.openjpa.ObjectGridDataCache(objectGridName=Annuity,
              objectGridType=EMBEDDED, maxNumberOfReplicas=4)" />
     
<property name="openjpa.RemoteCommitProvider" value="sjvm" />
     
<property name="openjpa.QueryCache" 
                value="com.ibm.websphere.objectgrid.openjpa.ObjectGridQueryCache()" />
   
</properties>
 
</persistence-unit>
</persistence>

The openjpa-objectGrid.xml file that matches the persistence.xml file follows:

openjpa-objectGrid.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
  xmlns="http://ibm.com/ws/objectgrid/config">
 
<objectGrids>
   
<objectGrid name="Annuity">
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity" />
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address" />
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor" />
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person" />
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact" />
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject" 
                  readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject" />
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider" />
     
<backingMap name="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout" readOnly="false" copyKey="false"
                  lockStrategy="NONE" copyMode="NO_COPY" evictionTriggers="MEMORY_USAGE_THRESHOLD"
                  pluginCollectionRef="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout" />
     
<backingMap name="ObjectGridQueryCache" readOnly="false" copyKey="false"  
                  lockStrategy="NONE" copyMode="NO_COPY" pluginCollectionRef="ObjectGridQueryCache" 
                  evictionTriggers="MEMORY_USAGE_THRESHOLD"  />
   
</objectGrid>
 
</objectGrids>
 
<backingMapPluginCollections>
   
<backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection 
            id="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection id="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout">
     
<bean id="ObjectTransformer" 
            className="com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer" />
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
   
<backingMapPluginCollection id="ObjectGridQueryCache">
     
<bean id="MapIndexPlugin" className="com.ibm.websphere.objectgrid.plugins.index.HashIndex" >
         
<property name="Name" type="java.lang.String" 
                    value="QueryCacheKeyIndex" description="name of index"/>
         
<property name="POJOKeyIndex" type="boolean" value="true" description="POJO Key Index "/>
     
</bean>
     
<bean id="Evictor" className="com.ibm.websphere.objectgrid.plugins.builtins.LRUEvictor" >
     
</bean>
   
</backingMapPluginCollection>
 
</backingMapPluginCollections>
</objectGridConfig>

1. Each entity is mapped to a BackingMap named as the fully qualified entity class name.

   By default, entities are part of the second level cache. In the Entity classes to be exclude from caching, you can include the @DataCache(enabled=false) annotation on the entity class that to exclude from L2 cache:

   import org.apache.openjpa.persistence.DataCache;
   @Entity
   @DataCache(enabled=false)
   public class OpenJPACacheTest { ... }
   

2. If entity classes are in an inheritance hierarchy, child classes map to the parent BackingMap. The inheritance hierarchy shares a single BackingMap.

3. The ObjectGridQueryCache map is required to support QueryCache.

4. The backingMapPluginCollection for each entity map must have the ObjectTransformer using the com.ibm.ws.objectgrid.openjpa.ObjectGridPCDataObjectTransformer class.

5. The backingMapPluginCollection for ObjectGridQueryCache map must have the key index named as QueryCacheKeyIndex as shown in the sample.

6. The evictor is optional for each map.

The openjpa-objectGridDeployment.xml file that matches the persistence.xml file follows:

openjpa-objectGridDeployment.xml

<?xml version="1.0" encoding="UTF-8" ?>
<deploymentPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://ibm.com/ws/objectgrid/deploymentPolicy ../deploymentPolicy.xsd"
  xmlns="http://ibm.com/ws/objectgrid/deploymentPolicy">
 
<objectgridDeployment objectgridName="Annuity">
   
<mapSet name="MAPSET_Annuity" numberOfPartitions="1" numInitialContainers="1" 
            minSyncReplicas="0" maxSyncReplicas="4" maxAsyncReplicas="0" 
            replicaReadEnabled="true">
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Annuity" />
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Address" />
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payor" />
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Person" />
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Contact" />
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.AnnuityPersistebleObject" />
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Rider" />
     
<map ref="com.ibm.wssvt.acme.annuity.common.bean.jpa.Payout" />
     
<map ref="ObjectGridQueryCache" />
   
</mapSet>
 
</objectgridDeployment>
</deploymentPolicy>

The ObjectGridQueryCache map is required to support QueryCache.

External system for a cache with REMOTE ObjectGrid type

You must set up an external system if to configure an cache with REMOTE ObjectGrid type. You need both ObjectGrid and ObjectGridDeployment configuration XML files that are based on a persistence.xml file to set up an external system. The OpenJPA ObjectGrid and ObjectGridDeployment configuration XML files described in the OpenJPA ObjectGrid XML file examples section can also be used to set up an external eXtreme Scale system.

An external eXtreme Scale system has both catalog service and container server processes. You must start the catalog server before starting container servers.

Troubleshoot

1. CacheException: Failed to get ObjectGrid server

   With either an EMBEDDED or EMBEDDED_PARTITION ObjectGridType, the eXtreme Scale cache tries to obtain a server instance from the run time. In a Java™ Platform, Standard Edition environment, an eXtreme Scale server with embedded catalog service is started. The embedded catalog service tries to listen to port 2809; if that port is being used by another process, the error occurs. If external catalog service endpoints are specified, for example, with the objectGridServer.properties file, this error occurs if the host name or port is specified incorrectly.

2. CacheException: Failed to get REMOTE ObjectGrid for configured REMOTE ObjectGrid. objectGridName = [ObjectGridName], PU name = [persistenceUnitName]

   This error occurs when the cache fails to obtain an ObjectGrid from the provided catalog service endpoints. Typically, the error is because of an incorrect host name or port.

3. CacheException: Cannot have two PUs [persistenceUnitName_1, persistenceUnitName_2] configured with same ObjectGridName [ObjectGridName] of EMBEDDED ObjectGridType

   This exception results if you have a many persistence unit configuration and the eXtreme Scale caches of these units are configured with the same ObjectGrid name and EMBEDDED ObjectGridType. These persistence unit configurations could be in the same or different persistence.xml files. You must verify that the ObjectGrid name is unique for each persistence unit when ObjectGridType is EMBEDDED.

4. CacheException: REMOTE ObjectGrid [ObjectGridName] does not include required BackingMaps [mapName_1, mapName_2,...]

   With a REMOTE ObjectGrid type, if the obtained client-side ObjectGrid does not have complete entity BackingMaps to support the persistence unit cache, this exception occurs. For example, five entity classes are listed in the persistence unit configuration, but the obtained ObjectGrid only has two BackingMaps. Even though the obtained ObjectGrid might have ten BackingMaps, if any one of the five required entity BackingMaps is not found in the ten BackingMaps, this exception still occurs.

The OpenJPA eXtreme Scale cache has changed data format to improve performance. Any systems that are hosting OpenJPA applications that are configured with eXtreme Scale as an L2 cache must be stopped before migrating to WebSphere eXtreme Scale v7.0.

Parent topic

JPA cache plug-in configuration

+

Search Tips   |   Advanced Search