A newer version of Platform is available.

View latest

Programmatic Configuration

Besides declarative configuration, you can configure your cluster programmatically. For this you can create a Config object, set/change its properties and attributes and use this Config object to create a new Hazelcast member. Following is an example code which configures some network and Hazelcast Map properties.

        Config config = new Config();
        config.getNetworkConfig().setPort( 5900 )
                .setPortAutoIncrement( false );

        MapConfig mapConfig = new MapConfig();
        mapConfig.setName( "testMap" )
                .setBackupCount( 2 )
                .setTimeToLiveSeconds( 300 );

To create a Hazelcast member with the above example configuration, pass the configuration object as shown below:

HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance( config );
The Config must not be modified after the Hazelcast instance is started. In other words, all configuration must be completed before creating the HazelcastInstance. Certain additional configuration elements can be added at runtime as described in the Dynamically Adding Data Structure Configuration on a Cluster section.

You can also create a named Hazelcast member. In this case, you should set instanceName of Config object as shown below:

Config config = new Config();
config.setInstanceName( "my-instance" );
Hazelcast.newHazelcastInstance( config );

To retrieve an existing Hazelcast member by its name, use the following:

Hazelcast.getHazelcastInstanceByName( "my-instance" );

To retrieve all existing Hazelcast members, use the following:


If you want to specify your own configuration file to create Config, Hazelcast supports several ways including filesystem, classpath, InputStream and URL.

Building Config from the XML declarative configuration:

  • Config cfg = new XmlConfigBuilder(xmlFileName).build();

  • Config cfg = new XmlConfigBuilder(inputStream).build();

  • Config cfg = new ClasspathXmlConfig(xmlFileName);

  • Config cfg = new FileSystemXmlConfig(configFilename);

  • Config cfg = new UrlXmlConfig(url);

  • Config cfg = new InMemoryXmlConfig(xml);

Building Config from the YAML declarative configuration:

  • Config cfg = new YamlConfigBuilder(yamlFileName).build();

  • Config cfg = new YamlConfigBuilder(inputStream).build();

  • Config cfg = new ClasspathYamlConfig(yamlFileName);

  • Config cfg = new FileSystemYamlConfig(configFilename);

  • Config cfg = new UrlYamlConfig(url);

  • Config cfg = new InMemoryYamlConfig(yaml);

Configuration Loaders

Alternatively, you can configure Hazelcast to load its configuration from the classpath or working directory. By default, it will search for hazelcast.yaml/xml files in the classpath and working directory, but you can control the name of the files using the relevant system properties, i.e., hazelcast.config.

All configuration loaders take an optional properties parameter. In case of its absence System.getProperties() is used to resolve configuration file (XML or YAML).

Hazelcast configuration loaders are listed below:



=== Configuration Builders

Use one of the following classes to build a config object.

NOTE: If you use configuration builders or the new Config() constructor with the Java member API, you cannot override existing configuration with system properties and environment variables. To override existing configuration, you must use configuration loaders.

[tabs] ==== XML:: + —  - xmlConfigBuilder - ClasspathXmlConfig

- FileSystemXmlConfig

- UrlXmlConfig

- InMemoryXmlConfig — YAML:: + — - yamlConfigBuilder - ClasspathYamlConfig


Creates Config which is loaded from a classpath resource.


Creates Config from the provided XML or YAML string content.


Creates Config from the provided XML or YAML stream content.

Here is the sample code for creating a new Jet engine configuration using the configuration loader:

String yaml = ""
   + "hazelcast:\n"
   + "  instance:\n"
   + "    cooperative-thread-count: 64\n"
   + "    flow-control-period: 50\n"
   + "    backup-count: 2\n"
   + "    scale-up-delay-millis: 5000\n"
   + "    lossless-restart-enabled: true\n";

Config config = Config.loadFromString(yaml);
HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);

Or using properties:

String yaml = ""
   + "hazelcast:\n"
   + "  instance:\n"
   + "    backup-count: ${backup-count}\n"
   + "    scale-up-delay-millis: ${scale-up-delay-millis}\n";

Properties properties = new Properties();
properties.setProperty("backup-count", "2");
properties.setProperty("scale-up-delay-millis", "5000");

Config config = Config.loadFromString(yaml, properties);
HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);