Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface IMap<K, V>

Concurrent, distributed, observable and queryable map.

Methods that require serialization/deserialization may throw RangeError, e.g when there is no suitable serializer for a certain type.

Type parameters

  • K

  • V

Hierarchy

  • DistributedObject
    • IMap

Index

Methods

Methods

addEntryListener

  • addEntryListener(listener: MapListener<K, V>, key?: K, includeValue?: boolean): Promise<string>

  • Adds a MapListener for this map.

    Parameters

    • listener: MapListener<K, V>

      listener object

    • Optional key: K

      optional key to restrict events to associated entry

    • Optional includeValue: boolean

      if set to true, event message will contain new value of the key

    Returns Promise<string>

    registration id of the listener

addEntryListenerWithPredicate

  • addEntryListenerWithPredicate(listener: MapListener<K, V>, predicate: Predicate, key?: K, includeValue?: boolean): Promise<string>

  • Adds a MapListener for this map. Listener will get notified for map add/remove/update/evict events filtered by the given predicate.

    Parameters

    • listener: MapListener<K, V>

      listener object

    • predicate: Predicate

      predicate

    • Optional key: K

      optional key to restrict events to associated entry

    • Optional includeValue: boolean

      if set to true, event message will contain new value of the key

    Returns Promise<string>

    registration id of the listener

addIndex

  • addIndex(indexConfig: IndexConfig): Promise<void>

  • Adds an index to this map for the specified entries so that queries can run faster.

    Let's say your map values are Employee objects.

    class Employee implements Portable {
    active: boolean = false;
    age: number;
    name: string = null;
    // other fields

    // portable implementation
}

    If you are querying your values mostly based on age and active then you may consider indexing these fields.

    const map = client.getMap('employees');
// Sorted index for range queries:
map.addIndex({
    type: 'SORTED',
    attributes: ['age']
});
// Hash index for equality predicates:
map.addIndex({
    type: 'HASH',
    attributes: ['active']
});

    Index attribute should either have a getter method or be public. You should also make sure to add the indexes before adding entries to this map.

    Time to Index

    Indexing time is executed in parallel on each partition by operation threads. The Map is not blocked during this operation.

    The time taken in proportional to the size of the Map and the number Members.

    Searches while indexes are being built

    Until the index finishes being created, any searches for the attribute will use a full Map scan, thus avoiding using a partially built index and returning incorrect results.

    Parameters

    • indexConfig: IndexConfig

      Index configuration.

    Returns Promise<void>

aggregate

  • aggregate<R>(aggregator: Aggregator<R>): Promise<R>

  • Applies the aggregation logic on all map entries and returns the result.

    Fast-Aggregations are the successor of the Map-Reduce Aggregators. They are equivalent to the Map-Reduce Aggregators in most of the use-cases, but instead of running on the Map-Reduce engine they run on the Query infrastructure. Their performance is tens to hundreds times better due to the fact that they run in parallel for each partition and are highly optimized for speed and low memory consumption.

    Type parameters

    • R

      type of the result

    Parameters

    • aggregator: Aggregator<R>

      aggregator to aggregate the entries with

    Returns Promise<R>

    the result of the given type

aggregateWithPredicate

  • aggregateWithPredicate<R>(aggregator: Aggregator<R>, predicate: Predicate): Promise<R>

  • Applies the aggregation logic on map entries filtered with the Predicated and returns the result.

    Fast-Aggregations are the successor of the Map-Reduce Aggregators. They are equivalent to the Map-Reduce Aggregators in most of the use-cases, but instead of running on the Map-Reduce engine they run on the Query infrastructure. Their performance is tens to hundreds times better due to the fact that they run in parallel for each partition and are highly optimized for speed and low memory consumption.

    Type parameters

    • R

      type of the result

    Parameters

    • aggregator: Aggregator<R>

      aggregator to aggregate the entries with

    • predicate: Predicate

      predicate to filter the entries with

    Returns Promise<R>

    the result of the given type

clear

  • clear(): Promise<void>

  • Removes all of the mappings.

    Returns Promise<void>

containsKey

  • containsKey(key: K): Promise<boolean>

  • Returns true if this map has an item associated with key.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<boolean>

    true if the map contains the key, false otherwise

containsValue

  • containsValue(value: V): Promise<boolean>

  • Returns true if this map has key(s) associated with given value.

    throws

    RangeError if value is null or undefined

    Parameters

    • value: V

      the value of the map entry

    Returns Promise<boolean>

    true if the map has key or keys associated with given value

delete

  • delete(key: K): Promise<void>

  • Removes specified key from the map. Unlike remove this method does not return the deleted value. Therefore, it eliminates deserialization cost of the returned value.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<void>

destroy

  • destroy(): Promise<void>

  • Destroys this object cluster-wide. Clears all resources taken for this object.

    Returns Promise<void>

entrySet

  • entrySet(): Promise<[K, V][]>

  • Returns entries as an array of key-value pairs.

    Returns Promise<[K, V][]>

entrySetWithPredicate

  • entrySetWithPredicate(predicate: Predicate): Promise<[K, V][]>

  • Queries the map based on the specified predicate and returns matching entries. Specified predicate runs on all members in parallel.

    Parameters

    • predicate: Predicate

      specified query criteria.

    Returns Promise<[K, V][]>

    result entry set of the query.

evict

  • evict(key: K): Promise<boolean>

  • Evicts the specified key from this map.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<boolean>

evictAll

  • evictAll(): Promise<void>

  • Evicts all keys from this map.

    Returns Promise<void>

executeOnEntries

  • Applies the user defined EntryProcessor to the all entries in the map. Returns the results mapped by each key in the map. Note that entryProcessor should be registered at server side too.

    Parameters

    Returns Promise<[K, V][]>

    entries after EntryProcessor is applied

executeOnKey

  • Applies the user defined EntryProcessor to the entry mapped by the key.

    Parameters

    Returns Promise<V>

    result of entry process

executeOnKeys

  • Applies the user defined EntryProcessor to the entries mapped by the given keys.

    Parameters

    Returns Promise<[K, V][]>

    result of entry process

flush

  • flush(): Promise<void>

  • If this map has a MapStore, this method flushes all local dirty entries.

    Returns Promise<void>

forceUnlock

  • forceUnlock(key: K): Promise<void>

  • Releases the lock for the specified key regardless of the owner. This operation always unlocks the key.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<void>

get

  • get(key: K): Promise<V>

  • Retrieves the value associated with given key.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<V>

    value associated with key, null if the key does not exist

getAll

  • getAll(keys: K[]): Promise<[K, V][]>

  • Retrieves key value pairs of given keys.

    Parameters

    • keys: K[]

      the array of keys

    Returns Promise<[K, V][]>

getEntryView

  • getEntryView(key: K): Promise<SimpleEntryView<K, V>>

  • Returns a key-value pair representing the association of given key.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<SimpleEntryView<K, V>>

getName

  • getName(): string

  • Returns the unique name of this object.

    Returns string

getPartitionKey

  • getPartitionKey(): string

  • Returns the key of the partition that this DistributedObject is assigned to. For a partitioned data structure, the returned value will not be null, but otherwise undefined.

    Returns string

getServiceName

  • getServiceName(): string

  • Returns the service name for this object.

    Returns string

isEmpty

  • isEmpty(): Promise<boolean>

  • Returns whether this map is empty or not.

    Returns Promise<boolean>

isLocked

  • isLocked(key: K): Promise<boolean>

  • Checks whether given key is locked.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<boolean>

    true if key is locked, false otherwise

keySet

  • keySet(): Promise<K[]>

  • Returns the keys of this map as an array.

    Returns Promise<K[]>

keySetWithPredicate

  • keySetWithPredicate(predicate: Predicate): Promise<K[]>

  • Queries the map based on the specified predicate and returns the keys of matching entries.

    Parameters

    • predicate: Predicate

      predicate to filter map entries

    Returns Promise<K[]>

loadAll

  • loadAll(keys?: K[], replaceExistingValues?: boolean): Promise<void>

  • Loads keys to the store.

    Parameters

    • Optional keys: K[]

      loads only given keys if set

    • Optional replaceExistingValues: boolean

      if set to true existing keys will be replaced by newly loaded keys.

    Returns Promise<void>

lock

  • lock(key: K, leaseTime?: number): Promise<void>

  • Locks the given key for this map. Promise is resolved when lock is successfully acquired. This means it may never be resolved if some other process holds the lock and does not unlock it. A lock may be acquired on non-existent keys. In that case, other clients would block until the non-existent key is unlocked. If the lock holder introduces the key to the map, the put operation is not blocked. If a client not holding a lock on the non-existent key tries to introduce the key while a lock exists on the non-existent key, the put operation blocks until it is unlocked.

    Locking is reentrant, meaning that the lock owner client can obtain the lock multiple times. If the lock was acquired multiple times, then unlock() method must be called the same amount of times, otherwise the lock will remain unavailable.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • Optional leaseTime: number

      lock is automatically unlocked after leaseTime milliseconds; defaults to infinity

    Returns Promise<void>

put

  • put(key: K, value: V, ttl?: number | Long, maxIdle?: number | Long): Promise<V>

  • Associates the specified value with the specified key. If key was associated with another value, it replaces the old value.

    The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).

    The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the Max Idle is 0, then the entry lives forever. If the Max Idle is negative, then the Max Idle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The Max Idle that is less than 1 second can lead to unexpected behaviour.

    throws

    RangeError if key or value is undefined or null or ttl is negative

    Parameters

    • key: K

      the key of the map entry

    • value: V

      new value

    • Optional ttl: number | Long

      optional time to live in milliseconds. 0 means infinite, negative means map config default. Time resolution for TTL is seconds. The given value is rounded to the next closest second value.

    • Optional maxIdle: number | Long

      optional maximum time in milliseconds for this entry to stay idle in the map. 0 means infinite, negative means map config default.

    Returns Promise<V>

    old value if there was any, null otherwise

putAll

  • putAll(pairs: [K, V][]): Promise<void>

  • Puts all key value pairs from this array to the map as key -> value mappings.

    The behaviour of this operation is undefined if the specified pairs are modified while this operation is in progress.

    Interactions with the map store

    For each element not found in memory MapLoader#load(Object) is invoked to load the value from the map store backing the map, which may come at a significant performance cost. Exceptions thrown by load fail the operation and are propagated to the caller. The elements which were added before the exception was thrown will remain in the map, the rest will not be added.

    If write-through persistence mode is configured, MapStore#store(Object, Object) is invoked for each element before the element is added in memory, which may come at a significant performance cost. Exceptions thrown by store fail the operation and are propagated to the caller. The elements which were added before the exception was thrown will remain in the map, the rest will not be added.

    If write-behind persistence mode is configured with write-coalescing turned off, this call may be rejected with ReachedMaxSizeError if the write-behind queue has reached its per-node maximum capacity.

    Parameters

    • pairs: [K, V][]

      entries to be put

    Returns Promise<void>

putIfAbsent

  • putIfAbsent(key: K, value: V, ttl?: number | Long, maxIdle?: number | Long): Promise<V>

  • Puts specified key value association if it was not present before.

    The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).

    The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the Max Idle is 0, then the entry lives forever. If the Max Idle is negative, then the Max Idle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The Max Idle that is less than 1 second can lead to unexpected behaviour.

    throws

    RangeError if key or value is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • value: V

      new value

    • Optional ttl: number | Long

      optional time to live in milliseconds. 0 means infinite, negative means map config default. Time resolution for TTL is seconds. The given value is rounded to the next closest second value.

    • Optional maxIdle: number | Long

      optional maximum time in milliseconds for this entry to stay idle in the map. 0 means infinite, negative means map config default.

    Returns Promise<V>

    old value of the entry

putTransient

  • putTransient(key: K, value: V, ttl?: number | Long, maxIdle?: number | Long): Promise<void>

  • Same as put except it does not call underlying MapStore.

    throws

    RangeError if key or value is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • value: V

      new value

    • Optional ttl: number | Long

      optional time to live in milliseconds. 0 means infinite, negative means map config default. Time resolution for TTL is seconds. The given value is rounded to the next closest second value.

    • Optional maxIdle: number | Long

      optional maximum time in milliseconds for this entry to stay idle in the map. 0 means infinite, negative means map config default.

    Returns Promise<void>

remove

  • remove(key: K, value?: V): Promise<boolean | V>

  • Removes specified key from map. If optional value is specified, the key is removed only if currently mapped to given value. Note that serialized version of the value is used in comparison.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • Optional value: V

      expected value

    Returns Promise<boolean | V>

    value associated with key, null if the key did not exist before. If optional value is specified, a boolean representing whether or not entry is removed is returned

removeEntryListener

  • removeEntryListener(listenerId: string): Promise<boolean>

  • Removes a MapListener from this map.

    Parameters

    • listenerId: string

      registration Id of the listener

    Returns Promise<boolean>

    true if remove operation is successful, false if unsuccessful or this listener did not exist

replace

  • replace(key: K, newValue: V): Promise<V>

  • Replaces value of given key with newValue.

    throws

    RangeError if key or newValue is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • newValue: V

    Returns Promise<V>

    previous value

replaceIfSame

  • replaceIfSame(key: K, oldValue: V, newValue: V): Promise<boolean>

  • Replaces value of the key if only it was associated to oldValue.

    throws

    RangeError if key, oldValue or newValue is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • oldValue: V

      expected old value

    • newValue: V

      new value

    Returns Promise<boolean>

    true if the value was replaced

set

  • set(key: K, value: V, ttl?: number | Long, maxIdle?: number | Long): Promise<void>

  • Similar to put except it does not return the old value.

    The entry will expire and get evicted after the TTL. It limits the lifetime of the entries relative to the time of the last write access performed on them. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).

    The entry will expire and get evicted after the Max Idle time. It limits the lifetime of the entries relative to the time of the last read or write access performed on them. If the Max Idle is 0, then the entry lives forever. If the Max Idle is negative, then the Max Idle from the map configuration will be used (default: forever). The time precision is limited by 1 second. The Max Idle that is less than 1 second can lead to unexpected behaviour.

    throws

    RangeError if key or value is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • value: V

      new value

    • Optional ttl: number | Long

      optional time to live in milliseconds. 0 means infinite, negative means map config default. Time resolution for TTL is seconds. The given value is rounded to the next closest second value.

    • Optional maxIdle: number | Long

      optional maximum time in milliseconds for this entry to stay idle in the map. 0 means infinite, negative means map config default.

    Returns Promise<void>

setAll

  • setAll(pairs: [K, V][]): Promise<void>

  • Puts all key value pairs from this array to the map as key -> value mappings without loading non-existing elements from map store which is more efficient than putAll.

    This method breaks the contract of EntryListener. EntryEvent of all the updated entries will have null oldValue even if they exist previously.

    The behaviour of this operation is undefined if the specified pairs are modified while this operation is in progress.

    Interactions with the map store

    If write-through persistence mode is configured, MapStore#store(Object, Object) is invoked for each element before the element is added in memory, which may come at a significant performance cost. Exceptions thrown by store fail the operation and are propagated to the caller. The elements which were added before the exception was thrown will remain in the map, the rest will not be added.

    If write-behind persistence mode is configured with write-coalescing turned off, this call may be rejected with ReachedMaxSizeError if the write-behind queue has reached its per-node maximum capacity.

    Works with Hazelcast versions 4.1 and above.

    Parameters

    • pairs: [K, V][]

      entries to be put

    Returns Promise<void>

setTtl

  • setTtl(key: K, ttl: number | Long): Promise<boolean>

  • Updates the TTL (time to live) value of the entry specified by key with a new TTL value. New TTL value is valid starting from the time this operation is invoked, not since the time the entry was created. If the entry does not exist or is already expired, this call has no effect.

    The entry will expire and get evicted after the TTL. If the TTL is 0, then the entry lives forever. If the TTL is negative, then the TTL from the map configuration will be used (default: forever).

    If there is no entry with key key or is already expired, this call makes no changes to entries stored in this map.

    throws

    RangeError if key or ttl is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • ttl: number | Long

      time to live in milliseconds. 0 means infinite, negative means map config default. Time resolution for TTL is seconds. The given value is rounded to the next closest second value.

    Returns Promise<boolean>

    true if the entry exists and its TTL value is changed, false otherwise

size

  • size(): Promise<number>

  • Retrieves the number of elements in the map.

    Returns Promise<number>

    number of elements in map

tryLock

  • tryLock(key: K, timeout?: number, leaseTime?: number): Promise<boolean>

  • Tries to acquire the lock for the specified key. If lock is not available, server immediately responds with false.

    Locking is reentrant, meaning that the lock owner client can obtain the lock multiple times. If the lock was acquired multiple times, then unlock() method must be called the same amount of times, otherwise the lock will remain unavailable.

    throws

    RangeError if key is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • Optional timeout: number

      server waits for timeout milliseconds to acquire the lock before giving up; defaults to 0

    • Optional leaseTime: number

      lock is automatically release after leaseTime milliseconds; defaults to infinity

    Returns Promise<boolean>

tryPut

  • tryPut(key: K, value: V, timeout: number): Promise<boolean>

  • Tries to put specified key value pair into the map. If this method returns false, it indicates that caller thread was not able to acquire the lock for given key in timeout milliseconds.

    throws

    RangeError if key or value or timeout is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • value: V

      new value

    • timeout: number

      maximum time to wait in milliseconds

    Returns Promise<boolean>

tryRemove

  • tryRemove(key: K, timeout: number): Promise<boolean>

  • Tries to remove specified key from the map. If this method returns false, it indicates that caller thread was not able to acquire the lock for given key in timeout milliseconds.

    throws

    RangeError if key or timeout is null or undefined

    Parameters

    • key: K

      the key of the map entry

    • timeout: number

      maximum time to wait in milliseconds

    Returns Promise<boolean>

unlock

  • unlock(key: K): Promise<void>

  • Releases the lock for this key. If this client holds the lock, hold count is decremented. If hold count is zero, lock is released.

    throws

    RangeError if this client is not the owner of the key

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<void>

values

  • values(): Promise<ReadOnlyLazyList<V>>

  • Returns a list of values contained in this map.

    Returns Promise<ReadOnlyLazyList<V>>

valuesWithPredicate

  • valuesWithPredicate(predicate: Predicate): Promise<ReadOnlyLazyList<V>>

  • Queries the map based on the specified predicate and returns the values of matching entries. Specified predicate runs on all members in parallel.

    Parameters

    Returns Promise<ReadOnlyLazyList<V>>

    a list of values that satisfies the given predicate

Generated using TypeDoc