Package org.eclipse.persistence.sessions.interceptors

Class CacheInterceptor

  • All Implemented Interfaces:
    java.lang.Cloneable, org.eclipse.persistence.internal.identitymaps.IdentityMap
    public abstract class CacheInterceptor
extends java.lang.Object
implements org.eclipse.persistence.internal.identitymaps.IdentityMap

    Purpose: Define a class through which Cache access can be intercepted.

    Description: EclipseLink makes extensive use of caching functionality. This class provides the mechanism for intercepting the cache access. Once intercepted applications can allow the process to continue by calling the method on the class attribute targetIdentityMap as described in the API javadocs or redirect the process entirely. * As with IdentityMaps an entire class inheritance hierarchy will share the same interceptor.

    To implement a CacheInterceptor users should subclass this class implementing those methods they wish to intercept.

    Configuration: Interceptors may be added to a session by using a Session or Descriptor customizer to set the class name of the interceptor on the target ClassDescriptor through the method setCacheInterceptorClass(Class).

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected org.eclipse.persistence.internal.sessions.AbstractSession interceptedSession  
      protected org.eclipse.persistence.internal.identitymaps.IdentityMap targetIdentityMap
      This attribute stores the actual IdentityMap as configured by the user.

    • Constructor Summary

      Constructors 
      Constructor Description
      CacheInterceptor​(org.eclipse.persistence.internal.identitymaps.IdentityMap targetIdentityMap, org.eclipse.persistence.internal.sessions.AbstractSession interceptedSession)  

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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.
      abstract java.lang.Object clone()
      Clone the map and all of the CacheKeys.
      java.util.Enumeration<org.eclipse.persistence.internal.identitymaps.CacheKey> cloneKeys()
      Allow for the CacheKey elements to be iterated.
      void collectLocks​(java.util.HashMap threadList)
      Add all locked CacheKeys to the map grouped by thread.
      boolean containsKey​(java.lang.Object primaryKey)
      Return true if an CacheKey with the primary key is in the map.
      protected abstract CacheKeyInterceptor createCacheKeyInterceptor​(org.eclipse.persistence.internal.identitymaps.CacheKey wrappedCacheKey)  
      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.
      abstract 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.
      abstract 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 primaryKey, boolean forMerge)
      Get the cache key (with object) for the primary key.
      org.eclipse.persistence.internal.identitymaps.CacheKey getCacheKeyForLock​(java.lang.Object primaryKey)
      Get the cache key (with object) for the primary key.
      ClassDescriptor getDescriptor()
      Return the descriptor that this is the map for.
      java.lang.Class getDescriptorClass()
      Return the class that this is the map for.
      int getMaxSize()  
      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.
      org.eclipse.persistence.internal.identitymaps.IdentityMap getTargetIdenttyMap()
      Return the instance of the IdentityMap that this intercpetor is wrapping.
      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.
      java.util.Enumeration<org.eclipse.persistence.internal.identitymaps.CacheKey> keys()
      Allow for the CacheKey elements to be iterated.
      java.util.Enumeration<org.eclipse.persistence.internal.identitymaps.CacheKey> keys​(boolean checkReadLocks)
      Allow for the CacheKey elements to be iterated.
      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.
      java.lang.Object remove​(java.lang.Object primaryKey, java.lang.Object object)
      Remove the CacheKey with the primaryKey from the map.
      java.lang.Object remove​(org.eclipse.persistence.internal.identitymaps.CacheKey cacheKey)
      Remove the CacheKey from the map.
      void setDescriptor​(ClassDescriptor descriptor)
      Set the descriptor that this is the map for.
      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.
      java.lang.String toString()  
      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 java.lang.Object

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

      • Methods inherited from interface org.eclipse.persistence.internal.identitymaps.IdentityMap

        release

    • Field Detail

      • targetIdentityMap

        protected org.eclipse.persistence.internal.identitymaps.IdentityMap targetIdentityMap
        This attribute stores the actual IdentityMap as configured by the user.

      • interceptedSession

        protected org.eclipse.persistence.internal.sessions.AbstractSession interceptedSession

    • Constructor Detail

      • CacheInterceptor

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

    • Method Detail

      • 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

      • 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

      • 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

      • 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

      • acquireReadLockOnCacheKey

        public org.eclipse.persistence.internal.identitymaps.CacheKey acquireReadLockOnCacheKey​(java.lang.Object primaryKey)
        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

      • acquireReadLockOnCacheKeyNoWait

        public org.eclipse.persistence.internal.identitymaps.CacheKey acquireReadLockOnCacheKeyNoWait​(java.lang.Object primaryKey)
        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

      • collectLocks

        public void collectLocks​(java.util.HashMap threadList)
        Add all locked CacheKeys to the map grouped by thread. Used to print all the locks in the identity map.
        Specified by:
        collectLocks in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • clone

        public abstract java.lang.Object clone()
        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
        Overrides:
        clone in class java.lang.Object

      • containsKey

        public boolean containsKey​(java.lang.Object primaryKey)
        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
        Parameters:
        primaryKey - is the primary key for the object to search for.

      • createCacheKeyInterceptor

        protected abstract CacheKeyInterceptor createCacheKeyInterceptor​(org.eclipse.persistence.internal.identitymaps.CacheKey wrappedCacheKey)

      • elements

        public java.util.Enumeration elements()
        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

      • get

        public java.lang.Object get​(java.lang.Object primaryKey)
        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

      • getAllFromIdentityMapWithEntityPK

        public abstract 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
        Parameters:
        pkList - List of Entity PKs to extract from the cache
        descriptor - Descriptor type to be retrieved.
        Returns:
        Map of Entity PKs associated to the Entities that were retrieved
        Throws:
        QueryException

      • getAllCacheKeysFromIdentityMapWithEntityPK

        public abstract 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
        Parameters:
        pkList - List of Entity PKs to extract from the cache
        descriptor - 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 primaryKey,
                                                                          boolean forMerge)
        Get the cache key (with object) for the primary key.
        Specified by:
        getCacheKey in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • getCacheKeyForLock

        public org.eclipse.persistence.internal.identitymaps.CacheKey getCacheKeyForLock​(java.lang.Object primaryKey)
        Get the cache key (with object) for the primary key.
        Specified by:
        getCacheKeyForLock in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • getDescriptor

        public ClassDescriptor getDescriptor()
        Return the descriptor that this is the map for.
        Specified by:
        getDescriptor in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • getDescriptorClass

        public java.lang.Class getDescriptorClass()
        Return the class that this is the map for.
        Specified by:
        getDescriptorClass in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • getMaxSize

        public int getMaxSize()
        Specified by:
        getMaxSize in interface org.eclipse.persistence.internal.identitymaps.IdentityMap
        Returns:
        The maxSize for the IdentityMap (NOTE: some subclasses may use this differently).

      • getSize

        public int getSize()
        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

      • getSize

        public int getSize​(java.lang.Class myClass,
                   boolean recurse)
        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

      • getTargetIdenttyMap

        public org.eclipse.persistence.internal.identitymaps.IdentityMap getTargetIdenttyMap()
        Return the instance of the IdentityMap that this intercpetor is wrapping. Any call that is to be passed on to the underlying EclipseLink cache should be passed to this IdentityMap.

      • getWrapper

        public 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.
        Specified by:
        getWrapper in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • getWriteLockValue

        public java.lang.Object getWriteLockValue​(java.lang.Object primaryKey)
        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

      • keys

        public java.util.Enumeration<org.eclipse.persistence.internal.identitymaps.CacheKey> keys()
        Allow for the CacheKey elements to be iterated. CacheKey Collection is reused so this iteration may not be thread safe.
        Specified by:
        keys in interface org.eclipse.persistence.internal.identitymaps.IdentityMap
        Returns:
        Enumeration of CacheKey instances.

      • cloneKeys

        public java.util.Enumeration<org.eclipse.persistence.internal.identitymaps.CacheKey> cloneKeys()
        Allow for the CacheKey elements to be iterated. Clone of CacheKey Collection is returned so this iteration should be thread safe.
        Specified by:
        cloneKeys in interface org.eclipse.persistence.internal.identitymaps.IdentityMap
        Returns:
        Enumeration with clone of the CacheKey Collection

      • keys

        public java.util.Enumeration<org.eclipse.persistence.internal.identitymaps.CacheKey> keys​(boolean checkReadLocks)
        Allow for the CacheKey elements to be iterated. CacheKey Collection is reused so this iteration may not be thread safe.
        Specified by:
        keys in interface org.eclipse.persistence.internal.identitymaps.IdentityMap
        Parameters:
        checkReadLocks - value of true if read lock on the CacheKey instances should be checked or false otherwise
        Returns:
        Enumeration of CacheKey instances.

      • 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

      • 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
        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.

      • 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

      • 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

      • updateMaxSize

        public 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. 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

      • setDescriptor

        public void setDescriptor​(ClassDescriptor descriptor)
        Set the descriptor that this is the map for.
        Specified by:
        setDescriptor in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • setWrapper

        public 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.
        Specified by:
        setWrapper in interface org.eclipse.persistence.internal.identitymaps.IdentityMap

      • setWriteLockValue

        public void setWriteLockValue​(java.lang.Object primaryKey,
                              java.lang.Object writeLockValue)
        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

      • toString

        public java.lang.String toString()
        Specified by:
        toString in interface org.eclipse.persistence.internal.identitymaps.IdentityMap
        Overrides:
        toString in class java.lang.Object