org.redisson.api.RMapCacheReactive Maven / Gradle / Ivy
Show all versions of redisson Show documentation
/**
* Copyright (c) 2013-2022 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 reactor.core.publisher.Mono;
import java.time.Duration;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;
/**
* 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)} method.
* 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 and clean task runs asynchronous.
* Clean task deletes removes 100 expired entries at once.
* In addition there is {@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.reactive.RedissonMapReactive}.
*
* @author Nikita Koksharov
*
* @param key
* @param value
*/
public interface RMapCacheReactive extends RMapReactive, RDestroyable {
/**
* Sets max size of the map.
* Superfluous elements are evicted using LRU algorithm.
*
* @param maxSize - max size
* @return void
*/
Mono 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
*/
Mono 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.
*/
Mono 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.
*/
Mono trySetMaxSize(int maxSize, EvictionMode mode);
/**
* 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.
* 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
*/
Mono putIfAbsent(K key, V value, long ttl, TimeUnit unit);
/**
* 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.
*
* 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
*/
Mono 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
*/
Mono 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
*/
Mono put(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
*/
Mono putAll(java.util.Map map, long ttl, TimeUnit ttlUnit);
/**
* 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 unit - 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.
*/
Mono fastPut(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.
*
* 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.
*/
Mono 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 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
*/
Mono fastPutIfAbsent(K key, V value, long ttl, TimeUnit ttlUnit, long maxIdleTime, TimeUnit maxIdleUnit);
/**
* 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
Mono 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.
*/
Mono 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.
*/
Mono 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.
*/
Mono 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.
*/
Mono 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.
*
* 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
*/
Mono 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
*/
Mono> getAllWithTTLOnly(Set keys);
/**
* Returns the number of entries in cache.
* This number can reflects expired entries too
* due to non realtime cleanup process.
*
*/
@Override
Mono size();
/**
* 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.
*/
Mono remainTimeToLive(K key);
/**
* 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
*/
Mono addListener(MapEntryListener listener);
}