Introduction

Hazelcast integrates well with Spring because a Hazelcast member or client can be exposed as a normal Spring bean and injected wherever distributed data structures are needed. The important configuration choice is whether your application should start an embedded Hazelcast member or connect as a client to an existing cluster.

Core Sections

Embedded member versus client mode

There are two common deployment models.

In embedded mode, the application starts a Hazelcast member inside the Spring process. This is simple for small clusters or apps that want each instance to participate directly in the data grid.

In client mode, the Spring application connects to a separate Hazelcast cluster. This is common when the cache or distributed data grid is managed independently from the application tier.

Choosing between those two models changes the configuration style, networking expectations, and operational boundaries.

Java-based embedded configuration

In modern Spring applications, Java configuration is usually clearer than XML. A minimal embedded setup looks like this:

1import com.hazelcast.config.Config;
2import com.hazelcast.config.MapConfig;
3import com.hazelcast.core.Hazelcast;
4import com.hazelcast.core.HazelcastInstance;
5import org.springframework.context.annotation.Bean;
6import org.springframework.context.annotation.Configuration;
7
8@Configuration
9public class HazelcastConfiguration {
10
11    @Bean
12    public HazelcastInstance hazelcastInstance() {
13        Config config = new Config();
14        config.setInstanceName("spring-hazelcast");
15
16        config.getNetworkConfig().setPort(5701).setPortAutoIncrement(true);
17        config.addMapConfig(new MapConfig("users").setTimeToLiveSeconds(3600));
18
19        return Hazelcast.newHazelcastInstance(config);
20    }
21}

Once this bean exists, Spring-managed classes can inject HazelcastInstance and work with distributed structures such as IMap.

1import com.hazelcast.core.HazelcastInstance;
2import com.hazelcast.map.IMap;
3import org.springframework.stereotype.Service;
4
5@Service
6public class UserCacheService {
7    private final HazelcastInstance hazelcastInstance;
8
9    public UserCacheService(HazelcastInstance hazelcastInstance) {
10        this.hazelcastInstance = hazelcastInstance;
11    }
12
13    public void putUser(String id, String name) {
14        IMap<String, String> users = hazelcastInstance.getMap("users");
15        users.put(id, name);
16    }
17}

Client mode when the cluster is external

If the application should not become a cluster member, configure a Hazelcast client instead.

1import com.hazelcast.client.HazelcastClient;
2import com.hazelcast.client.config.ClientConfig;
3import com.hazelcast.core.HazelcastInstance;
4import org.springframework.context.annotation.Bean;
5import org.springframework.context.annotation.Configuration;
6
7@Configuration
8public class HazelcastClientConfiguration {
9
10    @Bean
11    public HazelcastInstance hazelcastClient() {
12        ClientConfig clientConfig = new ClientConfig();
13        clientConfig.setClusterName("demo-cluster");
14        clientConfig.getNetworkConfig().addAddress("127.0.0.1:5701");
15        return HazelcastClient.newHazelcastClient(clientConfig);
16    }
17}

This keeps the application process lighter and makes cluster topology easier to manage independently.

Integrating Hazelcast with Spring Cache

One of the most common Spring uses is wiring Hazelcast into the Spring Cache abstraction.

1import com.hazelcast.core.HazelcastInstance;
2import com.hazelcast.spring.cache.HazelcastCacheManager;
3import org.springframework.cache.CacheManager;
4import org.springframework.cache.annotation.EnableCaching;
5import org.springframework.context.annotation.Bean;
6import org.springframework.context.annotation.Configuration;
7
8@Configuration
9@EnableCaching
10public class CacheConfiguration {
11
12    @Bean
13    public CacheManager cacheManager(HazelcastInstance hazelcastInstance) {
14        return new HazelcastCacheManager(hazelcastInstance);
15    }
16}

After that, application services can use @Cacheable, @CachePut, and @CacheEvict while Hazelcast provides the backing store.

When XML still makes sense

Older Spring applications may still rely on XML bean configuration. Hazelcast supports that style, but most teams working in current Spring Boot codebases prefer Java configuration because it is easier to refactor, test, and keep close to application code.

The key point is not XML versus Java. The key point is that Hazelcast should be configured as one clear bean source, with cluster membership, networking, and map settings visible in one place.

Common Pitfalls

• Starting an embedded Hazelcast member when the application should have been a client can accidentally change cluster topology and resource usage.
• Creating multiple HazelcastInstance beans unintentionally can lead to duplicate members or unexpected memory overhead.
• Leaving default networking settings untouched in multi-node environments can cause confusing discovery or port-binding behavior.
• Treating Hazelcast as a simple local cache and ignoring serialization and cluster boundaries often creates surprises in production.
• Mixing XML and Java configuration without a clear ownership model makes it hard to see which bean definition is actually active.

Summary

• In Spring, Hazelcast is typically exposed as a bean and injected like any other infrastructure dependency.
• The first major decision is embedded member mode versus client mode.
• Java-based configuration is usually the clearest approach in modern Spring codebases.
• Hazelcast integrates naturally with Spring Cache through HazelcastCacheManager.
• Keep cluster configuration centralized so networking, map settings, and deployment intent stay explicit.