Understanding the Cache API

To configure the TopLink 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 Descriptor API summarized in Example 90-1.

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

Example 90-1 Object Identity Descriptor API

useCacheIdentityMap()
useFullIdentityMap()
useHardCacheWeakIdentityMap()
useNoIdentityMap()
useSoftCacheWeakIdentityMap()
useWeakIdentityMap()

Cache Refresh API

You configure cache refresh using the Descriptor API summarized in Example 90-2.

For more information, see "Configuring Cache Refreshing".

Example 90-2 Cache Refresh Descriptor API

alwaysRefreshCache()
alwaysRefreshCacheOnRemote()
disableCacheHits()
disableCacheHitsOnRemote()
onlyRefreshCacheIfNewerVersion()

Cache Invalidation API

You configure cache invalidation using Descriptor methods getCacheInvalidationPolicy and setCacheInvalidationPolicy to configure an oracle.toplink.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 oracle.toplink.sessions.IdentityMapAccessor method invalidateObject.

• TimeToLiveCacheInvalidationPolicy: The object is automatically flagged as invalid after a specified time period has elapsed since the object was read.

For more information, see the following:

• "Configuring Cache Expiration at the Project Level"

• "Configuring Cache Expiration at the Descriptor Level"

• "Configuring Cache Expiration at the Query Level"

Cache Coordination API

You configure cache coordination using the Session methods summarized in Example 90-3.

You configure how object changes are propagated using the Descriptor methods summarized in Example 90-4.

For more information, see "Configuring Common Coordinated Cache Options".

Example 90-3 Cache Coordination Session API

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()

Example 90-4 Cache Coordination Descriptor API

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