com.solarmetric.kodo.runtime.datacache
Interface DataCache

All Known Implementing Classes:

AbstractCacheImpl, TimedDataCache

public interface DataCache

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

Method Summary

void	addExpirationListener(com.solarmetric.util.Listener listen) Add a new expiration event listener to this cache.
void	batchUpdate(Collection additions, Collection newUpdates, Collection existingUpdates, Collection deletes) 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.
boolean	containsKey(Object key) Returns true if this cache contains data corresponding to key; otherwise returns false.
PCData	get(Object key) Return the cached object for the given key.
String	getName() Returns a string name that can be used by end-user-visible code to identify this cache.
boolean	isDecorator() Returns true if this cache is a decorator that wraps another cache.
boolean	pin(Object key) Pin the value stored under key into the cache.
PCData	put(PCData value) Set the cached value for the given key.
PCData	remove(Object key) Remove the value stored under the given key.
DataCache	removeDecorator() Returns an undecorated version of this cache.
DataCache	removeDecorators() Returns the lowest cache in the chain of caches in this object.
void	removeExpirationListener(com.solarmetric.util.Listener listen) Remove an expiration event listener from this cache.
void	setName(String name) Sets a string name to be used to identify this cache to end-user needs.
boolean	unpin(Object key) Unpin the value stored under key into the cache.
void	updateValue(PCData value) Update the cached value for the given key.

Method Detail

batchUpdate

public void batchUpdate(Collection additions,
                        Collection newUpdates,
                        Collection existingUpdates,
                        Collection deletes)

Perform a batch update of the cache. Add all PCData objects in additions and in newUpdates, make the appropriate modifications to all PCDatas in existingUpdates, and delete all OIDs in deletes.

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:

additions - A collection of PCData objects. These represent data that have been newly created, and thus must be added to the cache.

newUpdates - A collection of PCData objects. These represent data that have been modified but were not originally in the cache, and thus must be added to the cache.

existingUpdates - A collection of PCData objects. These represent data that have been modified and were originally loaded from the cache. It is up to the cache implementation to decide if these values must be re-enlisted in the cache. Some caches may return live data from get(java.lang.Object) invocations, in which case these values need not be re-enlisted.

deletes - A collection of object IDs that have been deleted and must therefore be dropped from the cache.

get

public PCData get(Object key)

Return the cached object for the given key. Modifying the returned object may or may not change the cached value; the updateValue(com.solarmetric.kodo.runtime.PCData) method should be used to re-cache any changed objects.

Returns:

the object matching the given key, or null if none

put

public PCData put(PCData 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.Collection, java.util.Collection, java.util.Collection, java.util.Collection) 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.

updateValue

public void updateValue(PCData value)

Update 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.Collection, java.util.Collection, java.util.Collection, java.util.Collection) method.

A cache implementation may or may not return a live object from get(java.lang.Object) invocations. If an object retrieved from a get(java.lang.Object) operation needs to be updated, this method can be invoked instead of invoking put(com.solarmetric.kodo.runtime.PCData). The DataCache implementation can then make optimizations based on how its get(java.lang.Object) method works.

remove

public PCData 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(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection) 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(java.util.Collection, java.util.Collection, java.util.Collection, java.util.Collection) 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(java.lang.Object).

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.

containsKey

public boolean containsKey(Object key)

Returns true if this cache contains data corresponding to key; otherwise returns false.

setName

public void setName(String name)

Sets a string name to be used to identify this cache to end-user needs.

Since:

2.5.0

getName

public String getName()

Returns a string name that can be used by end-user-visible code to identify this cache.

Since:

2.5.0

isDecorator

public boolean isDecorator()

Returns true if this cache is a decorator that wraps another cache. Otherwise, returns false.

Since:

2.5.0

removeDecorator

public DataCache removeDecorator()

Returns an undecorated version of this cache. If this cache is not a decorator, returns this.

Since:

2.5.0

removeDecorators

public DataCache removeDecorators()

Returns the lowest cache in the chain of caches in this object. If this cache is not a decorator, returns this. This is equivalent to repeatedly invoking removeDecorator() until the returned DataCache returns false from isDecorator().

Since:

2.5.0

addExpirationListener

public void addExpirationListener(com.solarmetric.util.Listener listen)

Add a new expiration event listener to this cache.

Since:

2.5.0

removeExpirationListener

public void removeExpirationListener(com.solarmetric.util.Listener listen)

Remove an expiration event listener from this cache.

Since:

2.5.0