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 true if the cache has a valid cached item specified by the
046 key. If no item is found for that key or if the item has expired,
047 returns <tt>false</tt>.
048
049 @param key typically a <tt>String</tt> but can be any object
050 **/
051 public boolean containsKey(Object key);
052
053
054 /**
055 Returns the cached item specified by the key. If no item is found for that
056 key or if the item has expired, returns <tt>null</tt>.
057
058 @param key typically a <tt>String</tt> but can be any object
059 **/
060 public Object get(Object key);
061
062 /**
063 Returns all objects in the cache. The returned map is implementation specific
064 but will typically contain <key,item> pairs of all objects in the cache. The
065 item might be encapsulated in another implementation-specific class.
066 <p>
067 Modification to this map will affect this cache.
068 **/
069 public Map getAll();
070
071 /**
072 Puts the specified object into the cache, mapped with the specified key.
073 The object stays in the cache for the specified amount of time, after which
074 it is discarded. If that key already contains a value, then that value is
075 returned by this method (and also replaced by the new value).
076
077 @param key key with which the specified value is to be associated.
078 @param val value to be associated with the specified key.
079 @param expiry time in <b>milliseconds</b> (from the time the
080 object is put into the cache) before it is expired. Specify
081 <tt>-1</tt> for the <tt>item</tt> to never expire.
082 **/
083 public Object put(Object key, Object val, long expiry);
084
085 /**
086 Convenience method that puts an object into the cache that expires in
087 the default TTL. The default TTL can be get/set by the {@link #setDefaultTTL}
088 method and subclasses are free to implement a default TTL as they see fit.
089 If that key already contains a value, then that value is returned by this
090 method (and also replaced by the new value).
091 **/
092 public Object put(Object key, Object item);
093
094 /**
095 Returns the amount of time left (in milliseconds) before the object will be
096 expired from the cache.
097 <p>If the object specified by the key is <i>not</i> found in the cache,
098 then <tt>0</tt> is returned.
099 <p>If the object has already expired, then <tt>0</tt> is returned.
100 <p>If the object will never expire, then <tt>-1</tt> is returned.
101
102 @param key the key with which to find the object under consideration.
103 **/
104 public long getTimeLeft(Object key);
105
106 /**
107 Expires immediately the object specified by the key. Overrides any previous
108 setting for that object's expire time.
109
110 @param key the key with which to find the object under consideration.
111 **/
112 void expire(Object key);
113
114 /**
115 Adds the specified amount of time to the object (to it's current time left)
116 before that object will be expired. Overrides any previous setting that the
117 object may have had, such as never expiring. Specify <tt>-1</tt> for that
118 object to never expire. Does not work for objects that have already
119 expired.
120
121 @param key the key with which to find the object
122 under consideration.
123 @param extendTime exntension time in milliseconds, valid
124 values are >= 0 and -1
125 **/
126 void extend(Object key, long extendTime);
127
128 /**
129 Sets the default TTL in milliseconds.
130 */
131 void setDefaultTTL(long millis);
132
133 /**
134 Gets the default TTL in milliseconds.
135 */
136 long getDefaultTTL();
137
138 /**
139 Closes this cache, which makes all items in the cache unavailable. Any
140 items needed for later should be taken out of the cache before closing it.
141 **/
142 public void close();
143
144 /**
145 Returns true if this cache has been closed, false otherwise.
146 **/
147 public boolean isClosed();
148 }