001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2004-2005 TONBELLER AG
008// Copyright (C) 2006-2012 Pentaho and others
009// All Rights Reserved.
010*/
011package mondrian.rolap.cache;
012
013import java.util.Iterator;
014import java.util.Map.Entry;
015
016/**
017 * Defines a cache API. Implementations exist for hard and soft references.
018 *
019 * <p>To iterate over the contents of a cache, you must pass a
020 * {@link #execute(SmartCacheTask)} instance. The code using the iterator
021 * can be assured that it will be thread safe.
022 *
023 * <p>Implementations are responsible of enforcing thread safety.
024 * @author av
025 * @since Nov 21, 2005
026 */
027public interface SmartCache <K, V> {
028    /**
029     * Places a key/value pair into the cache.
030     *
031     * @param key Key
032     * @param value Value
033     * @return the previous value of <code>key</code> or null
034     */
035    V put(K key, V value);
036
037    /**
038     * Looks up and returns a cache value according to a given key.
039     * If the cache does not correspond an entry corresponding to the key,
040     * <code>null</code> is returned.
041     */
042    V get(K key);
043
044    /**
045     * Removes a key from the cache.
046     *
047     * @param key Key
048     *
049     * @return Previous value associated with the key
050     */
051    V remove(K key);
052
053    /**
054     * Clears the contents of this cache.
055     */
056    void clear();
057
058    /**
059     * Returns the number of elements in cache.
060     */
061    int size();
062
063    /**
064     * Executes a task over the contents of the cache and guarantees
065     * exclusive write access while processing.
066     * @param task The task to execute.
067     */
068    void execute(SmartCacheTask<K, V> task);
069
070    /**
071     * Defines a task to be run over the entries of the cache.
072     * Used in conjunction with {@link #execute(Iterator)}.
073     */
074    public interface SmartCacheTask<K, V> {
075        void execute(
076            Iterator<Entry<K, V>> iterator);
077    }
078}
079
080// End SmartCache.java