Dynamic Configuration with Programmatic APIs (Java)

You can use the Java member or client APIs to add dynamic configuration for some supported features at runtime.

Before you Begin

You can add new configuration only for some features. See Supported Dynamic Configuration Changes.

Dynamic configuration changes are not persisted by default. See Dynamic Configuration Persistence.

Adding Dynamic Configuration

To add new configuration to a member at runtime, use the add*Config() method of a supported data structure after starting the Hazelcast instance.

Example of adding properties to the Config object

Member API

java

Config config = new Config();
MapConfig mapConfig = new MapConfig("sessions");
config.addMapConfig(mapConfig);
HazelcastInstance instance = Hazelcast.newHazelcastInstance(config);
MapConfig noBackupsMap = new MapConfig("dont-backup").setBackupCount(0);
instance.getConfig().addMapConfig(noBackupsMap);

Java Client

java

HazelcastInstance client = HazelcastClient.newHazelcastClient();
MapConfig noBackupsMap = new MapConfig("dont-backup");
noBackupsMap.setBackupCount(0);
client.getConfig().addMapConfig(noBackupsMap);

Example of loading from a configuration file

Member API

java

Config config = Config.loadFromFile(/path/to/config/file);
HazelcastInstance instance = Hazelcast.newHazelcastInstance(config);
MapConfig noBackupsMap = new MapConfig("dont-backup").setBackupCount(0);
instance.getConfig().addMapConfig(noBackupsMap);

Java Client

java

HazelcastInstance client = HazelcastClient.newHazelcastClient();
MapConfig noBackupsMap = new MapConfig("dont-backup");
noBackupsMap.setBackupCount(0);
client.getConfig().addMapConfig(noBackupsMap);

When the member receives the request, it will check if the configuration already exists and propagate any new configuration across the rest of the cluster.

Handling Partial Propagation

When you submit dynamic configuration changes to a member, they are propagated across all cluster members as well as those that may join the cluster later. If a failure occurs, such as timeouts, network partitions, or IO failures, you need to try adding the dynamic configuration changes again, dynamic changes are idempotent.

Handling Configuration Conflicts

You can add only new dynamic configuration. You cannot use dynamic configuration to override existing configuration at runtime.

If you add dynamic configuration for a configuration block that already exists, Hazelcast throws InvalidConfigurationException.

For example, assuming you start a member with the following fragment in hazelcast.xml configuration:

xml

<hazelcast>
    ...
    <map name="sessions">
        ...
    </map>
    ...
</hazelcast>

If you add dynamic configuration for a map with the name sessions, Hazelcast throws InvalidConfigurationException:

java

HazelcastInstance instance = Hazelcast.newHazelcastInstance();

MapConfig sessionsMapConfig = new MapConfig("sessions");

// this will throw ConfigurationException:
instance.getConfig().addMapConfig(sessionsMapConfig);

When attempting to add dynamic configuration for an element for which dynamic configuration has already been added, then if a configuration conflict is detected InvalidConfigurationException is thrown:

java

HazelcastInstance instance = Hazelcast.newHazelcastInstance();

MapConfig sessionsMapConfig = new MapConfig("sessions").setBackupCount(0);
instance.getConfig().addMapConfig(sessionsMapConfig);

MapConfig sessionsWithBackup = new MapConfig("sessions").setBackupCount(1);
// throws ConfigurationException because the new MapConfig conflicts with existing one
instance.getConfig().addMapConfig(sessionsWithBackup);

MapConfig sessionsWithoutBackup = new MapConfig("sessions").setBackupCount(0);
// does not throw exception: new dynamic config is equal to existing dynamic config of same name
instance.getConfig().addMapConfig(sessionsWithoutBackup);

To ignore conflicts between dynamic configurations, set the hazelcast.dynamicconfig.ignore.conflicts system property to true.