Skip to main content
Version: 6.0-SNAPSHOT

Configuring a MapStore

This topic explains how to configure a map with a MapStore. It includes configuration options for loading data, as well as caching behaviors, and MapStore reuse.

Before you Begin​

If you use Hazelcast in client/server mode, make sure to add the MapStore to the cluster's classpath.

Quickstart Configuration​

To configure a MapStore, you must provide the name of your class that implements the MapStore.

note

Follow the instructions in Using the generic MapLoader or Using the generic MapStore for this step if you are using a pre-built Mapstore.

xml
<hazelcast>
    ...
    <map name="default">
        <map-store enabled="true">
            <class-name>com.hazelcast.examples.DummyStore</class-name>
        </map-store>
    </map>
    ...
</hazelcast>

Configuring for Write-Behind Caching​

To configure a MapStore to use write-behind caching, set the write-delay-seconds configuration to a number greater than 0.

Configuring the Offloading of MapStore Operations​

To improve cluster throughput, MapStore API calls, such as load() and store() operations, are offloaded by default. This way partition threads are not blocked by them.

Because each partition in a member is managed by a single thread, the write operations to a given partition are handled one at a time in first-in-first-out order. However, MapStore operations may take a long time to connect to the data store and complete, blocking the affected partitions. To avoid blocking partition threads, MapStore operations communicate with the data store asynchronously, using an executor.

note

The init() and destroy() methods of the MapLoaderLifecycleSupport interface are not offloaded. These methods are triggered only once in the whole lifecycle of a map.

You can configure the executor service that handles asynchronous MapStore operations. The offload executor's name is hz:map-store-offloadable. You can configure the number of threads for this executor and its task queue capacity. See Configuring Executor Service for a guide.

xml
<hazelcast>
    ...
    <executor-service name="hz:map-store-offloadable">
        <pool-size>16</pool-size>
        <queue-capacity>0</queue-capacity>
    </executor-service>
    ...
</hazelcast>

Blocking Partition Threads​

You can choose not to offload MapStore operations, which is the behavior in previous Hazelcast Platform releases before version 5.2. To block partition threads during MapStore API operations, set the offload configuration to false.

Delaying the Loading Process of a MapStore​

By default, the MapStore is loaded as soon as the first cluster member starts. If you want the cluster to wait until a certain number of members are available, you can use the hazelcast.initial.min.cluster.size system property. For example, if you set this value to 3, the MapStore is not loaded until three cluster members are running.

Applying the Same MapStore to Multiple Maps​

A MapStore can be applied to more than one map, using wildcards. But a MapStore does not know which entries to store when there is one configuration applied to multiple maps. To store entries when there is one configuration applied to multiple maps, use the Java MapStoreFactory interface. Using the MapStoreFactory interface, a MapStore for each map can be created when a wildcard configuration is used.

note

This option applies only to custom MapStore implementations, not the generic MapStore.

To initialize the MapStore with the given map name, configuration properties, and Hazelcast instance, the MapStore must implement the MapLoaderLifecycleSupport interface.

java
Config config = new Config();
MapConfig mapConfig = config.getMapConfig( "*" );
MapStoreConfig mapStoreConfig = mapConfig.getMapStoreConfig();
mapStoreConfig.setFactoryImplementation( new MapStoreFactory<Object, Object>() {
    @Override
    public MapLoader<Object, Object> newMapStore( String mapName, Properties properties ) {
        return null;
    }
});

Configuration Options for All MapStores​

Use these configuration options to configure the Mapstore for specific maps.

If you are using Java to configure the Mapstore, use the MapStoreConfig object.

OptionDescriptionDefaultExample
enabledWhether the MapStore is enabled for the map.true
xml
<hazelcast>
  <map name="default">
    <map-store enabled="true">
    </map-store>
</hazelcast>
class-nameName of a class that implements the MapStore.'' (empty)
xml
<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.examples.DummyStore</class-name>
    </map-store>
</hazelcast>
offloadWhether MapStore operations are handled asynchronously to avoid blocking partition threads.true
xml
<hazelcast>
    <map name="default">
        <map-store enabled="true">
            <offload>true</offload>
            ...
        </map-store>
    </map>
</hazelcast>
write-delay-secondsNumber of seconds of delay before the MapStore.store(key, value) method is called. If this value is zero, the Mapstore is write-through, otherwise it is write-behind.0
xml
<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.examples.DummyStore
      </class-name>
      <write-delay-seconds>0
      </write-delay-seconds>
    </map-store>
</hazelcast>
write-batch-sizeNumber of batches to group map entries into before writing them to the data store. By default, all map entries are written in one go.1
xml
<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.examples.DummyStore
      </class-name>
      <write-batch-size>1
      </write-batch-size>
    </map-store>
</hazelcast>
write-coalescingWhen write-coalescing is true, only the latest store operation on a key is written to the data store when the change is made within the write-delay-seconds time window. If this value is false, Hazelcast writes every change to the data store in order.true
xml
<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.examples.DummyStore
      </class-name>
      <write-coalescing>true
      </write-coalescing>
    </map-store>
</hazelcast>
initial-mode

The load mode for populating empty maps:

  • LAZY: MapStore operations are asynchronous.
  • EAGER: Map operations are blocked until the MapStore loads all partitions.
note

If you add indexes to the map, then the initial-mode property is overridden by EAGER.

LAZY
xml
<hazelcast>
  <map name="default">
    <map-store enabled="true" initial-mode="LAZY">
      <class-name>com.hazelcast.examples.DummyStore
      </class-name>
    </map-store>
</hazelcast>

More configuration options:

Edit this page