org.redisson.api.RMap 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 java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ConcurrentMap;
import org.redisson.api.map.MapLoader;
import org.redisson.api.map.MapWriter;
import org.redisson.api.mapreduce.RMapReduce;
/**
* Redis based implementation of {@link java.util.concurrent.ConcurrentMap}
* and {@link java.util.Map}
*
* This map uses serialized state of key instead of hashCode or equals methods.
* This map doesn't allow to store null
as key or value.
*
* @author Nikita Koksharov
*
* @param map key
* @param value
*/
public interface RMap extends ConcurrentMap, RExpirable, RMapAsync, RDestroyable {
/**
* Loads all map entries to this Redis map using {@link org.redisson.api.map.MapLoader}.
*
* @param replaceExistingValues - true
if existed values should be replaced, false
otherwise.
* @param parallelism - parallelism level, used to increase speed of process execution
*/
void loadAll(boolean replaceExistingValues, int parallelism);
/**
* Loads map entries using {@link org.redisson.api.map.MapLoader} whose keys are listed in defined keys
parameter.
*
* @param keys - map keys
* @param replaceExistingValues - true
if existed values should be replaced, false
otherwise.
* @param parallelism - parallelism level, used to increase speed of process execution
*/
void loadAll(Set extends K> keys, boolean replaceExistingValues, int parallelism);
/**
* 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.
*
* @param key the key
* @return the value mapped by defined key
or {@code null} if value is absent
*/
@Override
V get(Object key);
/**
* Stores the specified value
mapped by specified key
.
* Returns previous value if map entry with specified key
already existed.
*
* If {@link MapWriter} is defined then map entry is stored in write-through mode.
*
* @param key - map key
* @param value - map value
* @return previous associated value
*/
@Override
V put(K key, V value);
/**
* Stores the specified value
mapped by key
* only if there is no value with specifiedkey
stored before.
*
* If {@link MapWriter} is defined then new map entry is stored in write-through mode.
*
* @param key - map key
* @param value - map value
* @return null
if key is a new one in the hash and value was set.
* Previous value if key already exists in the hash and change hasn't been made.
*/
@Override
V putIfAbsent(K key, V value);
/**
* Stores the specified value
mapped by key
* only if mapping already exists.
*
* If {@link MapWriter} is defined then new map entry is stored in write-through mode.
*
* @param key - map key
* @param value - map value
* @return null
if key doesn't exist in the hash and value hasn't been set.
* Previous value if key already exists in the hash and new value has been stored.
*/
V putIfExists(K key, V value);
/**
* Returns random keys from this map limited by count
*
* @param count - keys amount to return
* @return random keys
*/
Set randomKeys(int count);
/**
* Returns random map entries from this map limited by count
*
* @param count - entries amount to return
* @return random entries
*/
Map randomEntries(int count);
/**
* Returns RMapReduce
object associated with this map
*
* @param output key
* @param output value
* @return MapReduce instance
*/
RMapReduce mapReduce();
/**
* Returns RCountDownLatch
instance associated with key
*
* @param key - map key
* @return countdownlatch
*/
RCountDownLatch getCountDownLatch(K key);
/**
* Returns RPermitExpirableSemaphore
instance associated with key
*
* @param key - map key
* @return permitExpirableSemaphore
*/
RPermitExpirableSemaphore getPermitExpirableSemaphore(K key);
/**
* Returns RSemaphore
instance associated with key
*
* @param key - map key
* @return semaphore
*/
RSemaphore getSemaphore(K key);
/**
* Returns RLock
instance associated with key
*
* @param key - map key
* @return fairlock
*/
RLock getFairLock(K key);
/**
* Returns RReadWriteLock
instance associated with key
*
* @param key - map key
* @return readWriteLock
*/
RReadWriteLock getReadWriteLock(K key);
/**
* Returns RLock
instance associated with key
*
* @param key - map key
* @return lock
*/
RLock getLock(K key);
/**
* Returns size of value mapped by specified key
in bytes
*
* @param key - map key
* @return size of value
*/
int valueSize(K key);
/**
* Adds the given delta
to the current value
* by mapped key
.
*
* Works only with codecs below
*
* {@link org.redisson.codec.JsonJacksonCodec},
*
* {@link org.redisson.client.codec.StringCodec},
*
* {@link org.redisson.client.codec.IntegerCodec},
*
* {@link org.redisson.client.codec.DoubleCodec}
*
* {@link org.redisson.client.codec.LongCodec}
*
* @param key - map key
* @param delta the value to add
* @return the updated value
*/
V addAndGet(K key, Number delta);
/**
* Returns true
if this map contains map entry
* mapped by specified key
, otherwise false
*
* @param key - map key
* @return true
if this map contains map entry
* mapped by specified key
, otherwise false
*/
@Override
boolean containsKey(Object key);
/**
* Returns true
if this map contains any map entry
* with specified value
, otherwise false
*
* @param value - map value
* @return true
if this map contains any map entry
* with specified value
, otherwise false
*/
@Override
boolean containsValue(Object value);
/**
* Removes map entry by specified key
and returns value.
*
* If {@link MapWriter} is defined then key
is deleted in write-through mode.
*
* @param key - map key
* @return deleted value, null
if map entry doesn't exist
*/
@Override
V remove(Object key);
/**
* Replaces previous value with a new value
mapped by specified key
.
* Returns null
if there is no map entry stored before and doesn't store new map entry.
*
* If {@link MapWriter} is defined then new value
is written in write-through mode.
*
* @param key - map key
* @param value - map value
* @return previous associated value
* or null
if there is no map entry stored before and doesn't store new map entry
*/
@Override
V replace(K key, V value);
/**
* Replaces previous oldValue
with a newValue
mapped by specified key
.
* Returns false
if previous value doesn't exist or equal to oldValue
.
*
* If {@link MapWriter} is defined then newValue
is written in write-through mode.
*
* @param key - map key
* @param oldValue - map old value
* @param newValue - map new value
* @return true
if value has been replaced otherwise false
.
*/
@Override
boolean replace(K key, V oldValue, V newValue);
/**
* Removes map entry only if it exists with specified key
and value
.
*
* If {@link MapWriter} is defined then key
is deleted in write-through mode.
*
* @param key - map key
* @param value - map value
* @return true
if map entry has been removed otherwise false
.
*/
@Override
boolean remove(Object key, Object value);
/**
* Stores map entries specified in map
object in batch mode.
*
* If {@link MapWriter} is defined then map entries will be stored in write-through mode.
*
* @param map mappings to be stored in this map
*/
@Override
void putAll(java.util.Map extends K, ? extends V> map);
/**
* Stores map entries specified in map
object in batch mode.
* Batch inserted by chunks limited by batchSize
value
* to avoid OOM and/or Redis response timeout error for map with big size.
*
* If {@link MapWriter} is defined then map entries are stored in write-through mode.
*
* @param map mappings to be stored in this map
* @param batchSize - size of map entries batch
*/
void putAll(Map extends K, ? extends V> map, int batchSize);
/**
* 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.
*
* The returned map is NOT backed by the original map.
*
* @param keys map keys
* @return Map slice
*/
Map getAll(Set keys);
/**
* Removes map entries mapped by specified keys
.
*
* Works faster than {@link #remove(Object)}
but not returning
* the value.
*
* If {@link MapWriter} is defined then keys
are deleted in write-through mode.
*
* @param keys - map keys
* @return the number of keys that were removed from the hash, not including specified but non existing keys
*/
long fastRemove(K... keys);
/**
* Stores the specified value
mapped by specified key
.
*
* Works faster than {@link #put(Object, Object)}
but not returning
* previous value.
*
* Returns true
if key is a new key in the hash and value was set or
* false
if key already exists in the hash and the value was updated.
*
* If {@link MapWriter} is defined then map entry is stored in write-through mode.
*
* @param key - map key
* @param value - map value
* @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);
/**
* Replaces previous value with a new value
mapped by specified key
.
*
* Works faster than {@link #replace(Object, Object)}
but not returning
* the previous value.
*
* Returns true
if key exists and value was updated or
* false
if key doesn't exists and value wasn't updated.
*
* If {@link MapWriter} is defined then new map entry is stored in write-through mode.
*
* @param key - map key
* @param value - map value
* @return true
if key exists and value was updated.
* false
if key doesn't exists and value wasn't updated.
*/
boolean fastReplace(K key, V value);
/**
* Stores the specified value
mapped by specified key
* only if there is no value with specifiedkey
stored before.
*
* Returns true
if key is a new one in the hash and value was set or
* false
if key already exists in the hash and change hasn't been made.
*
* Works faster than {@link #putIfAbsent(Object, Object)}
but not returning
* the previous value associated with key
*
* If {@link MapWriter} is defined then new map entry is stored in write-through mode.
*
* @param key - map key
* @param value - map value
* @return true
if key is a new one in the hash and value was set.
* false
if key already exists in the hash and change hasn't been made.
*/
boolean fastPutIfAbsent(K key, V value);
/**
* Stores the specified value
mapped by key
* only if mapping already exists.
*
* Returns true
if key is a new one in the hash and value was set or
* false
if key already exists in the hash and change hasn't been made.
*
* Works faster than {@link #putIfExists(Object, Object)}
but doesn't return
* previous value associated with key
*
* If {@link MapWriter} is defined then new map entry is stored in write-through mode.
*
* @param key - map key
* @param value - map value
* @return true
if key already exists in the hash and new value has been stored.
* false
if key doesn't exist in the hash and value hasn't been set.
*/
boolean fastPutIfExists(K key, V value);
/**
* Read all keys at once
*
* @return keys
*/
Set readAllKeySet();
/**
* Read all values at once
*
* @return values
*/
Collection readAllValues();
/**
* Read all map entries at once
*
* @return entries
*/
Set> readAllEntrySet();
/**
* Read all map as local instance at once
*
* @return map
*/
Map readAllMap();
/**
* Returns key set of this map.
* Keys are loaded in batch. Batch size is 10
.
*
* @see #readAllKeySet()
*
* @return key set
*/
@Override
Set keySet();
/**
* Returns key set of this map.
* Keys are loaded in batch. Batch size is defined by count
param.
*
* @see #readAllKeySet()
*
* @param count - size of keys batch
* @return key set
*/
Set keySet(int count);
/**
* Returns key set of this map.
* If pattern
is not null then only keys match this pattern are loaded.
* Keys are loaded in batch. Batch size is defined by count
param.
*
* Use org.redisson.client.codec.StringCodec
for Map keys.
*
*
* Supported glob-style patterns:
*
* h?llo subscribes to hello, hallo and hxllo
*
* h*llo subscribes to hllo and heeeello
*
* h[ae]llo subscribes to hello and hallo, but not hillo
*
* @see #readAllKeySet()
*
* @param pattern - key pattern
* @param count - size of keys batch
* @return key set
*/
Set keySet(String pattern, int count);
/**
* Returns key set of this map.
* If pattern
is not null then only keys match this pattern are loaded.
*
* Use org.redisson.client.codec.StringCodec
for Map keys.
*
*
* Supported glob-style patterns:
*
* h?llo subscribes to hello, hallo and hxllo
*
* h*llo subscribes to hllo and heeeello
*
* h[ae]llo subscribes to hello and hallo, but not hillo
*
* @see #readAllKeySet()
*
* @param pattern - key pattern
* @return key set
*/
Set keySet(String pattern);
/**
* Returns values collection of this map.
* Values are loaded in batch. Batch size is 10
.
*
* @see #readAllValues()
*
* @return values collection
*/
@Override
Collection values();
/**
* Returns values collection of this map.
* Values are loaded in batch. Batch size is 10
.
* If keyPattern
is not null then only values mapped by matched keys of this pattern are loaded.
*
* Use org.redisson.client.codec.StringCodec
for Map keys.
*
* Usage example:
*
* Codec valueCodec = ...
* RMap map = redissonClient.getMap("simpleMap", new CompositeCodec(StringCodec.INSTANCE, valueCodec, valueCodec));
*
* // or
*
* RMap map = redissonClient.getMap("simpleMap", StringCodec.INSTANCE);
*
*
* Supported glob-style patterns:
* h?llo subscribes to hello, hallo and hxllo
* h*llo subscribes to hllo and heeeello
* h[ae]llo subscribes to hello and hallo, but not hillo
*
* @see #readAllValues()
*
* @param keyPattern - key pattern
* @return values collection
*/
Collection values(String keyPattern);
/**
* Returns values collection of this map.
* Values are loaded in batch. Batch size is defined by count
param.
* If keyPattern
is not null then only values mapped by matched keys of this pattern are loaded.
*
* Use org.redisson.client.codec.StringCodec
for Map keys.
*
* Usage example:
*
* Codec valueCodec = ...
* RMap map = redissonClient.getMap("simpleMap", new CompositeCodec(StringCodec.INSTANCE, valueCodec, valueCodec));
*
* // or
*
* RMap map = redissonClient.getMap("simpleMap", StringCodec.INSTANCE);
*
*
* Supported glob-style patterns:
* h?llo subscribes to hello, hallo and hxllo
* h*llo subscribes to hllo and heeeello
* h[ae]llo subscribes to hello and hallo, but not hillo
*
* @see #readAllValues()
*
* @param keyPattern - key pattern
* @param count - size of values batch
* @return values collection
*/
Collection values(String keyPattern, int count);
/**
* Returns values collection of this map.
* Values are loaded in batch. Batch size is defined by count
param.
*
* @see #readAllValues()
*
* @param count - size of values batch
* @return values collection
*/
Collection values(int count);
/**
* Returns map entries collection.
* Map entries are loaded in batch. Batch size is 10
.
*
* @see #readAllEntrySet()
*
* @return map entries collection
*/
@Override
Set> entrySet();
/**
* Returns map entries collection.
* Map entries are loaded in batch. Batch size is 10
.
* If keyPattern
is not null then only entries mapped by matched keys of this pattern are loaded.
*
* Use org.redisson.client.codec.StringCodec
for Map keys.
*
* Usage example:
*
* Codec valueCodec = ...
* RMap map = redissonClient.getMap("simpleMap", new CompositeCodec(StringCodec.INSTANCE, valueCodec, valueCodec));
*
* // or
*
* RMap map = redissonClient.getMap("simpleMap", StringCodec.INSTANCE);
*
*
* Supported glob-style patterns:
* h?llo subscribes to hello, hallo and hxllo
* h*llo subscribes to hllo and heeeello
* h[ae]llo subscribes to hello and hallo, but not hillo
*
* @see #readAllEntrySet()
*
* @param keyPattern key pattern
* @return map entries collection
*/
Set> entrySet(String keyPattern);
/**
* Returns map entries collection.
* Map entries are loaded in batch. Batch size is defined by count
param.
* If keyPattern
is not null then only entries mapped by matched keys of this pattern are loaded.
*
* Use org.redisson.client.codec.StringCodec
for Map keys.
*
* Usage example:
*
* Codec valueCodec = ...
* RMap map = redissonClient.getMap("simpleMap", new CompositeCodec(StringCodec.INSTANCE, valueCodec, valueCodec));
*
* // or
*
* RMap map = redissonClient.getMap("simpleMap", StringCodec.INSTANCE);
*
*
* Supported glob-style patterns:
* h?llo subscribes to hello, hallo and hxllo
* h*llo subscribes to hllo and heeeello
* h[ae]llo subscribes to hello and hallo, but not hillo
*
* @see #readAllEntrySet()
*
* @param keyPattern key pattern
* @param count size of entries batch
* @return map entries collection
*/
Set> entrySet(String keyPattern, int count);
/**
* Returns map entries collection.
* Map entries are loaded in batch. Batch size is defined by count
param.
*
* @see #readAllEntrySet()
*
* @param count - size of entries batch
* @return map entries collection
*/
Set> entrySet(int count);
/**
* Adds object event listener
*
* @see org.redisson.api.listener.TrackingListener
* @see org.redisson.api.listener.MapPutListener
* @see org.redisson.api.listener.MapRemoveListener
* @see org.redisson.api.ExpiredObjectListener
* @see org.redisson.api.DeletedObjectListener
*
* @param listener object event listener
* @return listener id
*/
int addListener(ObjectListener listener);
}