001 /** 002 * JDBM LICENSE v1.00 003 * 004 * Redistribution and use of this software and associated documentation 005 * ("Software"), with or without modification, are permitted provided 006 * that the following conditions are met: 007 * 008 * 1. Redistributions of source code must retain copyright 009 * statements and notices. Redistributions must also contain a 010 * copy of this document. 011 * 012 * 2. Redistributions in binary form must reproduce the 013 * above copyright notice, this list of conditions and the 014 * following disclaimer in the documentation and/or other 015 * materials provided with the distribution. 016 * 017 * 3. The name "JDBM" must not be used to endorse or promote 018 * products derived from this Software without prior written 019 * permission of Cees de Groot. For written permission, 020 * please contact cg@cdegroot.com. 021 * 022 * 4. Products derived from this Software may not be called "JDBM" 023 * nor may "JDBM" appear in their names without prior written 024 * permission of Cees de Groot. 025 * 026 * 5. Due credit should be given to the JDBM Project 027 * (http://jdbm.sourceforge.net/). 028 * 029 * THIS SOFTWARE IS PROVIDED BY THE JDBM PROJECT AND CONTRIBUTORS 030 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 031 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 032 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 033 * CEES DE GROOT OR ANY CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 034 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 035 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 036 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 037 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 038 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 039 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 040 * OF THE POSSIBILITY OF SUCH DAMAGE. 041 * 042 * Copyright 2000 (C) Cees de Groot. All Rights Reserved. 043 * Contributions are Copyright (C) 2000 by their associated contributors. 044 * 045 * $Id: CachePolicy.java,v 1.5 2003/11/01 13:25:02 dranatunga Exp $ 046 */ 047 package jdbm.helper; 048 049 050 import java.util.Enumeration; 051 052 053 /** 054 * CachePolicity is an abstraction for different cache policies. 055 * (ie. MRU, time-based, soft-refs, ...) 056 * 057 * @author <a href="mailto:boisvert@intalio.com">Alex Boisvert</a> 058 * @author <a href="mailto:dranatunga@users.sourceforge.net">Dilum Ranatunga</a> 059 * @version $Id: CachePolicy.java,v 1.5 2003/11/01 13:25:02 dranatunga Exp $ 060 */ 061 public interface CachePolicy<K,V> 062 { 063 /** 064 * Place an object in the cache. If the cache does not currently contain 065 * an object for the key specified, this mapping is added. If an object 066 * currently exists under the specified key, the current object is 067 * replaced with the new object. 068 * <p> 069 * If the changes to the cache cause the eviction of any objects 070 * <strong>stored under other key(s)</strong>, events corresponding to 071 * the evictions are fired for each object. If an event listener is 072 * unable to handle the eviction, and throws a cache eviction exception, 073 * that exception is propagated to the caller. If such an exception is 074 * thrown, the cache itself should be left as it was before the 075 * <code>put()</code> operation was invoked: the the object whose 076 * eviction failed is still in the cache, and the new insertion or 077 * modification is reverted. 078 * 079 * @param key key for the cached object 080 * @param value the cached object 081 * @throws CacheEvictionException propagated if, while evicting objects 082 * to make room for new object, an eviction listener encountered 083 * this problem. 084 */ 085 public void put( K key, V value ) throws CacheEvictionException; 086 087 088 /** 089 * Obtain the object stored under the key specified. 090 * 091 * @param key key the object was cached under 092 * @return the object if it is still in the cache, null otherwise. 093 */ 094 public V get( K key ); 095 096 097 /** 098 * Remove the object stored under the key specified. Note that since 099 * eviction notices are only fired when objects under <strong>different 100 * keys</strong> are evicted, no event is fired for any object stored 101 * under this key (see {@link #put(Object, Object) put( )}). 102 * 103 * @param key key the object was stored in the cache under. 104 */ 105 public void remove( K key ); 106 107 108 /** 109 * Remove all objects from the cache. Consistent with 110 * {@link #remove(Object) remove( )}, no eviction notices are fired. 111 */ 112 public void removeAll(); 113 114 115 /** 116 * Enumerate through the objects currently in the cache. 117 */ 118 public Enumeration<V> elements(); 119 120 121 /** 122 * Add a listener to this cache policy. 123 * <p> 124 * If this cache policy already contains a listener that is equal to 125 * the one being added, this call has no effect. 126 * 127 * @param listener the (non-null) listener to add to this policy 128 * @throws IllegalArgumentException if listener is null. 129 */ 130 public void addListener( CachePolicyListener<V> listener ) throws IllegalArgumentException; 131 132 133 /** 134 * Remove a listener from this cache policy. The listener is found 135 * using object equality, not identity. 136 * 137 * @param listener the listener to remove from this policy 138 */ 139 public void removeListener( CachePolicyListener<V> listener ); 140 }