oracle.eclipselink.coherence.integrated.cache

Class CoherenceInterceptor

java.lang.Object

org.eclipse.persistence.sessions.interceptors.CacheInterceptor

oracle.eclipselink.coherence.integrated.cache.CoherenceInterceptor

All Implemented Interfaces:

java.lang.Cloneable, org.eclipse.persistence.internal.identitymaps.IdentityMap

public class CoherenceInterceptor
extends CacheInterceptor

Purpose: This Cache Interceptor should be set on the descriptor for any class that is cached within Coherence. Once this Interceptor is applied EclipseLink will ensure that all Entities read into EclipseLink or updated by EclipseLink will be put into the Coherence Cache. TopLink cache settings will not be used. Developers should set the Coherence Cache name that corresponds to this class in a descriptor property called "coherence.cache.name". Each class should have its own Cache unless the PK's of the instances are unique amoung all classes stored in a single cache This Interceptor can be set on the class descriptor through a Session or Descriptor customizer or annotations

Since:

Oracle TopLink 11g (11.1.1.0.0)

Author:

gyorke

See Also:

org.eclipse.persistence.descriptors.ClassDescriptor.setCacheInterceptorClass, org.eclipse.persistence.annoations.CacheInterceptor

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	CoherenceInterceptor.CoherenceOnlyCacheKeyWrapper

Constructor Summary

Constructors

Constructor and Description
CoherenceInterceptor(org.eclipse.persistence.internal.identitymaps.IdentityMap targetIdentityMap, org.eclipse.persistence.internal.sessions.AbstractSession interceptedSession) Instantiate an new Cache Interceptor passing in the identity map that will be intercepted and the session that holds that identity map.

Method Summary

Methods

Modifier and Type	Method and Description
org.eclipse.persistence.internal.identitymaps.CacheKey	acquireDeferredLock(java.lang.Object primaryKey, boolean isCacheCheckComplete) Acquire a deferred lock on the object.
org.eclipse.persistence.internal.identitymaps.CacheKey	acquireLock(java.lang.Object primaryKey, boolean forMerge, boolean isCacheCheckComplete) Acquire an active lock on the object.
org.eclipse.persistence.internal.identitymaps.CacheKey	acquireLockNoWait(java.lang.Object primaryKey, boolean forMerge) Acquire an active lock on the object, if not already locked.
org.eclipse.persistence.internal.identitymaps.CacheKey	acquireLockWithWait(java.lang.Object primaryKey, boolean forMerge, int wait) Acquire an active lock on the object, if not already locked.
org.eclipse.persistence.internal.identitymaps.CacheKey	acquireReadLockOnCacheKey(java.lang.Object primaryKey) Acquire a read lock on the object.
org.eclipse.persistence.internal.identitymaps.CacheKey	acquireReadLockOnCacheKeyNoWait(java.lang.Object primaryKey) Acquire a read lock on the object, if not already locked.
java.lang.Object	clone() Clone the map and all of the CacheKeys.
boolean	containsKey(java.lang.Object primaryKey) Return true if an CacheKey with the primary key is in the map.
java.util.Enumeration	elements() Allow for the cache to be iterated on.
java.lang.Object	get(java.lang.Object primaryKey) Return the object cached in the identity map or null if it could not be found.
java.util.Map<java.lang.Object,org.eclipse.persistence.internal.identitymaps.CacheKey>	getAllCacheKeysFromIdentityMapWithEntityPK(java.lang.Object[] pkList, ClassDescriptor descriptor, org.eclipse.persistence.internal.sessions.AbstractSession session) ADVANCED: Using a list of Entity PK this method will attempt to bulk load the entire list from the cache.
java.util.Map<java.lang.Object,java.lang.Object>	getAllFromIdentityMapWithEntityPK(java.lang.Object[] pkList, ClassDescriptor descriptor, org.eclipse.persistence.internal.sessions.AbstractSession session) ADVANCED: Using a list of Entity PK this method will attempt to bulk load the entire list from the cache.
org.eclipse.persistence.internal.identitymaps.CacheKey	getCacheKey(java.lang.Object searchKey, boolean forMerge) Return the cache key (with object) matching the searchKey.
org.eclipse.persistence.internal.identitymaps.CacheKey	getCacheKeyForLock(java.lang.Object searchKey) Return the cache key (with object) matching the searchKey.
int	getMaxSize()
com.tangosol.net.NamedCache	getNamedCache()
int	getSize() Return the number of CacheKeys in the IdentityMap.
int	getSize(java.lang.Class myClass, boolean recurse) Return the number of actual objects of type myClass in the IdentityMap.
java.lang.Object	getWrapper(java.lang.Object primaryKey) Get the wrapper object from the cache key associated with the given primary key, this is used for EJB2.
java.lang.Object	getWriteLockValue(java.lang.Object primaryKey) Get the write lock value from the cache key associated to the primarykey.
void	lazyRelationshipLoaded(java.lang.Object rootEntity, ValueHolderInterface valueHolder, ForeignReferenceMapping mapping) Notify the cache that a lazy relationship has been triggered in the object and the cache may need to be updated
org.eclipse.persistence.internal.identitymaps.CacheKey	put(java.lang.Object primaryKey, java.lang.Object object, java.lang.Object writeLockValue, long readTime) Store the object in the cache at its primary key.
void	release() Used to release the reference to the named cache durring initialize all identity maps.
java.lang.Object	remove(org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey) Remove the CacheKey from the map.
java.lang.Object	remove(java.lang.Object primaryKey, java.lang.Object object) Remove the CacheKey with the primaryKey from the map.
void	setDescriptor(ClassDescriptor descriptor) Set the descriptor that this is the map for.
void	setTriggerFetchGroups(boolean triggerFetchGroups)
void	setWrapper(java.lang.Object primaryKey, java.lang.Object wrapper) Update the wrapper object in the CacheKey associated with the given primaryKey, this is used for EJB2.
void	setWriteLockValue(java.lang.Object primaryKey, java.lang.Object writeLockValue) Update the write lock value of the CacheKey associated with the given primaryKey.
boolean	shouldTriggerFetchGroups()
java.lang.String	toString()
void	trackComponents(ClassDescriptor sourceDesc, ClassDescriptor root, org.eclipse.persistence.internal.sessions.AbstractSession session, boolean allowSharedComponents)
void	updateMaxSize(int maxSize) This method will be used to update the max cache size, any objects exceeding the max cache size will be remove from the cache.

Methods inherited from class org.eclipse.persistence.sessions.interceptors.CacheInterceptor

collectLocks, getDescriptor, getDescriptorClass, getTargetIdenttyMap, keys, keys

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CoherenceInterceptor

public CoherenceInterceptor(org.eclipse.persistence.internal.identitymaps.IdentityMap targetIdentityMap,
                    org.eclipse.persistence.internal.sessions.AbstractSession interceptedSession)

Instantiate an new Cache Interceptor passing in the identity map that will be intercepted and the session that holds that identity map. This is an internal method as this class should not be instantiated by the user.

Method Detail

clone

public java.lang.Object clone()

Description copied from class: CacheInterceptor

Clone the map and all of the CacheKeys. This is used by UnitOfWork commitAndResumeOnFailure to avoid corrupting the cache during a failed commit.

Specified by:

clone in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Specified by:

clone in class CacheInterceptor

trackComponents

public void trackComponents(ClassDescriptor sourceDesc,
                   ClassDescriptor root,
                   org.eclipse.persistence.internal.sessions.AbstractSession session,
                   boolean allowSharedComponents)

acquireDeferredLock

public org.eclipse.persistence.internal.identitymaps.CacheKey acquireDeferredLock(java.lang.Object primaryKey,
                                                                         boolean isCacheCheckComplete)

Acquire a deferred lock on the object. This is used while reading if the object has relationships without indirection. This first thread will get an active lock. Other threads will get deferred locks, all threads will wait until all other threads are complete before releasing their locks.

Specified by:

acquireDeferredLock in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

acquireDeferredLock in class CacheInterceptor

acquireLock

public org.eclipse.persistence.internal.identitymaps.CacheKey acquireLock(java.lang.Object primaryKey,
                                                                 boolean forMerge,
                                                                 boolean isCacheCheckComplete)

Acquire an active lock on the object. This is used by reading (when using indirection or no relationships) and by merge.

Specified by:

acquireLock in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

acquireLock in class CacheInterceptor

acquireLockNoWait

public org.eclipse.persistence.internal.identitymaps.CacheKey acquireLockNoWait(java.lang.Object primaryKey,
                                                                       boolean forMerge)

Acquire an active lock on the object, if not already locked. This is used by merge for missing existing objects.

Specified by:

acquireLockNoWait in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

acquireLockNoWait in class CacheInterceptor

acquireLockWithWait

public org.eclipse.persistence.internal.identitymaps.CacheKey acquireLockWithWait(java.lang.Object primaryKey,
                                                                         boolean forMerge,
                                                                         int wait)

Acquire an active lock on the object, if not already locked. This is used by merge for missing existing objects.

Specified by:

acquireLockWithWait in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

acquireLockWithWait in class CacheInterceptor

getAllFromIdentityMapWithEntityPK

public java.util.Map<java.lang.Object,java.lang.Object> getAllFromIdentityMapWithEntityPK(java.lang.Object[] pkList,
                                                                                 ClassDescriptor descriptor,
                                                                                 org.eclipse.persistence.internal.sessions.AbstractSession session)

ADVANCED: Using a list of Entity PK this method will attempt to bulk load the entire list from the cache. In certain circumstances this can have large performance improvements over loading each item individually.

Specified by:

getAllFromIdentityMapWithEntityPK in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Specified by:

getAllFromIdentityMapWithEntityPK in class CacheInterceptor

Parameters:

pkList - List of Entity PKs to extract from the cache

ClassDescriptor - Descriptor type to be retrieved.

Returns:

Map of Entity PKs associated to the Entities that were retrieved

Throws:

QueryException

getAllCacheKeysFromIdentityMapWithEntityPK

public java.util.Map<java.lang.Object,org.eclipse.persistence.internal.identitymaps.CacheKey> getAllCacheKeysFromIdentityMapWithEntityPK(java.lang.Object[] pkList,
                                                                                                                                ClassDescriptor descriptor,
                                                                                                                                org.eclipse.persistence.internal.sessions.AbstractSession session)

ADVANCED: Using a list of Entity PK this method will attempt to bulk load the entire list from the cache. In certain circumstances this can have large performance improvements over loading each item individually.

Specified by:

getAllCacheKeysFromIdentityMapWithEntityPK in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Specified by:

getAllCacheKeysFromIdentityMapWithEntityPK in class CacheInterceptor

Parameters:

pkList - List of Entity PKs to extract from the cache

ClassDescriptor - Descriptor type to be retrieved.

Returns:

Map of Entity PKs associated to the Entities that were retrieved

Throws:

QueryException

getCacheKey

public org.eclipse.persistence.internal.identitymaps.CacheKey getCacheKey(java.lang.Object searchKey,
                                                                 boolean forMerge)

Return the cache key (with object) matching the searchKey.

Specified by:

getCacheKey in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

getCacheKey in class CacheInterceptor

getCacheKeyForLock

public org.eclipse.persistence.internal.identitymaps.CacheKey getCacheKeyForLock(java.lang.Object searchKey)

Return the cache key (with object) matching the searchKey.

Specified by:

getCacheKeyForLock in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

getCacheKeyForLock in class CacheInterceptor

getNamedCache

public com.tangosol.net.NamedCache getNamedCache()

lazyRelationshipLoaded

public void lazyRelationshipLoaded(java.lang.Object rootEntity,
                          ValueHolderInterface valueHolder,
                          ForeignReferenceMapping mapping)

Notify the cache that a lazy relationship has been triggered in the object and the cache may need to be updated

Specified by:

lazyRelationshipLoaded in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

lazyRelationshipLoaded in class CacheInterceptor

put

public org.eclipse.persistence.internal.identitymaps.CacheKey put(java.lang.Object primaryKey,
                                                         java.lang.Object object,
                                                         java.lang.Object writeLockValue,
                                                         long readTime)

Store the object in the cache at its primary key. This is used by InsertObjectQuery, typically into the UnitOfWork identity map. Merge and reads do not use put, but acquireLock. Also an advanced (very) user API.

Specified by:

put in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

put in class CacheInterceptor

Parameters:

primaryKey - is the primary key for the object.

object - is the domain object to cache.

writeLockValue - is the current write lock value of object, if null the version is ignored.

release

public void release()

Used to release the reference to the named cache durring initialize all identity maps.

remove

public java.lang.Object remove(java.lang.Object primaryKey,
                      java.lang.Object object)

Remove the CacheKey with the primaryKey from the map. This is used by DeleteObjectQuery and merge. This is also an advanced (very) user API.

Specified by:

remove in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

remove in class CacheInterceptor

remove

public java.lang.Object remove(org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey)

Remove the CacheKey from the map.

Specified by:

remove in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

remove in class CacheInterceptor

acquireReadLockOnCacheKey

public org.eclipse.persistence.internal.identitymaps.CacheKey acquireReadLockOnCacheKey(java.lang.Object primaryKey)

Description copied from class: CacheInterceptor

Acquire a read lock on the object. This is used by UnitOfWork cloning. This will allow multiple users to read the same object but prevent writes to the object while the read lock is held.

Specified by:

acquireReadLockOnCacheKey in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

acquireReadLockOnCacheKey in class CacheInterceptor

acquireReadLockOnCacheKeyNoWait

public org.eclipse.persistence.internal.identitymaps.CacheKey acquireReadLockOnCacheKeyNoWait(java.lang.Object primaryKey)

Description copied from class: CacheInterceptor

Acquire a read lock on the object, if not already locked. This is used by UnitOfWork cloning. This will allow multiple users to read the same object but prevent writes to the object while the read lock is held.

Specified by:

acquireReadLockOnCacheKeyNoWait in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

acquireReadLockOnCacheKeyNoWait in class CacheInterceptor

containsKey

public boolean containsKey(java.lang.Object primaryKey)

Description copied from class: CacheInterceptor

Return true if an CacheKey with the primary key is in the map. User API.

Specified by:

containsKey in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

containsKey in class CacheInterceptor

Parameters:

primaryKey - is the primary key for the object to search for.

elements

public java.util.Enumeration elements()

Description copied from class: CacheInterceptor

Allow for the cache to be iterated on. This method is only used during debugging when validateCache() has been called to print out the contents of the cache.

Specified by:

elements in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

elements in class CacheInterceptor

get

public java.lang.Object get(java.lang.Object primaryKey)

Description copied from class: CacheInterceptor

Return the object cached in the identity map or null if it could not be found. User API.

Specified by:

get in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

get in class CacheInterceptor

getMaxSize

public int getMaxSize()

Specified by:

getMaxSize in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

getMaxSize in class CacheInterceptor

Returns:

The maxSize for the IdentityMap (NOTE: some subclasses may use this differently).

getSize

public int getSize()

Description copied from class: CacheInterceptor

Return the number of CacheKeys in the IdentityMap. This may contain weak referenced objects that have been garbage collected.

Specified by:

getSize in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

getSize in class CacheInterceptor

getSize

public int getSize(java.lang.Class myClass,
          boolean recurse)

Description copied from class: CacheInterceptor

Return the number of actual objects of type myClass in the IdentityMap. Recurse = true will include subclasses of myClass in the count.

Specified by:

getSize in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

getSize in class CacheInterceptor

getWrapper

public java.lang.Object getWrapper(java.lang.Object primaryKey)

Description copied from class: CacheInterceptor

Get the wrapper object from the cache key associated with the given primary key, this is used for EJB2.

Specified by:

getWrapper in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

getWrapper in class CacheInterceptor

getWriteLockValue

public java.lang.Object getWriteLockValue(java.lang.Object primaryKey)

Description copied from class: CacheInterceptor

Get the write lock value from the cache key associated to the primarykey. User API.

Specified by:

getWriteLockValue in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

getWriteLockValue in class CacheInterceptor

updateMaxSize

public void updateMaxSize(int maxSize)

Description copied from class: CacheInterceptor

This method will be used to update the max cache size, any objects exceeding the max cache size will be remove from the cache. Please note that this does not remove the object from the identityMap, except in the case of the CacheIdentityMap.

Specified by:

updateMaxSize in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

updateMaxSize in class CacheInterceptor

setDescriptor

public void setDescriptor(ClassDescriptor descriptor)

Description copied from class: CacheInterceptor

Set the descriptor that this is the map for.

Specified by:

setDescriptor in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

setDescriptor in class CacheInterceptor

setWrapper

public void setWrapper(java.lang.Object primaryKey,
              java.lang.Object wrapper)

Description copied from class: CacheInterceptor

Update the wrapper object in the CacheKey associated with the given primaryKey, this is used for EJB2.

Specified by:

setWrapper in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

setWrapper in class CacheInterceptor

setWriteLockValue

public void setWriteLockValue(java.lang.Object primaryKey,
                     java.lang.Object writeLockValue)

Description copied from class: CacheInterceptor

Update the write lock value of the CacheKey associated with the given primaryKey. This is used by UpdateObjectQuery, and is also an advanced (very) user API.

Specified by:

setWriteLockValue in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

setWriteLockValue in class CacheInterceptor

toString

public java.lang.String toString()

Specified by:

toString in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

Overrides:

toString in class CacheInterceptor

shouldTriggerFetchGroups

public boolean shouldTriggerFetchGroups()

setTriggerFetchGroups

public void setTriggerFetchGroups(boolean triggerFetchGroups)