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
The 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 that the ObjectCache is cleared at certain times.
The EvictionSchedule property of the object cache implementation
accepts a cron-style eviction schedule. The cron format specifies
the minute, hour of day, day of month, and day of the week beginning
with 1 for Sunday; the * (asterisk) indicates match all. To schedule
a cache to evict at 3:45 PM on Sunday every month, add this property:
<property name="openjpa.DataCache" value="true(Types=com.ibm.wsjpa.Foo; com.ibm.wsjpa.Bar, MaxSize=5000, EvictionSchedule='15,45 * * 1')”/>
In
addition to the cron syntax you can specify an interval style eviction schedule.
The format of this property is a plus sign (+) followed by the number
of minutes between each time that the cache should be evicted. To
schedule a cache to evict every 20 minutes add this property:<property name="openjpa.DataCache" 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.