ERXEnterpriseObjectCache< T extends EOEnterpriseObject > Class Reference

Collaboration diagram for ERXEnterpriseObjectCache< T extends EOEnterpriseObject >:

[legend]

List of all members.

Classes
class	EORecord< T >
Public Member Functions
void	addObject (T eo)
void	addObjectForKey (T eo, Object key)
NSArray< T >	allObjects (EOEditingContext ec, EOQualifier additionalQualifier)
NSArray< T >	allObjects (EOEditingContext ec)
void	clearCaches (NSNotification n)
void	editingContextDidSaveChanges (NSNotification n)
	ERXEnterpriseObjectCache (String entityName, String keyPath, EOQualifier qualifier, long timeout, boolean shouldRetainObjects, boolean shouldFetchInitialValues, boolean shouldReturnUnsavedObjects)
	ERXEnterpriseObjectCache (String entityName, String keyPath, EOQualifier qualifier, long timeout, boolean shouldRetainObjects, boolean shouldFetchInitialValues)
	ERXEnterpriseObjectCache (String entityName, String keyPath, EOQualifier qualifier, long timeout)
	ERXEnterpriseObjectCache (String entityName, String keyPath, long timeout)
	ERXEnterpriseObjectCache (Class c, String keyPath)
	ERXEnterpriseObjectCache (String entityName, String keyPath)
T	objectForKey (EOEditingContext ec, Object key, boolean handleUnsuccessfulQueryForKey)
T	objectForKey (EOEditingContext ec, Object key)
EOQualifier	qualifier ()
void	removeObject (T eo)
void	removeObjectForKey (T eo, Object key)
synchronized void	reset ()
void	setFetchInitialValues (boolean fetchInitialValues)
void	setResetOnChange (boolean resetOnChange)
void	setRetainObjects (boolean retainObjects)
void	setReuseEditingContext (boolean reuseEditingContext)
void	start ()
void	stop ()
T	unsavedMatchingObject (EOEditingContext ec, Object key)
void	updateObject (T eo)
void	updateObjectForKey (T eo, Object key)
Static Public Attributes
static String	ClearCachesNotification = "ERXEnterpriseObjectCache.ClearCaches"
Protected Member Functions
synchronized ERXExpiringCache < Object, EORecord< T > >	cache ()
EORecord< T >	createRecord (EOGlobalID gid, T eo)
ERXEC	editingContext ()
String	entityName ()
NSArray< T >	fetchObjectsForKey (EOEditingContext editingContext, Object key)
EOQualifier	fetchObjectsQualifier (Object key)
void	handleUnsuccessfullQueryForKey (Object key)
String	keyPath ()
void	preLoadCacheIfNeeded ()
Static Protected Attributes
static final EOGlobalID	NO_GID_MARKER = new EOTemporaryGlobalID()
Private Member Functions
NSArray< T >	relevantChanges (NSDictionary dict, String key)
Static Private Member Functions
static String	entityNameForClass (Class c)
Private Attributes
ERXExpiringCache< Object, EORecord< T > >	_cache
ERXEC	_editingContext
String	_entityName
boolean	_fetchInitialValues
long	_fetchTime
String	_keyPath
EOQualifier	_qualifier
boolean	_resetOnChange
boolean	_retainObjects
boolean	_returnUnsavedObjects
boolean	_reuseEditingContext
long	_timeout

---

Detailed Description

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

Parameters:

<T>

the type of EOEnterpriseObject in this cache

---

Constructor & Destructor Documentation

ERXEnterpriseObjectCache	(	String	entityName,
		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	(	Class	c,
		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	(	String	entityName,
		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	(	String	entityName,
		String	keyPath,
		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);.

See also:

setResetOnChange(boolean)

setFetchInitialValues(boolean)

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

ERXEnterpriseObjectCache	(	String	entityName,
		String	keyPath,
		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.

See also:

setResetOnChange(boolean)

setFetchInitialValues(boolean)

setRetainObjects(boolean)

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

ERXEnterpriseObjectCache	(	String	entityName,
		String	keyPath,
		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.

See also:

setResetOnChange(boolean)

setFetchInitialValues(boolean)

setRetainObjects(boolean)

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)

---

Member Function Documentation

void addObject

(

T

eo

)

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

See also:

addObjectForKey(EOEnterpriseObject, Object)

Parameters:

eo

the object to add to the cache

void addObjectForKey	(	T	eo,
		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

NSArray<T> allObjects	(	EOEditingContext	ec,
		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

NSArray<T> allObjects

(

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

synchronized ERXExpiringCache<Object, EORecord<T> > cache

(

)

[protected]

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

void clearCaches

(

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

EORecord<T> createRecord	(	EOGlobalID	gid,
		T	eo
	)			[protected]

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

ERXEC editingContext

(

)

[protected]

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

void editingContextDidSaveChanges

(

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.

See also:

EOEditingContext.ObjectsChangedInEditingContextNotification

reset()

Parameters:

n

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

String entityName

(

)

[protected]

Returns:

the name of the EOEntity this cache is for

static String entityNameForClass

(

Class

c

)

[static, private]

NSArray<T> fetchObjectsForKey	(	EOEditingContext	editingContext,
		Object	key
	)			[protected]

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

EOQualifier fetchObjectsQualifier

(

Object

key

)

[protected]

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

void handleUnsuccessfullQueryForKey

(

Object

key

)

[protected]

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

String keyPath

(

)

[protected]

Returns:

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

T objectForKey	(	EOEditingContext	ec,
		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

T objectForKey	(	EOEditingContext	ec,
		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

void preLoadCacheIfNeeded

(

)

[protected]

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

EOQualifier qualifier

(

)

Returns the additional qualifier for this cache.

Returns:

the additional qualifier for this cache

NSArray<T> relevantChanges	(	NSDictionary	dict,
		String	key
	)			[private]

Helper to check a dictionary of objects from an EOF notification and return any that are for the entity that we are caching.

Parameters:

	dict	dictionary of key to NSArray<EOEnterpriseObject>
	key	key into dict indicating which list to process

Returns:

objects from the list that are of the entity we are caching, or an empty array if there are no matches

void removeObject

(

T

eo

)

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

See also:

removeObjectForKey(EOEnterpriseObject, Object)

Parameters:

eo

the object to remove from the cache

void removeObjectForKey	(	T	eo,
		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

synchronized 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()

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

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

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

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

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

void stop

(

)

Call this to stop cache updating.

See also:

start()

T unsavedMatchingObject	(	EOEditingContext	ec,
		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

void updateObject

(

T

eo

)

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

See also:

updateObjectForKey(EOEnterpriseObject, Object)

Parameters:

eo

the object to update in the cache

void updateObjectForKey	(	T	eo,
		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

---

Member Data Documentation

ERXExpiringCache<Object, EORecord<T> > _cache [private]

Actual cache implementation.

ERXEC _editingContext [private]

The single editing context instance is used for this cache instance if _reuseEditingContext is true.

String _entityName [private]

Name of the EOEntity to cache.

boolean _fetchInitialValues [private]

true if this cache should be populated when created, false for lazy population.

long _fetchTime [private]

The time when the objects in this cache were fetched. Only used if _fetchInitialValues is true.

String _keyPath [private]

Key path to data uniquely identifying an instance of this entity.

EOQualifier _qualifier [private]

EOQualifier restricting which instances are stored in this cache

boolean _resetOnChange [private]

If true, the entire cache contents are discarded when any object in it changes. Probably not what you want.

See also:

editingContextDidSaveChanges(NSNotification)

boolean _retainObjects [private]

If true, this cache retains an instance of each object so that the snapshot does not expire.

boolean _returnUnsavedObjects [private]

If true, object that have not been saved yet are found by the cache.

boolean _reuseEditingContext [private]

If true, just a single editing context instance is used for this cache instance.

long _timeout [private]

Time to live in milliseconds for an object in this cache.

String ClearCachesNotification = "ERXEnterpriseObjectCache.ClearCaches" [static]

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.

final EOGlobalID NO_GID_MARKER = new EOTemporaryGlobalID() [static, protected]

---

The documentation for this class was generated from the following file:

• /opt/source/Wonder/Frameworks/Core/ERExtensions/Sources/er/extensions/eof/ERXEnterpriseObjectCache.java