Getting Started with Hazelcast using Spring Boot

See something wrong? Edit this page.

This guide will get you started to use Hazelcast in a Spring Boot application.

You can see the whole project here.

What You’ll Learn

In this guide, you will learn how to use Hazelcast IMDG within Spring Boot microservices.

The Spring Boot application contains two REST controllers which helps you to put data and read it back. The application initializes a single Hazelcast IMDG member instance which is used to keep the data. When you run the application multiple times, Hazelcast IMDG instances build a cluster and share the data.

Prerequisites

  • ~15 minutes

  • A text editor or IDE

  • JDK 1.8+

  • Apache Maven 3.2+

The Spring Boot Application Structure

The application is a basic Spring Boot app having 2 endpoints defined in CommandController:

  • /put is the page where key and values can be put on a Hazelcast distributed map. It takes key and value as query parameters and returns the entry in JSON format.

  • /get is the page where the values in the Hazelcast distributed map can be obtained by keys. It takes key as query parameter and returns the found entry in JSON format.

Using Hazelcast in the Application

If Hazelcast is on the classpath and a suitable configuration is found, Spring Boot auto-configures a HazelcastInstance that you can inject into your application. In the pom.xml file, you can see Hazelcast is added as a dependency:

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast-all</artifactId>
</dependency>

Hazelcast configuration (hazelcast.yaml) is placed under src/main/resources/ folder. We only need to auto-wire HazelcastInstance bean in CommandController and use it to access to Hazelcast data structures:

package guides.hazelcast.springboot;

import com.hazelcast.core.HazelcastInstance;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.concurrent.ConcurrentMap;

@RestController
public class CommandController {
    @Autowired
    private HazelcastInstance hazelcastInstance;

    private ConcurrentMap<String,String> retrieveMap() {
        return hazelcastInstance.getMap("map");
    }

    @PostMapping("/put")
    public CommandResponse put(@RequestParam(value = "key") String key, @RequestParam(value = "value") String value) {
        retrieveMap().put(key, value);
        return new CommandResponse(value);
    }

    @GetMapping("/get")
    public CommandResponse get(@RequestParam(value = "key") String key) {
        String value = retrieveMap().get(key);
        return new CommandResponse(value);
    }
}

Running the Sample Application

Run the application using Maven on a terminal:

mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dserver.port=8080"

Then rerun the application on another terminal. Note that you need to set a different value for the server.port.

mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dserver.port=8081"

After both application instances are initialized, you should see the Hazelcast cluster formation in the output similar to below:

Members {size:2, ver:2} [
	Member [192.168.1.64]:5701 - 520aec3f-58a6-4fcb-a3c7-498dcf37d8ff
	Member [192.168.1.64]:5702 - 5c03e467-d457-4847-b49a-745a335db557 this
]

Now, you can issue HTTP requests to put and get data back. Run the following command to put the data into Hazelcast distributed map:

curl --data "key=key1&value=hazelcast" "localhost:8080/put"

You will see the value in the output. Then run the command below to get the data back. Please note that the call is made to the other application instance:

curl "localhost:8081/get?key=key1"

Again, you will see the value in the output since the data is distributed among Hazelcast cluster instances and can be accessed from any of them.

Testing the Application

To run the integration tests, run the following command in terminal. But before, make sure to kill the running application instances.

mvn verify -Ptests

If the tests pass, you’ll see a similar output to the following:

[INFO] Results:
[INFO]
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

Summary

In this guide, we developed a simple Spring Boot application that stores the data in a Hazelcast instance. We started two application instances, and they formed a Hazelcast cluster. We pushed data to an application instance, and since the data was shared among Hazelcast cluster instances, we could access it from both application instances.

See Also