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