org.eclipse.persistence.sessions.IdentityMapAccessor Maven / Gradle / Ivy
Show all versions of eclipselink Show documentation
/*
* Copyright (c) 1998, 2019 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:
// Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.sessions;
import java.util.Collection;
import java.util.Vector;
import org.eclipse.persistence.exceptions.QueryException;
import org.eclipse.persistence.expressions.Expression;
import org.eclipse.persistence.queries.InMemoryQueryIndirectionPolicy;
import org.eclipse.persistence.queries.ReadQuery;
/**
* PUBLIC:
* IdentityMapAccessor provides the public interface into all functionality associated with
* EclipseLink's cache. An appropriate IdentityMapAccessor can be obtained from a session
* with its getIdentityMapAccessor() method.
* Methods that used to be called on the Session to access identity maps can now be called
* through the IdentityMapAccessor.
*
* For instance, to initialize identity maps the code used to be:
*
* session.initializeIdentityIdentityMaps()
* With this class, the code now is:
* session.getIdentityMapAccessor().initializeIdentityMaps()
*
NOTE: Be careful using this method. This method blows away both this session's and its parent's caches.
* This includes the server cache or any other cache. This throws away any Objects that have been read in.
* Extreme caution should be used before doing this because Object identity will no longer
* be maintained for any Objects currently read in. This should only be called
* if the application knows that it no longer has references to Objects held in the cache.
*/
void initializeAllIdentityMaps();
/**
* PUBLIC:
* Resets the identity map for only the instances of the given Class type.
* For inheritance the user must make sure that they only use the root class.
*
NOTE: Caution must be used in doing this to ensure that the Objects within the identity map
* are not referenced from other Objects of other classes or from the application.
* @param theClass Class
*/
void initializeIdentityMap(Class theClass);
/**
* PUBLIC:
* Resets the entire local Object cache.
*
NOTE: This throws away any Objects that have been read in.
* Extreme caution should be used before doing this because Object identity will no longer
* be maintained for any Objects currently read in. This should only be called
* if the application knows that it no longer has references to Objects held in the cache.
*/
void initializeIdentityMaps();
/**
* ADVANCED:
* Sets an Object to be invalid in the cache.
* If this Object does not exist in the cache, this method will return
* without any action.
* @param object Object
*/
void invalidateObject(Object object);
/**
* ADVANCED:
* Set an object to be invalid in the cache.
* @param invalidateCluster if true the invalidation will be broadcast to each server in the cluster.
*/
void invalidateObject(Object object, boolean invalidateCluster);
/**
* ADVANCED:
* Sets an Object with the specified primary key and Class type to be invalid in
* the cache. If the Object does not exist in the cache,
* this method will return without any action.
*/
void invalidateObject(Object primaryKey, Class theClass);
/**
* ADVANCED:
* Set an object to be invalid in the cache.
* @param invalidateCluster if true the invalidation will be broadcast to each server in the cluster.
*/
void invalidateObject(Object primaryKey, Class theClass, boolean invalidateCluster);
/**
* ADVANCED:
* Sets an Object with the specified primary key of the passed in Row and Class type to
* be invalid in the cache. If the Object does not exist in the cache,
* this method will return without any action.
*/
void invalidateObject(Record rowContainingPrimaryKey, Class theClass);
/**
* ADVANCED:
* Set an object to be invalid in the cache.
* @param invalidateCluster if true the invalidation will be broadcast to each server in the cluster.
*/
void invalidateObject(Record rowContainingPrimaryKey, Class theClass, boolean invalidateCluster);
/**
* ADVANCED:
* Sets all of the Objects in the given collection to be invalid in the TopLink identity maps.
* This method will take no action for any Objects in the collection that do not exist in the cache.
* @param collection objects to be invalidated
*/
void invalidateObjects(Collection collection);
/**
* ADVANCED:
* Set all of the objects in the given collection to be invalid in the cache.
* @param invalidateCluster if true the invalidation will be broadcast to each server in the cluster.
*/
void invalidateObjects(Collection collection, boolean invalidateCluster);
/**
* ADVANCED:
* Sets all of the Objects matching the given Expression to be invalid in the cache.
*
* Example - Invalidating Employee Objects with non-null first names:
*
*
* ExpressionBuilder eb = new ExpressionBuilder(Employee.class);
* Expression exp = eb.get("firstName").notNull();
* session.getIdentityMapAccessor().invalidateObjects(exp);
*
* @param selectionCriteria Expression
*/
void invalidateObjects(Expression selectionCriteria);
/**
* ADVANCED:
* Queries the cache in-memory with the passed in criteria and invalidates matching Objects.
* If the expression is too complex either all or none object of theClass invalidated (depending on shouldInvalidateOnException value).
* @param selectionCriteria Expression selecting the Objects to be returned
* @param theClass Class to be considered
* @param translationRow Record
* @param shouldInvalidateOnException boolean indicates weather to invalidate the object if conform threw exception.
*/
void invalidateObjects(Expression selectionCriteria, Class theClass, Record translationRow, boolean shouldInvalidateOnException);
/**
* ADVANCED:
* Sets all of the Objects for all classes to be invalid in the cache.
* It will recurse on inheritance.
*/
void invalidateAll();
/**
* ADVANCED:
* Sets all of the Objects of the specified Class type to be invalid in the cache.
* Will set the recurse on inheritance to true.
*/
void invalidateClass(Class theClass);
/**
* ADVANCED:
* Sets all of the Objects of the specified Class type to be invalid in the cache.
* User can set the recurse flag to false if they do not want to invalidate
* all the same Class types within an inheritance tree.
* @param theClass Class
* @param recurse boolean
*/
void invalidateClass(Class theClass, boolean recurse);
/**
* ADVANCED:
* Returns true if an Object with the same primary key and Class type of the
* the given Object is valid in the cache.
*/
boolean isValid(Object object);
/**
* ADVANCED:
* Returns true if the Object described by the given primary key and Class type is valid
* in the cache.
*/
boolean isValid(Object primaryKey, Class theClass);
/**
* ADVANCED:
* Returns true if this Object with the given primary key of the Row and Class type
* given is valid in the cache.
*/
boolean isValid(Record rowContainingPrimaryKey, Class theClass);
/**
* PUBLIC:
* Used to print all the Objects in the identity map of the given Class type.
* The output of this method will be logged to this session's SessionLog at SEVERE level.
*/
void printIdentityMap(Class theClass);
/**
* PUBLIC:
* Used to print all the Objects in every identity map in this session.
* The output of this method will be logged to this session's SessionLog at SEVERE level.
*/
void printIdentityMaps();
/**
* PUBLIC:
* Used to print all the locks in every identity map in this session.
* The output of this method will be logged to this session's SessionLog at FINEST level.
*/
void printIdentityMapLocks();
/**
* ADVANCED:
* Registers the given Object with the identity map.
* The Object must always be registered with its version number if optimistic locking is used.
* @param domainObject Object
* @return Object
*/
Object putInIdentityMap(Object domainObject);
/**
* ADVANCED:
* Registers the Object and given key with the identity map.
* The Object must always be registered with its version number if optimistic locking is used.
*/
Object putInIdentityMap(Object domainObject, Object key);
/**
* ADVANCED:
* Registers the Object and given key with the identity map.
* The Object must always be registered with its version number if optimistic locking is used.
*/
Object putInIdentityMap(Object domainObject, Object key, Object writeLockValue);
/**
* ADVANCED:
* Registers the given Object with the identity map.
* The Object must always be registered with its version number if optimistic locking is used.
* The readTime may also be included in the cache key as it is constructed.
* @param domainObject Object
* @param key Object
* @param writeLockValue Object for versioning
* @param readTime long, time in milliseconds
* @return Object the Object put into the identity map
*/
Object putInIdentityMap(Object domainObject, Object key, Object writeLockValue, long readTime);
/**
* ADVANCED:
* Removes the Object from the Object cache.
*
NOTE: Caution should be used when calling to avoid violating Object identity.
* The application should only call this if its known that no references to the Object exist.
* @param domainObject Object
* @return Object the Object removed from the identity map
*/
Object removeFromIdentityMap(Object domainObject);
/**
* ADVANCED:
* Removes the Object with given primary key and Class from the Object cache.
*
NOTE: Caution should be used when calling to avoid violating Object identity.
* The application should only call this if its known that no references to the Object exist.
* @return Object the Object removed from the identity map
*/
Object removeFromIdentityMap(Object key, Class theClass);
/**
* ADVANCED:
* Updates the write lock value in the identity map for cache key of the primary key
* the given Object.
* @param domainObject Object
* @param writeLockValue Object for versioning
*/
void updateWriteLockValue(Object domainObject, Object writeLockValue);
/**
* ADVANCED:
* Updates the write lock value in the cache for the Object with same primary key as the given Object.
* The write lock values is used when optimistic locking is stored in the cache instead of in the object.
*/
void updateWriteLockValue(Object primaryKey, Class theClass, Object writeLockValue);
/**
* ADVANCED:
* This can be used to help debugging an Object identity problem.
* An Object identity problem is when an Object in the cache references an
* Object that is not in the cache. This method will validate that all cached
* Objects are in a correct state.
*/
void validateCache();
}