Guide to Hazelcast with Java

1. Overview

This is an introductory article on Hazelcast where we’ll see how to create a cluster member, a distributed Map to share 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 the auto-discovery of nodes and intelligent synchronization.

Hazelcast is available in different editions. In this tutorial, we’ll use the open-source edition.

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

3. Maven Dependency

Hazelcast offers many different libraries to deal with various requirements. We can find them under com.hazelcast group in Maven Central.

However, in this article, we’ll only use the core dependency needed to create a standalone Hazelcast cluster member and the Hazelcast Java Client:

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

The current version is available in maven central repository.

4. A First Hazelcast Application

4.1. Create a 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. As a result, Hazelcast will automatically create and add a new member to the cluster.

For example, if we run the ServerNode application again, we’ll 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 a Distributed Map

Next, let’s create a distributed Map. We need the instance of HazelcastInstance created earlier to construct a distributed Map which extends java.util.concurrent.ConcurrentMap interface.

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

Finally, let’s add some entries to the map:

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

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

While this may not be a real-world example, we only used it to demonstrate one of the many operations that we can apply to the distributed map. Later on, we’ll see how to retrieve the entries added by the cluster member from the Hazelcast Java client.

Internally, Hazelcast partitions the map entries and distributes and replicates the entries among the cluster members. For more details on Hazelcast Map, we can check out the following link.

4.3. Create a 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();
config.setClusterName("dev");
HazelcastInstance hazelcastInstanceClient = HazelcastClient.newHazelcastClient(config);

It’s simple as that.

4.4. Access Distributed Map From Java Client

Next, we’ll use the instance of HazelcastInstance created earlier to access the distributed Map:

Map<Long, String> map = hazelcastInstanceClient.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 entries:

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

5. Configuring Hazelcast

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

While Hazelcast is starting up, it looks for a hazelcast.config system property. If it’s set, its value is used as the path. Otherwise, Hazelcast searches for a hazelcast.xml file in the working directory or on the classpath.

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 isn’t a preferred way of discovery for our environment, then we can configure Hazelcast for a full TCP/IP cluster.

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

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

Alternatively, we can use the Java config approach:

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 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 by setting auto-increment to false.

5.2. Management Center Configuration

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

To use the 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.

So let’s now configure the management center using declarative configuration:

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

Likewise, here’s the 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 more details, we can take a look at the Reference Manual.