1 /** 2 * JDBM LICENSE v1.00 3 * 4 * Redistribution and use of this software and associated documentation 5 * ("Software"), with or without modification, are permitted provided 6 * that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain copyright 9 * statements and notices. Redistributions must also contain a 10 * copy of this document. 11 * 12 * 2. Redistributions in binary form must reproduce the 13 * above copyright notice, this list of conditions and the 14 * following disclaimer in the documentation and/or other 15 * materials provided with the distribution. 16 * 17 * 3. The name "JDBM" must not be used to endorse or promote 18 * products derived from this Software without prior written 19 * permission of Cees de Groot. For written permission, 20 * please contact cg@cdegroot.com. 21 * 22 * 4. Products derived from this Software may not be called "JDBM" 23 * nor may "JDBM" appear in their names without prior written 24 * permission of Cees de Groot. 25 * 26 * 5. Due credit should be given to the JDBM Project 27 * (http://jdbm.sourceforge.net/). 28 * 29 * THIS SOFTWARE IS PROVIDED BY THE JDBM PROJECT AND CONTRIBUTORS 30 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 31 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 32 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 33 * CEES DE GROOT OR ANY CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 34 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 35 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 36 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 37 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 38 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 39 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 40 * OF THE POSSIBILITY OF SUCH DAMAGE. 41 * 42 * Copyright 2000 (C) Cees de Groot. All Rights Reserved. 43 * Contributions are Copyright (C) 2000 by their associated contributors. 44 * 45 * $Id: CachePolicy.java,v 1.5 2003/11/01 13:25:02 dranatunga Exp $ 46 */ 47 48 package jdbm.helper; 49 50 import java.util.Enumeration; 51 52 /** 53 * CachePolicity is an abstraction for different cache policies. 54 * (ie. MRU, time-based, soft-refs, ...) 55 * 56 * @author <a href="mailto:boisvert@intalio.com">Alex Boisvert</a> 57 * @author <a href="mailto:dranatunga@users.sourceforge.net">Dilum Ranatunga</a> 58 * @version $Id: CachePolicy.java,v 1.5 2003/11/01 13:25:02 dranatunga Exp $ 59 */ 60 public interface CachePolicy 61 { 62 63 /** 64 * Place an object in the cache. If the cache does not currently contain 65 * an object for the key specified, this mapping is added. If an object 66 * currently exists under the specified key, the current object is 67 * replaced with the new object. 68 * <p> 69 * If the changes to the cache cause the eviction of any objects 70 * <strong>stored under other key(s)</strong>, events corresponding to 71 * the evictions are fired for each object. If an event listener is 72 * unable to handle the eviction, and throws a cache eviction exception, 73 * that exception is propagated to the caller. If such an exception is 74 * thrown, the cache itself should be left as it was before the 75 * <code>put()</code> operation was invoked: the the object whose 76 * eviction failed is still in the cache, and the new insertion or 77 * modification is reverted. 78 * 79 * @param key key for the cached object 80 * @param value the cached object 81 * @throws CacheEvictionException propagated if, while evicting objects 82 * to make room for new object, an eviction listener encountered 83 * this problem. 84 */ 85 public void put( Object key, Object value ) 86 throws CacheEvictionException; 87 88 89 /** 90 * Obtain the object stored under the key specified. 91 * 92 * @param key key the object was cached under 93 * @return the object if it is still in the cache, null otherwise. 94 */ 95 public Object get( Object key ); 96 97 98 /** 99 * Remove the object stored under the key specified. Note that since 100 * eviction notices are only fired when objects under <strong>different 101 * keys</strong> are evicted, no event is fired for any object stored 102 * under this key (see {@link #put(Object, Object) put( )}). 103 * 104 * @param key key the object was stored in the cache under. 105 */ 106 public void remove( Object key ); 107 108 109 /** 110 * Remove all objects from the cache. Consistent with 111 * {@link #remove(Object) remove( )}, no eviction notices are fired. 112 */ 113 public void removeAll(); 114 115 116 /** 117 * Enumerate through the objects currently in the cache. 118 */ 119 public Enumeration elements(); 120 121 122 /** 123 * Add a listener to this cache policy. 124 * <p> 125 * If this cache policy already contains a listener that is equal to 126 * the one being added, this call has no effect. 127 * 128 * @param listener the (non-null) listener to add to this policy 129 * @throws IllegalArgumentException if listener is null. 130 */ 131 public void addListener( CachePolicyListener listener ) 132 throws IllegalArgumentException; 133 134 135 /** 136 * Remove a listener from this cache policy. The listener is found 137 * using object equality, not identity. 138 * 139 * @param listener the listener to remove from this policy 140 */ 141 public void removeListener( CachePolicyListener listener ); 142 143 }