Configuring the OpenJPA cache plug-in

You can configure both DataCache and QueryCache implementations for OpenJPA.

1. Set properties in your persistence.xml file to configure the OpenJPA cache plug-in:
   You can set these properties on either the DataCache or Query cache implementation.

   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.

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

   or

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

   Note: You can enable the QueryCache configuration for embedded and embedded-intradomain topologies only.
   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"/>

   See JPA cache configuration properties for Hibernate Version 4.0 for a list of the properties that you can set.
2. In the persistence.xml file, you also must set the openjpa.RemoteCommitProvider property to sjvm.

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

3. Optional: To further customize the data grid used by the cache, you can provide additional settings with XML files.

   For most scenarios, setting 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 initialization, the cache tries to locate these XML files and process them if found.

   There are three types of OpenJPA ObjectGrid configuration XML files:

   • openjpa-objectGrid.xml (ObjectGrid configuration)

     File path: META-INF/openjpa-objectGrid.xml

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

   • openjpa-objectGridDeployment.xml (deployment policy)

     File path: META-INF/openjpa-objectGridDeployment.xml

     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.

   • openjpa-objectGrid-client-override.xml (client ObjectGrid override configuration)

     File path: META-INF/openjpa-objectGrid-client-override.xml

     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. You can enable the near cache by providing the openjpa-objectGrid-client-override.xml file that overrides this configuration. For more information about the settings to change in this file to enable near cache, see Configuring the near cache. 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.

   Depending on the configured eXtreme Scale topology, you can provide any one of these three XML files to customize that topology.

   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.

4. Optional: (Remote configurations only) Set up an external eXtreme Scale system if you want to configure a cache with a REMOTE ObjectGrid type.

   You must set up an external eXtreme Scale system if you want to configure a cache with a REMOTE ObjectGrid type. You need both ObjectGrid and ObjectGridDeployment configuration XML files that are based on the persistence.xml file to set up an external system. For examples of these configuration files, see Example: OpenJPA ObjectGrid XML files.