org.redisson.api.RMapCache Maven / Gradle / Ivy
Show all versions of redisson-all Show documentation
/**
* Copyright (c) 2013-2024 Nikita Koksharov
*
* 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.redisson.api;
import org.redisson.api.map.MapLoader;
import org.redisson.api.map.MapWriter;
import org.redisson.api.map.event.MapEntryListener;
import java.time.Duration;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;
import java.util.function.Function;
/**
* Map-based cache with ability to set TTL for each entry via
* {@link #put(Object, Object, long, TimeUnit)} or {@link #putIfAbsent(Object, Object, long, TimeUnit)}
* And therefore has an complex lua-scripts inside.
*
* Current redis implementation doesnt have map entry eviction functionality.
* Thus entries are checked for TTL expiration during any key/value/entry read operation.
* If key/value/entry expired then it doesn't returns.
* Expired tasks cleaned by {@link org.redisson.eviction.EvictionScheduler}. This scheduler
* deletes expired entries in time interval between 5 seconds to 2 hours.
*
* If eviction is not required then it's better to use {@link org.redisson.RedissonMap}.
*
* @author Nikita Koksharov
*
* @param key
* @param value
*/
public interface RMapCache extends RMap, RMapCacheAsync {
/**
* Sets max size of the map and overrides current value.
* Superfluous elements are evicted using LRU algorithm.
*
* @param maxSize - max size
* If 0 the cache is unbounded (default).
*/
void setMaxSize(int maxSize);
/**
* Sets max size of the map and overrides current value.
* Superfluous elements are evicted using defined algorithm.
*
* @param maxSize - max size
* @param mode - eviction mode
*/
void setMaxSize(int maxSize, EvictionMode mode);
/**
* Tries to set max size of the map.
* Superfluous elements are evicted using LRU algorithm.
*
* @param maxSize - max size
* @return true if max size has been successfully set, otherwise false.
* If 0 the cache is unbounded (default).
*/
boolean trySetMaxSize(int maxSize);
/**
* Tries to set max size of the map.
* Superfluous elements are evicted using defined algorithm.
*
* @param maxSize - max size
* @param mode - eviction mode
* @return true if max size has been successfully set, otherwise false.
*/
boolean trySetMaxSize(int maxSize, EvictionMode mode);
/**
* If the specified key is not already associated
* with a value, attempts to compute its value using the given mapping function and enters it into this map .
*
* Stores value mapped by key with specified time to live.
* Entry expires after specified time to live.
*
* @param key - map key
* @param ttl - time to live for key\value entry.
* If 0 then stores infinitely.
* @param mappingFunction the mapping function to compute a value
* @return current associated value
*/
V computeIfAbsent(K key, Duration ttl, Function mappingFunction);
/**
* If the specified key is not already associated
* with a value, associate it with the given value.
*
* Stores value mapped by key with specified time to live.
* Entry expires after specified time to live.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then stores infinitely.
* @param ttlUnit - time unit
* @return current associated value
*/
V putIfAbsent(K key, V value, long ttl, TimeUnit ttlUnit);
/**
* If the specified key is not already associated
* with a value, associate it with the given value.
*
* Stores value mapped by key with specified time to live and max idle time.
* Entry expires when specified time to live or max idle time has expired.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param ttlUnit - time unit
* @param maxIdleTime - max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
* @param maxIdleUnit - time unit
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
*
* @return current associated value
*/
V putIfAbsent(K key, V value, long ttl, TimeUnit ttlUnit, long maxIdleTime, TimeUnit maxIdleUnit);
/**
* Stores value mapped by key with specified time to live.
* Entry expires after specified time to live.
*
* If the map previously contained a mapping for
* the key, the old value is replaced by the specified value.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then stores infinitely.
* @param unit - time unit
* @return previous associated value
*/
V put(K key, V value, long ttl, TimeUnit unit);
/**
* Stores value mapped by key with specified time to live and max idle time.
* Entry expires when specified time to live or max idle time has expired.
*
* If the map previously contained a mapping for
* the key, the old value is replaced by the specified value.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param ttlUnit - time unit
* @param maxIdleTime - max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
* @param maxIdleUnit - time unit
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
*
* @return previous associated value
*/
V put(K key, V value, long ttl, TimeUnit ttlUnit, long maxIdleTime, TimeUnit maxIdleUnit);
/**
* Stores value mapped by key with specified time to live.
* Entry expires after specified time to live.
*
* If the map previously contained a mapping for
* the key, the old value is replaced by the specified value.
*
* Works faster than usual {@link #put(Object, Object, long, TimeUnit)}
* as it not returns previous value.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then stores infinitely.
* @param ttlUnit - time unit
*
* @return true if key is a new key in the hash and value was set.
* false if key already exists in the hash and the value was updated.
*/
boolean fastPut(K key, V value, long ttl, TimeUnit ttlUnit);
/**
* Stores value mapped by key with specified time to live and max idle time.
* Entry expires when specified time to live or max idle time has expired.
*
* If the map previously contained a mapping for
* the key, the old value is replaced by the specified value.
*
* Works faster than usual {@link #put(Object, Object, long, TimeUnit, long, TimeUnit)}
* as it not returns previous value.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param ttlUnit - time unit
* @param maxIdleTime - max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
* @param maxIdleUnit - time unit
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
* @return true if key is a new key in the hash and value was set.
* false if key already exists in the hash and the value was updated.
*/
boolean fastPut(K key, V value, long ttl, TimeUnit ttlUnit, long maxIdleTime, TimeUnit maxIdleUnit);
/**
* If the specified key is not already associated
* with a value, associate it with the given value.
*
* Stores value mapped by key with specified time to live.
* Entry expires after specified time to live.
*
* Works faster than usual {@link #putIfAbsent(Object, Object, long, TimeUnit)}
* as it not returns previous value.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then stores infinitely.
* @param ttlUnit - time unit
*
* @return true if key is a new key in the hash and value was set.
* false if key already exists in the hash
*/
boolean fastPutIfAbsent(K key, V value, long ttl, TimeUnit ttlUnit);
/**
* If the specified key is not already associated
* with a value, associate it with the given value.
*
* Stores value mapped by key with specified time to live and max idle time.
* Entry expires when specified time to live or max idle time has expired.
*
* Works faster than usual {@link #putIfAbsent(Object, Object, long, TimeUnit, long, TimeUnit)}
* as it not returns previous value.
*
* @param key - map key
* @param value - map value
* @param ttl - time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param ttlUnit - time unit
* @param maxIdleTime - max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
* @param maxIdleUnit - time unit
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
*
* @return true if key is a new key in the hash and value was set.
* false if key already exists in the hash.
*/
boolean fastPutIfAbsent(K key, V value, long ttl, TimeUnit ttlUnit, long maxIdleTime, TimeUnit maxIdleUnit);
/**
* Associates the specified value with the specified key
* in batch.
*
* If {@link MapWriter} is defined then new map entries will be stored in write-through mode.
*
* @param map - mappings to be stored in this map
* @param ttl - time to live for all key\value entries.
* If 0 then stores infinitely.
* @param ttlUnit - time unit
*/
void putAll(java.util.Map map, long ttl, TimeUnit ttlUnit);
/**
* Use {@link #expireEntry(Object, Duration, Duration)} instead.
*
* @param key - map key
* @param ttl - time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param ttlUnit - time unit
* @param maxIdleTime - max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
* @param maxIdleUnit - time unit
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
*
* @return returns false if entry already expired or doesn't exist,
* otherwise returns true.
*/
@Deprecated
boolean updateEntryExpiration(K key, long ttl, TimeUnit ttlUnit, long maxIdleTime, TimeUnit maxIdleUnit);
/**
* Updates time to live and max idle time of specified entry by key.
* Entry expires when specified time to live or max idle time was reached.
*
* Returns false if entry already expired or doesn't exist,
* otherwise returns true.
*
* @param key map key
* @param ttl time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param maxIdleTime max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
*
* @return returns false if entry already expired or doesn't exist,
* otherwise returns true.
*/
boolean expireEntry(K key, Duration ttl, Duration maxIdleTime);
/**
* Updates time to live and max idle time of specified entries by keys.
* Entries expires when specified time to live or max idle time was reached.
*
* Returns amount of updated entries.
*
* @param keys map keys
* @param ttl time to live for key\value entries.
* If 0 then time to live doesn't affect entry expiration.
* @param maxIdleTime max idle time for key\value entries.
* If 0 then max idle time doesn't affect entry expiration.
*
* if maxIdleTime and ttl params are equal to 0
* then entries are stored infinitely.
*
* @return amount of updated entries.
*/
int expireEntries(Set keys, Duration ttl, Duration maxIdleTime);
/**
* Sets time to live and max idle time of specified entry by key.
* If these parameters weren't set before.
* Entry expires when specified time to live or max idle time was reached.
*
* Returns false if entry already has expiration time or doesn't exist,
* otherwise returns true.
*
* @param key map key
* @param ttl time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param maxIdleTime max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
*
* @return returns false if entry already has expiration time or doesn't exist,
* otherwise returns true.
*/
boolean expireEntryIfNotSet(K key, Duration ttl, Duration maxIdleTime);
/**
* Sets time to live and max idle time of specified entries by keys.
* If these parameters weren't set before.
* Entries expire when specified time to live or max idle time was reached.
*
* Returns amount of updated entries.
*
* @param keys map keys
* @param ttl time to live for key\value entry.
* If 0 then time to live doesn't affect entry expiration.
* @param maxIdleTime max idle time for key\value entry.
* If 0 then max idle time doesn't affect entry expiration.
*
* if maxIdleTime and ttl params are equal to 0
* then entry stores infinitely.
*
* @return amount of updated entries.
*/
int expireEntriesIfNotSet(Set keys, Duration ttl, Duration maxIdleTime);
/**
* Returns the value mapped by defined key or {@code null} if value is absent.
*
* If map doesn't contain value for specified key and {@link MapLoader} is defined
* then value will be loaded in read-through mode.
*
* NOTE: Idle time of entry is not taken into account.
* Entry last access time isn't modified if map limited by size.
*
* @param key the key
* @return the value mapped by defined key or {@code null} if value is absent
*/
V getWithTTLOnly(K key);
/**
* Returns map slice contained the mappings with defined keys.
*
* If map doesn't contain value/values for specified key/keys and {@link MapLoader} is defined
* then value/values will be loaded in read-through mode.
*
* NOTE: Idle time of entry is not taken into account.
* Entry last access time isn't modified if map limited by size.
*
* @param keys map keys
* @return Map slice
*/
Map getAllWithTTLOnly(Set keys);
/**
* Returns the number of entries in cache.
* This number can reflects expired entries too
* due to non realtime cleanup process.
*
*/
@Override
int size();
/**
* Adds map entry listener
*
* @see org.redisson.api.map.event.EntryCreatedListener
* @see org.redisson.api.map.event.EntryUpdatedListener
* @see org.redisson.api.map.event.EntryRemovedListener
* @see org.redisson.api.map.event.EntryExpiredListener
*
* @param listener - entry listener
* @return listener id
*/
int addListener(MapEntryListener listener);
/**
* Removes map entry listener
*
* @param listenerId - listener id
*/
void removeListener(int listenerId);
/**
* Remaining time to live of map entry associated with a key.
*
* @param key - map key
* @return time in milliseconds
* -2 if the key does not exist.
* -1 if the key exists but has no associated expire.
*/
long remainTimeToLive(K key);
}