/*
* Copyright Terracotta, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.ehcache;
import org.ehcache.config.
CacheRuntimeConfiguration;
import org.ehcache.spi.loaderwriter.
BulkCacheLoadingException;
import org.ehcache.spi.loaderwriter.
BulkCacheWritingException;
import org.ehcache.spi.loaderwriter.
CacheLoadingException;
import org.ehcache.spi.loaderwriter.
CacheWritingException;
import org.ehcache.spi.loaderwriter.
CacheLoaderWriter;
import java.util.
Map;
import java.util.
Set;
/**
* Defines all operational methods to create, access, update and delete mappings of key to value.
* <p>
* In order to function, cache keys must respect the {@link Object#hashCode() hash code} and
* {@link Object#equals(Object) equals} contracts. This contract is what will be used to lookup values based on key.
* <p>
* A {@code Cache} is not a map, mostly because it has the following two concepts linked to mappings:
* <ul>
* <li>Eviction: A {@code Cache} has a capacity constraint and in order to honor it, a {@code Cache} can
* evict (remove) a mapping at any point in time. Note that eviction may occur before maximum capacity is
* reached.</li>
* <li>Expiry: Data in a {@code Cache} can be configured to expire after some time. There is no way for a
* {@code Cache} user to differentiate from the API between a mapping being absent or expired.</li>
* </ul>
*
* @param <K> the key type for the cache
* @param <V> the value type for the cache
*/
public interface
Cache<K, V> extends
Iterable<
Cache.
Entry<K,V>> {
/**
* Retrieves the value currently mapped to the provided key.
*
* @param key the key, may not be {@code null}
* @return the value mapped to the key, {@code null} if none
*
* @throws NullPointerException if the provided key is {@code null}
* @throws CacheLoadingException if the {@link CacheLoaderWriter} associated with this cache was
* invoked and threw an {@code Exception}
*/
V
get(K
key) throws
CacheLoadingException;
/**
* Associates the given value to the given key in this {@code Cache}.
*
* @param key the key, may not be {@code null}
* @param value the value, may not be {@code null}
*
* @throws NullPointerException if either key or value is {@code null}
* @throws CacheWritingException if the {@link CacheLoaderWriter} associated with this cache threw an
* {@link Exception} while writing the value for the given key to the underlying system of record.
*/
void
put(K
key, V
value) throws
CacheWritingException;
/**
* Checks whether a mapping for the given key is present, without retrieving the associated value.
*
* @param key the key, may not be {@code null}
* @return {@code true} if a mapping is present, {@code false} otherwise
*
* @throws NullPointerException if the provided key is {@code null}
*/
boolean
containsKey(K
key);
/**
* Removes the value, if any, associated with the provided key.
*
* @param key the key to remove the value for, may not be {@code null}
*
* @throws NullPointerException if the provided key is {@code null}
* @throws CacheWritingException if the {@link CacheLoaderWriter} associated with this cache threw an
* {@link Exception} while removing the value for the given key from the underlying system of record.
*/
void
remove(K
key) throws
CacheWritingException;
/**
* Retrieves all values associated with the given key set.
*
* @param keys keys to query for, may not contain {@code null}
* @return a map from keys to values or {@code null} if the key was not mapped
*
* @throws NullPointerException if the {@code Set} or any of the contained keys are {@code null}.
* @throws BulkCacheLoadingException if loading some or all values failed
*/
Map<K, V>
getAll(
Set<? extends K>
keys) throws
BulkCacheLoadingException;
/**
* Associates all the provided key:value pairs.
*
* @param entries key:value pairs to associate, keys or values may not be {@code null}
*
* @throws NullPointerException if the {@code Map} or any of the contained keys or values are {@code null}.
* @throws BulkCacheWritingException if the {@link CacheLoaderWriter} associated with this cache threw an
* {@link Exception} while writing given key:value pairs to the underlying system of record.
*/
void
putAll(
Map<? extends K, ? extends V>
entries) throws
BulkCacheWritingException;
/**
* Removes any associated value for the given key set.
*
* @param keys keys to remove values for, may not be {@code null}
*
* @throws NullPointerException if the {@code Set} or any of the contained keys are {@code null}.
* @throws BulkCacheWritingException if the {@link CacheLoaderWriter} associated with this cache threw an
* {@link Exception} while removing mappings for given keys from the underlying system of record.
*/
void
removeAll(
Set<? extends K>
keys) throws
BulkCacheWritingException;
/**
* Removes all mappings currently present in the {@code Cache}.
* <p>
* It does so without invoking the {@link CacheLoaderWriter} or any registered
* {@link org.ehcache.event.CacheEventListener} instances.
* <em>This is not an atomic operation and can potentially be very expensive.</em>
*/
void
clear();
/**
* Maps the specified key to the specified value in this cache, unless a non-expired mapping
* already exists.
* <p>
* This is equivalent to
* <pre>
* if (!cache.containsKey(key))
* cache.put(key, value);
* return null;
* else
* return cache.get(key);
* </pre>
* except that the action is performed atomically.
* <p>
* The value can be retrieved by calling the {@code get} method
* with a key that is equal to the original key.
* <p>
* Neither the key nor the value can be {@code null}.
*
* @param key key with which the specified value is to be associated
* @param value value to be associated with the specified key
* @return the value to which the specified key was previously mapped,
* or {@code null} if no such mapping existed or the mapping was expired
*
* @throws NullPointerException if any of the arguments is {@code null}
* @throws CacheWritingException if the {@link CacheLoaderWriter} associated
* with this cache threw an {@link Exception} while writing the value for the
* given key to the underlying system of record.
* @throws CacheLoadingException if the {@link CacheLoaderWriter}
* associated with this cache was invoked and threw an {@link Exception}
*/
V
putIfAbsent(K
key, V
value) throws
CacheLoadingException,
CacheWritingException;
/**
* Removes the entry for a key only if currently mapped to the given value
* and the entry is not expired.
* <p>
* This is equivalent to
* <pre>
* if (cache.containsKey(key) && cache.get(key).equals(value)) {
* cache.remove(key);
* return true;
* } else return false;
* </pre>
* except that the action is performed atomically.
* <p>
* The key cannot be {@code null}.
*
* @param key key with which the specified value is associated
* @param value value expected to be removed
* @return true if the value was successfully removed
*
* @throws NullPointerException if any of the arguments is {@code null}
* @throws CacheWritingException if the {@link CacheLoaderWriter} associated
* with this cache threw an {@link Exception} while removing the value for the
* given key from the underlying system of record.
*/
boolean
remove(K
key, V
value) throws
CacheWritingException;
/**
* Replaces the entry for a key only if currently mapped to some value and the entry is not expired.
* <p>
* This is equivalent to
* <pre>
* V oldValue = cache.get(key);
* if (oldValue != null) {
* cache.put(key, value);
* }
* return oldValue; </pre>
* except that the action is performed atomically.
* <p>
* Neither the key nor the value can be {@code null}.
*
* @param key of the value to be replaced
* @param value the new value
* @return the existing value that was associated with the key, or {@code null} if
* no such mapping existed or the mapping was expired
*
* @throws NullPointerException if any of the arguments is {@code null}
* @throws CacheWritingException if the {@link CacheLoaderWriter} associated
* with this cache threw an {@link Exception} while writing the value for the
* given key to the underlying system of record.
* @throws CacheLoadingException if the {@link CacheLoaderWriter}
* associated with this cache was invoked and threw an {@link Exception}
*/
V
replace(K
key, V
value) throws
CacheLoadingException,
CacheWritingException;
/**
* Replaces the entry for a key only if currently mapped to the given value
* and the entry is not expired.
* <p>
* This is equivalent to
* <pre>
* if (cache.containsKey(key) && cache.get(key).equals(oldValue)) {
* cache.put(key, newValue);
* return true;
* } else return false;</pre>
* except that the action is performed atomically.
* <p>
* Neither the key nor the value can be {@code null}.
*
* @param key key with which the specified value is associated
* @param oldValue value expected to be associated with the specified key
* @param newValue value to be associated with the specified key
* @return true if the oldValue was successfully replaced by the newValue
*
* @throws NullPointerException if any of the arguments is {@code null}
* @throws CacheWritingException if the {@link CacheLoaderWriter} associated
* with this cache threw an {@link Exception} while writing the value for the
* given key to the underlying system of record.
* @throws CacheLoadingException if the {@link CacheLoaderWriter}
* associated with this cache was invoked and threw an {@link Exception}
*/
boolean
replace(K
key, V
oldValue, V
newValue) throws
CacheLoadingException,
CacheWritingException;
/**
* Exposes the {@link org.ehcache.config.CacheRuntimeConfiguration} associated with this Cache instance.
*
* @return the configuration currently in use
*/
CacheRuntimeConfiguration<K, V>
getRuntimeConfiguration();
/**
* A mapping of key to value held in a {@link Cache}.
*
* @param <K> the key type
* @param <V> the value type
*/
interface
Entry<K, V> {
/**
* Returns the key of this mapping
*
* @return the key, not {@code null}
*/
K
getKey();
/**
* Returns the value of this mapping
*
* @return the value, not {@code null}
*/
V
getValue();
}
}