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 }