io.github.sinri.keel.cache.KeelAsyncCacheInterface Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of Keel Show documentation
A website framework with VERT.X for ex-PHP-ers, exactly Ark Framework Users.
The newest version!
package io.github.sinri.keel.cache;

import io.github.sinri.keel.cache.impl.KeelCacheBet;
import io.github.sinri.keel.facade.async.KeelAsyncKit;
import io.vertx.core.Future;

import javax.annotation.Nonnull;
import java.util.concurrent.ConcurrentMap;
import java.util.function.Function;

/**
 * @param 
 * @param 
 * @since 1.14
 */
public interface KeelAsyncCacheInterface {
    /**
     * @since 2.5
     */
    static  KeelAsyncCacheInterface createDefaultInstance() {
        return new KeelCacheBet<>();
    }

    /**
     * Save an item (as key and value pair) into cache, keep it available for a certain time.
     *
     * @param key           key
     * @param value         value
     * @param lifeInSeconds The lifetime of the cache item, in seconds.
     */
    Future save(@Nonnull K key, V value, long lifeInSeconds);

    /**
     * Read an available cached item with key in returned future,
     * or return a failed future of NotCached.
     *
     * @param key key
     * @return value of found available cached item, or `null`
     */
    Future read(@Nonnull K key);

    /**
     * Read an available cached item with key, or return `fallbackValue` when not found;
     * no failed future.
     *
     * @param key           key
     * @param fallbackValue the certain value returned when not found
     * @return value of found available cached item, or `fallbackValue`
     */
    Future read(@Nonnull K key, V fallbackValue);

    /**
     * Read an available cached item with key;
     * if not found, try to generate one with key using `fallbackValueGenerator` to save into cache, then return it in the future;
     * if failed to generate, failed future instead.
     *
     * @param key           key
     * @param generator     function to generate a value for given key, to be saved into cache and return when no cached item found
     * @param lifeInSeconds cache available in this period, in seconds
     * @return the valued read from cache
     * @since 2.5
     */
    Future read(@Nonnull K key, Function> generator, long lifeInSeconds);

    /**
     * Remove the cached item with key.
     *
     * @param key key
     */
    Future remove(@Nonnull K key);

    /**
     * Remove all the cached items.
     */
    Future removeAll();

    /**
     * clean up the entries that is not alive (expired, etc.)
     */
    Future cleanUp();

    /**
     * @return ConcurrentMap K → V alive value only
     * @since 1.14
     */
    Future> getSnapshotMap();

    class NotCached extends Exception {
        public NotCached(String key) {
            super("For key [" + key + "], no available cached record found.");
        }
    }

    /**
     * Start an endless for cleaning up.
     * Use it manually if needed.
     *
     * @since 3.0.4
     */
    default void startEndlessCleanUp(long sleepTime) {
        KeelAsyncKit.endless(() -> {
            return cleanUp().compose(cleaned -> {
                return KeelAsyncKit.sleep(sleepTime);
            });
        });
    }
}