All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.eclipse.persistence.internal.identitymaps.IdentityMap Maven / Gradle / Ivy

The newest version!
/*
 * Copyright (c) 1998, 2024 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 org.eclipse.persistence.descriptors.ClassDescriptor;
import org.eclipse.persistence.indirection.ValueHolderInterface;
import org.eclipse.persistence.internal.sessions.AbstractSession;
import org.eclipse.persistence.mappings.ForeignReferenceMapping;

import java.util.Enumeration;
import java.util.Map;
import java.util.Set;

/**
 * 

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. * * @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. */ IdentityMap clone(); /** * Add all locked CacheKeys to the map grouped by thread. * Used to print all the locks in the identity map. */ void collectLocks(Map> 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 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 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 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 cloneKeys(); /** * Allow for the CacheKeys to be iterated on. * @param checkReadLocks - true if readLocks should be checked, false otherwise. */ Enumeration 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(); }