com.ibm.websphere.objectgrid.openjpa
Class ObjectGridDataCache

java.lang.Object
  org.apache.openjpa.lib.util.concurrent.AbstractConcurrentEventManager
      org.apache.openjpa.datacache.AbstractDataCache
          com.ibm.websphere.objectgrid.openjpa.ObjectGridDataCache

All Implemented Interfaces:

Serializable, DataCache, RemoteCommitListener, Configurable, Closeable, EventManager

public class ObjectGridDataCache
extends AbstractDataCache
implements RemoteCommitListener

A DataCache implementation is a DataCache plugin to integrate Open JPA with ObjectGrid for leveraging the cluster server advantages provided by ObjectGrid.

ObjectGrid cache is enabled / disable for OpenJPA by setting the openjpa.DataCache and openjpa.QueryCache configuration properties in persistence.xml. The syntax for setting the property is as the following:

 <property
   name="openjpa.DataCache"
   value="com.ibm.websphere.objectgrid.openjpa.ObjectGridDataCache(<property>=<value>,...)" />
 <property
   name="openjpa.QueryCache"
   value="com.ibm.websphere.objectgrid.openjpa.ObjectGridQueryCache(<property>=<value>,...)" />
 

If both DataCache and QueryCache are enabled, the QueryCache will use the same configuration as DataCache, so the QueryCache does not need to have any property.

The following ObjectGrid related properties can apply to both DataCache and QueryCache:

• ObjectGridName: the uniquely identified ObjectGrid name of the ObjectGrid to use.
• ObjectGridType: (EMBEDDED | EMBEDDED_PARTITION | REMOTE) the type of ObjectGrid.
  • EMBEDDED: This is the default ObjectGrid type. There will be only 1 partition with SYNC replica mode and the maximum number of replicas set to 47 by default. With the EMBEDDED type, users can specify the ReplicaMode and MaxNumberOfReplicas to determine the type of replication and the maximum number of replicas. The ReplicaReadEnabled will be always true. If a system has more than 47 JVMs, users should set the MaxNumberOfReplicas to be equal to the number of JVMs. This EMBEDDED mode has two limitations:
    • limited cache size: because there is only one partition so the cache size is limited to the heap size of the JVM. If the system need to cache 100GB, it should use EMBEDDED_PARTITION type.
    • All write operations will go to one JVM.
  • EMBEDDED_PARTITION: This type should be used when the system would like to cache large amount of data. It is default to have 47 partitions with NONE replica mode. In a small system that has only few JVMs, users should set the NumberOfPartitions to be the number of JVMs. Users can specify ReplicaMode, NumberOfPartitions, MaxNumberOfReplicas, and ReplicaReadEnabled to tune the system
  • REMOTE: With this REMOTE type, the cache simply try to obtain a distributed ObjectGrid from catalog service. Users should place objectGridServer.properties file in classpath. The objectGridServer.properties should have the catalogServiceEndPoints property. It is users' responsibility to setup the remote ObjectGrid system.
• NumberOfPartitions: (>=1) the number of partitions to be used for the cache. The default value is 47 for EMBEDDED-PARTITION. Only apply on EMBEDDED-PARTITION ObjectGrid type.
• ReplicaMode: (SYNC/ASYNC/NONE; not case sensitive) how cache is replicated to replica. The default value is NONE. Only apply on EMBEDDED and EMBEDDED-PARTITION ObjectGrid type.
• ReplicaReadEnabled: (TRUE/FALSE; not case sensitive) to enable reading data from replica or not. The default value is FALSE. Only apply on EMBEDDED_PARTITION ObjectGrid type.
• MaxUsedMemory: (TRUE/FALSE; not case sensitive) to enable memory-based evictors on maps. The default value is TRUE.
• MaxNumberOfReplicas: (>=1) the maximum number of replicas to be used for the cache. For EMBEDDED ObjectGrid type, this number should be equal or greater than the number of JVMs in a system.
• PlacementScope: (DOMAIN_SCOPE/CONTAINER_SCOPE)
  DOMAIN_SCOPE: This is the default placement scope. It will result in a single primary shard for each partition in the grid being placed in the replication domain. When using a single partition topology, all writes will go to the container hosting this shard. CONTAINER_SCOPE: This placement scope will result in a primary shard for every partition being placed in every container. This should only be used when a single partition is configured and the ObjectGrid type is EMBEDDED. This will result in each container having a local primary shard that it can write to without making a remote call. The writes performed in different containers will be reconciled via intra-domain replication. The number of replicas will be automatically set to zero if this scope is selected as the redundant primary shards implicitly act as replicas.
• PlacementScopeTopology: (HUB/RING) determines the connection scheme between containers when CONTAINER_SCOPE placement is used. HUB corresponds to a hub/spoke model and RING corresponds to a standard ring topology.

The following is a configuration example of JPA persistence.xml file.

 <property
   name="openjpa.DataCache"
   value="com.ibm.websphere.objectgrid.openjpa.ObjectGridDataCache(objectGridName=MyObjectGridName, objectGridType=EMBEDDED, MaxNumberOfReplicas=47)" />
 <property
   name="openjpa.ObjectGridQueryCache"
   value="com.ibm.websphere.objectgrid.openjpa.ObjectGridQueryCache()" />
 <property name="openjpa.RemoteCommitProvider" value="sjvm" />
 

Since:

WAS XD 6.1.0.3

See Also:

Serialized Form

Field Summary

Fields inherited from class org.apache.openjpa.datacache.AbstractDataCache

conf, log

Fields inherited from class org.apache.openjpa.lib.util.concurrent.AbstractConcurrentEventManager

_listeners

Fields inherited from interface org.apache.openjpa.datacache.DataCache

NAME_DEFAULT

Constructor Summary

ObjectGridDataCache()

Method Summary

protected void	clearInternal() Clear all maps for a PU.
void	close() Close this data cache
void	commit(Collection additions, Collection newUpdates, Collection existingUpdates, Collection deletes) Commits a transaction
Map	getAll(List keys) Returns a list of objects associated with the given keys
protected DataCachePCData	getInternal(Object key) Returns an object for a given key
String	getMaxNumberOfReplicas() Returns the maximum number of replicas for the EMBEDDED or EMBEDDED_PARTITION ObjectGrid type
String	getMaxUsedMemory() Returns setting of whether memory based eviction is enabled
String	getNumberOfPartitions() Returns the number of partitions used in the cache
String	getObjectGridName() Returns the name of the ObjectGrid that handel the cache
String	getObjectGridType() Returns the ObjectGrid type.
String	getPlacementScope() Retrieve the scope used for partition placement.
String	getPlacementScopeTopology() Retrieve the link topology used to perform intradomain replication.
String	getReplicaMode() Returns the replica mode
String	getReplicaReadEnabled() Returns setting of whether reading from the replica is enabled
void	initialize(DataCacheManager mgr) Initialize this data cache
protected boolean	pinInternal(Object key) This is not applicable to ObjectGrid
protected void	putAllInternal(Collection pcs) Caches a collection of cache objects
protected DataCachePCData	putInternal(Object key, DataCachePCData pc) Caches an object by a given key
protected boolean	recacheUpdates() Return true because ObjectGrid is a external cache and updates to data already in the cache (either in commit(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection) or the AbstractDataCache.update(org.apache.openjpa.datacache.DataCachePCData)) should be put back into the cache.
DataCachePCData	remove(Object key) Removes a cache object by a given key.
protected void	removeAllInternal(Class cls, boolean subs) Clear the map corresponding to the entity class
protected void	removeAllInternal(Collection keys) Deletes a collection of objects from the cache.
protected DataCachePCData	removeInternal(Object key) Deletes a cached object by a given key.
void	setMaxNumberOfReplicas(String numberOfReplicas) Sets the maximum number of replicas for the EMBEDDED or EMBEDDED_PARTITION ObjectGrid type
void	setMaxUsedMemory(String maxUsedMemory) Sets whether memory based eviction is enabled
void	setNumberOfPartitions(String number) Sets the number of partitions to be used in the cache
void	setObjectGridName(String name) Sets the name of the ObjectGrid that handles the cache
void	setObjectGridType(String objectGridType) Sets the ObjectGrid type.
void	setPlacementScope(String scope) Set the scope used for partition placement.
void	setPlacementScopeTopology(String scopeTopology) Set the link topology used to perform intradomain replication.
void	setReplicaMode(String mode) Sets the replica mode
void	setReplicaReadEnabled(String read) Sets whether reading from replica is enabled
void	unpinAll(Class cls, boolean subs) This is not applicable to ObjectGrid
protected boolean	unpinInternal(Object key) This is not applicable to ObjectGrid
void	writeLock() Acquires write lock
void	writeUnlock() Releases writeLock, paired with writeLock() for update synchronization

Methods inherited from class org.apache.openjpa.datacache.AbstractDataCache

addExpirationListener, afterCommit, clear, close, contains, containsAll, endConfiguration, fireEvent, get, getEvictionSchedule, getName, isClosed, keyRemoved, pin, pinAll, pinAll, put, removeAll, removeAll, removeAllTypeNamesInternal, removeExpirationListener, setConfiguration, setEvictionSchedule, setName, startConfiguration, toString, unpin, unpinAll, update

Methods inherited from class org.apache.openjpa.lib.util.concurrent.AbstractConcurrentEventManager

addListener, fireEvent, getListeners, hasListener, hasListeners, isFailFast, newListenerCollection, removeListener, setFailFast

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.openjpa.event.RemoteCommitListener

afterCommit

Constructor Detail

ObjectGridDataCache

public ObjectGridDataCache()

Method Detail

initialize

public void initialize(DataCacheManager mgr)

Initialize this data cache

Specified by:

initialize in interface DataCache

Overrides:

initialize in class AbstractDataCache

See Also:

DataCache.initialize(org.apache.openjpa.datacache.DataCacheManager)

unpinAll

public void unpinAll(Class cls,
                     boolean subs)

This is not applicable to ObjectGrid

Specified by:

unpinAll in interface DataCache

Overrides:

unpinAll in class AbstractDataCache

See Also:

AbstractDataCache.unpinAll(java.lang.Class, boolean)

writeLock

public void writeLock()

Acquires write lock

writeLock is for synchroning the update on the cache. Before any update to the cache, writeLock should be obtained and held until commit is done. After each commit, writeLock should be released (by calling writeUnlock()) for others to update the cache.

Specified by:

writeLock in interface DataCache

See Also:

DataCache.writeLock()

writeUnlock

public void writeUnlock()

Releases writeLock, paired with writeLock() for update synchronization

Specified by:

writeUnlock in interface DataCache

See Also:

DataCache.writeUnlock()

getInternal

protected DataCachePCData getInternal(Object key)

Returns an object for a given key

Specified by:

getInternal in class AbstractDataCache

See Also:

AbstractDataCache.getInternal(java.lang.Object)

putInternal

protected DataCachePCData putInternal(Object key,
                                      DataCachePCData pc)

Caches an object by a given key

Specified by:

putInternal in class AbstractDataCache

See Also:

AbstractDataCache.putInternal(java.lang.Object, org.apache.openjpa.datacache.DataCachePCData)

putAllInternal

protected void putAllInternal(Collection pcs)

Caches a collection of cache objects

Overrides:

putAllInternal in class AbstractDataCache

See Also:

AbstractDataCache.putAllInternal(java.util.Collection)

remove

public DataCachePCData remove(Object key)

Removes a cache object by a given key.

Specified by:

remove in interface DataCache

Overrides:

remove in class AbstractDataCache

See Also:

AbstractDataCache.remove(java.lang.Object)

removeInternal

protected DataCachePCData removeInternal(Object key)

Deletes a cached object by a given key.

Specified by:

removeInternal in class AbstractDataCache

See Also:

AbstractDataCache.removeInternal(java.lang.Object)

removeAllInternal

protected void removeAllInternal(Class cls,
                                 boolean subs)

Clear the map corresponding to the entity class

Specified by:

removeAllInternal in class AbstractDataCache

See Also:

AbstractDataCache.removeAllInternal(java.lang.Class, boolean)

removeAllInternal

protected void removeAllInternal(Collection keys)

Deletes a collection of objects from the cache.

Overrides:

removeAllInternal in class AbstractDataCache

See Also:

AbstractDataCache.removeAllInternal(java.util.Collection)

clearInternal

protected void clearInternal()

Clear all maps for a PU.

Specified by:

clearInternal in class AbstractDataCache

See Also:

AbstractDataCache.clearInternal()

pinInternal

protected boolean pinInternal(Object key)

This is not applicable to ObjectGrid

Specified by:

pinInternal in class AbstractDataCache

See Also:

AbstractDataCache.pinInternal(java.lang.Object)

unpinInternal

protected boolean unpinInternal(Object key)

This is not applicable to ObjectGrid

Specified by:

unpinInternal in class AbstractDataCache

See Also:

AbstractDataCache.unpinInternal(java.lang.Object)

setMaxUsedMemory

public void setMaxUsedMemory(String maxUsedMemory)

Sets whether memory based eviction is enabled

getMaxUsedMemory

public String getMaxUsedMemory()

Returns setting of whether memory based eviction is enabled

setObjectGridName

public void setObjectGridName(String name)

Sets the name of the ObjectGrid that handles the cache

getObjectGridName

public String getObjectGridName()

Returns the name of the ObjectGrid that handel the cache

setObjectGridType

public void setObjectGridType(String objectGridType)

Sets the ObjectGrid type. Valid values includ EMBEDDED, EMBEDDED_PARTITION, and REMOTE

getObjectGridType

public String getObjectGridType()

Returns the ObjectGrid type.

setNumberOfPartitions

public void setNumberOfPartitions(String number)

Sets the number of partitions to be used in the cache

getNumberOfPartitions

public String getNumberOfPartitions()

Returns the number of partitions used in the cache

setReplicaMode

public void setReplicaMode(String mode)

Sets the replica mode

getReplicaMode

public String getReplicaMode()

Returns the replica mode

setReplicaReadEnabled

public void setReplicaReadEnabled(String read)

Sets whether reading from replica is enabled

getReplicaReadEnabled

public String getReplicaReadEnabled()

Returns setting of whether reading from the replica is enabled

getMaxNumberOfReplicas

public String getMaxNumberOfReplicas()

Returns the maximum number of replicas for the EMBEDDED or EMBEDDED_PARTITION ObjectGrid type

setMaxNumberOfReplicas

public void setMaxNumberOfReplicas(String numberOfReplicas)

Sets the maximum number of replicas for the EMBEDDED or EMBEDDED_PARTITION ObjectGrid type

getPlacementScope

public String getPlacementScope()

Retrieve the scope used for partition placement. Either DOMAIN_SCOPE or CONTAINER_SCOPE. DOMAIN_SCOPE corresponds to default partition placement behavior in which one primary shard will exist for each partition, within the scope of the entire domain. CONTAINER_SCOPE corresponds to intra-domain replication behavior in which each one primary shard will exist for each partition within the scope of each container.

Returns:

the placement scope for the grid

Since:

7.1.1

setPlacementScope

public void setPlacementScope(String scope)

Set the scope used for partition placement. Either DOMAIN_SCOPE or CONTAINER_SCOPE. Retrieve the scope used for partition placement. Either DOMAIN_SCOPE or CONTAINER_SCOPE. DOMAIN_SCOPE corresponds to default partition placement behavior in which one primary shard will exist for each partition, within the scope of the entire domain. CONTAINER_SCOPE corresponds to intradomain replication behavior in which each one primary shard will exist for each partition within the scope of each container.

Parameters:

scope - the placement scope for the grid

Since:

7.1.1

getPlacementScopeTopology

public String getPlacementScopeTopology()

Retrieve the link topology used to perform intradomain replication. Supported values are RING and HUB.

Returns:

the link topology

Since:

7.1.1

setPlacementScopeTopology

public void setPlacementScopeTopology(String scopeTopology)

Set the link topology used to perform intradomain replication. Supported values are RING and HUB.

Parameters:

scopeTopology - the link topology

Since:

7.1.1

commit

public void commit(Collection additions,
                   Collection newUpdates,
                   Collection existingUpdates,
                   Collection deletes)

Commits a transaction

Specified by:

commit in interface DataCache

Overrides:

commit in class AbstractDataCache

See Also:

AbstractDataCache.commit(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection)

getAll

public Map getAll(List keys)

Returns a list of objects associated with the given keys

Specified by:

getAll in interface DataCache

Overrides:

getAll in class AbstractDataCache

Parameters:

keys - the keys of the entries to retrieve.

Returns:

a list of PCData

See Also:

AbstractDataCache.getAll(java.util.List)

close

public void close()

Close this data cache

Specified by:

close in interface DataCache

Specified by:

close in interface RemoteCommitListener

Specified by:

close in interface Closeable

Overrides:

close in class AbstractDataCache

See Also:

AbstractDataCache.close()

recacheUpdates

protected boolean recacheUpdates()

Return true because ObjectGrid is a external cache and updates to data already in the cache (either in commit(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection) or the AbstractDataCache.update(org.apache.openjpa.datacache.DataCachePCData)) should be put back into the cache.

Overrides:

recacheUpdates in class AbstractDataCache

See Also:

AbstractDataCache.recacheUpdates()