001    package org.rakeshv.utils;
002    
003    /**
004     * A sub-class of <code>java.util.Map</code> that defines additional
005     * methods that will be implemented by all the implementations that
006     * are used to implement caches.
007     *
008     * <p>Copyright 2004-2006 Rakesh Vidyadharan</p>
009     * @author Rakesh Vidyadharan 2004 September 1
010     * @version $Id: Map.java,v 1.1 2006/03/11 01:00:43 rakesh Exp $
011     */
012    public interface Map<K,V> extends java.util.Map<K,V>
013    {
014      /**
015       * Returns the maximum number of entries that may be held in the map.
016       *
017       * @return int The maximum numer of entries.
018       */
019      public int getMaxEntries();
020      
021      /**
022       * Set the maximum number of entries that may be help in the map.  
023       * This can be used to dynamically change the size of the cache.
024       *
025       * @param maxEntries The value to set.
026       */
027      public void setMaxEntries( int maxEntries );
028      
029      /**
030       * Returns statistics about cache access.  This may be used by client
031       * applications to monitor cache usage.
032       *
033       * @return Statistics The object that contains information about
034       *   cache access.
035       */
036      public Statistics getStatistics();
037    
038      /**
039       * An interface that defines the methods that may be invoked to
040       * monitor cache usage.
041       */
042      public interface Statistics
043      {
044        /**
045         * Returns the total number of requests that have been made for
046         * <code>values</code> from the cache based upon a <code>key</code>.
047         *
048         * @return int The total number of requests.
049         */
050        public int getTotalRequests();
051        
052        /**
053         * Returns the total number of successful requests for
054         * <code>values</code> from the cache based upon a <code>key</code>.
055         *
056         * @return int The total number of successful requests.
057         */
058        public int getSuccessfulRequests();
059        
060        /**
061         * Returns the total number of <code>Map.Entry</code> items that
062         * were evicted from the cache after it reached its maximum
063         * configured size.  Note that this value does not track user
064         * triggered entry removals from the cache.
065         *
066         * @return int The total number of entries that have been removed
067         *   from the cache.
068         */
069        public int getTotalRemoved();
070      }
071    }