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.backend;
018
019/**
020 * Interface for cache backends. This is a basic key-based get/set interface.
021 * However, we do not use the method names from the map interface, as we do not
022 * have map semantics (i.e. information can get lost).
023 * <p>
024 * Implementations are not required to deal with synchronization. This has to be
025 * handled by the caller.
026 * 
027 * @param <K>
028 *            the key type. This must have both {@link Object#equals(Object)}
029 *            and {@link Object#hashCode()} correctly implemented.
030 * 
031 * @param <V>
032 *            the value type. It is generally recommended to use an immutable
033 *            type here, but this is not required.
034 */
035public interface ICacheBackend<K, V> {
036
037        /** Stores an element (value) using the given key. */
038        void store(K key, V value);
039
040        /**
041         * Returns the value stored at a given key or null. The cache guarantees,
042         * that only values inserted via {@link #store(Object, Object)} can be
043         * returned. However, there is no guarantee that a non-null value is
044         * returned, i.e. the cache may forget information.
045         */
046        V retrieve(K key);
047
048        /**
049         * Returns a new instance of this backend. This is required as certain cache
050         * implementations require multiple backends, and cloning is not an option
051         * as we do not want to duplicate the cache contents.
052         */
053        ICacheBackend<K, V> newInstance();
054}