WebSphere® eXtreme Scale includes
level 2 cache plug-ins for both OpenJPA and Hibernate Java™ Persistence
API (JPA) providers. To configure
the L2 cache plug-in, you must update properties in the persistence.xml file.
Tip: The JPA L2 cache plug-in
requires an application
that uses the JPA APIs. If you want to use
WebSphere eXtreme Scale APIs to access
a JPA data source, use the JPA loader. For more information, see
Configuring JPA loaders.
Properties
location
You can configure these
properties in the
persistence.xml file. The syntax
for specifying the properties in this file varies depending if you
are using OpenJPA or Hibernate Version 3.0:
- OpenJPA: You can set the properties on the DataCache or
QueryCache:
<property name="openjpa.DataCache"
value="<object_grid_datacache_class(<property>=<value>,...)"/>
or<property name="openjpa.QueryCache"
value="<object_grid_querycache_class(<property>=<value>,...)"/>
- Hibernate Version 3.0:
<property name="objectgrid.configuration"
value="<property>=<value>,..." />
Default topology and
properties
The following
default property values are used if you do not specify any values
in the configuration:
- ObjectGridName: persistence
unit name
- ObjectGridType: EMBEDDED
- NumberOfPartitions: 1 (cannot
be
changed when ObjectGrid type is EMBEDDED)
- ReplicaMode: SYNC
- ReplicaReadEnabled: TRUE (cannot
be changed when ObjectGrid type is EMBEDDED)
- MaxUsedMemory: TRUE
- MaxNumberOfReplicas: 47 (must be
less than or equal to the number of Java virtual machines in a distributed system)
Properties
You can configure
JPA cache plug-ins
with the following properties.
- ObjectGridName
- 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.
- ObjectGridType
- 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.
- MaxNumberOfReplicas
- Specifies the maximum number of replicas
to be used for the cache.
This value applies to the EMBEDDED type only.
This number must be equal to or greater than the number of Java virtual machines in a system. The default
value is 47.
Valid values: greater
than or equal to 1
- MaxUsedMemory
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 objectGridServer.properties file
and placing this file in the class path. For more information about
evictors, see Plug-ins for evicting cache objectsthe information
about evictors in the Product Overview.
For more information about the server properties file, see Server properties file.
- NumberOfPartitions
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.
- PlacementScope
- Indicates the granularity of a single instance of a map set.
Valid
values:- DOMAIN_SCOPE
- (Default) Places
one primary shard for each partition on a container
server within the catalog service domain. Replica shards for each
partition are placed on the other container servers within the catalog
service domain.
- CONTAINER_SCOPE
- Places a primary shard on each container server in the catalog
service domain.
- PlacementScopeTopology
- Defines the
linking topology of the container servers within the
catalog service domain. This value is only used when the PlacementScope
value is set to something other than DOMAIN_SCOPE.
Valid
values:- HUB
- (Default) If the hub topology
is selected, then a single data
grid is selected to be the hub. Every other data grid connects to
the hub. This topology is fairly scalable because the spokes have
a single connection. The hub can become a bottleneck and temporary
single point of failure. The hub is relocated to another container
server when it fails. The advantage to this configuration is more
complex arbitration code can be written that allows a single point,
the hub, to handle all collisions.
- RING
- If the ring topology is selected, each data grid is linked with
two other data grids. The ordering of the links is not guaranteed.
However, each container that starts is likely linked to the first
container and last container to be added to the ring. This topology
is the most scalable, but only two links can fail before being temporarily
cut off. If the container servers fail, links are established among
the survivors after the failure has been discovered.
- ReplicaMode
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.
- ReplicaReadEnabled
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.
- writeBehind
For Hibernate providers only: When writeBehind is enabled,
updates are temporarily stored in a JVM scope data storage until either
the writeBehindInterval or writeBehindMaxBatchSize conditions are
met.
Attention: Unless writeBehind is enabled, the
other write behind configuration settings are disregarded.
Important: Take care when using the write behind function. Write
behind configurations introduce longer latency of data synchronization
across all JVMs and a higher chance of lost updates. In a system
that has write behind configuration enabled with four or more JVMs,
the update performed on one JVM has an approximate 15 second delay
before the update becomes available to other JVMs. If any two JVMs
update the same entry, the one that flushes the update first loses
its update.
Valid values: TRUE or FALSE
Default
value: FALSE
- writeBehindInterval
For Hibernate providers only: Specifies the time interval
in milliseconds to flush updates to the cache.
Valid values: greater
than or equal to 1
Default value: 5000 (5 seconds)
- writeBehindPoolSize
For
Hibernate providers only: Specifies the maximum
size of the thread pool used in flushing updates to the cache.
Valid
values: greater than or equal to 1
Default value: 5
- writeBehindMaxBatchSize
For Hibernate providers only: Specifies the maximum
batch size per region cache in flushing updates to the cache. For
example, if the size is set to 1000, and the updates stored in the
write behind storage of a region cache exceeds 1000 entries, the updates
are flushed to the cache, even the specified writeBehindInterval condition
is not met. Updates flush to the cache either approximately at the
number of seconds specified by the writeBehindInterval value or whenever
the size of write behind storage of each region cache exceeds 1000
entries. Note, in the case of the writeBehindMaxBatchSize condition
met; only the region cache that meets this condition flushes its updates
in write behind storage to cache. A region cache usually corresponds
to an entity or a query.
Valid values: greater than or
equal to 1
Default value: 1000