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 }