Network Deployment (Distributed operating systems), v8.0 > Reference > Administrator best practices


Dynamic cache provider for the JPA 2.0 second level cache

Learn to use the WAS dynamic cache service as a Java Persistence API (JPA) second level (L2) cache provider. JPA 2.0 has standardized the L2 cache interface. WAS supports the JPA standard. The dynamic cache service plugs in as a level 2 cache provider to JPA. This topic describes how the L2 cache boosts the performance of your JPA application, the advantages of using DynaCache as L2 cache provider and how to configure and monitor the dynamic cache service for your JPA application in the WAS environment.

New feature: A dynamic cache JPA second level (L2) cache provider for JPA 2.0 shares entity states across various persistence contexts, transactions and users. When caching is enabled, entities that are not found in the persistence context are loaded from the L2 cache. L2 caching avoids database access for currently-loaded entities. For more details about L2 caching, view the JPA 2.0 specification.New feature:

Attention: L2 caching increases the memory consumption of the application, therefore, it is important to limit the size of the L2 cache. There is also a possibility of stale data for updated objects in a clustered environment. Configure L2 caching for read-mostly, infrequently modified entities. L2 caches are not recommended for frequently and concurrently updated entities.

JPA utilizes several configurable L2 caches to maximize performance. The JPA data cache is a cache of persistent object data that operates at the EntityManagerFactory level. When enabled, the data cache is checked before making a trip to the datastore. Data is stored in the cache when objects are committed and when persistent objects are loaded from the datastore. In addition to the data cache, JPA defines service provider interfaces for a query cache.

The query cache stores the object IDs that are returned by query executions. When you run a query, JPA assembles a key that is based on the query properties and the parameters that are used at launch time and checks for a cached query result. If one is found, the object IDs in the cached result are looked up, and the resulting persistence-capable objects are returned. Otherwise, the query is launched against the database and the object IDs that are loaded by the query are placed into the cache. The object ID list is not cached until the list that is returned at query launch time is fully traversed.

The WebSphere Dynamic cache cache provider provides an excellent alternative to the default concurrent data and query cache providers on WAS, due to the value-added features that the dynamic cache service brings, such as its own feature set and the capabilities that are inherited from WAS. The dynamic cache provides the following advantages:

The JPA standard provides aliases as a mechanism to configure JPA plug-ins. The dynamic cache level 2 cache provider for JPA 2.0 is typically configured with the dynacache alias. We can use the dynacache alias for setting the DataCache and QueryCache properties of JPA. If the QueryCache property is set to use dynacache, then the DataCache property will also use the dynacache alias. We can configure the QueryCache and DataCache properties to use different types of cache providers. We can set the QueryCache property to default and set the DataCache to use dynamic cache, or reverse. It is ideal to use the WAS dynamic cache service for the DataCache, QueryCache, and the DataCacheManager. If the DataCache is set to dynacache, then the RemoteCommitProvider does nothing because DRS and HAM are leveraged to do the cache synchronization. We cannot enable the QueryCache property separately from the DataCache. The QueryCache property benefits from the availability of the DataCache property, where the entity data is cached.


Configure the JPA dynamic cache L2 provider (basic method)

Enable the dynamic cache service as the level 2 cache provider for JPA 2.0 by setting some or all of the following properties to dynacache: OpenJPA openjpa.QueryCache, openjpa.DataCache, and the openjpa.DataCacheManager. This default configuration is a suitable default for most environments. 

<property name="openjpa.DataCache" value="dynacache(CacheSize=1000)"/>
<property name="openjpa.QueryCache" value="dynacache"/>

<property name="openjpa.DataCacheManager" value="dynacache"/>

Property names and aliases.. Fully-qualified property names and aliases for the dynamic cache.

Dynamic cache name Property name Alias
DataCache cache provider com.ibm.ws.cache.openjpa. DynacacheDataCache dynacache
QueryCache cache provider com.ibm.ws.cache.openjpa. DynacacheQueryCache dynacache
RemoteCommitProvider com.ibm.ws.cache.openjpa. NoOpRemoteCommitProvider none
DataCacheManager com.ibm.ws.cache.openjpa. DynacacheDataCacheManager dynacache


Configure the JPA dynamic cache L2 provider (advanced method)

Configure the dynamic cache instance for the JPA 2.0 Level 2 data or query cache with additional or advanced configuration properties in the persistent unit (advanced method). Enable the dynamic cache service as the level 2 cache provider for JPA 2.0 by setting some or all of the following properties to dynacache: OpenJPA openjpa.QueryCache, openjpa.DataCache, and openjpa.DataCacheManager properties. 

<property name="openjpa.DataCache" value="dynacache(CacheName="myJPACache",
                                                    CacheSize=1000,
                                                    EnableDiskOffload=true,
                                                    DiskCacheSizeInGB=4,
                                                    DiskOffloadLocation=c:\temp,
                                                    EnableCacheReplication=true)"/>

Dynamic cache property names and values. Properties of the dynamic cache cache instance that can be configured in the persistent unit.

Dynamic cache custom properties Default values
CacheName default
CacheSize 2000
EnableDiskOffload false
EnableCacheReplication false
DiskCacheSizeInGB not applicable
DiskOffloadLocation not applicable
ReplicationType 1 , 2 or 4. 1 means NOT_SHARED, 2 is PUSH and 4 is PUSH_PULL

The properties in the table are not mandatory. If not specified, the dynamic cache service assumes default values that are suitable for the majority of users.

The following example showcases the dynamic cache mbean operations in action to introspect the L2 cache: 

wsadmin>set mbean [$AdminControl queryNames type=DynaCache,*]

wsadmin> $AdminControl invoke $mbean getCacheIDsInMemory {default \S}
66
71
10
A5614-67

wsadmin> $AdminControl invoke $mbean getJPACacheStatistics {OpenBooks openbooks.war OpenBooks default}
HIT_COUNT=0
TOTAL_HIT_COUNT=0
READ_COUNT=5
TOTAL_READ_COUNT=5
WRITE_COUNT=4
TOTAL_WRITE_COUNT=4

wsadmin> $AdminControl invoke $mbean getJPACacheStatistics {OpenBooks openbooks.war OpenBooks default openbook.domain.Customer}
HIT_COUNT=0
TOTAL_HIT_COUNT=0
READ_COUNT=0
TOTAL_READ_COUNT=0
WRITE_COUNT=1
TOTAL_WRITE_COUNT=1
We can also use the Extended Cache Monitor to view the contents of the cache ID and key values that are placed in the cache by the JPA runtime.


Use the dynamic cache L2 cache provider in a clustered environment

Customers can define a cache-instance in the customary way in WAS and then reference the name in the CacheName property of the JPA DataCache property value. We can define an object cache instance using the cacheinstances.properties file, DistributedMapFactory, or the administrative console.

All properties are optional and if they are not specified, defaults properties are assumed. If the cache instance does not exist, the dynamic cache service creates the cache instance. Advanced configuration for a QueryCache Dynacache instance is completed in a similar manner.

The JPA data cache operates in both single-JVM and multi-JVM environments. Multi-JVM caching is achieved through the use of the Data Replication Service (DRS) in a clustered WAS ND environment.

For entities and queries in the dynamic cache DataCache and QueryCache instances that are replicated across servers in a WAS ND environment using the Data Replication Service, configure a replication domain and associate the replication domain with the cache instance. The persistent unit must also have the openjpa.RemoteCommitProvider openJPA property set to none.

Replicate an OpenJPA L2 dynamic cache instance, as follows:

  1. Create a replication domain in the admin console and associate the replication domain with the baseCache cache instance on the dynamic cache service panel on all application servers that must share the distributed cache. The dynamic cache service uses this replication domain to replicate data across servers in the replication domain.

  2. Configure the cache instance by setting the enableCacheReplication property to true when defining the configuration of the cache instance. If you do not specify the replicationType property, the cache instance is configured by default in the NOT_SHARED sharing mode, where only invalidations are propagated. We can configure the cache instance in the NOT_SHARED, PUSH and PUSH_PULL sharing types. Refer to the cache replication topic to learn more about this topic.

  3. Set the com.ibm.ws.cache.CacheConfig.createCacheAtServerStartup JVM custom property to true on all the application servers in the replication domain. This custom property helps the JPA cache instances on servers bootstrap earlier and faster.

  4. Create a shared library to make the entity classes available in the classpath of the application server by defining a shared library and associating it with the server classloader. This step is necessary for the dynamic cache service and DRS to deserialize the replicated entity objects. Refer to the Shared library collection, Managing shared libraries, and Associating shared libraries with servers topics for more information about shared libraries.

  5. Set the openjpa.RemoteCommitProvider to none.

You might also use other RemoteCommitProvider implementations that are included with JPA 2.0 with dynamic cache, specifically the following implementations:

Read more about remote and offline operation in the JPA documentation.

Attention: Configure dynamic cache with DRS for replication of JPA data and QueryCache objects and using the NoOp RemoteCommitProvider property in a distributed or clustered environment.


Troubleshoot the JPA L2 cache

Look for the following messages in the log file when using the dynamic cache service as a JPA cache provider: 

# Significant dynamic cache OpenJPA messages in the SystemOut.log file DYNA1081I: OpenJPA L2 DataCache Dynacache instance \"{0}\" created or retrieved successfully for persistent unit \"{1}\".

# Applicable only if QueryCache is enabled
DYNA1080I: OpenJPA L2 QueryCache Dynacache instance \"{0}\" created or retrieved successfully for persistent unit \"{1}\".

New feature: Beginning in WAS v8.0 you can configure the server to use the HPEL log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files or native z/OS logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.New feature:
Task overview: Using the dynamic cache service to improve performance
Use HPEL to troubleshoot applications
Configure OpenJPA caching to improve performance
Manage shared libraries
Associate shared libraries with servers
Apache OpenJPA documentation
Shared library collection
IBM Extended Cache Monitor for IBM WAS technology preview

+

Search Tips   |   Advanced Search