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:
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.
// 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:
-
Form a cluster not just on your local machine: see Setting Up Clusters.
-
Start using our distributed data structures: see Distributed Data Structures.
-
Learn how to configure Hazelcast IMDG: see Understanding Configuration.
You can always reach out via Slack, Mail Group or StackOverflow.