* A cache, being a mechanism for efficient temporary storage of objects * for the purpose of improving the overall performance of an application * system, should not be necessary for the application to function correctly, * it only improves the performance. *
* A cache could be scoped, for examples to a JVM, all JVMs on a node, all * nodes in a cluster, etc. Operations that are scoped to a cache such as put * or load would affect all JVMs in the cache. So the object loaded in 1 JVM * would be equally available to all other JVMs in the cache. *
* Objects are identified in the cache by a key. A key can be any Java * object that implements the equals and hashcode methods. If the object is * to be distributed or persisted (if supported) it must implement * serializable. *
* Each object in the cache will have aCacheEntry object associated with
* it. This object will encapsulate the metadata associated with the cached
* object. Mainly it represents the object statistics.
*
* "CacheStatistics" represents the read-only statistics of the cache,
* while "CacheAttributes" represents the user settable attributes of the
* cache.
*/
public interface Cache extends Map
{
/**
* Returns true if the cache contains the specified key. The search is
* scoped to the cache. Other caches in the system will not be searched
* and a CacheLoader will not be called.
* @return true, if the cache contains the specified key.
*/
public boolean containsKey(Object key);
/**
* @return true if the cache contains one or more keys to the specified value.
*/
public boolean containsValue(Object value);
/**
* Returns a set view of the objects currently contained in the cache.
* A CacheLoader will not be called. The behavior is unspecified for the
* case when an object is remove from the cache while the return set is
* being traversed.
*/
public Set entrySet();
/**
* Equality is based on the Set returned by entrySet. Equal will return
* true if the two objects are referencing the same object or
* entrySet.equals(((Map)o).entrySet()) returns true.
*/
public boolean equals(Object o);
/**
* @param ht a hashtable which holds a pointer pointing to the
* declarative cache description.
* @throws CacheException if any error occurs.
*/
/**
* @return the hash code value for this the cache.
*/
public int hashCode();
/**
* @return true if entrySet().isEmpty() returns true.
*/
public boolean isEmpty();
/**
* Returns a set view of the keys currently contained in the cache. A
* CacheLoader will not be called. The behavior is unspecified for the
* case when an object is remove from the cache while the return set is
* being traversed.
*/
public Set keySet();
/**
* Copies all of the mappings from the specified map to the cache. This
* would be equivalent to t.entrySet() then iterating through the Set and
* calling put with each key value pair.
*/
public void putAll(Map t);
/**
* @return the number of objects in the cache. This should be the same
* value as entrySet().size();
*/
public int size();
/**
* @return a collection view of the values contained in the cache.
*/
public Collection values();
/**
* The get method will return, from the cache, the object associated with
* the argument "key". If the object is not in the cache, the associated
* cache loader will be called. If no loader is associated with the object,
* a null is returned. If a problem is encountered during the retrieving
* or loading of the object, an exception (to be defined) will be thrown.
* If the "arg" argument is set, the arg object will be passed to the
* CacheLoader.load method. The cache will not dereference the object.
* If no "arg" value is provided a null will be passed to the load method.
* The storing of null values in the cache is permitted, however, the get
* method will not distinguish returning a null stored in the cache and
* not finding the object in the cache. In both cases a null is returned.
*/
public Object get(Object key);
// REVIEW adam@bea.com 23-Jun-04 - I think that it is strange that get()
// doesn't throw an exception whereas getAll() does. I understand the
// historical reason for it, but think it looks ugly nonetheless.
/**
* The getAll method will return, from the cache, a Map of the objects
* associated with the Collection of keys in argument "keys". If the objects
* are not in the cache, the associated cache loader will be called. If no
* loader is associated with an object, a null is returned. If a problem
* is encountered during the retrieving or loading of the objects, an
* exception will be thrown.
* If the "arg" argument is set, the arg object will be passed to the
* CacheLoader.loadAll method. The cache will not dereference the object.
* If no "arg" value is provided a null will be passed to the loadAll
* method.
* The storing of null values in the cache is permitted, however, the get
* method will not distinguish returning a null stored in the cache and
* not finding the object in the cache. In both cases a null is returned.
*/
public Map getAll(Collection keys) throws CacheException;
/**
* The load method provides a means to "pre load" the cache. This method
* will, asynchronously, load the specified object into the cache using
* the associated cacheloader. If the object already exists in the cache,
* no action is taken. If no loader is associated with the object, no object
* will be loaded into the cache. If a problem is encountered during the
* retrieving or loading of the object, an exception should
* be logged.
* If the "arg" argument is set, the arg object will be passed to the
* CacheLoader.load method. The cache will not dereference the object. If
* no "arg" value is provided a null will be passed to the load method.
* The storing of null values in the cache is permitted, however, the get
* method will not distinguish returning a null stored in the cache and not
* finding the object in the cache. In both cases a null is returned.
*/
public void load(Object key) throws CacheException;
/**
* The loadAll method provides a means to "pre load" objects into the cache.
* This method will, asynchronously, load the specified objects into the
* cache using the associated cache loader. If the an object already exists
* in the cache, no action is taken. If no loader is associated with the
* object, no object will be loaded into the cache. If a problem is
* encountered during the retrieving or loading of the objects, an
* exception (to be defined) should be logged.
* The getAll method will return, from the cache, a Map of the objects
* associated with the Collection of keys in argument "keys". If the objects
* are not in the cache, the associated cache loader will be called. If no
* loader is associated with an object, a null is returned. If a problem
* is encountered during the retrieving or loading of the objects, an
* exception (to be defined) will be thrown.
* If the "arg" argument is set, the arg object will be passed to the
* CacheLoader.loadAll method. The cache will not dereference the object.
* If no "arg" value is provided a null will be passed to the loadAll
* method.
*/
public void loadAll(Collection keys) throws CacheException;
/**
* The peek method will return the object associated with "key" if it
* currently exists (and is valid) in the cache. If not, a null is
* returned. With "peek" the CacheLoader will not be invoked and other
* caches in the system will not be searched.
*/
public Object peek(Object key);
/**
* The put method adds the object "value" to the cache identified by the
* object "key".
*/
public Object put(Object key, Object value);
/**
* Returns the CacheEntry object associated with the object identified by
* "key". If the object is not in the cache a null is returned.
*/
public CacheEntry getCacheEntry(Object key);
/**
* Returns the CacheStatistics object associated with the cache.
* May return null if the cache does not support statistics gathering.
*/
public CacheStatistics getCacheStatistics();
/**
* The remove method will delete the object from the cache including the
* key, the associated value and the associated CacheStatistics object.
*/
public Object remove(Object key);
/**
* The clear method will remove all objects from the cache including the
* key, the associated value and the associated CacheStatistics object.
*/
public void clear();
/**
* The evict method will remove objects from the cache that are no longer
* valid. Objects where the specified expiration time has been reached.
*/
public void evict();
/** Add a listener to the list of cache listeners */
public void addListener(CacheListener listener);
/** Remove a listener from the list of cache listeners */
public void removeListener(CacheListener listener);
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/CacheEntry.java 0000644 0001750 0001750 00000001203 10617577002 023013 0 ustar arnaud arnaud package net.sf.jsr107cache;
import java.util.Map;
/**
* CacheEntry
*
* @author Brian Goetz
*/
public interface CacheEntry extends Map.Entry {
int getHits();
long getLastAccessTime();
long getLastUpdateTime();
long getCreationTime();
long getExpirationTime();
/**
* Returns a version counter.
* An implementation may use timestamps for this or an incrementing
* number. Timestamps usually have issues with granularity and are harder
* to use across clusteres or threads, so an incrementing counter is often safer.
*/
long getVersion();
boolean isValid();
long getCost();
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/CacheException.java 0000644 0001750 0001750 00000001472 10617577002 023660 0 ustar arnaud arnaud package net.sf.jsr107cache;
/**
* CacheException is a generic exception, which indicates
* a cache error has occurred. All the other cache exceptions are the
* subclass of this class. All the methods in the cache package only
* throw CacheException or the sub class of it.
*
*
*/
public class CacheException extends Exception
{
/**
* Constructs a new CacheException.
*/
public CacheException()
{
super();
}
/**
* Constructs a new CacheException with a message string.
*/
public CacheException(String s)
{
super(s);
}
/**
* Constructs a CacheException with a message string, and
* a base exception
*/
public CacheException(String s, Throwable ex)
{
super(s, ex);
}
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/CacheFactory.java 0000644 0001750 0001750 00000001220 10617577002 023320 0 ustar arnaud arnaud package net.sf.jsr107cache;
import java.util.Map;
/**
* CacheFactory is a service provider specific interface.
* Service provider should implement CacheFactory to provide
* the functionality to create a new implementation specific Cache object.
*/
public interface CacheFactory
{
/**
* creates a new implementation specific Cache object using the env parameters.
* @param env implementation specific environment parameters passed to the
* CacheFactory.
* @return an implementation specific Cache object.
* @throws CacheException if any error occurs.
*/
public Cache createCache(Map env) throws CacheException;
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/CacheListener.java 0000644 0001750 0001750 00000001247 10617577002 023507 0 ustar arnaud arnaud package net.sf.jsr107cache;
/** Interface describing various events that can happen as elements are added to
* or removed from a cache
*/
public interface CacheListener {
/** Triggered when a cache mapping is created due to the cache loader being consulted */
public void onLoad(Object key);
/** Triggered when a cache mapping is created due to calling Cache.put() */
public void onPut(Object key);
/** Triggered when a cache mapping is removed due to eviction */
public void onEvict(Object key);
/** Triggered when a cache mapping is removed due to calling Cache.remove() */
public void onRemove(Object key);
public void onClear();
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/CacheLoader.java 0000644 0001750 0001750 00000002320 10617577002 023121 0 ustar arnaud arnaud package net.sf.jsr107cache;
import java.util.Collection;
import java.util.Map;
/**
* User should implement this CacheLoader interface to
* provide a loader object to load the objects into cache.
*/
public interface CacheLoader
{
/**
* loads an object. Application writers should implement this
* method to customize the loading of cache object. This method is called
* by the caching service when the requested object is not in the cache.
*
*
* @param key the key identifying the object being loaded
*
* @return The object that is to be stored in the cache.
* @throws CacheException
*
*/
public Object load(Object key) throws CacheException;
/**
* loads multiple object. Application writers should implement this
* method to customize the loading of cache object. This method is called
* by the caching service when the requested object is not in the cache.
*
*
* @param keys a Collection of keys identifying the objects to be loaded
*
* @return A Map of objects that are to be stored in the cache.
* @throws CacheException
*
*/
public Map loadAll(Collection keys) throws CacheException;
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/CacheManager.java 0000644 0001750 0001750 00000007605 10617577002 023300 0 ustar arnaud arnaud package net.sf.jsr107cache;
import java.io.*;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.Properties;
/**
* CacheManager is used in J2SE environments for looking up named caches.
*/
public class CacheManager {
private static final String FACTORY_PROPERTY_NAME = "net.sf.jsr107cache.CacheFactory";
private static final String DEFAULT_FACTORY_NAME = "ri.cache.BasicCacheFactory";
protected static CacheManager instance = new CacheManager();
// REVIEW brian@quiotix.com
// Should this be a HashMap>?
private final Map caches = Collections.synchronizedMap(new HashMap());
/**
* Returns the singleton CacheManager
*/
public static CacheManager getInstance() {
return instance;
}
public Cache getCache(String cacheName) {
return (Cache) caches.get(cacheName);
}
public void registerCache(String cacheName, Cache cache) {
caches.put(cacheName, cache);
}
public CacheFactory getCacheFactory() throws CacheException {
String factoryName = findFactory(FACTORY_PROPERTY_NAME);
try {
ClassLoader cl = findClassLoader();
Class spiClass = Class.forName(factoryName, true, cl);
return (CacheFactory) spiClass.newInstance();
} catch (ClassNotFoundException cnfe) {
throw new CacheException("Could not find class: '" + factoryName + "'");
} catch (ClassCastException cce) {
throw new CacheException("Class: '" + factoryName + "' does not implement CacheFactory");
} catch (InstantiationException ie) {
throw new CacheException("Could not instantiate: '" + factoryName + "'");
} catch (IllegalAccessException iae) {
throw new CacheException("Could not find public default constructor for: '" + factoryName + "'");
}
}
private ClassLoader findClassLoader() {
ClassLoader cl = Thread.currentThread().getContextClassLoader();
if (cl == null) cl = ClassLoader.getSystemClassLoader();
return cl;
}
private boolean isEmptyString(String s) {
return s == null || "".equals(s);
}
String findFactory(String factoryId) {
// Use the system property first
try {
String factoryClass = System.getProperty(factoryId);
if (!isEmptyString(factoryClass)) return factoryClass;
} catch (SecurityException ignore) {
}
// try to read from $java.home/lib/jcache.properties
try {
String configFile = System.getProperty("java.home") +
File.separator + "lib" + File.separator + "jcache.properties";
File f = new File(configFile);
if (f.exists()) {
InputStream in = new FileInputStream(f);
try {
Properties props = new Properties();
props.load(in);
String factoryClass = props.getProperty(factoryId);
if (!isEmptyString(factoryClass)) return factoryClass;
} finally {
in.close();
}
}
} catch (SecurityException ignore) {
} catch (IOException ignore) {
}
// try to find services in CLASSPATH
try {
ClassLoader cl = findClassLoader();
InputStream is = cl.getResourceAsStream("META-INF/services/" + factoryId);
if (is != null) {
BufferedReader r = new BufferedReader(new InputStreamReader(is, "UTF-8"));
try {
String factoryName = r.readLine();
if (!isEmptyString(factoryName)) return factoryName;
} finally {
r.close();
}
}
} catch (IOException ignore) {
}
return DEFAULT_FACTORY_NAME;
}
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/CacheStatistics.java 0000644 0001750 0001750 00000001312 10617577002 024045 0 ustar arnaud arnaud package net.sf.jsr107cache;
public interface CacheStatistics {
public static final int STATISTICS_ACCURACY_NONE = 0;
public static final int STATISTICS_ACCURACY_BEST_EFFORT = 1;
public static final int STATISTICS_ACCURACY_GUARANTEED = 2;
public int getStatisticsAccuracy();
// REVIEW adam@bea.com 21-Jun-04 - How does this differ from Cache.size()?
// REVIEW brian@quiotix.com - Implementation may well delegate to Cache.size,
// but it seemed like it would be a glaring omission to leave objectCount
// out of CacheStatistics
public int getObjectCount();
public int getCacheHits();
public int getCacheMisses();
public void clearStatistics();
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/EvictionStrategy.java 0000644 0001750 0001750 00000000463 10617577002 024300 0 ustar arnaud arnaud package net.sf.jsr107cache;
import java.util.Map;
public interface EvictionStrategy {
public CacheEntry createEntry(Object key, Object value, long ttl);
public void discardEntry(CacheEntry e);
public void touchEntry(CacheEntry entry);
public void clear();
public Map evict(Cache c);
}
jsr107cache-1.0.dfsg.1.orig/net/sf/jsr107cache/overview.html 0000644 0001750 0001750 00000000277 10617577002 022671 0 ustar arnaud arnaud
Overview
jsr107cache is a place for the evolving JCACHE API so that code can be written to the spec before final release.
jsr107cache-1.0.dfsg.1.orig/LICENSE.txt 0000644 0001750 0001750 00000001141 10617576650 016547 0 ustar arnaud arnaud /**
* Copyright 2003-2007 Greg Luck
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/