Guide to Hazelcast with Java

1. Overview

This is an introductory article on Hazelcast where we will walk through how to create a cluster member, distributed Map to share Map data among the cluster nodes and create a Java client to connect and query data in the cluster.

2. What Is Hazelcast?

Hazelcast is a distributed In-Memory Data Grid platform for Java. The architecture supports high scalability and data distribution in a clustered environment. It supports auto-discovery of nodes and intelligent synchronization. To see the features for all Hazelcast editions we can refer to following link.

Hazelcast is available in different editions. You can find the list of available Hazelcast editions in the following link. For the purpose of this article, we will focus on the open-source edition of Hazelcast.

Likewise, Hazelcast offers various features such as Distributed Data Structure, Distributed Compute, Distributed Query etc. For the purpose of this article, we will focus on distributed Map.

3. Maven Dependencies

Hazelcast offers different libraries based on the usage. We can find maven dependencies under group com.hazelcast in Maven Central.

For the purpose of this article, we will focus on dependencies needed to create standalone Hazelcast cluster member and the Hazelcast Java Client.

3.1. Hazelcast Cluster Member

We need to add hazelcast dependency in pom.xml as shown below:

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast</artifactId>
    <version>3.7.2</version>
</dependency>

The dependency is available in maven central repository.

3.2. Hazelcast Java Client

Besides Hazelcast core dependency, we will also need to include the client dependency:

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast-client</artifactId>
    <version>3.7.2</version>
</dependency>

The dependency is available in the maven central repository.

4. Your First Hazelcast Application

4.1. Create Hazelcast Member

Members (also called nodes) automatically join together to form a cluster. This automatic joining takes place with various discovery mechanisms that the members use to find each other.

Let’s create a member that stores data in a Hazelcast distributed map:

public class ServerNode {
    
    HazelcastInstance hzInstance = Hazelcast.newHazelcastInstance();
    ...
}

When we start the ServerNode application, we can see the flowing text in the console which means that we create a new Hazelcast node in our JVM which will have to join the cluster.

Members [1] {
    Member [192.168.1.105]:5701 - 899898be-b8aa-49aa-8d28-40917ccba56c this
}

To create multiple nodes we can start the multiple instances of ServerNode application. Hazelcast will automatically create and add a new member to the cluster.

For example, if we run the ServerNode application again, we will see the following log in the console which says that there are two members in the cluster.

Members [2] {
  Member [192.168.1.105]:5701 - 899898be-b8aa-49aa-8d28-40917ccba56c
  Member [192.168.1.105]:5702 - d6b81800-2c78-4055-8a5f-7f5b65d49f30 this
}

4.2. Create Distributed Map

Next, we will create a distributed Map. We need the instance of HazelcastInstance created earlier to create a distributed Map which extends java.util.concurrent.ConcurrentMap interface.

Map<Long, String> map = hazelcastInstance.getMap("data");
...

Let’s add some entries to the map:

IdGenerator idGenerator = hazelcastInstance.getIdGenerator("newid");
for (int i = 0; i < 10; i++) {
    map.put(idGenerator.newId(), "message" + 1);
}

As we can see above, we have added 10 entries in the map. We used IdGenerator to ensure that we get the unique key for the map. For more details on IdGenerator, you can check out the following link.

While this may not be the real world example, it is just used to demonstrate one of the many operations that we can apply to the distributed map. We will see in the later section how we can retrieve the map entries added by the cluster member from the Hazelcast java client.

Internally, Hazelcast will partition the map entries and distribute and replicate the entries among the cluster members. For more details on Hazelcast Map, you can check out the following link.

4.3. Create Hazelcast Java Client

Hazelcast client allows us to do all Hazelcast operations without being a member of the cluster. It connects to one of the cluster members and delegates all cluster-wide operations to it.

Let’s create a native client:

ClientConfig config = new ClientConfig();
GroupConfig groupConfig = config.getGroupConfig();
groupConfig.setName("dev");
groupConfig.setPassword("dev-pass");
HazelcastInstance hzClient
  = HazelcastClient.newHazelcastClient(config);

The default username and password to access the cluster are dev and dev-pass. For more details on Hazelcast client, you can check out the following link.

4.4. Access Distributed Map From Java Client

Next, we will access the distributed Map that we created earlier. We need the instance of HazelcastInstance created earlier to access the distributed Map.

IMap<Long, String> map = hzClient.getMap("data");
...

Now we can do operations on a map without being a member of the cluster. For example, let’s try to iterate over the map entries added by the cluster member:

for (Entry<Long, String> entry : map.entrySet()) {
    ...
}

5. Configuring Hazelcast

In this section will focus on how to configure the Hazelcast network using declaratively (XML) and programmatically (API) and use Hazelcast management center to monitor and manage nodes that are running.

While Hazelcast is starting up, it looks for hazelcast.config system property. If it is set, its value is used as the path. If the above system property is not set, Hazelcast then checks whether there is a hazelcast.xml file in the working directory. If not, then it checks whether

If not, then it checks whether hazelcast.xml exists on the classpath. If none of the above works, Hazelcast loads the default configuration, i.e.

If none of the above works, Hazelcast loads the default configuration, i.e. hazelcast-default.xml that comes with hazelcast.jar.

5.1. Network Configuration

By default, Hazelcast uses multicast for discovering other members that can form a cluster. If multicast is not a preferred way of discovery for our environment, then we can configure Hazelcast for full TCP/IP cluster.

Let’s configure the TCP/IP cluster using declarative configuration:

<?xml version="1.0" encoding="UTF-8"?>
<hazelcast xsi:schemaLocation=
  "http://www.hazelcast.com/schema/config hazelcast-config-3.7.xsd"
  xmlns="http://www.hazelcast.com/schema/config"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <network>
        <port auto-increment="true" port-count="20">5701</port>
        <join>
            <multicast enabled="false">
	    </multicast>
	    <tcp-ip enabled="true">
	        <member>machine1</member>
		<member>localhost</member>
	    </tcp-ip>
        </join>
    </network>
</hazelcast>

and programmatic configuration:

Config config = new Config();
NetworkConfig network = config.getNetworkConfig();
network.setPort(5701).setPortCount(20);
network.setPortAutoIncrement(true);
JoinConfig join = network.getJoin();
join.getMulticastConfig().setEnabled(false);
join.getTcpIpConfig()
  .addMember("machine1")
  .addMember("localhost").setEnabled(true);

By default, Hazelcast will try 100 ports to bind. In the example above, if we set the value of port as 5701 and limit the port count to 20, as members are joining to the cluster, Hazelcast tries to find ports between 5701 and 5721.

If we want to choose to use only one port, we can disable the auto-increment feature of a port by setting auto-increment to false.

5.2. Management Center Configuration

Management center allows us to monitor overall state of clusters, we can also analyze and browse your data structures in detail, update map configurations and take thread dump from nodes.

In order to user Hazelcast management center, we can either deploy the mancenter-version.war application into our Java application server/container or we can start Hazelcast Management Center from the command line. We can download the latest Hazelcast ZIP from hazelcast.org. The ZIP contains the mancenter-version.war file.

We can configure our Hazelcast nodes by adding the URL of the web application to hazelcast.xml and then have the Hazelcast members communicate with the management center.

Let’s configure the management center using declarative configuration:

<management-center enabled="true">
    http://localhost:8080/mancenter
</management-center>

and programmatic configuration:

ManagementCenterConfig manCenterCfg = new ManagementCenterConfig();
manCenterCfg.setEnabled(true).setUrl("http://localhost:8080/mancenter");

6. Conclusion

In this article, we covered introductory concepts about Hazelcast. For details, you can take a look at the Reference Manual.

You can find the source code for this article over on GitHub.