+

Search Tips   |   Advanced Search

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. WebSphere Application Server supports the JPA standard. The dynamic cache service plugs in as a level 2 cache provider to JPA. The L2 cache boosts the performance of the JPA application and we can configure and monitor the dynamic cache service for your JPA application in the WAS environment.

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.

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 based on the query properties and the parameters 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 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 WebSphere Application Server, 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 WebSphere Application Server. The dynamic cache provides the following advantages:

The JPA standard provides aliases as a mechanism to easily 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"/>

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.

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

Important: 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 WebSphere Application Server 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 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 WebSphere Application Server Network Deployment environment.

For entities and queries in the dynamic cache DataCache and QueryCache instances that are replicated across servers in a WAS Network Deployment 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 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 we 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 Associate shared libraries with servers topics for more information about shared libraries.

  5. Set the openjpa.RemoteCommitProvider to none.

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

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.


Troubleshooting 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}\".

This topic references one or more of the application server log files. As a recommended alternative, we can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM i systems. We can also use HPEL in conjunction with the native z/OS logging facilities. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.


Related tasks

  • Task overview: Use the dynamic cache service to improve performance
  • Use High Performance Extensible Logging to troubleshoot applications
  • Configure OpenJPA caching to improve performance
  • Manage shared libraries
  • Associate shared libraries with servers


    Related information:

  • Apache OpenJPA documentation
  • IBM Extended Cache Monitor for IBM WebSphere Application Server technology preview
  • Shared library collection