Package com.hazelcast.map

Interface MapStore<K,V>

Type Parameters:
K - type of the MapStore key
V - type of the MapStore value
All Superinterfaces:
MapLoader<K,V>
All Known Subinterfaces:
EntryStore<K,V>
All Known Implementing Classes:
GenericMapStore, MapStoreAdapter
public interface MapStore<K,V> extends 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, NOSQL, or simply a file-based data store.

IMap.put(key, value) normally stores the entry into JVM's memory. If the MapStore implementation is provided then Hazelcast will also call the MapStore implementation to store the entry into a user-defined storage, such as RDBMS or some other external storage system. It is completely up to the user how the key-value will be stored or deleted.

Same goes for IMap.remove(key).

Implementations must assume:

  • Operations may be retried, reordered, or replayed after failures or migrations.
  • Batch methods (storeAll/deleteAll) may partially succeed and be retried as per-entry operations.
  • At-least-once delivery semantics; exactly-once or atomic multi-row guarantees are not provided.

Implementations must therefore ensure:

  • Idempotent writes and deletes.
  • Tolerance to partial failure and replay.
  • No reliance on global ordering, transactional isolation, or side effects.

MapStore is not a durability layer in the database sense. It exists to make in-memory state recoverable, not to provide transactional persistence.

*

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    delete(K key)
    Deletes the entry with the given key from the external store.
    void
    deleteAll(Collection<K> keys)
    Deletes multiple entries from the external store.
    void
    store(K key, V value)
    Stores the key-value pair in the external store.
    void
    storeAll(Map<K,V> map)
    Stores multiple entries in the external store.

    Methods inherited from interface com.hazelcast.map.MapLoader

    load, loadAll, loadAllKeys

  • Method Details

    • store

      void store(K key, V value)
      Stores the key-value pair in the external store.

      Invocation semantics depend on configuration:

      • Write-through (writeDelaySeconds == 0): this method is invoked synchronously as part of the IMap.put() call. If this method throws an exception, the map operation fails.
      • Write-behind (writeDelaySeconds > 0): this method may be invoked asynchronously on a background thread, potentially long after the original map operation has completed.

      Under normal circumstances Hazelcast provides at-least-once delivery semantics for calls to this method. Implementations must therefore be idempotent and tolerate retries, reordering, and duplicate invocations.

      Parameters:
      key - key of the entry to store
      value - value of the entry to store

    • storeAll

      void storeAll(Map<K,V> map)
      Stores multiple entries in the external store.

      This method is primarily used with write-behind enabled (writeDelaySeconds > 0) when batching is applicable. Hazelcast may still invoke store(Object, Object) instead of this method depending on runtime conditions (for example, batch size, write coalescing, or number of distinct keys in the current write window). Implementations must not rely on this method being invoked for every flush.

      Error handling and retries:

      • If this method throws an exception, Hazelcast treats the batch as failed and starts retry handling.
      • If the provided map has not been modified (no entries removed to signal partial success), Hazelcast retries storeAll(map) up to three times, waiting about 1 second between attempts.
      • After the final batch attempt fails, Hazelcast falls back to calling store(Object, Object) for the remaining entries, one by one.
      • If the implementation removes entries from map as they are stored (before throwing), Hazelcast treats removed entries as successful and does not retry them; only the entries still present in map are retried and/or passed to the per-entry fallback.

      This allows implementations to signal partial success explicitly. Entries left in the map after an exception will be retried individually; removed entries will not be passed to subsequent calls.

      Hazelcast does not provide transactional guarantees across entries. Batch boundaries do not imply atomicity.

      Parameters:
      map - map of entries to store

    • delete

      void delete(K key)
      Deletes the entry with the given key from the external store.

      Invocation semantics depend on configuration:

      • Write-through: invoked synchronously as part of IMap.remove().
      • Write-behind: invoked asynchronously on a background thread.

      Hazelcast provides at-least-once delivery semantics. Implementations must tolerate retries and duplicate invocations. Deleting a non-existent entry should be treated as a successful no-op.

      Parameters:
      key - the key to delete from the store

    • deleteAll

      void deleteAll(Collection<K> keys)
      Deletes multiple entries from the external store.

      This method is primarily used with write-behind enabled (writeDelaySeconds > 0) when batching is applicable. Hazelcast may still invoke delete(Object) instead of this method depending on configuration and runtime conditions. Implementations must not rely on this method being invoked for every flush.

      Error handling and retries:

      • If this method throws an exception, Hazelcast initiates retry handling.
      • On retry, Hazelcast invokes delete(Object) one-by-one for the remaining keys.
      • If the implementation removes successfully deleted keys from the provided keys collection before throwing, those keys are treated as successful and are not retried.

      This allows implementations to signal partial success explicitly. Keys left in the keys collection after an exception will be retried individually; removed keys will not be passed to subsequent calls.

      Batch deletion does not imply atomicity or ordering guarantees.

      Parameters:
      keys - the keys of the entries to delete