/*
* Copyright 2002-2017 the original author or authors.
*
* 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.springframework.cache;
import java.util.concurrent.Callable;
import org.springframework.lang.Nullable;
Interface that defines common cache operations.
Note: Due to the generic use of caching, it is recommended that
implementations allow storage of null values (for example to cache methods that return null). Author: Costin Leau, Juergen Hoeller, Stephane Nicoll Since: 3.1
/**
* Interface that defines common cache operations.
*
* <b>Note:</b> Due to the generic use of caching, it is recommended that
* implementations allow storage of <tt>null</tt> values (for example to
* cache methods that return {@code null}).
*
* @author Costin Leau
* @author Juergen Hoeller
* @author Stephane Nicoll
* @since 3.1
*/
public interface Cache {
Return the cache name.
/**
* Return the cache name.
*/
String getName();
Return the underlying native cache provider.
/**
* Return the underlying native cache provider.
*/
Object getNativeCache();
Return the value to which this cache maps the specified key.
Returns null if the cache contains no mapping for this key; otherwise, the cached value (which may be null itself) will be returned in a ValueWrapper.
Params: - key – the key whose associated value is to be returned
See Also: Returns: the value to which this cache maps the specified key, contained within a ValueWrapper which may also hold a cached null value. A straight null being returned means that the cache contains no mapping for this key.
/**
* Return the value to which this cache maps the specified key.
* <p>Returns {@code null} if the cache contains no mapping for this key;
* otherwise, the cached value (which may be {@code null} itself) will
* be returned in a {@link ValueWrapper}.
* @param key the key whose associated value is to be returned
* @return the value to which this cache maps the specified key,
* contained within a {@link ValueWrapper} which may also hold
* a cached {@code null} value. A straight {@code null} being
* returned means that the cache contains no mapping for this key.
* @see #get(Object, Class)
*/
@Nullable
ValueWrapper get(Object key);
Return the value to which this cache maps the specified key,
generically specifying a type that return value will be cast to.
Note: This variant of get does not allow for differentiating between a cached null value and no cache entry found at all. Use the standard get(Object) variant for that purpose instead.
Params: - key – the key whose associated value is to be returned
- type – the required type of the returned value (may be
null to bypass a type check; in case of a null value found in the cache, the specified type is irrelevant)
Throws: - IllegalStateException – if a cache entry has been found
but failed to match the specified type
See Also: Returns: the value to which this cache maps the specified key (which may be null itself), or also null if the cache contains no mapping for this key Since: 4.0
/**
* Return the value to which this cache maps the specified key,
* generically specifying a type that return value will be cast to.
* <p>Note: This variant of {@code get} does not allow for differentiating
* between a cached {@code null} value and no cache entry found at all.
* Use the standard {@link #get(Object)} variant for that purpose instead.
* @param key the key whose associated value is to be returned
* @param type the required type of the returned value (may be
* {@code null} to bypass a type check; in case of a {@code null}
* value found in the cache, the specified type is irrelevant)
* @return the value to which this cache maps the specified key
* (which may be {@code null} itself), or also {@code null} if
* the cache contains no mapping for this key
* @throws IllegalStateException if a cache entry has been found
* but failed to match the specified type
* @since 4.0
* @see #get(Object)
*/
@Nullable
<T> T get(Object key, @Nullable Class<T> type);
Return the value to which this cache maps the specified key, obtaining that value from valueLoader if necessary. This method provides a simple substitute for the conventional "if cached, return; otherwise create, cache and return" pattern. If possible, implementations should ensure that the loading operation is synchronized so that the specified valueLoader is only called once in case of concurrent access on the same key.
If the valueLoader throws an exception, it is wrapped in a ValueRetrievalException
Params: - key – the key whose associated value is to be returned
Throws: - ValueRetrievalException – if the
valueLoader throws an exception
Returns: the value to which this cache maps the specified key Since: 4.3
/**
* Return the value to which this cache maps the specified key, obtaining
* that value from {@code valueLoader} if necessary. This method provides
* a simple substitute for the conventional "if cached, return; otherwise
* create, cache and return" pattern.
* <p>If possible, implementations should ensure that the loading operation
* is synchronized so that the specified {@code valueLoader} is only called
* once in case of concurrent access on the same key.
* <p>If the {@code valueLoader} throws an exception, it is wrapped in
* a {@link ValueRetrievalException}
* @param key the key whose associated value is to be returned
* @return the value to which this cache maps the specified key
* @throws ValueRetrievalException if the {@code valueLoader} throws an exception
* @since 4.3
*/
@Nullable
<T> T get(Object key, Callable<T> valueLoader);
Associate the specified value with the specified key in this cache.
If the cache previously contained a mapping for this key, the old
value is replaced by the specified value.
Params: - key – the key with which the specified value is to be associated
- value – the value to be associated with the specified key
/**
* Associate the specified value with the specified key in this cache.
* <p>If the cache previously contained a mapping for this key, the old
* value is replaced by the specified value.
* @param key the key with which the specified value is to be associated
* @param value the value to be associated with the specified key
*/
void put(Object key, @Nullable Object value);
Atomically associate the specified value with the specified key in this cache
if it is not set already.
This is equivalent to:
Object existingValue = cache.get(key);
if (existingValue == null) {
cache.put(key, value);
return null;
} else {
return existingValue;
}
except that the action is performed atomically. While all out-of-the-box CacheManager implementations are able to perform the put atomically, the operation may also be implemented in two steps, e.g. with a check for presence and a subsequent put, in a non-atomic way. Check the documentation of the native cache implementation that you are using for more details. Params: - key – the key with which the specified value is to be associated
- value – the value to be associated with the specified key
Returns: the value to which this cache maps the specified key (which may be null itself), or also null if the cache did not contain any mapping for that key prior to this call. Returning null is therefore an indicator that the given value has been associated with the key. Since: 4.1
/**
* Atomically associate the specified value with the specified key in this cache
* if it is not set already.
* <p>This is equivalent to:
* <pre><code>
* Object existingValue = cache.get(key);
* if (existingValue == null) {
* cache.put(key, value);
* return null;
* } else {
* return existingValue;
* }
* </code></pre>
* except that the action is performed atomically. While all out-of-the-box
* {@link CacheManager} implementations are able to perform the put atomically,
* the operation may also be implemented in two steps, e.g. with a check for
* presence and a subsequent put, in a non-atomic way. Check the documentation
* of the native cache implementation that you are using for more details.
* @param key the key with which the specified value is to be associated
* @param value the value to be associated with the specified key
* @return the value to which this cache maps the specified key (which may be
* {@code null} itself), or also {@code null} if the cache did not contain any
* mapping for that key prior to this call. Returning {@code null} is therefore
* an indicator that the given {@code value} has been associated with the key.
* @since 4.1
*/
@Nullable
ValueWrapper putIfAbsent(Object key, @Nullable Object value);
Evict the mapping for this key from this cache if it is present.
Params: - key – the key whose mapping is to be removed from the cache
/**
* Evict the mapping for this key from this cache if it is present.
* @param key the key whose mapping is to be removed from the cache
*/
void evict(Object key);
Remove all mappings from the cache.
/**
* Remove all mappings from the cache.
*/
void clear();
A (wrapper) object representing a cache value.
/**
* A (wrapper) object representing a cache value.
*/
@FunctionalInterface
interface ValueWrapper {
Return the actual value in the cache.
/**
* Return the actual value in the cache.
*/
@Nullable
Object get();
}
Wrapper exception to be thrown from Cache.get(Object, Callable<Object>) in case of the value loader callback failing with an exception. Since: 4.3
/**
* Wrapper exception to be thrown from {@link #get(Object, Callable)}
* in case of the value loader callback failing with an exception.
* @since 4.3
*/
@SuppressWarnings("serial")
class ValueRetrievalException extends RuntimeException {
@Nullable
private final Object key;
public ValueRetrievalException(@Nullable Object key, Callable<?> loader, Throwable ex) {
super(String.format("Value for key '%s' could not be loaded using '%s'", key, loader), ex);
this.key = key;
}
@Nullable
public Object getKey() {
return this.key;
}
}
}