Skip navigation links

oracle.toplink.sessions
Interface IdentityMapAccessor

public interface IdentityMapAccessor

PUBLIC: IdentityMapAccessor provides the public interface into all functionality associated with TopLink identity maps. 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()

See Also:

Session

Method Summary

void	clearQueryCache() ADVANCED: Clears all the query caches.
void	clearQueryCache(ReadQuery query) ADVANCED: Clears the query cache of the results associated with the given read query.
void	clearQueryCache(java.lang.String sessionQueryName) ADVANCED: Clears the query cache of the results associated with the given session query name.
void	clearQueryCache(java.lang.String descriptorQueryName, java.lang.Class queryClass) ADVANCED: Clears the query cache associated with the given descriptor query name and Class type.
boolean	containsObjectInIdentityMap(java.lang.Object domainObject) ADVANCED: Returns true if the identity map contains an Object with the same primary key and Class type of the given domainObject.
boolean	containsObjectInIdentityMap(Record rowContainingPrimaryKey, java.lang.Class theClass) ADVANCED: Returns true if the identity map contains an Object with the same primary key of the specified row (ie. the database record) and Class type.
boolean	containsObjectInIdentityMap(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Returns true if the identity map contains an Object with the same primary key and Class type as those specified.
java.util.Vector	getAllFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, Record translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy) ADVANCED: Queries the cache in-memory with the passed in criteria and returns matching Objects.
java.util.Vector	getAllFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, Record translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy, boolean shouldReturnInvalidatedObjects) ADVANCED: Queries the cache in-memory with the passed in criteria and returns matching Objects.
java.lang.Object	getFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, Record translationRow) ADVANCED: Queries the cache in-memory and returns an Object from this identity map.
java.lang.Object	getFromIdentityMap(Expression selectionCriteria, java.lang.Class theClass, Record translationRow, InMemoryQueryIndirectionPolicy valueHolderPolicy) ADVANCED: Queries the cache in-memory and returns an Object from this identity map.
java.lang.Object	getFromIdentityMap(java.lang.Object domainObject) ADVANCED: Returns the Object from the identity map with the same primary key and Class type of the given domainObject.
java.lang.Object	getFromIdentityMap(Record rowContainingPrimaryKey, java.lang.Class theClass) ADVANCED: Returns the Object from the identity map with the same primary key of the specified row (ie. the database record) and Class type.
java.lang.Object	getFromIdentityMap(Record rowContainingPrimaryKey, java.lang.Class theClass, boolean shouldReturnInvalidatedObjects) ADVANCED: Returns the Object from the identity map with the same primary key of the specified row and Class type.
java.lang.Object	getFromIdentityMap(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Returns the Object from the identity map with the same primary key and Class type as those specified.
java.lang.Object	getFromIdentityMap(java.util.Vector primaryKey, java.lang.Class theClass, boolean shouldReturnInvalidatedObjects) ADVANCED: Returns the Object from the identity map with the same primary key and Class type as specified.
long	getRemainingValidTime(java.lang.Object object) ADVANCED: Returns the remaining life of the given Object.
java.lang.Object	getWriteLockValue(java.lang.Object domainObject) ADVANCED: Extracts and returns the write lock value from the identity map through the given Object.
java.lang.Object	getWriteLockValue(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Extracts the write lock value from the identity map through the passed in primaryKey and Class type.
void	initializeAllIdentityMaps() PUBLIC: Resets the entire Object cache.
void	initializeIdentityMap(java.lang.Class theClass) PUBLIC: Resets the identity map for only the instances of the given Class type.
void	initializeIdentityMaps() PUBLIC: Resets the entire local Object cache.
void	invalidateAll() ADVANCED: Sets all of the Objects for all classes to be invalid in TopLink's identity maps.
void	invalidateClass(java.lang.Class myClass) ADVANCED: Sets all of the Objects of the specified Class type to be invalid in TopLink's identity maps Will set the recurse on inheritance to true.
void	invalidateClass(java.lang.Class myClass, boolean recurse) ADVANCED: Sets all of the Objects of the specified Class type to be invalid in TopLink's identity maps.
void	invalidateObject(java.lang.Object object) ADVANCED: Sets an Object to be invalid in the TopLink identity maps.
void	invalidateObject(Record rowContainingPrimaryKey, java.lang.Class theClass) ADVANCED: Sets an Object with the specified primary key of the passed in Row and Class type to be invalid in the TopLink identity maps.
void	invalidateObject(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Sets an Object with the specified primary key and Class type to be invalid in the TopLink identity maps.
void	invalidateObjects(Expression selectionCriteria) ADVANCED: Sets all of the Objects matching the given Expression to be invalid in the TopLink identity maps.
void	invalidateObjects(java.util.Vector collection) ADVANCED: Sets all of the Objects in the given collection to be invalid in the TopLink identity maps.
boolean	isValid(DatabaseRow rowContainingPrimaryKey, java.lang.Class theClass) ADVANCED: Returns true if this Object with the given primary key of the Row and Class type given is valid in TopLink's identity maps.
boolean	isValid(java.lang.Object object) ADVANCED: Returns true if an Object with the same primary key and Class type of the the given Object is valid in TopLink's identity maps.
boolean	isValid(java.util.Vector primaryKey, java.lang.Class theClass) ADVANCED: Returns true if the Object described by the given primary key and Class type is valid in TopLink's identity maps.
void	printIdentityMap(java.lang.Class businessClass) PUBLIC: Used to print all the Objects in the identity map of the given Class type.
void	printIdentityMapLocks() PUBLIC: Used to print all the locks in every identity map in this session.
void	printIdentityMaps() PUBLIC: Used to print all the Objects in every identity map in this session.
java.lang.Object	putInIdentityMap(java.lang.Object domainObject) ADVANCED: Registers the given Object with the identity map.
java.lang.Object	putInIdentityMap(java.lang.Object domainObject, java.util.Vector key) ADVANCED: Registers the Object and given key with the identity map.
java.lang.Object	putInIdentityMap(java.lang.Object domainObject, java.util.Vector key, java.lang.Object writeLockValue) ADVANCED: Registers the Object and given key with the identity map.
java.lang.Object	putInIdentityMap(java.lang.Object domainObject, java.util.Vector key, java.lang.Object writeLockValue, long readTime) ADVANCED: Registers the given Object with the identity map.
java.lang.Object	removeFromIdentityMap(java.lang.Object domainObject) ADVANCED: Removes the Object from the Object cache.
java.lang.Object	removeFromIdentityMap(java.util.Vector key, java.lang.Class theClass) ADVANCED: Removes the Object with given primary key and Class from the Object cache.
void	updateWriteLockValue(java.lang.Object domainObject, java.lang.Object writeLockValue) ADVANCED: Updates the write lock value in the identity map for cache key of the primary key the given Object.
void	updateWriteLockValue(java.util.Vector primaryKey, java.lang.Class theClass, java.lang.Object writeLockValue) ADVANCED: Updates the write lock value in the cache for the Object with same primary key as the given Object.
void	validateCache() ADVANCED: This can be used to help debugging an Object identity problem.

Method Detail

clearQueryCache

public void clearQueryCache()

ADVANCED: Clears all the query caches.

clearQueryCache

public void clearQueryCache(ReadQuery query)

ADVANCED: Clears the query cache of the results associated with the given read query.

Parameters:

query - ReadQuery

clearQueryCache

public void clearQueryCache(java.lang.String sessionQueryName)

ADVANCED: Clears the query cache of the results associated with the given session query name.

Parameters:

sessionQueryName - String

clearQueryCache

public void clearQueryCache(java.lang.String descriptorQueryName,
                            java.lang.Class queryClass)

ADVANCED: Clears the query cache associated with the given descriptor query name and Class type.

Parameters:

descriptorQueryName - String

queryClass - Class

containsObjectInIdentityMap

public boolean containsObjectInIdentityMap(java.lang.Object domainObject)

ADVANCED: Returns true if the identity map contains an Object with the same primary key and Class type of the given domainObject.

Parameters:

domainObject - Object

Returns:

boolean

containsObjectInIdentityMap

public boolean containsObjectInIdentityMap(java.util.Vector primaryKey,
                                           java.lang.Class theClass)

ADVANCED: Returns true if the identity map contains an Object with the same primary key and Class type as those specified.

Parameters:

primaryKey - Vector

theClass - Class

Returns:

boolean

containsObjectInIdentityMap

public boolean containsObjectInIdentityMap(Record rowContainingPrimaryKey,
                                           java.lang.Class theClass)

ADVANCED: Returns true if the identity map contains an Object with the same primary key of the specified row (ie. the database record) and Class type.

Parameters:

rowContainingPrimaryKey - Record

theClass - Class type to be found

Returns:

boolean - true if Object in indentity map

getAllFromIdentityMap

public java.util.Vector getAllFromIdentityMap(Expression selectionCriteria,
                                              java.lang.Class theClass,
                                              Record translationRow,
                                              InMemoryQueryIndirectionPolicy valueHolderPolicy,
                                              boolean shouldReturnInvalidatedObjects)
                                       throws QueryException

ADVANCED: Queries the cache in-memory with the passed in criteria and returns matching Objects. If the expression is too complex an exception will be thrown. Only returns Objects that are invalid from the map if specified with the boolean shouldReturnInvalidatedObjects.

Parameters:

selectionCriteria - Expression selecting the Objects to be returned

theClass - Class to be considered

translationRow - Record

valueHolderPolicy - see InMemoryQueryIndirectionPolicy

shouldReturnInvalidatedObjects - boolean - true if only invalid Objects should be returned

Returns:

Vector of Objects

Throws:

QueryException

getAllFromIdentityMap

public java.util.Vector getAllFromIdentityMap(Expression selectionCriteria,
                                              java.lang.Class theClass,
                                              Record translationRow,
                                              InMemoryQueryIndirectionPolicy valueHolderPolicy)
                                       throws QueryException

ADVANCED: Queries the cache in-memory with the passed in criteria and returns matching Objects. If the expression is too complex an exception will be thrown.

Parameters:

selectionCriteria - Expression selecting the Objects to be returned

theClass - Class to be considered

translationRow - Record

valueHolderPolicy - see InMemoryQueryIndirectionPolicy

Returns:

Vector of Objects with type theClass and matching the selectionCriteria

Throws:

QueryException

getFromIdentityMap

public java.lang.Object getFromIdentityMap(java.lang.Object domainObject)

ADVANCED: Returns the Object from the identity map with the same primary key and Class type of the given domainObject.

Parameters:

domainObject - Object

Returns:

Object from identity map, may be null.

getFromIdentityMap

public java.lang.Object getFromIdentityMap(java.util.Vector primaryKey,
                                           java.lang.Class theClass)

ADVANCED: Returns the Object from the identity map with the same primary key and Class type as those specified.

Parameters:

primaryKey - Vector

theClass - Class

Returns:

Object from identity map, may be null.

getFromIdentityMap

public java.lang.Object getFromIdentityMap(Record rowContainingPrimaryKey,
                                           java.lang.Class theClass)

ADVANCED: Returns the Object from the identity map with the same primary key of the specified row (ie. the database record) and Class type.

Parameters:

rowContainingPrimaryKey - Record

theClass - Class

Returns:

Object from identity map, may be null.

getFromIdentityMap

public java.lang.Object getFromIdentityMap(java.util.Vector primaryKey,
                                           java.lang.Class theClass,
                                           boolean shouldReturnInvalidatedObjects)

ADVANCED: Returns the Object from the identity map with the same primary key and Class type as specified. May return null and will only return an Object that is invalidated if specified with the boolean shouldReturnInvalidatedObjects.

Parameters:

primaryKey - Vector

theClass - Class

shouldReturnInvalidatedObjects - InMemoryQueryIndirectionPolicy

Returns:

Object from identity map, may be null.

getFromIdentityMap

public java.lang.Object getFromIdentityMap(Record rowContainingPrimaryKey,
                                           java.lang.Class theClass,
                                           boolean shouldReturnInvalidatedObjects)

ADVANCED: Returns the Object from the identity map with the same primary key of the specified row and Class type. May return null and will only Only return an Object that is invalidated if specified with the boolean shouldReturnInvalidatedObjects.

Parameters:

rowContainingPrimaryKey - Record

theClass - Class

shouldReturnInvalidatedObjects - boolean

Returns:

Object from identity map, may be null.

getFromIdentityMap

public java.lang.Object getFromIdentityMap(Expression selectionCriteria,
                                           java.lang.Class theClass,
                                           Record translationRow)
                                    throws QueryException

ADVANCED: Queries the cache in-memory and returns an Object from this identity map. If the Object is not found with the passed in Class type, Row and selectionCriteria, null is returned. If the expression is too complex an exception will be thrown.

Parameters:

selectionCriteria - Expression

theClass - Class

translationRow - Record

Returns:

Object from identity map, may be null

Throws:

QueryException

getFromIdentityMap

public java.lang.Object getFromIdentityMap(Expression selectionCriteria,
                                           java.lang.Class theClass,
                                           Record translationRow,
                                           InMemoryQueryIndirectionPolicy valueHolderPolicy)
                                    throws QueryException

ADVANCED: Queries the cache in-memory and returns an Object from this identity map. If the Object is not found with the passed in Class type, Row and selectionCriteria, null is returned. This method allows for control of un-instantiated indirection access with valueHolderPolicy. If the expression is too complex an exception will be thrown.

Parameters:

selectionCriteria - Expression

theClass - Class

translationRow - Record

valueHolderPolicy - see InMemoryQueryIndirectionPolicy

Returns:

Object from identity map, may be null

Throws:

QueryException

getRemainingValidTime

public long getRemainingValidTime(java.lang.Object object)

ADVANCED: Returns the remaining life of the given Object. This method is associated with use of TopLink's cache invalidation feature and returns the difference between the next expiry time of the Object and its read time. The method will return 0 for invalidated Objects.

Parameters:

object - Object under consideration

Returns:

long time in milliseconds

getWriteLockValue

public java.lang.Object getWriteLockValue(java.lang.Object domainObject)

ADVANCED: Extracts and returns the write lock value from the identity map through the given Object. Write lock values are used when optimistic locking is stored in the cache instead of the object.

Parameters:

domainObject - Object

Returns:

Object for versioning

getWriteLockValue

public java.lang.Object getWriteLockValue(java.util.Vector primaryKey,
                                          java.lang.Class theClass)

ADVANCED: Extracts the write lock value from the identity map through the passed in primaryKey and Class type. Write lock values are used when optimistic locking is stored in the cache instead of the object.

Parameters:

primaryKey - Vector

theClass - Class

Returns:

Object for versioning

initializeAllIdentityMaps

public void initializeAllIdentityMaps()

PUBLIC: Resets the entire Object cache.

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.

initializeIdentityMap

public void initializeIdentityMap(java.lang.Class theClass)

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.

Parameters:

theClass - Class

initializeIdentityMaps

public void initializeIdentityMaps()

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.

invalidateObject

public void invalidateObject(java.lang.Object object)

ADVANCED: Sets an Object to be invalid in the TopLink identity maps. If this Object does not exist in the cache, this method will return without any action.

Parameters:

object - Object

invalidateObject

public void invalidateObject(java.util.Vector primaryKey,
                             java.lang.Class theClass)

ADVANCED: Sets an Object with the specified primary key and Class type to be invalid in the TopLink identity maps. If the Object does not exist in the cache, this method will return without any action.

Parameters:

primaryKey - Vector

theClass - Class

invalidateObject

public void invalidateObject(Record rowContainingPrimaryKey,
                             java.lang.Class theClass)

ADVANCED: Sets an Object with the specified primary key of the passed in Row and Class type to be invalid in the TopLink identity maps. If the Object does not exist in the cache, this method will return without any action.

Parameters:

rowContainingPrimaryKey - Record

theClass - Class

invalidateObjects

public void invalidateObjects(java.util.Vector collection)

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.

Parameters:

collection - Vector of Objects to be invalidated

invalidateObjects

public void invalidateObjects(Expression selectionCriteria)

ADVANCED: Sets all of the Objects matching the given Expression to be invalid in the TopLink identity maps.

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);


Parameters:

selectionCriteria - Expression

invalidateAll

public void invalidateAll()

ADVANCED: Sets all of the Objects for all classes to be invalid in TopLink's identity maps. It will recurse on inheritance.

invalidateClass

public void invalidateClass(java.lang.Class myClass)

ADVANCED: Sets all of the Objects of the specified Class type to be invalid in TopLink's identity maps Will set the recurse on inheritance to true.

Parameters:

myClass - Class

invalidateClass

public void invalidateClass(java.lang.Class myClass,
                            boolean recurse)

ADVANCED: Sets all of the Objects of the specified Class type to be invalid in TopLink's identity maps. User can set the recurse flag to false if they do not want to invalidate all the same Class types within an inheritance tree.

Parameters:

myClass - Class

recurse - boolean

isValid

public boolean isValid(java.lang.Object object)

ADVANCED: Returns true if an Object with the same primary key and Class type of the the given Object is valid in TopLink's identity maps.

Parameters:

object - Object

Returns:

boolean

isValid

public boolean isValid(java.util.Vector primaryKey,
                       java.lang.Class theClass)

ADVANCED: Returns true if the Object described by the given primary key and Class type is valid in TopLink's identity maps.

Parameters:

primaryKey - Vector

theClass - Class

Returns:

boolean

isValid

public boolean isValid(DatabaseRow rowContainingPrimaryKey,
                       java.lang.Class theClass)

ADVANCED: Returns true if this Object with the given primary key of the Row and Class type given is valid in TopLink's identity maps.

Parameters:

rowContainingPrimaryKey - DatabaseRow, now deprecated, replaced by DatabaseRecord and Record
Use Database as a replacement in this instance.

theClass - Class

Returns:

boolean

printIdentityMap

public void printIdentityMap(java.lang.Class businessClass)

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.

Parameters:

businessClass - Class

printIdentityMaps

public void printIdentityMaps()

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.

printIdentityMapLocks

public void printIdentityMapLocks()

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.

putInIdentityMap

public java.lang.Object putInIdentityMap(java.lang.Object domainObject)

ADVANCED: Registers the given Object with the identity map. The Object must always be registered with its version number if optimistic locking is used.

Parameters:

domainObject - Object

Returns:

Object

putInIdentityMap

public java.lang.Object putInIdentityMap(java.lang.Object domainObject,
                                         java.util.Vector 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.

Parameters:

domainObject - Object

key - Vector

Returns:

Object

putInIdentityMap

public java.lang.Object putInIdentityMap(java.lang.Object domainObject,
                                         java.util.Vector key,
                                         java.lang.Object writeLockValue)

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.

Parameters:

domainObject - Object

key - Vector

writeLockValue - Object for versioning

Returns:

Object

putInIdentityMap

public java.lang.Object putInIdentityMap(java.lang.Object domainObject,
                                         java.util.Vector key,
                                         java.lang.Object writeLockValue,
                                         long readTime)

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.

Parameters:

domainObject - Object

key - Vector

writeLockValue - Object for versioning

readTime - long, time in milliseconds

Returns:

Object the Object put into the identity map

removeFromIdentityMap

public java.lang.Object removeFromIdentityMap(java.lang.Object domainObject)

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.

Parameters:

domainObject - Object

Returns:

Object the Object removed from the identity map

removeFromIdentityMap

public java.lang.Object removeFromIdentityMap(java.util.Vector key,
                                              java.lang.Class theClass)

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.

Parameters:

key - Vector

theClass - Class

Returns:

Object the Object removed from the identity map

updateWriteLockValue

public void updateWriteLockValue(java.lang.Object domainObject,
                                 java.lang.Object writeLockValue)

ADVANCED: Updates the write lock value in the identity map for cache key of the primary key the given Object.

Parameters:

domainObject - Object

writeLockValue - Object for versioning

updateWriteLockValue

public void updateWriteLockValue(java.util.Vector primaryKey,
                                 java.lang.Class theClass,
                                 java.lang.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.

Parameters:

primaryKey - Vector

theClass - Class

writeLockValue - Object for versioning

validateCache

public void validateCache()

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.

Skip navigation links