Hazelcast - Configuration

Hazelcast supports programmatic as well as XML-based configuration. However, it is the XML configuration which is heavily used in production, given its ease of use. But XML configuration internally uses the Programmatic configuration.

XML Configuration

The hazelcast.xml is where these configurations need to be placed. The file is searched for in the following location (in same order) and is chosen from the first available location −

  • Passing the location of the XML to the JVM via the system property - Dhazelcast.config=/path/to/hazelcast.xml

  • hazelcast.xml in the current working directory

  • hazelcast.xml in the classpath

  • default hazelcast.xml provided by Hazelcast

Once the XML is found, Hazelcast would load the required configuration from the XML file.

Let's try that out with an example. Create an XML in your current directory with the name hazelcast.xml.

<hazelcast
   xsi:schemaLocation="http://www.hazelcast.com/schema/config  
   http://www.hazelcast.com/schema/config/hazelcast-config-3.12.12.xsd"
   xmlns="http://www.hazelcast.com/schema/config"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <!-- name of the instance -->
   <instance-name>XML_Hazelcast_Instance</instance-name>
</hazelcast>

The XML as of now only contains the schema location of the Hazelcast XML which is used for validation. But more importantly, it contains the instance name.

Example

Now create an XMLConfigLoadExample.java file with the following content.

package com.example.demo;

import com.hazelcast.core.Hazelcast;
import com.hazelcast.core.HazelcastInstance;

public class XMLConfigLoadExample {
   public static void main(String... args) throws InterruptedException{
      //initialize hazelcast server/instance
      HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance();

      //specified the name written in the XML file
      System.out.println(String.format("Name of the instance: %s",hazelcast.getName()));
      
      //perform a graceful shutdown
      hazelcast.shutdown();
   }
}

Execute the above Java file with the following command −

java -Dhazelcast.config=hazelcast.xml -cp .\target\demo-0.0.1-SNAPSHOT.jar
com.example.demo.XMLConfigLoadExample

Output

The output for above command would be −

Jan 30, 2021 1:21:41 PM com.hazelcast.config.XmlConfigLocator
INFO: Loading configuration hazelcast.xml from System property
'hazelcast.config'
Jan 30, 2021 1:21:41 PM com.hazelcast.config.XmlConfigLocator
INFO: Using configuration file at C:\Users\demo\eclipseworkspace\
hazelcast\hazelcast.xml
...
Members {size:1, ver:1} [
   Member [localhost]:5701 - 3d400aed-ddb9-4e59-9429-3ab7773e7e09 this
]
Name of cluster: XML_Hazelcast_Instance

As you see, Hazelcast loaded the configuration and printed the name which was specified in the configuration (last line).

There are a whole lot of configuration options which can be specified in the XML. The complete list can be found at −

https://github.com/hazelcast/hazelcast/blob/master/hazelcast/src/main/resources/hazelcast-full-example.xml

We will see a few of these configurations as we move along the tutorial.

Programmatic Configuration

As stated earlier, XML configuration is ultimately done via programmatic configuration. So, let’s try programmatic configuration for the same example which we saw in XML configuration. For that, let’s create the ProgramaticConfigLoadExample.java file with the following content.

Example

package com.example.demo;

import com.hazelcast.config.Config;
import com.hazelcast.core.Hazelcast;
import com.hazelcast.core.HazelcastInstance;

public class ProgramaticConfigLoadExample {
   public static void main(String... args) throws InterruptedException {
      Config config = new Config();
      config.setInstanceName("Programtic_Hazelcast_Instance");
      
      // initialize hazelcast server/instance
      HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance(config);

      // specified the name written in the XML file
      System.out.println(String.format("Name of the instance: %s", hazelcast.getName()));

      // perform a graceful shutdown
      hazelcast.shutdown();
   }
}

Let’s execute the code without passing any hazelcast.xml file by −

java -cp .\target\demo-0.0.1-SNAPSHOT.jar
com.example.demo.ProgramaticConfigLoadExample

Output

The output of the above code is −

Name of the instance: Programtic_Hazelcast_Instance

Logging

To avoid dependencies, Hazelcast by default uses JDK based logging. But it also supports logging via slf4j, log4j. For example, if we want to setup logging via for sl4j with logback, we can update the POM to contain the following dependencies −

<!-- contains both sl4j bindings and the logback core -->
<dependency>
   <groupId>ch.qos.logback</groupId>
   <artifactId>logback-classic</artifactId>
   <version>1.2.3</version>
</dependency>

Example

Define a configuration logback.xml file and add it to your classpath, for example, src/main/resources.

<configuration>
   <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
         <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
      </encoder>
   </appender>

   <root level="info">
      <appender-ref ref="STDOUT" />
   </root>
   
   <logger name="com.hazelcast" level="error">
      <appender-ref ref="STDOUT" />
   </logger>
</configuration>

Now, when we execute the following command, we notice that all the meta information about the Hazelcast member creation etc. is not printed. And this is because we have set the logging level for Hazelcast to error and asked Hazelcast to use sl4j logger.

java  -Dhazelcast.logging.type=slf4j -cp .\target\demo-0.0.1-SNAPSHOT.jar com.example.demo.SingleInstanceHazelcastExample

Output

John

Variables

Value written to XML configuration files can vary based on the environment. For example, in production, you may use a different username/password for connecting to the Hazelcast cluster compared to the dev environment. Instead of maintaining separate XML files, one can also write variables in the XML files and then pass those variables via command line or programmatically to Hazelcast. Here is an example for choosing the name of the instance from the command line.

So, here is our XML file with the variable ${varname}

<hazelcast
   xsi:schemaLocation="http://www.hazelcast.com/schema/config
   http://www.hazelcast.com/schema/config/hazelcast-config-3.12.12.xsd"
   xmlns="http://www.hazelcast.com/schema/config"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   
   <instance-name>${instance_name}</instance-name>
</hazelcast>

Example

And here is the sample Java code we would use to print the variable value −

package com.example.demo;

import java.util.Map;
import com.hazelcast.core.Hazelcast;
import com.hazelcast.core.HazelcastInstance;

public class XMLConfigLoadWithVariable {
   public static void main(String... args) throws InterruptedException {
      // initialize hazelcast server/instance
      HazelcastInstance hazelcast = Hazelcast.newHazelcastInstance();

      // specified the name written in the XML file
      System.out.println(String.format("Name of the instance: %s", hazelcast.getName()));

      // perform a graceful shutdown
      hazelcast.shutdown();
   }
}

And, following is the command −

java -Dhazelcast.config=others\hazelcast.xml -Dinstance_name=dev_cluster -cp
.\target\demo-0.0.1-SNAPSHOT.jar com.example.demo.XMLConfigLoadWithVariable

Output

And the output shows that the variable was replaced by Hazelcast correctly.

Name of the instance: dev_cluster
Advertisements