001 /*--------------------------------------------------------------------------+ 002 $Id: CacheBase.java 26268 2010-02-18 10:44:30Z juergens $ 003 | | 004 | Copyright 2005-2010 Technische Universitaet Muenchen | 005 | | 006 | Licensed under the Apache License, Version 2.0 (the "License"); | 007 | you may not use this file except in compliance with the License. | 008 | You may obtain a copy of the License at | 009 | | 010 | http://www.apache.org/licenses/LICENSE-2.0 | 011 | | 012 | Unless required by applicable law or agreed to in writing, software | 013 | distributed under the License is distributed on an "AS IS" BASIS, | 014 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | 015 | See the License for the specific language governing permissions and | 016 | limitations under the License. | 017 +--------------------------------------------------------------------------*/ 018 package edu.tum.cs.commons.cache; 019 020 import edu.tum.cs.commons.error.NeverThrownRuntimeException; 021 022 /** 023 * Common base class for caches. This class basically works like a map that maps 024 * elements of type <code>I</code> to elements of type <code>E</code>. As this 025 * class uses a hash map and elements of type <code>I</code> are not necessarily 026 * suitable as hash map keys a special type (<code>H</code>) for the hash keys 027 * must be defined. Concrecte keys are determined by method 028 * <code>getHashKey(I)</code>. Please note that making the hash type explicit as 029 * generic parameter is not due to implementation reasons but to make design 030 * more obvious. 031 * 032 * @author hummelb 033 * @author $Author: juergens $ 034 * @version $Rev: 26268 $ 035 * @levd.rating GREEN Hash: A07537A9758D46A058FC18A23FBEB4FF 036 * 037 * @param <I> 038 * the index type of the cache 039 * @param <H> 040 * the hash map key type 041 * @param <E> 042 * the type stored in the cache 043 * @param <X> 044 * the type of exception thrown by the {@link #obtainItem(Object)} 045 * method. Use the {@link NeverThrownRuntimeException} if no 046 * exception will be thrown. 047 */ 048 public abstract class CacheBase<I, H, E, X extends Exception> { 049 050 /** 051 * Obtain an item from the cache. If the item was not cached yet, it will be 052 * cached. 053 * 054 * @param identifier 055 * an object identifying the item to retrieve from the cache. 056 * This class' implementation works with a hash map so 057 * identifiers must adhere to the conventions for 058 * <code>Object.hashcode()</code>. 059 * @return The item. 060 */ 061 public abstract E getItem(I identifier) throws X; 062 063 /** 064 * Extenders of the cache class must implemented that method to define the 065 * item acquisition mechanism. 066 * 067 * @param identifier 068 * identifer unambiguously identifying the item. 069 * @return the item to cache. 070 */ 071 protected abstract E obtainItem(I identifier) throws X; 072 073 /** 074 * Determine hash key for an identifier. If the identifier itself is a 075 * suitable hash key, simply return it or better, use one of the straight 076 * cache implementations. 077 * 078 * 079 * @param identifier 080 * @return an object that is suitable hash key 081 * @see Object#hashCode() 082 */ 083 protected abstract H getHashKey(I identifier); 084 }