The WebSphere® Java Persistence API (WSJPA) extension
to OpenJPA provides a read-only object cache that can improve performance
in certain use cases.
Before you begin
newfeatThe Feature
Pack for OSGi Applications and JPA 2.0 introduces support for Apache
OpenJPA 2.0.
This cache can improve the performance of an application
that has a set of data used in a static, read-only method. For example,
accessing basic persistent fields and persisting unidirectional relationships
to a read-only type. This set of data has a number of restrictions
that are documented here.
The WSJPA object cache is a non-distributed
cache of read-only Entities that operates at the EntityManagerFactory
level. These cached instances are shared by all EntityManagers in
the Java virtual machine (JVM),
but not managed by any. When enabled, the ObjectCache is examined
before accessing the OpenJPA DataCache and database. When persistent
objects are loaded from the database they are stored in the OpenJPA
ObjectCache. The ObjectCache can be used with the OpenJPA DataCache
and QueryCache for even greater performance. Types that are included
in the ObjectCache are not eligible to be cached in the OpenJPA
DataCache. The object cache is not to be confused with a second-level
cache as defined by the JPA 2.0 specification.
Types that are
included in the OpenJPA ObjectCache are as follows:
- Strictly read-only from the application point-of-view
- Passing a read only type into the following operations results
in an UnsupportedOperationException.
- 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.
- Restricted to having only basic fields. An exception occurs on
EntityManager creation if this rule is broken.
- Not to intersect types that are cacheable by the OpenJPA L2 cache
(openjpa.DataCache). An exception occurs on EntityManager creation
if this rule is broken.
- Passing a read-only Entity into EntityManager.contains(…) always
returns false, even if it was returned from a find or query operation.
About this task
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. To set up and configure the
object cache, do the following:
Attention: The preferred
property name is wsjpa.ObjectCache, but openjpa.ObjectCache is also
a valid configuration.
Procedure
- To enable the cache for a single JVM, set the wsjpa.ObjectCache
property to true and specify a list of Types.
<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:
<property name="wsjpa.ObjectCache" value="true(Types=com.ibm.wsjpa.Foo; com.ibm.wsjpa.Bar, MaxSize=5000)"/>
By default, the object cache holds 1000 elements. If the
cache overflows, it evicts random elements. Evicted elements 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:
- Minute
- Hour of day
- Day of month
- Month of the year
- 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')"/>
What to do next
Read about caching in the OpenJPA User Guide for information
about all caching extensions.