Dynamic cache provider for the JPA 2.0 second level cache

Learn to use the WebSphere® Application Server 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 your JPA application and you can configure and monitor the dynamic cache service for your JPA application in the WebSphere Application Server 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.

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 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:

Cluster distributed cache synchronization and replication through WebSphere Application Server data replication service (DRS) and high-availability (HA) services.
Sophisticated and advanced DataCache and QueryCache monitoring, tuning and administration of the cache. The L2 cache will inherit the entire ecosystem of the available dynamic cache tooling.
Native servant region z/OS® support.
Performs equally, if not better, to the default cache provider.

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. You 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. You can configure the QueryCache and DataCache properties to use different types of cache providers. You can set the QueryCache property to default and set the DataCache to use dynamic cache, or reverse. It is ideal to use the WebSphere Application Server 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. You 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.

Configuring 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"/>

Table 1. 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

Configuring 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)"/>

Table 2. 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

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

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

Using 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. You 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 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 WebSphere Application Server 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:

Create a replication domain in the administrative 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.
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. You 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.
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.
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.
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:

org.apache.openjpa.event.SingleJVMRemoteCommitProvider (configured with the "sjvm" alias)
org.apache.openjpa.event.TCPRemoteCommitProvider
org.apache.openjpa.event.JMSRemoteCommitProvider

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.

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

Note: This topic references one or more of the application server log files. As a recommended alternative, you 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. You can also use HPEL in conjunction with your 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.