EclipseLink/UserGuide/JPA/sandbox/caching/Cache API

EclipseLink JPA

• EclipseLink Destinations:
• Documentation
• FAQ
• Examples
• Development

Cache API

To configure the EclipseLink cache, you use the appropriate API in the following objects:

• Object Identity API
• Cache Refresh API
• Cache Invalidation API
• Cache Coordination API

Object Identity API

You configure object identity using the following ClassDescriptor API:

useCacheIdentityMap()

useFullIdentityMap()

useHardCacheWeakIdentityMap()

useNoIdentityMap()

useSoftCacheWeakIdentityMap()

useWeakIdentityMap()

useSoftIdentityMap() 

For more information, see Configuring Cache Type and Size at the Descriptor Level.

Cache Refresh API

You configure cache refresh using the following ClassDescriptor API:

alwaysRefreshCache()

alwaysRefreshCacheOnRemote()

disableCacheHits()

disableCacheHitsOnRemote()

onlyRefreshCacheIfNewerVersion()

You can also configure cache refresh using the following API calls:

• Session: refreshObject method
• DatabaseSession and UnitOfWork: refreshAndLockObject methods
• ObjectLevelReadQuery: refreshIdentityMapResult and refreshRemoteIdentityMapResult methods

For more information, see Configuring Cache Refreshing.

Cache Invalidation API

You configure cache invalidation using ClassDescriptor methods getCacheInvalidationPolicy and setCacheInvalidationPolicy to configure an org.eclipse.persistence.descriptors.invalidation.CacheInvalidationPolicy.

You can use any of the following CacheInvalidationPolicy instances:

• DailyCacheInvalidationPolicy: The object is automatically flagged as invalid at a specified time of day.
• NoExpiryCacheInvalidationPolicy: The object can only be flagged as invalid by explicitly calling org.eclipse.persistence.sessions.IdentityMapAccessor method invalidateObject.
• TimeToLiveCacheInvalidationPolicy: The object is automatically flagged as invalid after a specified time period has elapsed since the object was read.

You can also configure cache invalidation using a variety of API calls accessible through the Session. The org.eclipse.persistence.sessions.IdentityMapAccessor provides the following methods:

• getRemainingValidTime: Returns the remaining life of the specified object. This time represents the difference between the next expiry time of the object and its read time.
• invalidateAll: Sets all objects for all classes to be invalid in EclipseLink identity maps.
• invalidateClass(Class klass) and invalidateClass(Class klass, boolean recurse): Set all objects of a specified class to be invalid in EclipseLink identity maps.
• invalidateObject(Object object), invalidateObject(Record rowWithPrimaryKey, Class klass) and invalidateObject(Vector primaryKey, Class klass): Set an object to be invalid in EclipseLink identity maps.
• invalidateObjects(Expression selectionCriteria) and invalidateObjects(Vector collection): Set all objects from the specified Expression/collection to be invalid in EclipseLink identity maps.
• isValid(Record recordContainingPrimaryKey, Class theClass), isValid(Object object) and isValid(java.util.Vector primaryKey, Class theClass): Return true if the object is valid in EclipseLink identity maps.

For more information, see the following:

• Configuring Cache Expiration at the Project Level
• Configuring Cache Expiration at the Descriptor Level
• How to Configure Cache Expiration at the Query Level

Cache Coordination API

Configure cache coordination using the following Session methods:

Session.getCommandManager().
    setShouldPropagateAsynchronously(boolean)

Session.getCommandManager().getDiscoveryManager().
    setAnnouncementDelay()
    setMulticastGroupAddress()
    setMulticastPort()
    setPacketTimeToLive()

Session.getCommandManager().getTransportManager().
    setEncryptedPassword()
    setInitialContextFactoryName()
    setLocalContextProperties(Hashtable)
    setNamingServiceType() passing in one of:
        TransportManager.JNDI_NAMING_SERVICE
        TransportManager.REGISTRY_NAMING_SERVICE
    setPassword()
    setRemoteContextProperties(Hashtable)
    setShouldRemoveConnectionOnError()
    setUserName()

You configure how object changes are propagated using the following ClassDescriptor methods:

setCacheSynchronizationType() passing in one of:
    ClassDescriptor.DO_NOT_SEND_CHANGES
    ClassDescriptor.INVALIDATE_CHANGED_OBJECTS
    ClassDescriptor.SEND_NEW_OBJECTS_WITH_CHANGES
    ClassDescriptor.SEND_OBJECT_CHANGES

For more information, see Configuring Common Coordinated Cache Options.

Version: 2.2.0 DRAFT
Other versions...

caching	caching	caching
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...