Configuring WSJPA ObjectCache to improve performance

The WebSphere® Java™ Persistence API (WSJPA) extension to OpenJPA provides a read-only object cache that can improve performance in certain use cases. This configuration is only supported when you use WSJPA at the JPA 2.0 specification level.

About this task

Implementing a WSJPA ObjectCache object can improve the performance of an application that has a set of data that is used in a static, read-only method, like accessing basic persistent fields and persisting unidirectional relationships to a read-only type. WSJPA ObjectCache is a non-distributed cache of read-only entities that operates at the EntityManagerFactory object level. These cached instances are shared by all EntityManager objects in the Java virtual machine (JVM), but the instances are not managed by any. When the feature is enabled, the ObjectCache object is examined before the application accesses the OpenJPA DataCache object and database, and persistent objects are loaded from the database and stored in the OpenJPA object cache. In addition, the ObjectCache implementation can be used with OpenJPA DataCache and QueryCache features for even greater performance.

Be aware of the following conditions and limitations:

Include types that are strictly read-only from the application point-of-view
- Passing a read-only type into the following operations results in an UnsupportedOperationException error message:
  - Passing a read-only entity into EntityManager.merge(…).
  - Passing a read-only entity into EntityManager.persist(…).
  - Passing a read-only entity into EntityManager.remove(…).
- Calling a setter method on a read-only type that was returned by the WebSphere JPA runtime results in an UnsupportedOperationException error message.
Types that are included in the ObjectCache must not be eligible to be cached in the OpenJPA DataCache. Do not intersect types that are cacheable by the OpenJPA L2 cache (openjpa.DataCache); the ObjectCache should not be confused with the second-level cache that is defined by the JPA 2.0 specification. If types are intersected, an exception will occur when the EntityManager object is created.
Include only basic fields, or an exception can occur when the EntityManager object is created.
Passing a read-only entity into EntityManager.contains(…) always returns false, even if it was just returned from a find/query operation.

You can enable the object cache for a single JVM environment, specify the types that are included in this cache, set its maximum element size, and specify timeout values.

Supported configurations: The preferred property name is wsjpa.ObjectCache, but openjpa.ObjectCache is also a valid configuration.

Procedure

Enable the cache for a single JVM.
Set the wsjpa.ObjectCache property to true and specify a list of object types to be cached.
For example, use the following property:
```
<property name="wsjpa.ObjectCache" 
          value="true(Types=com.ibm.wsjpa.Foo; com.ibm.wsjpa.Bar)"/>
```
Adjust the maximum cache size by setting the MaxSize property.
For example:
```
<property name="wsjpa.ObjectCache" 
          value="true(Types=com.ibm.wsjpa.Foo; com.ibm.wsjpa.Bar, 
          MaxSize=5000)"/>
```
By default an ObjectCache object holds 1000 elements. If the cache overflows, it evicts random elements that are preserved in a soft reference map. The size of the soft reference map is unlimited and cannot be configured.
Specify to clear the object cache at certain times.
The EvictionSchedule property of the ObjectCache implementation accepts a cron-style or interval-style eviction schedule:
- The cron format specifies the time in the following order:
  1. Minute
  2. Hour of day
  3. Day of month
  4. Month of the year
  5. Day of the week, beginning with 1 for Sunday.
  Use an * (asterisk) for any value to match all for that field. To schedule a cache to evict at 3:15 and 3:45 PM on Sunday every month, add this property:
```
<property name="wsjpa.ObjectCache" 
          value="true(Types=com.ibm.wsjpa.Foo; com.ibm.wsjpa.Bar,
                      MaxSize=5000,
                      EvictionSchedule='15,45 15 * * 1')"/>
```
- The interval style eviction schedule specifies the number of minutes between each instance that the cache should be evicted. The format of this property is a plus sign (+) followed by the number of minutes between each instance that the cache should be evicted. To schedule a cache to evict every 20 minutes, for example, add this property:
```
<property name="wsjpa.ObjectCache" 
          value="true(Types=com.ibm.wsjpa.Foo; com.ibm.wsjpa.Bar,
                      MaxSize=5000,
                      EvictionSchedule='+20')"/>
```
Specify named queries, which will return read-only types, with the NamedQueries attribute.
In addition to the types cached, the maximum number of cached queries can be specified by the QuerySize property. This cache is cleared anytime data is removed from the main object cache.
Use the following example to configure the object cache with one type, two named queries, and 5000 cached named queries:
```
<property name="wsjpa.ObjectCache"
          value="true(Types=com.ibm.wsjpa.Foo;com.ibm.wsjpa.Bar,
                      NamedQueries='foo.byid,bar.byid',
                      QuerySize=5000)"/>
```
The default value for the QuerySize property is 1000.
Gain additional performance improvement of a fully tested application by disabling ObjectCache validation.
By default, the ObjectCache runtime performs various validation checks with regards to the usage of types that are included in the cache. After the application is thoroughly tested with the ObjectCache configuration, you can disable this validation processing by setting the validate property to false.
Use the following example to configure the ObjectCache with one type, and relaxed runtime validation:
```
<property name="wsjpa.ObjectCache " value="true(Types=com.ibm.wsjpa.Foo, validate=false)"/>
```

What to do next

To enable automatic loading of the entire ObjectCache when the first EntityManager object is created, follow the steps in the Pre-loading the WSJPA ObjectCache automatically topic. In addition, you can read more about caching in the OpenJPA User Guide for information about all caching extensions.