Hazelcast IMDG Standard Support has expired. Extended support for version 4.1 ends in April 2024. Extended support for version 4.2 ends in September 2024.

We recommend that you try Hazelcast Platform.

In Hazelcast Platform, we’ve combined the in-memory storage of IMDG with the stream processing power of Jet. Find out more in our Platform documentation.

The following topics are a good place to start:

Quickstart

This chapter intends to get you started in 5 minutes. The quick start shows how to start Hazelcast members, form a cluster, connect it with a client application in your preferred language and monitor the cluster using Hazelcast Management Center.

For a comprehensive overview of what Hazelcast IMDG actually is see What is Hazelcast IMDG?.

Installing

You can use the Hazelcast Command Line Interface (CLI) to install and start Hazelcast IMDG.

Run the following commands to install Hazelcast CLI:

  • Homebrew

  • Debian

  • RPM

brew tap hazelcast/hz
brew install hazelcast
wget -qO - https://repository.hazelcast.com/api/gpg/key/public | sudo apt-key add -
echo "deb https://repository.hazelcast.com/debian stable main" | sudo tee -a /etc/apt/sources.list
sudo apt update && sudo apt install hazelcast
wget https://repository.hazelcast.com/rpm/hazelcast-rpm.repo -O hazelcast-rpm.repo
sudo mv hazelcast-rpm.repo /etc/yum.repos.d/
sudo yum install hazelcast

After the installation of Hazelcast CLI, the package managers will display the installation directory and usage information.

Creating a Cluster

Use the following command on your terminal/command line to start a standalone Hazelcast member:

hz start

Now you have a 1-member cluster. To add one more member to the cluster, open another terminal/command line and rerun the above command. The members discover each other automatically and form a 2-member cluster. You should see happening it with log output in the command line like:

Members {size:2, ver:2} [
    Member [127.0.0.1]:5701 - e40081de-056a-4ae5-8ffe-632caf8a6cf1 this
    Member [127.0.0.1]:5702 - 93e82109-16bf-4b16-9c87-f4a6d0873080
]

Note that these members are started with the default configuration. The location of the hazelcast.xml is printed on the first line of the output of the above command.

Your First Client Application

Having a running cluster as started in the above section, let’s create a client application that connects to this cluster, creates a map and populates it. Below, we first briefly give how to install a client of your preference and then an example code for each. We are assuming that the members and clients are on the same machine for simplicity.

  • Java

  • C++

  • C Sharp

  • Node.js

  • Python

  • Go

// Installation notes: You have to have Hazelcast Java Client on the classpath.
// The simplest way of doing it is to put `hazelcast-all` JAR
// on the classpath, e.g. via Maven. See "Installation" chapter for details.

import com.hazelcast.client.HazelcastClient;
import com.hazelcast.core.HazelcastInstance;
import com.hazelcast.map.IMap;

public class MapSample {
    public static void main(String[] args) {
        // Start the client and connect to the cluster
        HazelcastInstance hz = HazelcastClient.newHazelcastClient();
        // Create a Distributed Map in the cluster
        IMap map = hz.getMap("my-distributed-map");
        //Standard Put and Get
        map.put("1", "John");
        map.put("2", "Mary");
        map.put("3", "Jane");
        // Shutdown the client
        hz.shutdown();
    }
}
//Installation notes: Download the latest C++ library from
//https://hazelcast.org/imdg/clients-languages/cplusplus/
//and see https://github.com/hazelcast/hazelcast-cpp-client for installation instructions.

#include <hazelcast/client/hazelcast_client.h>

using namespace hazelcast::client;
int main() {
    // Start the client and connect to the cluster
    hazelcast_client hz;
    // Create a Distributed Map in the cluster
    auto map = hz.get_map("my-distributed-map").get();
    //Standard put and get
    map->put<std::string, std::string>("1", "John").get();
    map->put<std::string, std::string>("2", "Mary").get();
    map->put<std::string, std::string>("3", "Jane").get();
    // Shutdown the client. Disconnects from cluster and releases the resources.
    hz.shutdown();

    return 0;
}
//Installation notes: Run the following command at the NuGet package manager console
//Install-Package Hazelcast.Net -Pre

using Hazelcast.Client;

namespace Hazelcast.Examples.Org.Website.Samples
{
    public class MapSample
    {
        public static void Run(string[] args)
        {
            // Start the client and connect to the cluster
            var hz = HazelcastClient.NewHazelcastClient();
            // Create a Distributed Map in the cluster
            var map = hz.GetMap("my-distributed-map");
            //Standard Put and Get
            map.put("1", "John");
            map.put("2", "Mary");
            map.put("3", "Jane");
            // Shutdown the client
            hz.Shutdown();
        }
    }
}
// Installation notes: Run the following command
// npm install hazelcast-client

const { Client } = require('hazelcast-client');

(async () => {
    try {
        // Start the client and connect to the cluster
        const hz = await Client.newHazelcastClient();
        // Create a Distributed Map in the cluster
        const map = await hz.getMap('my-distributed-map');
        // Standard Put and Get
        await map.put('1', 'John');
        await map.put('2', 'Mary');
        await map.put('3', 'Jane');
        // Shutdown the client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
# Installation notes: Run the following command
# pip install hazelcast-python-client

import hazelcast

if __name__ == "__main__":
    # Start the client and connect to the cluster
    hz = hazelcast.HazelcastClient()
    # Create a Distributed Map in the cluster
    map = hz.get_map("my-distributed-map").blocking()
    # Standard Put and Get
    map.put("1", "John")
    map.put("2", "Mary")
    map.put("3", "Jane")
    # Shutdown the client
    hz.shutdown()
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/hazelcast/hazelcast-go-client"
)

// Installation note: Run following command
// go get github.com/hazelcast/hazelcast-go-client

func main() {
    ctx := context.TODO()

    hz, err := hazelcast.StartNewClient(ctx)
    if err != nil {
        panic(fmt.Errorf("starting the client: %w", err))
    }

    defer hz.Shutdown(ctx)

    mp, err := hz.GetMap(ctx, "my-distributed-map")
    if err != nil {
        panic(fmt.Errorf("trying to get a map: %w", err))
    }

    _, err = mp.Put(ctx, 1, "John")
    if err != nil {
        panic(fmt.Errorf("trying to put to map: %w", err))
    }

    _, err = mp.Put(ctx, 2, "Mary")
    if err != nil {
        panic(fmt.Errorf("trying to put to map: %w", err))
    }

    _, err = mp.Put(ctx, 3, "Jane")
    if err != nil {
        panic(fmt.Errorf("trying to put to map: %w", err))
    }
}

For comprehensive information on the clients, see the following sections:

Connecting Management Center to the Cluster

Hazelcast Management Center helps you to monitor and manage your IMDG cluster. After you created your cluster and client application as depicted in the above sections, let’s connect Management Center to the cluster. Note that having client applications is not a must to use the Management Center; you can connect it to your cluster that does not have any clients.

Use the following command to start the Management Center:

hz mc start

Then, open your preferred web browser to http://localhost:8080 and select the default security provider to provide a username and password. Log in to Management Center using those credentials and create a cluster connection; the defaults should work fine. If using Docker for members, find out the Docker IP address of cluster rather than the default of localhost.

For comprehensive information on Management Center, see its documentation.

What’s Next?

In this chapter, you have learnt starting a Hazelcast IMDG cluster, inserting data to it via clients and monitoring it through Management Center. Now, you may want to perform the following:

You can always reach out via Slack, Mail Group or StackOverflow.