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    }