001: /**
002: * $RCSfile$
003: * $Revision: 8311 $
004: * $Date: 2007-05-14 12:51:36 -0700 (Mon, 14 May 2007) $
005: *
006: * Copyright (C) 2004 Jive Software. All rights reserved.
007: *
008: * This software is published under the terms of the GNU Public License (GPL),
009: * a copy of which is included in this distribution.
010: */package org.jivesoftware.util.cache;
011:
012: /**
013: * General purpose cache. It stores objects associated with unique keys in
014: * memory for fast access. All keys and values added to the cache must
015: * implement the Serializable interface. Values may implement the Cacheable
016: * interface, which allows the cache to determine object size much more quickly.
017: * These restrictions allow a cache to never grow larger than a specified number
018: * of bytes and to optionally be distributed over a cluster of servers.<p>
019: *
020: * If the cache does grow too large, objects will be removed such that those
021: * that are accessed least frequently are removed first. Because expiration
022: * happens automatically, the cache makes <b>no</b> gaurantee as to how long
023: * an object will remain in cache after it is put in.<p>
024: *
025: * Optionally, a maximum lifetime for all objects can be specified. In that
026: * case, objects will be deleted from cache after that amount of time, even
027: * if they are frequently accessed. This feature is useful if objects put in
028: * cache represent data that should be periodically refreshed; for example,
029: * information from a database.<p>
030: *
031: * All cache operations are thread safe.<p>
032: *
033: * @see Cacheable
034: */
035: public interface Cache<K, V> extends java.util.Map<K, V> {
036:
037: /**
038: * Returns the name of the cache.
039: *
040: * @return the name of the cache.
041: */
042: String getName();
043:
044: /**
045: * Sets the name of the cache
046: *
047: * @param name the name of the cache
048: */
049: void setName(String name);
050:
051: /**
052: * Returns the maximum size of the cache in bytes. If the cache grows larger
053: * than the max size, the least frequently used items will be removed. If
054: * the max cache size is set to -1, there is no size limit.
055: *
056: * @return the maximum size of the cache in bytes.
057: */
058: long getMaxCacheSize();
059:
060: /**
061: * Sets the maximum size of the cache in bytes. If the cache grows larger
062: * than the max size, the least frequently used items will be removed. If
063: * the max cache size is set to -1, there is no size limit.
064: *
065: * @param maxSize the maximum size of the cache in bytes.
066: */
067: void setMaxCacheSize(int maxSize);
068:
069: /**
070: * Returns the maximum number of milliseconds that any object can live
071: * in cache. Once the specified number of milliseconds passes, the object
072: * will be automatically expried from cache. If the max lifetime is set
073: * to -1, then objects never expire.
074: *
075: * @return the maximum number of milliseconds before objects are expired.
076: */
077: long getMaxLifetime();
078:
079: /**
080: * Sets the maximum number of milliseconds that any object can live
081: * in cache. Once the specified number of milliseconds passes, the object
082: * will be automatically expried from cache. If the max lifetime is set
083: * to -1, then objects never expire.
084: *
085: * @param maxLifetime the maximum number of milliseconds before objects are expired.
086: */
087: void setMaxLifetime(long maxLifetime);
088:
089: /**
090: * Returns the size of the cache contents in bytes. This value is only a
091: * rough approximation, so cache users should expect that actual VM
092: * memory used by the cache could be significantly higher than the value
093: * reported by this method.
094: *
095: * @return the size of the cache contents in bytes.
096: */
097: int getCacheSize();
098:
099: /**
100: * Returns the number of cache hits. A cache hit occurs every
101: * time the get method is called and the cache contains the requested
102: * object.<p>
103: *
104: * Keeping track of cache hits and misses lets one measure how efficient
105: * the cache is; the higher the percentage of hits, the more efficient.
106: *
107: * @return the number of cache hits.
108: */
109: long getCacheHits();
110:
111: /**
112: * Returns the number of cache misses. A cache miss occurs every
113: * time the get method is called and the cache does not contain the
114: * requested object.<p>
115: *
116: * Keeping track of cache hits and misses lets one measure how efficient
117: * the cache is; the higher the percentage of hits, the more efficient.
118: *
119: * @return the number of cache hits.
120: */
121: long getCacheMisses();
122:
123: }
|