001/**
002 * Copyright (C) 2006-2023 Talend Inc. - www.talend.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.talend.sdk.component.api.service.cache;
017
018import java.util.function.Predicate;
019import java.util.function.Supplier;
020
021/**
022 * Framework service injectable in components or services methods
023 * to handle local caching.
024 * Useful for actions when deployed in a long running instance
025 * when actions are costly.
026 */
027public interface LocalCache {
028
029    /**
030     * Use to enrich object with meta-data
031     * (help to choice if attached object has to be removed from cache)
032     */
033    interface Element {
034
035        /**
036         * Get the cached object.
037         * 
038         * @param expectedType : expected type of object.
039         * @param <T> : Type.
040         * @return cached object.
041         */
042        <T> T getValue(Class<T> expectedType);
043
044        default Object getValue() {
045            return this.getValue(Object.class);
046        }
047
048        /**
049         * time when this will be no longer valid.
050         * 
051         * @return Last validity timestamp.
052         */
053        long getLastValidityTimestamp();
054    }
055
056    /**
057     * Read or compute and save a value for a determined duration and predicate.
058     * 
059     * @param expectedClass : cached instance class.
060     * @param key : the cache key, must be unique accross the server.
061     * @param toRemove : is the object to be removed.
062     * @param timeoutMs : duration of cache value.
063     * @param value : the value provider if the cache get does a miss.
064     * @param <T> class of cached instance.
065     * @return the cached or newly computed value.
066     */
067    <T> T computeIfAbsent(Class<T> expectedClass, String key, Predicate<Element> toRemove, long timeoutMs,
068            Supplier<T> value);
069
070    /**
071     * Read or compute and save a value until remove predicate go to remove.
072     * 
073     * @param expectedClass : cached instance class.
074     * @param key : the cache key, must be unique accross the server.
075     * @param toRemove : is the object to be removed.
076     * @param value : the value provider if the cache get does a miss.
077     * @param <T> class of cached instance.
078     * @return the cached or newly computed value.
079     */
080    <T> T computeIfAbsent(Class<T> expectedClass, String key, Predicate<Element> toRemove, Supplier<T> value);
081
082    /**
083     * Read or compute and save a value for a determined duration.
084     * 
085     * @param expectedClass : cached instance class.
086     * @param key : the cache key, must be unique accross the server.
087     * @param timeoutMs : duration of cache value.
088     * @param value : value provider.
089     * @param <T> class of cached instance.
090     * @return the cached or newly computed value.
091     */
092    <T> T computeIfAbsent(Class<T> expectedClass, String key, long timeoutMs, Supplier<T> value);
093
094    /**
095     * Compute and save a value, if key not present, for undetermined duration.
096     * 
097     * @param expectedClass : cached instance class.
098     * @param key : the cache key, must be unique accross the server.
099     * @param value : value provider.
100     * @param <T> class of cached instance.
101     * @return the cached or newly computed value.
102     */
103    <T> T computeIfAbsent(Class<T> expectedClass, String key, Supplier<T> value);
104
105    /**
106     * Remove a cached entry.
107     * 
108     * @param key key to evict.
109     */
110    void evict(String key);
111
112    /**
113     * Remove a cached entry if a particular value is in the cache.
114     *
115     * @param key key to evict.
116     * @param expected expected value activating the eviction.
117     */
118    void evictIfValue(String key, Object expected);
119
120}