Package com.hazelcast.map

Interface MapLoader<K,V>

Type Parameters:
K - type of the MapLoader key
V - type of the MapLoader value
All Known Subinterfaces:
EntryLoader<K,V>, EntryStore<K,V>, MapStore<K,V>
All Known Implementing Classes:
GenericMapLoader, GenericMapStore, MapStoreAdapter
public interface MapLoader<K,V>
Hazelcast distributed map implementation is an in-memory data store, but it can be backed by any type of data store such as RDBMS, OODBMS, or simply a file-based data store.

IMap.get(Object) normally returns the value that is available in memory. If the entry doesn't exist in memory, Hazelcast returns null. If a MapLoader implementation is provided, then instead of returning null, Hazelcast will attempt to load the unknown entry by calling the implementation's load(Object) or loadAll(Collection) methods. Loaded entries will be placed into the distributed map, and they will stay in memory until they are explicitly removed or implicitly evicted (if eviction is configured).

Do not block a MapLoader with calls that may never return, as Hazelcast does not time out the call. A MapLoader should only load data for its own map; calling a map that has a MapLoader or MapStore from a MapLoader (including its own map) can deadlock.

The initial load and the IMap.loadAll methods always call loadAll(Collection) outside partition threads. For other map operations, the thread that calls the MapLoader depends on MapStoreConfig.setOffload(boolean):

  • With offload enabled (the default), the MapLoader runs on a thread pool shared by all maps. Most other operations on the same partition of the map wait for it, and a slow MapLoader can delay MapStore calls of other maps by occupying all available threads. A blocking call to a map with an offloaded MapStore, such as a get of a key not in memory, waits for a thread of the same pool; a call to the same partition of the MapLoader's own map never runs. Offloaded MapStore operations never time out, so once every thread in the pool is blocked this way, the pool deadlocks permanently.
  • With offload disabled, the MapLoader runs on a partition thread, which meanwhile cannot serve other partitions or data structures handled by that thread, such as another map or a queue, so avoid calling across a WAN or to a system that takes more than a few milliseconds to respond. A synchronous call to a different partition throws IllegalThreadStateException. A Hazelcast client calling a blocked partition thread blocks indefinitely; a call from another member eventually fails with OperationTimeoutException.

  • Method Summary

    Modifier and Type
    Method
    Description
    V
    load(K key)
    Loads the value of a given key.
    Map<K,V>
    loadAll(Collection<K> keys)
    Loads given keys.
    Iterable<K>
    loadAllKeys()
    Loads all the keys from the store.

  • Method Details

    • load

      V load(K key)
      Loads the value of a given key. If distributed map doesn't contain the value for the given key then Hazelcast will call implementation's load (key) method to obtain the value. Implementation can use any means of loading the given key; such as an O/R mapping tool, simple SQL or reading a file etc.
      Parameters:
      key - cannot be null
      Returns:
      value of the key; returning null value signals value missing in the underlying store

    • loadAll

      Map<K,V> loadAll(Collection<K> keys)
      Loads given keys. This is batch load operation so that implementation can optimize the multiple loads.

      For any key in the input keys, there should be a single mapping in the resulting map. Also, the resulting map should not have any keys that are not part of the input keys.

      The given collection should not contain any null keys. The returned Map should not contain any null keys or values.

      Loading other items than what provided in keys prevents the map from being filled from the map store.

      Parameters:
      keys - keys of the values entries to load
      Returns:
      map of loaded key-value pairs.

    • loadAllKeys

      Iterable<K> loadAllKeys()
      Loads all the keys from the store. The returned Iterable may return the keys lazily by loading them in batches. The Iterator of this Iterable may implement the Closeable interface in which case it will be closed once iteration is over. This is intended for releasing resources such as closing a JDBC result set.

      The returned Iterable should not contain any null keys.

      Returns:
      all the keys. Keys inside the Iterable cannot be null.