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

Index

Methods

  • 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(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

  • 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.

    throws

    AssertionError if indexConfig is null

    throws

    TypeError If the specified index configuration is invalid.

    Parameters

    Returns Promise<void>

  • 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.

    throws

    AssertionError if aggregator is null

    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

  • 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.

    throws

    AssertionError if aggregator or predicate is null

    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(): Promise<void>
  • Removes all of the mappings.

    Returns Promise<void>

  • containsKey(key: K): Promise<boolean>
  • Returns true if this map has an item associated with key.

    throws

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<boolean>

    true if the map contains the key, false otherwise

  • containsValue(value: V): Promise<boolean>
  • Returns true if this map has key(s) associated with given value.

    throws

    AssertionError if value is null

    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(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

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<void>

  • destroy(): Promise<void>
  • Destroys this object cluster-wide. Clears all resources taken for this object.

    Returns Promise<void>

  • entrySet(): Promise<[K, V][]>
  • Returns entries as an array of key-value pairs.

    Returns Promise<[K, V][]>

  • 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.

    throws

    AssertionError if predicate is null

    Parameters

    • predicate: Predicate

      specified query criteria.

    Returns Promise<[K, V][]>

    result entry set of the query.

  • evict(key: K): Promise<boolean>
  • Evicts the specified key from this map.

    throws

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<boolean>

  • evictAll(): Promise<void>
  • Evicts all keys from this map.

    Returns Promise<void>

  • executeOnEntries(entryProcessor: any, predicate?: Predicate): Promise<[K, V][]>
  • 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.

    throws

    AssertionError if entryProcessor is null

    Parameters

    • entryProcessor: any

      EntryProcessor object

    • Optional predicate: Predicate

      if specified, entry processor is applied to the entries that satisfy this predicate

    Returns Promise<[K, V][]>

    entries after EntryProcessor is applied

  • executeOnKey(key: K, entryProcessor: any): Promise<V>
  • Applies the user defined EntryProcessor to the entry mapped by the key.

    throws

    AssertionError if key or entryProcessor is null

    Parameters

    • key: K

      entry processor is applied only to the value that is mapped with this key

    • entryProcessor: any

      entry processor to be applied

    Returns Promise<V>

    result of entry process

  • executeOnKeys(keys: K[], entryProcessor: any): Promise<[K, V][]>
  • Applies the user defined EntryProcessor to the entries mapped by the given keys.

    throws

    AssertionError if keys is not an array

    Parameters

    • keys: K[]

      keys to be processed

    • entryProcessor: any

    Returns Promise<[K, V][]>

    result of entry process

  • flush(): Promise<void>
  • If this map has a MapStore, this method flushes all local dirty entries.

    Returns Promise<void>

  • forceUnlock(key: K): Promise<void>
  • Releases the lock for the specified key regardless of the owner. This operation always unlocks the key.

    throws

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<void>

  • get(key: K): Promise<V>
  • Retrieves the value associated with given key.

    throws

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<V>

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

  • getAll(keys: K[]): Promise<[K, V][]>
  • Retrieves key value pairs of given keys.

    throws

    AssertionError if keys is null or keys is not an array.

    Parameters

    • keys: K[]

      the array of keys

    Returns Promise<[K, V][]>

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

    throws

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<SimpleEntryView<K, V>>

  • getName(): string
  • Returns the unique name of this object.

    Returns string

  • 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(): string
  • isEmpty(): Promise<boolean>
  • Returns whether this map is empty or not.

    Returns Promise<boolean>

  • isLocked(key: K): Promise<boolean>
  • Checks whether given key is locked.

    throws

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<boolean>

    true if key is locked, false otherwise

  • keySet(): Promise<K[]>
  • Returns the keys of this map as an array.

    Returns Promise<K[]>

  • keySetWithPredicate(predicate: Predicate): Promise<K[]>
  • Queries the map based on the specified predicate and returns the keys of matching entries.

    throws

    AssertionError if predicate is null

    Parameters

    • predicate: Predicate

      predicate to filter map entries

    Returns Promise<K[]>

  • 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(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

    AssertionError if key is null

    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(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

    AssertionError if key or value is null

    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(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.

    throws

    AssertionError if any key or value in the specified array is null

    Parameters

    • pairs: [K, V][]

      entries to be put

    Returns Promise<void>

  • 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

    AssertionError if key or value is null

    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(key: K, value: V, ttl?: number | Long, maxIdle?: number | Long): Promise<void>
  • Same as put except it does not call underlying MapStore.

    throws

    AssertionError if key or value is null

    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(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

    AssertionError if key is null

    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

  • removeAll(predicate: Predicate): Promise<void>
  • Removes all entries which match with the supplied predicate. Note that calling this method also removes all entries from caller's Near Cache. If this map has index, matching entries will be found via index search, otherwise they will be found by full-scan.

    throws

    AssertionError if predicate is null

    Parameters

    • predicate: Predicate

      matching entries with this predicate will be removed from the map

    Returns Promise<void>

  • 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(key: K, newValue: V): Promise<V>
  • Replaces value of given key with newValue.

    throws

    AssertionError if key or newValue is null

    Parameters

    • key: K

      the key of the map entry

    • newValue: V

    Returns Promise<V>

    previous value

  • replaceIfSame(key: K, oldValue: V, newValue: V): Promise<boolean>
  • Replaces value of the key if only it was associated to oldValue.

    throws

    AssertionError if key, oldValue or newValue is null

    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(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

    AssertionError if key or value is null

    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(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.

    throws

    AssertionError if any key or value in the specified array is null

    Parameters

    • pairs: [K, V][]

      entries to be put

    Returns Promise<void>

  • 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

    AssertionError if key or ttl is null

    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(): Promise<number>
  • Retrieves the number of elements in the map.

    Returns Promise<number>

    number of elements in map

  • 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

    AssertionError if key is null

    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(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

    AssertionError if key, value or timeout is null

    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(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

    AssertionError if key or timeout is null

    Parameters

    • key: K

      the key of the map entry

    • timeout: number

      maximum time to wait in milliseconds

    Returns Promise<boolean>

  • 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

    AssertionError if key is null

    Parameters

    • key: K

      the key of the map entry

    Returns Promise<void>

  • Returns a list of values contained in this map.

    Returns 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.

    throws

    AssertionError if predicate is null

    Parameters

    Returns Promise<ReadOnlyLazyList<V>>

    a list of values that satisfies the given predicate

Generated using TypeDoc