foundation/org.eclipse.persistence.core/src/main/java/org/eclipse/persistence/internal/identitymaps/IdentityMap.java - eclipselink - Git at Google

 /*
  * Copyright (c) 1998, 2021 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
  * http://www.eclipse.org/legal/epl-2.0,
  * or the Eclipse Distribution License v. 1.0 which is available at
  * http://www.eclipse.org/org/documents/edl-v10.php.
  *
  * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
  */

 // Contributors:
 //     Gordon Yorke - Part of the Cache Interceptor feature. (ER 219683)
 //     12/14/2017-3.0 Tomas Kraus
 //       - 522635: ConcurrentModificationException when triggering lazy load from conforming query
 package org.eclipse.persistence.internal.identitymaps;

 import java.util.Enumeration;
 import java.util.HashMap;
 import java.util.Map;

 import org.eclipse.persistence.descriptors.ClassDescriptor;
 import org.eclipse.persistence.exceptions.QueryException;
 import org.eclipse.persistence.indirection.ValueHolderInterface;
 import org.eclipse.persistence.internal.sessions.AbstractSession;
 import org.eclipse.persistence.mappings.ForeignReferenceMapping;

 /**
  * <p><b>Purpose</b>: Provides the interface for IdentityMap interaction.
  * <p><b>Responsibilities</b>:
  * 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.
  *
  * @see CacheKey
  * @since EclipseLink 1.0M7
  */
 public interface IdentityMap extends Cloneable{

     /**
      * 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.
      */
     CacheKey acquireDeferredLock(Object primaryKey, boolean isCacheCheckComplete);

     /**
      * Acquire an active lock on the object.
      * This is used by reading (when using indirection or no relationships) and by merge.
      */
     CacheKey acquireLock(Object primaryKey, boolean forMerge, boolean isCacheCheckComplete);

     /**
      * Acquire an active lock on the object, if not already locked.
      * This is used by merge for missing existing objects.
      */
     CacheKey acquireLockNoWait(Object primaryKey, boolean forMerge);

     /**
      * Acquire an active lock on the object, if not already locked.
      * This is used by merge for missing existing objects.
      */
     CacheKey acquireLockWithWait(Object primaryKey, boolean forMerge, int wait);

     /**
      * 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.
      */
     CacheKey acquireReadLockOnCacheKey(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.
      */
     CacheKey acquireReadLockOnCacheKeyNoWait(Object primaryKey);

     /**
      * Clone the map and all of the CacheKeys.
      * This is used by UnitOfWork commitAndResumeOnFailure to avoid corrupting the cache during a failed commit.
      */
     Object clone();

         /**
      * Add all locked CacheKeys to the map grouped by thread.
      * Used to print all the locks in the identity map.
      */
     void collectLocks(HashMap threadList);


     /**
      * Return true if an CacheKey with the primary key is in the map.
      * User API.
      * @param primaryKey is the primary key for the object to search for.
      */
     boolean containsKey(Object primaryKey);

     /**
      * Allow for the cache to be iterated on.
      */
     Enumeration elements();

     /**
      * Return the object cached in the identity map or null if it could not be found.
      * User API.
      */
     Object get(Object primaryKey);

     /**
      * 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.
      * @param pkList List of Entity PKs to extract from the cache
      * @param descriptor Descriptor type to be retrieved.
      * @return Map of Entity PKs associated to the Entities that were retrieved
      */
     Map<Object, Object> getAllFromIdentityMapWithEntityPK(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.
      * @param pkList List of Entity PKs to extract from the cache
      * @param descriptor Descriptor type to be retrieved.
      * @return Map of Entity PKs associated to the Entities that were retrieved
      */
     Map<Object, CacheKey> getAllCacheKeysFromIdentityMapWithEntityPK(Object[] pkList, ClassDescriptor descriptor, AbstractSession session);

     /**
      * Get the cache key (with object) for the primary key.
      */
     CacheKey getCacheKey(Object primaryKey, boolean forMerge);

     /**
      * Get the cache key (with object) for the primary key in order to acquire a lock.
      */
     CacheKey getCacheKeyForLock(Object primaryKey);

         /**
      * Return the class that this is the map for.
      */
     Class getDescriptorClass();

     /**
      * Return the descriptor that this is the map for.
      */
     ClassDescriptor getDescriptor();

     /**
      * @return The maxSize for the IdentityMap (NOTE: some subclasses may use this differently).
      */
     int getMaxSize();

     /**
      * Return the number of CacheKeys in the IdentityMap.
      * This may contain weak referenced objects that have been garbage collected.
      */
     int getSize();

     /**
      * Return the number of actual objects of type myClass in the IdentityMap.
      * Recurse = true will include subclasses of myClass in the count.
      */
     int getSize(Class myClass, boolean recurse);

     /**
      * Get the wrapper object from the cache key associated with the given primary key,
      * this is used for EJB2.
      */
     Object getWrapper(Object primaryKey);

     /**
      * Get the write lock value from the cache key associated to the primarykey.
      * User API.
      */
     Object getWriteLockValue(Object primaryKey);

     /**
      * Allow for the CacheKeys to be iterated on.
      * Read locks should be checked
      */
     Enumeration<CacheKey> keys();

     /**
      * Allow for the CacheKeys to be iterated on using copy of keys enumeration.
      * This is thread safe access to keys.
      *
      * @return clone of the CacheKeys enumeration
      */
     Enumeration<CacheKey> cloneKeys();

     /**
      * Allow for the CacheKeys to be iterated on.
      * @param checkReadLocks - true if readLocks should be checked, false otherwise.
      */
     Enumeration<CacheKey> keys(boolean checkReadLocks);

     /**
      * Notify the cache that a lazy relationship has been triggered in the object
      * and the cache may need to be updated
      */
     void lazyRelationshipLoaded(Object rootEntity, ValueHolderInterface valueHolder,  ForeignReferenceMapping mapping);

     /**
      * 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.
      * @param primaryKey is the primary key for the object.
      * @param object is the domain object to cache.
      * @param writeLockValue is the current write lock value of object, if null the version is ignored.
      */
     CacheKey put(Object primaryKey, Object object, Object writeLockValue, long readTime);

     /**
      * 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.
      */
     void release();

     /**
      * Remove the CacheKey with the primaryKey from the map.
      * This is used by DeleteObjectQuery and merge.
      * This is also an advanced (very) user API.
      */
     Object remove(Object primaryKey, Object object);

     /**
      * Remove the CacheKey from the map.
      */
     Object remove(CacheKey cacheKey);

     /**
      * 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.
      */
     void updateMaxSize(int maxSize);

     /**
      * Set the descriptor that this is the map for.
      */
     void setDescriptor(ClassDescriptor descriptor);

     /**
      * Update the wrapper object in the CacheKey associated with the given primaryKey,
      * this is used for EJB2.
      */
     void setWrapper(Object primaryKey, Object wrapper);

     /**
      * 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.
      */
     void setWriteLockValue(Object primaryKey, Object writeLockValue);

     @Override
     String toString();
 }
	/*
	* Copyright (c) 1998, 2021 Oracle and/or its affiliates. All rights reserved.
	*
	* This program and the accompanying materials are made available under the
	* terms of the Eclipse Public License v. 2.0 which is available at
	* http://www.eclipse.org/legal/epl-2.0,
	* or the Eclipse Distribution License v. 1.0 which is available at
	* http://www.eclipse.org/org/documents/edl-v10.php.
	*
	* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
	*/

	// Contributors:
	// Gordon Yorke - Part of the Cache Interceptor feature. (ER 219683)
	// 12/14/2017-3.0 Tomas Kraus
	// - 522635: ConcurrentModificationException when triggering lazy load from conforming query
	package org.eclipse.persistence.internal.identitymaps;

	import java.util.Enumeration;
	import java.util.HashMap;
	import java.util.Map;

	import org.eclipse.persistence.descriptors.ClassDescriptor;
	import org.eclipse.persistence.exceptions.QueryException;
	import org.eclipse.persistence.indirection.ValueHolderInterface;
	import org.eclipse.persistence.internal.sessions.AbstractSession;
	import org.eclipse.persistence.mappings.ForeignReferenceMapping;

	/**
	* <p><b>Purpose</b>: Provides the interface for IdentityMap interaction.
	* <p><b>Responsibilities</b>:
	* 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.
	*
	* @see CacheKey
	* @since EclipseLink 1.0M7
	*/
	public interface IdentityMap extends Cloneable{

	/**
	* 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.
	*/
	CacheKey acquireDeferredLock(Object primaryKey, boolean isCacheCheckComplete);

	/**
	* Acquire an active lock on the object.
	* This is used by reading (when using indirection or no relationships) and by merge.
	*/
	CacheKey acquireLock(Object primaryKey, boolean forMerge, boolean isCacheCheckComplete);

	/**
	* Acquire an active lock on the object, if not already locked.
	* This is used by merge for missing existing objects.
	*/
	CacheKey acquireLockNoWait(Object primaryKey, boolean forMerge);

	/**
	* Acquire an active lock on the object, if not already locked.
	* This is used by merge for missing existing objects.
	*/
	CacheKey acquireLockWithWait(Object primaryKey, boolean forMerge, int wait);

	/**
	* 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.
	*/
	CacheKey acquireReadLockOnCacheKey(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.
	*/
	CacheKey acquireReadLockOnCacheKeyNoWait(Object primaryKey);

	/**
	* Clone the map and all of the CacheKeys.
	* This is used by UnitOfWork commitAndResumeOnFailure to avoid corrupting the cache during a failed commit.
	*/
	Object clone();

	/**
	* Add all locked CacheKeys to the map grouped by thread.
	* Used to print all the locks in the identity map.
	*/
	void collectLocks(HashMap threadList);


	/**
	* Return true if an CacheKey with the primary key is in the map.
	* User API.
	* @param primaryKey is the primary key for the object to search for.
	*/
	boolean containsKey(Object primaryKey);

	/**
	* Allow for the cache to be iterated on.
	*/
	Enumeration elements();

	/**
	* Return the object cached in the identity map or null if it could not be found.
	* User API.
	*/
	Object get(Object primaryKey);

	/**
	* 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.
	* @param pkList List of Entity PKs to extract from the cache
	* @param descriptor Descriptor type to be retrieved.
	* @return Map of Entity PKs associated to the Entities that were retrieved
	*/
	Map<Object, Object> getAllFromIdentityMapWithEntityPK(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.
	* @param pkList List of Entity PKs to extract from the cache
	* @param descriptor Descriptor type to be retrieved.
	* @return Map of Entity PKs associated to the Entities that were retrieved
	*/
	Map<Object, CacheKey> getAllCacheKeysFromIdentityMapWithEntityPK(Object[] pkList, ClassDescriptor descriptor, AbstractSession session);

	/**
	* Get the cache key (with object) for the primary key.
	*/
	CacheKey getCacheKey(Object primaryKey, boolean forMerge);

	/**
	* Get the cache key (with object) for the primary key in order to acquire a lock.
	*/
	CacheKey getCacheKeyForLock(Object primaryKey);

	/**
	* Return the class that this is the map for.
	*/
	Class getDescriptorClass();

	/**
	* Return the descriptor that this is the map for.
	*/
	ClassDescriptor getDescriptor();

	/**
	* @return The maxSize for the IdentityMap (NOTE: some subclasses may use this differently).
	*/
	int getMaxSize();

	/**
	* Return the number of CacheKeys in the IdentityMap.
	* This may contain weak referenced objects that have been garbage collected.
	*/
	int getSize();

	/**
	* Return the number of actual objects of type myClass in the IdentityMap.
	* Recurse = true will include subclasses of myClass in the count.
	*/
	int getSize(Class myClass, boolean recurse);

	/**
	* Get the wrapper object from the cache key associated with the given primary key,
	* this is used for EJB2.
	*/
	Object getWrapper(Object primaryKey);

	/**
	* Get the write lock value from the cache key associated to the primarykey.
	* User API.
	*/
	Object getWriteLockValue(Object primaryKey);

	/**
	* Allow for the CacheKeys to be iterated on.
	* Read locks should be checked
	*/
	Enumeration<CacheKey> keys();

	/**
	* Allow for the CacheKeys to be iterated on using copy of keys enumeration.
	* This is thread safe access to keys.
	*
	* @return clone of the CacheKeys enumeration
	*/
	Enumeration<CacheKey> cloneKeys();

	/**
	* Allow for the CacheKeys to be iterated on.
	* @param checkReadLocks - true if readLocks should be checked, false otherwise.
	*/
	Enumeration<CacheKey> keys(boolean checkReadLocks);

	/**
	* Notify the cache that a lazy relationship has been triggered in the object
	* and the cache may need to be updated
	*/
	void lazyRelationshipLoaded(Object rootEntity, ValueHolderInterface valueHolder, ForeignReferenceMapping mapping);

	/**
	* 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.
	* @param primaryKey is the primary key for the object.
	* @param object is the domain object to cache.
	* @param writeLockValue is the current write lock value of object, if null the version is ignored.
	*/
	CacheKey put(Object primaryKey, Object object, Object writeLockValue, long readTime);

	/**
	* 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.
	*/
	void release();

	/**
	* Remove the CacheKey with the primaryKey from the map.
	* This is used by DeleteObjectQuery and merge.
	* This is also an advanced (very) user API.
	*/
	Object remove(Object primaryKey, Object object);

	/**
	* Remove the CacheKey from the map.
	*/
	Object remove(CacheKey cacheKey);

	/**
	* 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.
	*/
	void updateMaxSize(int maxSize);

	/**
	* Set the descriptor that this is the map for.
	*/
	void setDescriptor(ClassDescriptor descriptor);

	/**
	* Update the wrapper object in the CacheKey associated with the given primaryKey,
	* this is used for EJB2.
	*/
	void setWrapper(Object primaryKey, Object wrapper);

	/**
	* 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.
	*/
	void setWriteLockValue(Object primaryKey, Object writeLockValue);

	@Override
	String toString();
	}