All Superinterfaces:

java.lang.Cloneable

All Known Implementing Classes:

AbstractIdentityMap, CacheIdentityMap, CacheInterceptor, FullIdentityMap, HardCacheWeakIdentityMap, NoIdentityMap, SoftCacheWeakIdentityMap, SoftIdentityMap, UnitOfWorkIdentityMap, WeakIdentityMap, WeakUnitOfWorkIdentityMap
```
public interface IdentityMap
extends java.lang.Cloneable
```
Purpose: Provides the interface for IdentityMap interaction.
Responsibilities: Provides access to all of the public interface for the EclipseLink IdentityMaps. This interface can be used if implementing custom identity maps that are radically different than the stock IdentityMaps otherwise simply extending the appropriate IdentityMap implementation is the best approach.

Since:

EclipseLink 1.0M7

See Also:

CacheKey

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
`CacheKey`	`acquireDeferredLock(java.lang.Object primaryKey, boolean isCacheCheckComplete)`	Acquire a deferred lock on the object.
`CacheKey`	`acquireLock(java.lang.Object primaryKey, boolean forMerge, boolean isCacheCheckComplete)`	Acquire an active lock on the object.
`CacheKey`	`acquireLockNoWait(java.lang.Object primaryKey, boolean forMerge)`	Acquire an active lock on the object, if not already locked.
`CacheKey`	`acquireLockWithWait(java.lang.Object primaryKey, boolean forMerge, int wait)`	Acquire an active lock on the object, if not already locked.
`CacheKey`	`acquireReadLockOnCacheKey(java.lang.Object primaryKey)`	Acquire a read lock on the object.
`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.
`java.util.Enumeration<CacheKey>`	`cloneKeys()`	Allow for the CacheKeys to be iterated on using copy of keys enumeration.
`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.
`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,CacheKey>`	`getAllCacheKeysFromIdentityMapWithEntityPK(java.lang.Object[] pkList, ClassDescriptor descriptor, 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, AbstractSession session)`	ADVANCED: Using a list of Entity PK this method will attempt to bulk load the entire list from the cache.
`CacheKey`	`getCacheKey(java.lang.Object primaryKey, boolean forMerge)`	Get the cache key (with object) for the primary key.
`CacheKey`	`getCacheKeyForLock(java.lang.Object primaryKey)`	Get the cache key (with object) for the primary key in order to acquire a lock.
`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.
`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<CacheKey>`	`keys()`	Allow for the CacheKeys to be iterated on.
`java.util.Enumeration<CacheKey>`	`keys(boolean checkReadLocks)`	Allow for the CacheKeys to be iterated on.
`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
`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()`	This method may be called during initialize all identity maps.
`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(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.

- Method Detail
  - acquireDeferredLock
```
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.
  - acquireLock
```
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.
  - acquireLockNoWait
```
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.
  - acquireLockWithWait
```
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.
  - acquireReadLockOnCacheKey
```
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.
  - acquireReadLockOnCacheKeyNoWait
```
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.
  - clone
```
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.
  - collectLocks
```
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.
  - containsKey
```
boolean containsKey(java.lang.Object primaryKey)
```
    Return true if an CacheKey with the primary key is in the map. User API.
    
    Parameters:
    
    primaryKey - is the primary key for the object to search for.
  - elements
```
java.util.Enumeration elements()
```
    Allow for the cache to be iterated on.
  - get
```
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.
  - getAllFromIdentityMapWithEntityPK
```
java.util.Map<java.lang.Object,java.lang.Object> getAllFromIdentityMapWithEntityPK(java.lang.Object[] pkList,
                                                                                         ClassDescriptor descriptor,
                                                                                         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.
    
    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
```
java.util.Map<java.lang.Object,CacheKey> getAllCacheKeysFromIdentityMapWithEntityPK(java.lang.Object[] pkList,
                                                                                          ClassDescriptor descriptor,
                                                                                          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.
    
    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
```
CacheKey getCacheKey(java.lang.Object primaryKey,
                     boolean forMerge)
```
    Get the cache key (with object) for the primary key.
  - getCacheKeyForLock
```
CacheKey getCacheKeyForLock(java.lang.Object primaryKey)
```
    Get the cache key (with object) for the primary key in order to acquire a lock.
  - getDescriptorClass
```
java.lang.Class getDescriptorClass()
```
    Return the class that this is the map for.
  - getDescriptor
```
ClassDescriptor getDescriptor()
```
    Return the descriptor that this is the map for.
  - getMaxSize
```
int getMaxSize()
```
    Returns:
    
    The maxSize for the IdentityMap (NOTE: some subclasses may use this differently).
  - getSize
```
int getSize()
```
    Return the number of CacheKeys in the IdentityMap. This may contain weak referenced objects that have been garbage collected.
  - getSize
```
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.
  - getWrapper
```
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.
  - getWriteLockValue
```
java.lang.Object getWriteLockValue(java.lang.Object primaryKey)
```
    Get the write lock value from the cache key associated to the primarykey. User API.
  - keys
```
java.util.Enumeration<CacheKey> keys()
```
    Allow for the CacheKeys to be iterated on. Read locks should be checked
  - cloneKeys
```
java.util.Enumeration<CacheKey> cloneKeys()
```
    Allow for the CacheKeys to be iterated on using copy of keys enumeration. This is thread safe access to keys.
    
    Returns:
    
    clone of the CacheKeys enumeration
  - keys
```
java.util.Enumeration<CacheKey> keys(boolean checkReadLocks)
```
    Allow for the CacheKeys to be iterated on.
    
    Parameters:
    
    checkReadLocks - - true if readLocks should be checked, false otherwise.
  - lazyRelationshipLoaded
```
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
  - put
```
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.
    
    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
```
void release()
```
    This method may be called during initialize all identity maps. It allows the identity map or interceptor the opportunity to release any resources before being thrown away.
  - remove
```
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.
  - remove
```
java.lang.Object remove(CacheKey cacheKey)
```
    Remove the CacheKey from the map.
  - updateMaxSize
```
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.
  - setDescriptor
```
void setDescriptor(ClassDescriptor descriptor)
```
    Set the descriptor that this is the map for.
  - setWrapper
```
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.
  - setWriteLockValue
```
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.
  - toString
```
java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Interface IdentityMap

Method Summary

Method Detail

acquireDeferredLock

acquireLock

acquireLockNoWait

acquireLockWithWait

acquireReadLockOnCacheKey

acquireReadLockOnCacheKeyNoWait

clone

collectLocks

containsKey

elements

get

getAllFromIdentityMapWithEntityPK

getAllCacheKeysFromIdentityMapWithEntityPK

getCacheKey

getCacheKeyForLock

getDescriptorClass

getDescriptor

getMaxSize

getSize

getSize

getWrapper

getWriteLockValue

keys

cloneKeys

keys

lazyRelationshipLoaded

put

release

remove

remove

updateMaxSize

setDescriptor

setWrapper

setWriteLockValue

toString