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    }