org.eclipse.persistence.internal.identitymaps

Class AbstractIdentityMap

java.lang.Object

org.eclipse.persistence.internal.identitymaps.AbstractIdentityMap

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, IdentityMap

Direct Known Subclasses:

FullIdentityMap, NoIdentityMap

public abstract class AbstractIdentityMap
extends java.lang.Object
implements IdentityMap, java.io.Serializable, java.lang.Cloneable

Purpose: Caches objects, and allows their retrieval by their primary key.

Responsibilities:

• Store CacheKeys containing objects and possibly writeLockValues.
• Insert & retrieve objects from the cache.
• Allow retrieval and modification of writeLockValue for a cached object.

Since:

TOPLink/Java 1.0

See Also:

CacheKey, Serialized Form

Constructor Summary

Constructors

Constructor and Description
AbstractIdentityMap()
AbstractIdentityMap(int size, ClassDescriptor descriptor, AbstractSession session, boolean isolated) Instantiate an new IdentityMap with it's maximum size.

Method Summary

Modifier and Type	Method and 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.
abstract 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.
CacheKey	createCacheKey(java.lang.Object primaryKey, java.lang.Object object, java.lang.Object writeLockValue, long readTime) Create the correct type of CacheKey for this map.
abstract 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.
abstract 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.
static java.lang.Class	getDefaultIdentityMapClass() Returns the class which should be used as an identity map in a descriptor by default.
ClassDescriptor	getDescriptor() Return the class that this is the map for.
java.lang.Class	getDescriptorClass() Return the class that this is the map for.
int	getMaxSize()
abstract int	getSize() Return the number of CacheKeys in the IdentityMap.
abstract 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.
abstract java.util.Enumeration	keys() Allow for the CacheKeys to be iterated on.
abstract 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.
abstract java.lang.Object	remove(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	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, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

keys, lazyRelationshipLoaded

Constructor Detail

AbstractIdentityMap

public AbstractIdentityMap()

AbstractIdentityMap

public AbstractIdentityMap(int size,
                           ClassDescriptor descriptor,
                           AbstractSession session,
                           boolean isolated)

Instantiate an new IdentityMap with it's maximum size.

NOTE: Subclasses may provide different behavior for maxSize.

Parameters:

size - is the maximum size to be allocated for the receiver.

Method Detail

acquireDeferredLock

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

acquireLock

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

acquireLockNoWait

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

acquireLockWithWait

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

acquireReadLockOnCacheKey

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

acquireReadLockOnCacheKeyNoWait

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

collectLocks

public abstract 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 IdentityMap

clone

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

Parameters:

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

createCacheKey

public CacheKey createCacheKey(java.lang.Object primaryKey,
                               java.lang.Object object,
                               java.lang.Object writeLockValue,
                               long readTime)

Create the correct type of CacheKey for this map.

elements

public abstract java.util.Enumeration elements()

Allow for the cache to be iterated on.

Specified by:

elements in interface 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 IdentityMap

getAllFromIdentityMapWithEntityPK

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

Specified by:

getAllFromIdentityMapWithEntityPK in interface IdentityMap

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

Specified by:

getAllCacheKeysFromIdentityMapWithEntityPK in interface IdentityMap

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 abstract CacheKey getCacheKey(java.lang.Object primaryKey,
                                     boolean forMerge)

Get the cache key (with object) for the primary key.

Specified by:

getCacheKey in interface IdentityMap

getCacheKeyForLock

public CacheKey getCacheKeyForLock(java.lang.Object primaryKey)

Get the cache key (with object) for the primary key.

Specified by:

getCacheKeyForLock in interface IdentityMap

getDefaultIdentityMapClass

public static java.lang.Class getDefaultIdentityMapClass()

Returns the class which should be used as an identity map in a descriptor by default.

getMaxSize

public int getMaxSize()

Specified by:

getMaxSize in interface IdentityMap

Returns:

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

getSize

public abstract 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 IdentityMap

getSize

public abstract 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 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 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 IdentityMap

keys

public abstract java.util.Enumeration keys()

Allow for the CacheKeys to be iterated on.

Specified by:

keys in interface IdentityMap

put

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

release

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

Specified by:

release in interface IdentityMap

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 IdentityMap

remove

public abstract java.lang.Object remove(CacheKey cacheKey)

Remove the CacheKey from the map.

Specified by:

remove in interface 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 IdentityMap

getDescriptor

public ClassDescriptor getDescriptor()

Return the class that this is the map for.

Specified by:

getDescriptor in interface IdentityMap

getDescriptorClass

public java.lang.Class getDescriptorClass()

Return the class that this is the map for.

Specified by:

getDescriptorClass in interface IdentityMap

setDescriptor

public void setDescriptor(ClassDescriptor descriptor)

Set the descriptor that this is the map for.

Specified by:

setDescriptor in interface 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 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 IdentityMap

toString

public java.lang.String toString()

Specified by:

toString in interface IdentityMap

Overrides:

toString in class java.lang.Object