A newer version of Hazelcast Platform is available.

View latest

Configuring a MapStore

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

MapStores connect to an external data store only when they are configured on a map. This topic explains how to configure a map with a MapStore.

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.

Follow the instructions in Configuring a Map with the Generic MapStore for this step if you are using a pre-built Mapstore.

  • XML

  • YAML

  • Java

<hazelcast>
    ...
    <map name="default">
        <map-store enabled="true">
            <class-name>com.hazelcast.examples.DummyStore</class-name>
        </map-store>
    </map>
    ...
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.examples.DummyStore
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.examples.DummyStore");

mapConfig.setMapStoreConfig(mapStoreConfig);

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 external data source and complete, blocking the affected partitions. To avoid blocking partition threads, MapStore operations communicate with the external data source asynchronously, using an executor.

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

  • Offloading is not supported for tiered storage, since currently MapStore and tiered storage cannot be enabled for a map at the same time.

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

  • YAML

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

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.

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.

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.

Table 1. MapStore configuration options
Option Description Default Example

enabled

Whether the MapStore is enabled for the map.

true

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setEnabled(true);

mapConfig.setMapStoreConfig(mapStoreConfig);

class-name

Name of a class that implements the MapStore.

'' (empty)

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.examples.DummyStore</class-name>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.examples.DummyStore
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.examples.DummyStore");

mapConfig.setMapStoreConfig(mapStoreConfig);

offload

Whether MapStore operations are handled asychronously to avoid blocking partition threads.

true

  • XML

  • YAML

  • Java

<hazelcast>
    <map name="default">
        <map-store enabled="true">
            <offload>true</offload>
            ...
        </map-store>
    </map>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        offload: true
        ...
Config config = new Config();
MapConfig mapConfig = config.getMapConfig();
MapStoreConfig mapStoreConfig = mapConfig.getMapStoreConfig();
mapStoreConfig.setOffload(true);
...

write-delay-seconds

Number 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

  • YAML

  • Java

<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>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.examples.DummyStore
        write-delay-seconds: 0
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.examples.DummyStore");
mapStoreConfig.setWriteDelaySeconds(0)

mapConfig.setMapStoreConfig(mapStoreConfig);

write-batch-size

Number of batches to group map entries into before writing them to the external data store. By default, all map entries are written in one go.

1

  • XML

  • YAML

  • Java

<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>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.examples.DummyStore
        write-batch-size: 1
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.examples.DummyStore");
mapStoreConfig.setWriteBatchSize(1)

mapConfig.setMapStoreConfig(mapStoreConfig);

write-coalescing

When write-coalescing is true, only the latest store operation on a key is written to the external 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 external data store in order.

true

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.examples.DummyStore
      </class-name>
      <write-coalescing>true
      </write-coalescing>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.examples.DummyStore
        write-coalescing: true
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.examples.DummyStore");
mapStoreConfig.setWriteCoalescing(true)

mapConfig.setMapStoreConfig(mapStoreConfig);

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.

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

LAZY

  • XML

  • YAML

  • Java

<hazelcast>
  <map name="default">
    <map-store enabled="true">
      <class-name>com.hazelcast.examples.DummyStore
      </class-name>
      <initial-mode>LAZY
      </initial-mode>
    </map-store>
</hazelcast>
hazelcast:
  map:
    default:
      map-store:
        enabled: true
        class-name: com.hazelcast.examples.DummyStore
        initial-mode: LAZY
MapConfig mapConfig = new MapConfig("default");

MapStoreConfig mapStoreConfig = new MapStoreConfig();
mapStoreConfig.setClassName("com.hazelcast.examples.DummyStore");
mapStoreConfig.setInitialLoadMode(MapStoreConfig.InitialLoadMode.LAZY)

mapConfig.setMapStoreConfig(mapStoreConfig);

If you’re using the generic MapStore, see Configuring a Map with the Generic MapStore for more configuration properties.

lifebuoy

Help and support