Get Started with Hazelcast using Spring Boot

What You’ll Learn

This tutorial will get you started with Hazelcast in a Spring Boot application.

Before you Begin

A text editor or IDE
JDK 17+
Apache Maven 3.8+

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.

Use 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-spring</artifactId>
    <version>${hazelcast.version}</version>
</dependency>

Hazelcast configuration (hazelcast.yaml) is placed in the src/main/resources/ directory. You only need to define map bean, if you want to autowire the IMap instance:

@Bean
public IMap<String, String> map(HazelcastInstance instance) {
    return instance.getMap("map");
}

Bean will have name "map" and can be autowired by IMap type (if it’s the only IMap added as bean).

Now you can autowire the IMap bean in the CommandController and use it to access the Hazelcast structure:

package guides.hazelcast.springboot;

import com.hazelcast.map.IMap;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
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;

@RestController
public class CommandController {
    @Autowired @Qualifier("map")
    private IMap<String, String> map;

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

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

Please notice, that we’ve used @Qualifier("map") - it’s strictly speaking optional, but once you add more IMaps, you will need to distinguish which map you want to autowire.

Run the Sample Application

Run the application using Maven in a terminal:

mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dserver.port=8080 -Djava.net.preferIPv4Stack=true"

Then, rerun the application in another terminal.

Notice the different value for the server.port argument.

We’ve used -Djava.net.preferIPv4Stack=true, because on some platforms there are problems with multicast on IPv6. Adding this option ensures smooth run when learning.

mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dserver.port=8081 -Djava.net.preferIPv4Stack=true"

After both application instances are initialized, you should see that the Hazelcast cluster is formed:

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 a 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 ({"value":"hazelcast"}), because the data is distributed among Hazelcast cluster instances and can be accessed from any of them.

Test 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

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, you developed a simple Spring Boot application that stores the data in a Hazelcast member. You started two application instances, and they formed a Hazelcast cluster. You pushed data to an application instance, and since the data was shared among Hazelcast cluster members, you could access it from both application instances.

Send us your feedback