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.
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.
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 your 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.
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>
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>
You must set up an external system if you want 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.
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.
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.
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.
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.