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    }