A newer version of Hazelcast Platform is available.

View latest

Configuring Hazelcast in Embedded Mode

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

You can use a configuration object (config object) to configure members with the Java member API. To create new instances of members, pass the config object to those instances.

You can create a Config object, set/change its properties and attributes, and use it to create new instances of members and clients. The following example configures some network and map properties for a member.

        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 configuration object, pass it to a new HazelcastInstance:

HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance(config);
All configuration must be completed before creating the HazelcastInstance. The Config object cannot be modified after the instance is started.

Using a Member Configuration File in Java

Configuration files allow you to store member configuration in YAML or XML format.

To use a configuration file to configure members, you can use one of the following:

Configuration Loaders

Use one of the following methods to load a configuration file into a config object:

Table 1. Configuration loader methods
Method Description

Config.loadFromFile()

Creates a configuration object based on a Hazelcast configuration file (XML or YAML).

Config.loadDefault()

Loads Config using the default lookup mechanism to locate the configuration file. Loads the nested Hazelcast configuration also by using its default lookup mechanism.

Config.loadFromClasspath()

Creates Config which is loaded from a classpath resource.

Config.loadFromString()

Creates Config from the provided XML or YAML string content.

Config.loadFromStream()

Creates Config from the provided XML or YAML stream content.

XMLConfigBuilder()

Builds a Config that does not apply overrides in environment variables or system properties.

Configuration Builders

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

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.

  • XML

  • YAML

By default, Hazelcast searches for hazelcast.yaml or hazelcast.xml files in the classpath and working directory. You can control the name of the files that Hazelcast searches for, using the relevant system properties such as hazelcast.config.

This sample code creates 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);

All configuration loaders take an optional properties parameter. The default behavior uses the System.getProperties() method to resolve the configuration file:

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);

Updating Member Configuration at Runtime

You can use dynamic configuration to add configuration for some supported features at runtime.

If you want to persist dynamic configuration changes, you need to use a configuration file method that sets the configurationFile field of the Config object such as Config.setConfigurationFile() or Config.loadFromFile().
lifebuoy

Help and support