at.spardat.enterprise.cache.ICache Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2003, 2007 s IT Solutions AT Spardat GmbH .
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* s IT Solutions AT Spardat GmbH - initial API and implementation
*******************************************************************************/
package at.spardat.enterprise.cache;
/**
* A cache is a in memory map of key-value-pairs. The keys are used to identify the
* cached values.
*
* Keys must not be null and implement the methods equals and hashCode,
* see class java.lang.Object. Moreover, keys should be immutable. If they are
* not, keys must not be modified after they have been passed into any method of this
* class! If you are not sure if you can absolutely correctly fulfill these
* conditions, please just use java.lang.Strings for all key arguments instead.
*
* Caches come in two flavors. The preferred type is a Transparent Cache. You
* create a transparent cache if you register a TransparentCacheDescriptor
* with the CacheManager. With a transparent cache, you usually just call
* the lookup-method and do not have to worry if the needed object is indeed
* in the cache or not. If the lookup-method discovers that your requested object
* is not cached (because it timed out, it had been LRU-evicted or it has not been
* loaded yet), it loads the object into the cache using the descriptor provided
* by you at registration time. The cache is called transparent, because the load
* operation is transparent to you. Either way, if loaded or not, it will return the object requested
* by you or it will throw an exception if it could not be loaded.
*
* A transparent cache is required to perform entry level synchronization during
* load operations. If a particular object for key x must be loaded because
* of a cache miss, threads doing lookups on other keys than x in this
* cache must not be affected. Threads which also do a lookup on key x
* are blocked until the object x is loaded.
*
* With a Non Transparent Cache you have to insert the objects yourself and
* lookup returns null on cache misses.
*
* The implementation of all classes implementing ICache must be thread safe.
*
* The behaviour of the cache in terms of replacement strategies is specified via
* the associated ICacheDescriptor. A cache may be restricted by size (maximum
* number of objects in the cache) or by time (maximum number of milliseconds an object
* may live in the cache) or both. The replacement-strategy is as follows:
*
*
* - If the cache is not restricted by size and not restricted by time, the cache
* behaves exactly like a java.util.HashMap.
*
- If the object-livetime in the cache is restricted, then at the start of every
* lookup-operation, outdated objects are removed from the cache.
*
- If the cache is restricted by size, then after every insertion which causes
* the maximum size to be exceeded, a victim is choosen according to a LRU strategy
* and removed from the cache.
*
*
* @author s2266
*/
public interface ICache {
/**
* Looks up the cache for a particular key.
*
* @return the found object or null, if there is no object cached for the key. If
* this is a transparent cache, this method never returns null.
* @exception RuntimeException if this is a transparent cache and a load operation
* which is triggered by this method throws an exception.
*/
Object lookup (Object key);
/**
* Removes a cached object for a particular key. If the cache does not contain an
* object for the key, this method is a noop.
*/
void remove (Object key);
/**
* Removes all cached objects in this cache.
*/
void removeAll ();
/**
* For every key in the cache, method f.accept() is called. If it returns
* true, the object is removed from the cache.
*
* @param f filter that qualifies keys.
*/
void removeAllHaving (IKeyFilter f);
/**
* Inserts an object for a particular key in the cache. If the cache already contained
* an object for the key, it is replaced. This method must not be called
* for transparent caches.
*/
void insert (Object key, Object value);
/**
* Is used to filter keys.
*/
public interface IKeyFilter {
/**
* The implementor gets a key-object and has to respond with true or false.
* Semantic depends on where the filter is used.
*/
public boolean accept (Object key);
}
}