MapLoader and MapStore

Before you Begin

Your cluster must be on the Enterprise plan to use this feature.

To use this feature, you must have either an admin or developer role. See Managing Teams and Users.

Terminology

Term Definition

Term	Definition
MapLoader	MapLoader is an SPI. When you provide a MapLoader implementation and request an entry (using `IMap.get()`) that does not exist in memory, MapLoader’s load method loads that entry from the data store. This loaded entry is placed into the map and will stay there until it is removed or evicted.
MapStore	MapStore is also an SPI. When a MapStore implementation is provided, an entry is also put into a user-defined data store. MapStore extends MapLoader. Later in this document, by MapStore we mean both MapStore and MapLoader since they compose a full-featured MapStore CRUD SPI.
Read-Through Persistence	If an entry does not exist in memory when an application asks for it, Hazelcast asks the loader implementation to load that entry from the data store. If the entry exists there, the loader implementation gets it, hands it to Hazelcast, and Hazelcast puts it into memory. This is read-through persistence mode.
Write-Through/Write-Behind Persistence	MapStore can be configured to be write-through by setting the write-delay-seconds property to 0. This means the entries are put to the data store synchronously. MapStore becomes write-behind when you set the write-delay-seconds property to a value bigger than 0. This means the modified entries will be put to the data store asynchronously after a configured delay.

MapLoader

MapLoader is an SPI. When you provide a MapLoader implementation and request an entry (using IMap.get()) that does not exist in memory, MapLoader’s load method loads that entry from the data store. This loaded entry is placed into the map and will stay there until it is removed or evicted.

MapStore

MapStore is also an SPI. When a MapStore implementation is provided, an entry is also put into a user-defined data store. MapStore extends MapLoader. Later in this document, by MapStore we mean both MapStore and MapLoader since they compose a full-featured MapStore CRUD SPI.

Read-Through Persistence

If an entry does not exist in memory when an application asks for it, Hazelcast asks the loader implementation to load that entry from the data store. If the entry exists there, the loader implementation gets it, hands it to Hazelcast, and Hazelcast puts it into memory. This is read-through persistence mode.

Write-Through/Write-Behind Persistence

MapStore can be configured to be write-through by setting the write-delay-seconds property to 0. This means the entries are put to the data store synchronously. MapStore becomes write-behind when you set the write-delay-seconds property to a value bigger than 0. This means the modified entries will be put to the data store asynchronously after a configured delay.

Enable MapStore or MapLoader

MapStore Configuration is available as a part of the Map Config. In order to enable it, you have to open Custom Configuration form and click Enable Map Store checkbox.

Custom configuration settings for maps

After that, you will see the Map Store fields:

Configuration settings for MapStore

Some of these fields are already predefined, some must be set. The following are the descriptions of MapStore configuration elements and attributes:

class-name: Name of the class implementing MapLoader and/or MapStore. This class can be uploaded via the [Custom Classes upload](doc:custom-classes-upload) feature.
write-delay-seconds: Number of seconds to delay to call the MapStore.store(key, value). If the value is zero then it is write-through, so the MapStore.store(key, value) method is called as soon as the entry is updated. Otherwise, it is write-behind; so the updates will be stored after the write-delay-seconds *value by calling the Hazelcast.storeAll(map) method. Its default value is *0.
write-batch-size: Used to create batch chunks when writing map store. In default mode, all map entries are tried to be written in one go. To create batch chunks, the minimum meaningful value for write-batch-size is 2. For values smaller than 2, it works as in default mode.
write-coalescing: In write-behind mode, Hazelcast coalesces updates on a specific key by default; it applies only the last update on it. You can set this element to false to store all updates performed on a key to the data store.
initial-mode: Sets the initial load mode. Lazy is the default load mode, where the load is asynchronous. Eager means the load is blocked till all partitions are loaded.
properties: The (key, value) properties for MapStore or MapLoader. For example database properties. To initialize the MapLoader/MapStore implementation with the given map name, configuration properties and the Hazelcast instance, implement the MapLoaderLifecycleSupport interface.

Example property for a MapStore

When all necessary fields are set just click Save Configuration button.

Uploaded classes are restricted by a limited set of JSP permissions.

If you need your uploaded code to be granted any additional permissions, please create a support ticket for it.

Code Samples

Please take a look into this repository for MapStore samples.