er.extensions.eof
Class ERXEnterpriseObjectCache<T extends com.webobjects.eocontrol.EOEnterpriseObject>

java.lang.Object
  er.extensions.eof.ERXEnterpriseObjectCache<T>

Type Parameters:

T - the type of EOEnterpriseObject in this cache

public class ERXEnterpriseObjectCache<T extends com.webobjects.eocontrol.EOEnterpriseObject>
extends java.lang.Object

Caches instances of one entity by a given key(path). Typically you'd have an "identifier" property and you'd fetch values by:

 ERXEnterpriseObjectCache<HelpText> helpTextCache = new ERXEnterpriseObjectCache<HelpText>("HelpText", "pageConfiguration");
 ...
 HelpText helpText = helpTextCache.objectForKey(ec, "ListHelpText");
 

You can supply a timeout after which individual objects (or all objects if fetchInitialValues is true) get cleared and re-fetched. This implementation can cache either only the global IDs, or the global ID and a copy of the actual object. Caching the actual object ensures that the snapshot stays around and thus prevent additional trips to the database. Listens to EOEditingContextDidSaveChanges notifications to track changes to objects in the cache and ClearCachesNotification for messages to purge the cache.

Author:

ak inspired by a class from Dominik Westner

Field Summary

static java.lang.String	ClearCachesNotification Other code can send this notification if it needs to have this cache discard all of the objects that it has.
protected static com.webobjects.eocontrol.EOGlobalID	NO_GID_MARKER

Constructor Summary

ERXEnterpriseObjectCache(java.lang.Class c, java.lang.String keyPath)
Creates the cache for the entity implemented by the passed class and the given keypath.

ERXEnterpriseObjectCache(java.lang.String entityName, java.lang.String keyPath)
Creates the cache for the given entity name and the given keypath.

ERXEnterpriseObjectCache(java.lang.String entityName, java.lang.String keyPath, com.webobjects.eocontrol.EOQualifier qualifier, long timeout)
Creates the cache for the given entity, keypath and timeout value in milliseconds.

ERXEnterpriseObjectCache(java.lang.String entityName, java.lang.String keyPath, com.webobjects.eocontrol.EOQualifier qualifier, long timeout, boolean shouldRetainObjects, boolean shouldFetchInitialValues)
Creates the cache for the given entity, keypath and timeout value in milliseconds.

ERXEnterpriseObjectCache(java.lang.String entityName, java.lang.String keyPath, com.webobjects.eocontrol.EOQualifier qualifier, long timeout, boolean shouldRetainObjects, boolean shouldFetchInitialValues, boolean shouldReturnUnsavedObjects)
Creates the cache for the given entity, keypath and timeout value in milliseconds.

ERXEnterpriseObjectCache(java.lang.String entityName, java.lang.String keyPath, long timeout)
Creates the cache for the given entity, keypath and timeout value in milliseconds.

Method Summary

void	addObject(T eo) Add an object to the cache using eo.valueForKeyPath(keyPath()) as the key.
void	addObjectForKey(T eo, java.lang.Object key) Add an object to the cache with the given key if it matches the qualifier, or if there is no qualifier.
com.webobjects.foundation.NSArray<T>	allObjects(com.webobjects.eocontrol.EOEditingContext ec) Returns a list of all the objects currently in the cache and not yet expired.
com.webobjects.foundation.NSArray<T>	allObjects(com.webobjects.eocontrol.EOEditingContext ec, com.webobjects.eocontrol.EOQualifier additionalQualifier) Returns a list of all the objects currently in the cache and not yet expired which match additionalQualifier.
protected ERXExpiringCache<java.lang.Object,er.extensions.eof.ERXEnterpriseObjectCache.EORecord<T>>	cache() Returns the backing cache.
void	clearCaches(com.webobjects.foundation.NSNotification n) Handler for the clearCaches notification.
protected er.extensions.eof.ERXEnterpriseObjectCache.EORecord<T>	createRecord(com.webobjects.eocontrol.EOGlobalID gid, T eo) Created an EORecord instance representing eo using its EOGlobalID.
protected ERXEC	editingContext() Returns the editing context that holds object that are in this cache.
void	editingContextDidSaveChanges(com.webobjects.foundation.NSNotification n) Handler for the editingContextDidSaveChanges notification.
protected java.lang.String	entityName()
protected com.webobjects.foundation.NSArray<T>	fetchObjectsForKey(com.webobjects.eocontrol.EOEditingContext editingContext, java.lang.Object key) Actually performs a fetch for the given key.
protected com.webobjects.eocontrol.EOQualifier	fetchObjectsQualifier(java.lang.Object key) Returns the qualifier to use during for fetching: the value for keyPath matches key AND qualifier() (if not null).
protected void	handleUnsuccessfullQueryForKey(java.lang.Object key) Called when a query hasn't found an entry in the cache.
protected java.lang.String	keyPath()
T	objectForKey(com.webobjects.eocontrol.EOEditingContext ec, java.lang.Object key) Retrieves an EO that matches the given key.
T	objectForKey(com.webobjects.eocontrol.EOEditingContext ec, java.lang.Object key, boolean handleUnsuccessfulQueryForKey) Retrieves an EO that matches the given key.
protected void	preLoadCacheIfNeeded() Loads all relevant objects into the cache if set to fetch initial values.
com.webobjects.eocontrol.EOQualifier	qualifier() Returns the additional qualifier for this cache.
void	removeObject(T eo) Removes an object from the cache using eo.valueForKeyPath(keyPath()) as the key.
void	removeObjectForKey(T eo, java.lang.Object key) Removes the object associated with key from the cache.
void	reset() Resets the cache by clearing the internal map.
void	setFetchInitialValues(boolean fetchInitialValues) Sets whether or not the initial values should be fetched into this cache or whether it should lazy load.
void	setResetOnChange(boolean resetOnChange) Sets whether or not the cache is cleared when any change occurs.
void	setRetainObjects(boolean retainObjects) Sets whether or not the cached EO's themselves are retained versus just their GID's.
void	setReuseEditingContext(boolean reuseEditingContext) Sets whether or not the editing context for this cache is reused for multiple requests.
void	start() Call this to re-start cache updating after stop() is called.
void	stop() Call this to stop cache updating.
T	unsavedMatchingObject(com.webobjects.eocontrol.EOEditingContext ec, java.lang.Object key) Looks in ec for an newly inserted (unsaved) EO that matches the given key.
void	updateObject(T eo) Updates an object in the cache (adding if not present) using eo.valueForKeyPath(keyPath()) as the key.
void	updateObjectForKey(T eo, java.lang.Object key) Updates an object in the cache (adding if not present) with the given key if it matches the qualifier, or if there is no qualifier.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ClearCachesNotification

public static java.lang.String ClearCachesNotification

Other code can send this notification if it needs to have this cache discard all of the objects that it has. The object in the notification is the name of the EOEntity to discard cache for.

NO_GID_MARKER

protected static final com.webobjects.eocontrol.EOGlobalID NO_GID_MARKER

Constructor Detail

ERXEnterpriseObjectCache

public ERXEnterpriseObjectCache(java.lang.String entityName,
                                java.lang.String keyPath)

Creates the cache for the given entity name and the given keypath. No timeout value is used.

Parameters:

entityName - name of the EOEntity to cache

keyPath - key path to data uniquely identifying an instance of this entity

ERXEnterpriseObjectCache

public ERXEnterpriseObjectCache(java.lang.Class c,
                                java.lang.String keyPath)

Creates the cache for the entity implemented by the passed class and the given keypath. No timeout value is used.

Parameters:

c - Class used to identify which EOEntity this cache is for

keyPath - key path to data uniquely identifying an instance of this entity

ERXEnterpriseObjectCache

public ERXEnterpriseObjectCache(java.lang.String entityName,
                                java.lang.String keyPath,
                                long timeout)

Creates the cache for the given entity, keypath and timeout value in milliseconds.

Parameters:

entityName - name of the EOEntity to cache

keyPath - key path to data uniquely identifying an instance of this entity

timeout - time to live in milliseconds for an object in this cache

ERXEnterpriseObjectCache

public ERXEnterpriseObjectCache(java.lang.String entityName,
                                java.lang.String keyPath,
                                com.webobjects.eocontrol.EOQualifier qualifier,
                                long timeout)

Creates the cache for the given entity, keypath and timeout value in milliseconds. Only objects that match qualifier are stored in the cache. Note that _resetOnChange (and _fetchInitialValues) are both true after this constructor. You will almost certainly want to call setResetOnChange(false);.

Parameters:

entityName - name of the EOEntity to cache

keyPath - key path to data uniquely identifying an instance of this entity

qualifier - EOQualifier restricting which instances are stored in this cache

timeout - time to live in milliseconds for an object in this cache

See Also:

setResetOnChange(boolean), setFetchInitialValues(boolean)

ERXEnterpriseObjectCache

public ERXEnterpriseObjectCache(java.lang.String entityName,
                                java.lang.String keyPath,
                                com.webobjects.eocontrol.EOQualifier qualifier,
                                long timeout,
                                boolean shouldRetainObjects,
                                boolean shouldFetchInitialValues)

Creates the cache for the given entity, keypath and timeout value in milliseconds. Only objects that match qualifier are stored in the cache.

Parameters:

entityName - name of the EOEntity to cache

keyPath - key path to data uniquely identifying an instance of this entity

qualifier - EOQualifier restricting which instances are stored in this cache

timeout - time to live in milliseconds for an object in this cache

shouldRetainObjects - true if this cache should retain the cached objects, false to keep only the GID

shouldFetchInitialValues - true if the cache should be fully populated on first access

See Also:

setResetOnChange(boolean), setFetchInitialValues(boolean), setRetainObjects(boolean)

ERXEnterpriseObjectCache

public ERXEnterpriseObjectCache(java.lang.String entityName,
                                java.lang.String keyPath,
                                com.webobjects.eocontrol.EOQualifier qualifier,
                                long timeout,
                                boolean shouldRetainObjects,
                                boolean shouldFetchInitialValues,
                                boolean shouldReturnUnsavedObjects)

Creates the cache for the given entity, keypath and timeout value in milliseconds. Only objects that match qualifier are stored in the cache.

Parameters:

entityName - name of the EOEntity to cache

keyPath - key path to data uniquely identifying an instance of this entity

qualifier - EOQualifier restricting which instances are stored in this cache

timeout - time to live in milliseconds for an object in this cache

shouldRetainObjects - true if this cache should retain the cached objects, false to keep only the GID

shouldFetchInitialValues - true if the cache should be fully populated on first access

shouldReturnUnsavedObjects - true if unsaved matching objects should be returned, see unsavedMatchingObject(EOEditingContext, Object)

See Also:

setResetOnChange(boolean), setFetchInitialValues(boolean), setRetainObjects(boolean)

Method Detail

start

public void start()

Call this to re-start cache updating after stop() is called. This is automatically called from the constructor so unless you call stop(), there is no need to ever call this method.

See Also:

stop()

stop

public void stop()

Call this to stop cache updating.

See Also:

start()

editingContext

protected ERXEC editingContext()

Returns the editing context that holds object that are in this cache. If _reuseEditingContext is false, a new editing context instance is returned each time. The returned editing context is autolocking.

Returns:

the editing context that holds object that are in this cache

editingContextDidSaveChanges

public void editingContextDidSaveChanges(com.webobjects.foundation.NSNotification n)

Handler for the editingContextDidSaveChanges notification. If _resetOnChange is true, this calls reset() to discard the entire cache contents if an object of the given entity has been changed. If _resetOnChange is false, this updates the cache to reflect the added/changed/removed objects.

Parameters:

n - NSNotification with EOEditingContext as the object and a dictionary of changes in the userInfo

See Also:

EOEditingContext.ObjectsChangedInEditingContextNotification, reset()

clearCaches

public void clearCaches(com.webobjects.foundation.NSNotification n)

Handler for the clearCaches notification. Calls reset if n.object is the name of the entity we are caching. Other code can send this notification if it needs to have this cache discard all of the objects.

Parameters:

n -

entityName

protected java.lang.String entityName()

Returns:

the name of the EOEntity this cache is for

keyPath

protected java.lang.String keyPath()

Returns:

Key path to data uniquely identifying an instance of the entity in this cache

cache

protected ERXExpiringCache<java.lang.Object,er.extensions.eof.ERXEnterpriseObjectCache.EORecord<T>> cache()

Returns the backing cache. If the cache is to old, it is cleared first. The cache is created if needed, and the contents populated if _fetchInitialValues.

Returns:

the backing cache

createRecord

protected er.extensions.eof.ERXEnterpriseObjectCache.EORecord<T> createRecord(com.webobjects.eocontrol.EOGlobalID gid,
                                                                              T eo)

Created an EORecord instance representing eo using its EOGlobalID. If _retainObjects, this will also include an instance of the EO to ensure that the snapshot is retained.

Parameters:

gid - EOGlobalID of eo

eo - the EO to make an EORecord for

Returns:

EORecord instance representing eo

preLoadCacheIfNeeded

protected void preLoadCacheIfNeeded()

Loads all relevant objects into the cache if set to fetch initial values.

addObject

public void addObject(T eo)

Add an object to the cache using eo.valueForKeyPath(keyPath()) as the key.

Parameters:

eo - the object to add to the cache

See Also:

addObjectForKey(EOEnterpriseObject, Object)

addObjectForKey

public void addObjectForKey(T eo,
                            java.lang.Object key)

Add an object to the cache with the given key if it matches the qualifier, or if there is no qualifier. The object can be null, in which case a place holder is added.

Parameters:

eo - eo the object to add to the cache

key - the key to add the object under

removeObject

public void removeObject(T eo)

Removes an object from the cache using eo.valueForKeyPath(keyPath()) as the key.

Parameters:

eo - the object to remove from the cache

See Also:

removeObjectForKey(EOEnterpriseObject, Object)

removeObjectForKey

public void removeObjectForKey(T eo,
                               java.lang.Object key)

Removes the object associated with key from the cache.

Parameters:

eo - eo the object to remove from the cache (ignored)

key - the key to remove the object for

updateObject

public void updateObject(T eo)

Updates an object in the cache (adding if not present) using eo.valueForKeyPath(keyPath()) as the key.

Parameters:

eo - the object to update in the cache

See Also:

updateObjectForKey(EOEnterpriseObject, Object)

updateObjectForKey

public void updateObjectForKey(T eo,
                               java.lang.Object key)

Updates an object in the cache (adding if not present) with the given key if it matches the qualifier, or if there is no qualifier. The object can be null, in which case is it removed from the cache. If qualifier() is not null, the object is removed from the cache if it does not match the qualifier.

Parameters:

eo - eo the object to update in the cache

key - the key of the object to update

objectForKey

public T objectForKey(com.webobjects.eocontrol.EOEditingContext ec,
                      java.lang.Object key)

Retrieves an EO that matches the given key. If there is no match in the cache, it attempts to fetch the missing objects. Null is returned if no matching object can be fetched.

Parameters:

ec - editing context to get the object into

key - key value under which the object is registered

Returns:

the matching object

objectForKey

public T objectForKey(com.webobjects.eocontrol.EOEditingContext ec,
                      java.lang.Object key,
                      boolean handleUnsuccessfulQueryForKey)

Retrieves an EO that matches the given key. If there is no match in the cache, and _returnUnsavedObjects is true, it attempts to find and return an unsaved object. If there is still no match and handleUnsuccessfulQueryForKey is true, it attempts to fetch the missing objects. Null is returned if handleUnsuccessfulQueryForKey is false or no matching object can be fetched.

Parameters:

ec - editing context to get the object into

key - key value under which the object is registered

handleUnsuccessfulQueryForKey - if false, a cache miss returns null rather than fetching

Returns:

the matching object

unsavedMatchingObject

public T unsavedMatchingObject(com.webobjects.eocontrol.EOEditingContext ec,
                               java.lang.Object key)

Looks in ec for an newly inserted (unsaved) EO that matches the given key. ONLY ec is examined. Null is returned if no matching

Parameters:

ec - editing context to search for unsaved, matching objects

key - key value to identify the unsaved object

Returns:

the matching object or null if not found

allObjects

public com.webobjects.foundation.NSArray<T> allObjects(com.webobjects.eocontrol.EOEditingContext ec)

Returns a list of all the objects currently in the cache and not yet expired.

Parameters:

ec - editing context to get the objects into

Returns:

all objects currently in the cache and unexpired

allObjects

public com.webobjects.foundation.NSArray<T> allObjects(com.webobjects.eocontrol.EOEditingContext ec,
                                                       com.webobjects.eocontrol.EOQualifier additionalQualifier)

Returns a list of all the objects currently in the cache and not yet expired which match additionalQualifier.

Parameters:

ec - editing context to get the objects into

additionalQualifier - qualifier to restrict which objects are returned from the cache

Returns:

all objects currently in the cache and unexpired

handleUnsuccessfullQueryForKey

protected void handleUnsuccessfullQueryForKey(java.lang.Object key)

Called when a query hasn't found an entry in the cache. This implementation puts a not-found marker in the cache so the next query will return null. If _fetchInitialValues is false, it will attempt to fetch the missing object and adds it to the cache if it is found. call addObject(EOEnterpriseObject) on it.

Parameters:

key - the key of the object that was not found in the cache

fetchObjectsForKey

protected com.webobjects.foundation.NSArray<T> fetchObjectsForKey(com.webobjects.eocontrol.EOEditingContext editingContext,
                                                                  java.lang.Object key)

Actually performs a fetch for the given key. Override this method to implement custom fetch rules.

Parameters:

editingContext - the editing context to fetch in

key - the key to fetch with

Returns:

the fetch objects

qualifier

public com.webobjects.eocontrol.EOQualifier qualifier()

Returns the additional qualifier for this cache.

Returns:

the additional qualifier for this cache

fetchObjectsQualifier

protected com.webobjects.eocontrol.EOQualifier fetchObjectsQualifier(java.lang.Object key)

Returns the qualifier to use during for fetching: the value for keyPath matches key AND qualifier() (if not null).

Parameters:

key - the key to fetch

Returns:

the qualifier to use

reset

public void reset()

Resets the cache by clearing the internal map. The values are refreshed right away if _fetchInitialValues is true, otherwise they are re-loaded on demand.

See Also:

preLoadCacheIfNeeded()

setFetchInitialValues

public void setFetchInitialValues(boolean fetchInitialValues)

Sets whether or not the initial values should be fetched into this cache or whether it should lazy load. If turned off, resetOnChange will also be turned off.

Parameters:

fetchInitialValues - if true, the initial values are fetched into the cache

setReuseEditingContext

public void setReuseEditingContext(boolean reuseEditingContext)

Sets whether or not the editing context for this cache is reused for multiple requests.

Parameters:

reuseEditingContext - whether or not the editing context for this cache is reused for multiple requests

setRetainObjects

public void setRetainObjects(boolean retainObjects)

Sets whether or not the cached EO's themselves are retained versus just their GID's. If set, this implicitly sets reuseEditingContext to true.

Parameters:

retainObjects - if true, the EO's are retained

setResetOnChange

public void setResetOnChange(boolean resetOnChange)

Sets whether or not the cache is cleared when any change occurs. This requires fetching initial values (and will be turned on if you set this)

Parameters:

resetOnChange - if true, the cache will clear on changes; if false, the cache will update on changes