org.opendaylight.infrautils.caches.Cache Maven / Gradle / Ivy
/*
* Copyright (c) 2017 Red Hat, Inc. and others. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v1.0 which accompanies this distribution,
* and is available at http://www.eclipse.org/legal/epl-v10.html
*/
package org.opendaylight.infrautils.caches;
import com.google.common.collect.ImmutableMap;
import java.util.Arrays;
import java.util.Map;
import org.eclipse.jdt.annotation.NonNull;
/**
* Cache of keys to values.
*
* Users typically obtain implementations from the {@link CacheProvider}.
*
*
Caches are not {@link Map}s! Differences include that a Map persists
* all elements that are added to it until they are explicitly removed. A Cache on the
* other hand is generally configured to evict entries automatically, in order to constrain
* its memory footprint, based on some policy (quoted from
* Caffeine's or
* Guava's
* introduction). Another notable difference, enforced by this caching API, is
* that caches should not be thought of as data structures that you put
* something in somewhere in your code to get it out of somewhere else. Instead, a
* Cache is "just a façade" to a {@link CacheFunction}'s get. This design enforces
* proper encapsulation, and helps you not to screw up the content of your cache (like you
* easily can, and usually do, when you use a Map as a cache).
*
*
The implementation of this API is, typically, backed by established cache frameworks,
* such as Ehcache, Infinispan, Guava's, Caffeine, ..., imcache, cache2k, ... etc.
*
*
Implementations of this interface are expected to be safe to use from multiple threads
* concurrently.
*
* @param key type of cache (must be immutable and have correct hashCode & equals)
* @param value type of cache (should, for monitoring and predictable memory
* effect of eviction, typically, be of "similar" size for all keys;
* else consider simply using separate Cache, if feasible)
*
* @author Michael Vorburger.ch
*/
public interface Cache extends BaseCache {
/**
* Get cache entry.
* If the cache does not currently contain an entry under this key,
* then one is created, using the {@link CacheFunction} given when the cache was
* created.
*
* @param key key of cache entry
* @return value, never null (but may be an Optional)
* @throws BadCacheFunctionRuntimeException if the cache's function returned null value
* @throws NullPointerException if the cache's users passed a null key
*/
@NonNull V get(@NonNull K key);
/**
* Get several cache entries, in one go.
*
* @param keys list of keys of cache entries
* @return Map of cache keys and values (neither ever null, but may be an Optional)
* @throws BadCacheFunctionRuntimeException if the cache's function returned null value
* @throws NullPointerException if the cache's users passed a null key
*/
ImmutableMap get(Iterable keys);
/**
* Convenience short-cut to {@link #get(Iterable)} with vararg syntax.
*/
@SuppressWarnings("unchecked")
default ImmutableMap get(@NonNull K... keys) {
return get(Arrays.asList(keys));
}
}