All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.springframework.cache.Cache Maven / Gradle / Ivy

The newest version!
/*
 * Copyright 2002-2015 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;

/**
 * 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 {@code null}).
 *
 * @author Costin Leau
 * @author Juergen Hoeller
 * @since 3.1
 */
public interface Cache {

	/**
	 * Return the cache name.
	 */
	String getName();

	/**
	 * Return the the underlying native cache provider.
	 */
	Object getNativeCache();

	/**
	 * Return the value to which this cache maps the specified key.
	 * 

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) */ 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 {@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) */ T get(Object key, Class type); /** * 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. * @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, 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 * {@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 */ ValueWrapper putIfAbsent(Object key, Object value); /** * 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. */ void clear(); /** * A (wrapper) object representing a cache value. */ interface ValueWrapper { /** * Return the actual value in the cache. */ Object get(); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy