001 // Copyright (c) 2001 Hursh Jain (http://www.mollypages.org)
002 // The Molly framework is freely distributable under the terms of an
003 // MIT-style license. For details, see the molly pages web site at:
004 // http://www.mollypages.org/. Use, modify, have fun !
005
006 package fc.util.cache;
007
008 import java.io.*;
009 import java.util.*;
010
011 // -cache hits, total, per-item, expired amount, average age
012 // -onexpire, onload
013
014
015 /**
016 A data cache. This is essentially a wrapper over a collection that allows
017 for objects to be cached for a specified amount of time and expired
018 thereafter. Objects in the cache can expire automatically or
019 can be removed manually.
020
021 @author hursh jain
022 @version 1.0 12/29/2001
023 **/
024 public interface Cache
025 {
026 /**
027 Empties the entire cache by expiring and removing all objects.
028 */
029 void clear();
030
031 /*
032 this is not needed, and implementations would have to convert all existing
033 cachedobject into a map of key,val pairs, because key,val pairs would
034 probably not be stored directly but wrapped around objects that also
035 maintain expire state
036
037 Returns a {@link java.util.Map} consisting of all cached items.
038 Implementations are required to return a <tt>Map</tt>,
039 regardless of their internal design.
040 */
041 //public Map getCacheMap();
042
043
044 /**
045 Returns the cached item specified by the key. If no item is found for that
046 key or if the item has expired, returns <tt>null</tt>.
047
048 @param key typically a <tt>String</tt> but can be any object
049 **/
050 public Object get(Object key);
051
052 /**
053 Returns all objects in the cache. The returned map is implementation specific
054 but will typically contain <key,item> pairs of all objects in the cache. The
055 item might be encapsulated in another implementation-specific class.
056 <p>
057 Modification to this map will affect this cache.
058 **/
059 public Map getAll();
060
061 /**
062 Puts the specified object into the cache, mapped with the specified key.
063 The object stays in the cache for the specified amount of time, after which
064 it is discarded. If that key already contains a value, then that value is
065 returned by this method (and also replaced by the new value).
066
067 @param key key with which the specified value is to be associated.
068 @param val value to be associated with the specified key.
069 @param expiry time in <b>milliseconds</b> (from the time the
070 object is put into the cache) before it is expired. Specify
071 <tt>-1</tt> for the <tt>item</tt> to never expire.
072 **/
073 public Object put(Object key, Object val, long expiry);
074
075 /**
076 Convenience method that puts an object into the cache that expires in
077 the default TTL. The default TTL can be get/set by the {@link #setDefaultTTL}
078 method and subclasses are free to implement a default TTL as they see fit.
079 If that key already contains a value, then that value is returned by this
080 method (and also replaced by the new value).
081 **/
082 public Object put(Object key, Object item);
083
084 /**
085 Returns the amount of time left (in milliseconds) before the object will be
086 expired from the cache.
087 <p>If the object specified by the key is <i>not</i> found in the cache,
088 then <tt>0</tt> is returned.
089 <p>If the object has already expired, then <tt>0</tt> is returned.
090 <p>If the object will never expire, then <tt>-1</tt> is returned.
091
092 @param key the key with which to find the object under consideration.
093 **/
094 public long getTimeLeft(Object key);
095
096 /**
097 Expires immediately the object specified by the key. Overrides any previous
098 setting for that object's expire time.
099
100 @param key the key with which to find the object under consideration.
101 **/
102 void expire(Object key);
103
104 /**
105 Adds the specified amount of time to the object (to it's current time left)
106 before that object will be expired. Overrides any previous setting that the
107 object may have had, such as never expiring. Specify <tt>-1</tt> for that
108 object to never expire. Does not work for objects that have already
109 expired.
110
111 @param key the key with which to find the object
112 under consideration.
113 @param extendTime exntension time in milliseconds, valid
114 values are >= 0 and -1
115 **/
116 void extend(Object key, long extendTime);
117
118 /**
119 Sets the default TTL in milliseconds.
120 */
121 void setDefaultTTL(long millis);
122
123 /**
124 Gets the default TTL in milliseconds.
125 */
126 long getDefaultTTL();
127
128 /**
129 Closes this cache, which makes all items in the cache unavailable. Any
130 items needed for later should be taken out of the cache before closing it.
131 **/
132 public void close();
133
134 /**
135 Returns true if this cache has been closed, false otherwise.
136 **/
137 public boolean isClosed();
138 }