001/*-------------------------------------------------------------------------+
002|                                                                          |
003| Copyright 2005-2011 The ConQAT Project                                   |
004|                                                                          |
005| Licensed under the Apache License, Version 2.0 (the "License");          |
006| you may not use this file except in compliance with the License.         |
007| You may obtain a copy of the License at                                  |
008|                                                                          |
009|    http://www.apache.org/licenses/LICENSE-2.0                            |
010|                                                                          |
011| Unless required by applicable law or agreed to in writing, software      |
012| distributed under the License is distributed on an "AS IS" BASIS,        |
013| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
014| See the License for the specific language governing permissions and      |
015| limitations under the License.                                           |
016+-------------------------------------------------------------------------*/
017package org.conqat.lib.commons.cache4j;
018
019import org.conqat.lib.commons.error.NeverThrownRuntimeException;
020import org.conqat.lib.commons.factory.IParameterizedFactory;
021
022/**
023 * Basic interface for a cache, which is basically a
024 * {@link IParameterizedFactory} with additional hit/miss statistics.
025 * 
026 * @param <K>
027 *            the key type. This must have both {@link Object#equals(Object)}
028 *            and {@link Object#hashCode()} correctly implemented.
029 * @param <V>
030 *            the value type. It is generally recommended to use an immutable
031 *            type here, but this is not required.
032 * @param <X>
033 *            the type of exception thrown. If no exception will be throws, use
034 *            {@link NeverThrownRuntimeException}.
035 */
036public interface ICache<K, V, X extends Exception> {
037
038        /**
039         * Obtain the value for a key. This returns the cached element is possible.
040         * Otherwise the value is calculated (and stored in the cache for later
041         * use).
042         */
043        V obtain(K key) throws X;
044
045        /**
046         * Clears the cache, i.e. removes all cached data.
047         * 
048         * @param allThreads
049         *            if this is true, data will be discarded for all threads,
050         *            otherwise only data for the current thread will be cleaned (if
051         *            possible).
052         */
053        void clear(boolean allThreads);
054
055        /** Returns the name (used for reporting). */
056        String getName();
057
058        /** Returns the number of cache hits so far. */
059        int getHits();
060
061        /** Returns the number of cache misses so far. */
062        int getMisses();
063
064        /**
065         * Returns an estimation of the overhead caused by cache misses in
066         * milliseconds.
067         */
068        long getMissCostMillis();
069}