The WebSphere® Java Persistence API (WSJPA) extension
to OpenJPA provides a read-only ObjectCache that can improve performance
in certain use cases.
Before you begin
This cache can improve the performance of an application
which has a set of data that is 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 ObjectCache
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 must not be eligible to be
cached in the OpenJPA DataCache. The ObjectCache 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 just returned from a find/query operation.
About this task
You can enable the ObjectCache 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
ObjectCache, 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 ObjectCache 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 should be cleared at certain
times. The EvictionSchedule property of the ObjectCache
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
To enable automatic loading of the entire ObjectCache when
the first EntityManager is created, follow the steps outlined 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.