New or updated for this feature pack


Configuring the WSJPA Object Cache 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.

Before you begin

New or updated for this feature pack 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

  1. 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)"/>
  2. 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.
  3. 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')"/>

What to do next

Read about caching in the OpenJPA User Guide for information about all caching extensions.



In this information ...


Related information

IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Jun 12, 2013 3:32:32 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=v700osgijpa&product=was-nd-mp&topic=tejb_jpaobjectcache.dita
File name: tejb_jpaobjectcache.html