/** * Asynchronously computes or retrieves the value corresponding to {@code key}. * * @param key the non-null key whose value should be loaded * @param executor the executor with which the entry is asynchronously loaded * @return the future value associated with {@code key} */ @NonNull CompletableFuture<V> asyncLoad(@NonNull K key, @NonNull Executor executor);
/** * Returns a view of the entries stored in this cache as a synchronous {@link Cache}. A mapping is * not present if the value is currently being loaded. Modifications made to the synchronous cache * directly affect the asynchronous cache. If a modification is made to a mapping that is * currently loading, the operation blocks until the computation completes. * * @return a thread-safe synchronous view of this cache */ @NonNull Cache<K, V> synchronous(); }
/** * Returns a snapshot of this counter's values. Note that this may be an inconsistent view, as it * may be interleaved with update operations. * * @return a snapshot of this counter's values */ @NonNull CacheStats snapshot();
/** * Returns an accumulator that does not record any cache events. * * @return an accumulator that does not record metrics */ static @NonNull StatsCounter disabledStatsCounter() { return DisabledStatsCounter.INSTANCE; }
/** * Returns a statistics instance where no cache events have been recorded. * * @return an empty statistics instance */ @NonNull public static CacheStats empty() { return EMPTY_STATS; }
/** * Returns a ticker that always returns {@code 0}. * * @return a ticker that always returns {@code 0} */ static @NonNull Ticker disabledTicker() { return DisabledTicker.INSTANCE; } }
/** * Discards any cached values for the {@code keys}. The behavior of this operation is undefined * for an entry that is being loaded and is otherwise not present. * * @param keys the keys whose associated values are to be removed * @throws NullPointerException if the specified collection is null or contains a null element */ void invalidateAll(@NonNull Iterable<?> keys);
/** * Returns a current snapshot of this cache's cumulative statistics. All statistics are * initialized to zero, and are monotonically increasing over the lifetime of the cache. * <p> * Due to the performance penalty of maintaining statistics, some implementations may not record * the usage history immediately or at all. * * @return the current snapshot of the statistics of this cache */ @NonNull CacheStats stats();
/** * Returns a view of the entries stored in this cache as a thread-safe map. Modifications made to * the map directly affect the cache. * <p> * Iterators from the returned map are at least <i>weakly consistent</i>: they are safe for * concurrent use, but if the cache is modified (including by eviction) after the iterator is * created, it is undefined which of the changes (if any) will be reflected in that iterator. * * @return a thread-safe view of this cache supporting all of the optional {@link Map} operations */ @NonNull ConcurrentMap<@NonNull K, @NonNull V> asMap();
/** * Returns access to perform operations based on the maximum size or maximum weight eviction * policy. If the cache was not constructed with a size-based bound or the implementation does * not support these operations, an empty {@link Optional} is returned. * * @return access to low-level operations for this cache if an eviction policy is used */ @NonNull Optional<Eviction<K, V>> eviction();
/** * Returns the approximate accumulated weight of entries in this cache. If this cache does not * use a weighted size bound, then the {@link OptionalLong} will be empty. * * @return the combined weight of the values in this cache */ @NonNull OptionalLong weightedSize();
/** * Returns a ticker that reads the current time using {@link System#nanoTime}. * * @return a ticker that reads the current time using {@link System#nanoTime} */ static @NonNull Ticker systemTicker() { return SystemTicker.INSTANCE; }
@NonNull Supplier<StatsCounter> getStatsCounterSupplier() { return (statsCounterSupplier == null) ? StatsCounter::disabledStatsCounter : statsCounterSupplier; }
/** * Returns a {@link Factory} that will produce instances of the specified class. * * @param className the fully qualified name of the desired class * @param <T> the type of the instances being produced * @return a {@link Factory} for the specified class */ @NonNull <T> Factory<T> factoryOf(String className); }
/** * Returns access to perform operations based on the time-to-live refresh policy. This policy * determines that an entry should be automatically reloaded once a fixed duration has elapsed * after the entry's creation, or the most recent replacement of its value. * <p> * If the cache was not constructed with write-based refresh or the implementation does not * support these operations, an empty {@link Optional} is returned. * * @return access to low-level operations for this cache if a time-to-live refresh policy is used */ @NonNull Optional<Expiration<K, V>> refreshAfterWrite();
/** * Returns {@code true} if the given objects are considered equivalent. A strongly held value is * compared by equality and a weakly or softly held value is compared by identity. */ public abstract boolean containsValue(@NonNull Object value);
/** * Copies all of the mappings from the specified map to the cache. The effect of this call is * equivalent to that of calling {@code put(k, v)} on this map once for each mapping from key * {@code k} to value {@code v} in the specified map. The behavior of this operation is undefined * if the specified map is modified while the operation is in progress. * * @param map the mappings to be stored in this cache * @throws NullPointerException if the specified map is null or the specified map contains null * keys or values */ void putAll(@NonNull Map<? extends @NonNull K,? extends @NonNull V> map);
/** * Returns the weight of the entry. If this cache does not use a weighted size bound or does not * support querying for the entry's weight, then the {@link OptionalInt} will be empty. * * @param key the key for the entry being queried * @return the weight if the entry is present in the cache */ @NonNull default OptionalInt weightOf(@NonNull K key) { // This method will be abstract in version 3.0.0 return OptionalInt.empty(); }