com.solarmetric.kodo.runtime.datacache
Interface DataCache

All Known Implementing Classes:

LocalCache

public interface DataCache

Interface that must be implemented by any level 2 cache used by Kodo.

Author:

Abe White, Patrick Linskey

Method Summary

void	batchUpdate(Map additions, Map updates, Collection deletes, Object origin) Perform a batch update of the cache.
void	clear() Remove all data from this cache.
void	close() Close this cache, dropping all hard references and releasing any resources that this cache maintains.
Object	get(Object key) Return the cached object for the given key.
boolean	pin(Object key) Pin the value stored under key into the cache.
Object	put(Object key, Object value) Set the cached value for the given key.
Object	remove(Object key) Remove the value stored under the given key.
boolean	unpin(Object key) Unpin the value stored under key into the cache.

Method Detail

batchUpdate

public void batchUpdate(Map additions,
                        Map updates,
                        Collection deletes,
                        Object origin)

Perform a batch update of the cache. Add all key-value pairs in additions, make the appropriate modifications to all key-value pairs in updates, and delete all keys in deletes. Processing the updates map might involve adding or removing objects to the cache or modifying data already in the cache.

All changes made to cached data must be cached via this method. It is this method that is responsible for performing any side-effects that should happen on meaningful cache changes.

Implementations should bear in mind that the deletes collection may contain oids that are also in the additions map. This is possible because it is valid for a user to delete an object with a particular oid and then add that object in the same batch.

Parameters:

origin - the object that initiated this cache update. This can be useful for implementations in which many sources share a single cache, which in turn communicates back to the sources on cache updates.

get

public Object get(Object key)

Return the cached object for the given key. Modifying the returned object may or may not change the cached value; the put(java.lang.Object, java.lang.Object) method should be used to re-cache any changed objects.

Returns:

the object matching the given key, or null if none

put

public Object put(Object key,
                  Object value)

Set the cached value for the given key. This does not result in an update of other caches. Rather, it should only be used for loading clean data into the cache. Meaningful changes to the state of the cache should be made via the batchUpdate(java.util.Map, java.util.Map, java.util.Collection, java.lang.Object) method.

Returns:

The previously cached value, or null if the key was not previously cached. See Map.put(java.lang.Object, java.lang.Object) for more information.

remove

public Object remove(Object key)

Remove the value stored under the given key. This does not result in an update of other caches. Rather, it should only be used for removing data into the cache. Meaningful changes to the state of the cache should be made via the batchUpdate method.

Returns:

The previously cached value, or null if the key was not previously cached. See Map.remove(java.lang.Object) for more information.

clear

public void clear()

Remove all data from this cache. This does not result in an update of other caches. Rather, it should only be used for clearing the cache. Meaningful changes to the state of the cache should be made via the batchUpdate method.

pin

public boolean pin(Object key)

Pin the value stored under key into the cache. This method guarantees that key's value will not be dropped by the caching algorithm. This method does not affect the behavior of remove.

Returns:

true if key's value was pinned into the cache; false if the key is not in the cache.

unpin

public boolean unpin(Object key)

Unpin the value stored under key into the cache. This method reverses a previous invocation of pin(java.lang.Object). This method does not remove anything from the cache; it merely makes key's value a candidate for flushing from the cache.

Returns:

true if key's value was unpinned from the cache; false if the key is not in the cache.

close

public void close()

Close this cache, dropping all hard references and releasing any resources that this cache maintains.