Configure Hazelcast in Spring
This section describes how to set up Hazelcast in a new or existing Spring application.
Enable Spring integration
These instructions assume you are using Apache Maven. If you use another build system, you will need to adjust the definition of dependencies as required.
To enable Spring integration:
-
Add
hazelcast-spring-6.0.0-SNAPSHOT.jar
to your Java classpath. -
Add the following lines to your
pom.xml
file:<dependency> <groupId>com.hazelcast</groupId> <artifactId>hazelcast-spring</artifactId> <version>6.0.0-SNAPSHOT</version> </dependency>
-
If you are an Enterprise customer and you want to use
hazelcast-spring
withhazelcast-enterprise
, you also need to exclude the transitivehazelcast
dependency:<dependency> <groupId>com.hazelcast</groupId> <artifactId>hazelcast-enterprise</artifactId> <version>6.0.0-SNAPSHOT</version> </dependency> <dependency> <groupId>com.hazelcast</groupId> <artifactId>hazelcast-spring</artifactId> <version>6.0.0-SNAPSHOT</version> <exclusions> <exclusion> <groupId>com.hazelcast</groupId> <artifactId>hazelcast</artifactId> </exclusion> </exclusions> </dependency>
Troubleshooting
When the Spring integration JARs are not correctly installed in the Java classpath, you may see one of the following exceptions:
org.xml.sax.SAXParseException; systemId: http://hazelcast.com/schema/spring/hazelcast-spring.xsd; lineNumber: 2; columnNumber: 35; s4s-elt-character: Non-whitespace characters are not allowed in schema elements other than 'xs:appinfo' and 'xs:documentation'. Saw '301 Moved Permanently'.
org.springframework.beans.factory.parsing.BeanDefinitionParsingException: Configuration problem: Unable to locate Spring NamespaceHandler for XML schema namespace [http://www.hazelcast.com/schema/spring]
org.xml.sax.SAXParseException; lineNumber: 25; columnNumber: 33; schema_reference.4: Failed to read schema document 'http://www.hazelcast.com/schema/spring/hazelcast-spring.xsd', because 1) could not find the document; 2) the document could not be read; 3) the root element of the document is not <xsd:schema>.
If you see one of these exceptions, check that the required classes are in the classpath.
Declare beans using Java configuration
Spring recommend using Java-based configuration. The following example provides basic configuration for using Hazelcast in a Spring application:
import javax.management.MXBean;@Configuration(proxyBeanMethods = false)
public class SpringHazelcastConfiguration {
@Bean
public HazelcastInstance hazelcastInstance() { // (1)
Config config = new Config();
config.setClusterName("spring-hazelcast-cluster-from-java");
NetworkConfig networkConfig = config.getNetworkConfig();
networkConfig.getInterfaces().addInterface("127.0.0.1");
config.addMapConfig(new MapConfig("testMap").setBackupCount(2));
config.addMapConfig(new MapConfig("otherTestMap"));
return Hazelcast.newHazelcastInstance(config);
}
@Bean
public IMap<String, String> testMap(HazelcastInstance instance) { // (2)
return instance.getMap("testMap");
}
@Bean
public IMap<String, String> otherTestMap(HazelcastInstance instance) {
return instance.getMap("otherTestMap");
}
}
(1) The HazelcastInstance
bean declaration is a standard way of declaring beans in Spring. It uses a plain old Java method.
(2) Declaration of bean for testMap
IMap, so that you will be able to inject IMap directly into a field.
You can then use Spring’s @Autowired
dependency injection annotation to automatically configure objects such as HazelcastInstance
and IMap
. For example:
/// (...)
@SpringBootApplication
public class SpringApplication {
@Autowired
private HazelcastInstance instance;
@Autowired
@Qualifier(value = "testMap") // Qualifier is needed because we configured two IMaps, so there are two beans with the same type
private IMap<String, String> testMap;
As @SpringBootApplication
is also a @Configuration
class, you could instead move the hazelcastInstance
bean declaration to SpringApplication
and remove SpringHazelcastConfiguration
. However, splitting configuration and usage provides more flexibility. For example, you can use application context creation directly from Java with AnnotationConfigApplicationContext
.
Declare beans using XML configuration
While Java-based configuration is now widely used and recommended, you may prefer to use XML-based configuration. You can easily configure Hazelcast using a dedicated hazelcast
XML namespace or the common Spring beans
XML namespace.
Declare beans using the beans namespace
The following example declares a Hazelcast cluster and IMap using the default Spring beans
namespace:
<bean id="instance" class="com.hazelcast.core.Hazelcast" factory-method="newHazelcastInstance">
<constructor-arg>
<bean class="com.hazelcast.config.Config">
<property name="clusterName" value="dev"/>
<!-- ... -->
</bean>
</constructor-arg>
</bean>
<bean id="map" factory-bean="instance" factory-method="getMap">
<constructor-arg value="map"/>
</bean>
Declare beans using the Hazelcast namespace
Hazelcast has its own namespace hazelcast
for bean definitions. You can add the namespace declaration xmlns:hz="http://www.hazelcast.com/schema/spring"
to the beans
element in the context file so that the hz
namespace shortcut can be used as a bean declaration.
Here is an example schema definition:
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:hz="http://www.hazelcast.com/schema/spring"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-5.5.xsd
http://www.hazelcast.com/schema/spring
http://www.hazelcast.com/schema/spring/hazelcast-spring.xsd">
The following example declares a Hazelcast instance with two cluster members using the hazelcast
namespace:
<hz:hazelcast id="instance">
<hz:config>
<hz:cluster-name name="dev"/>
<hz:network port="5701" port-auto-increment="false">
<hz:join>
<hz:multicast enabled="false"/>
<hz:tcp-ip enabled="true">
<hz:members>10.10.1.2, 10.10.1.3</hz:members>
</hz:tcp-ip>
</hz:join>
</hz:network>
</hz:config>
</hz:hazelcast>
Spring property placeholders
You can also pass values using Spring property placeholders. The following example declares a Hazelcast instance and sets a cluster name and Kubernetes service name:
<hz:hazelcast id="instance">
<hz:config>
<hz:cluster-name>${my.cluster.name}</hz:cluster-name>
<!-- ... -->
<hz:network>
<hz:join>
<hz:kubernetes service-name="${my.kubernetes.service.name}" />
</hz:join>
</hz:network>
</hz:config>
</hz:hazelcast>
Supported configuration in the Hazelcast namespace
The hazelcast
XML namespace supports the following configuration:
-
Configure a Hazelcast instance
<hz:hazelcast id="instance"> <hz:config> <hz:cluster-name name="dev"/> <hz:network port="5701" port-auto-increment="false"> <hz:join> <hz:multicast enabled="false" multicast-group="224.2.2.3" multicast-port="54327"/> <hz:tcp-ip enabled="true"> <hz:members>10.10.1.2, 10.10.1.3</hz:members> </hz:tcp-ip> </hz:join> </hz:network> <hz:map name="map" backup-count="2" read-backup-data="true" merge-policy="com.hazelcast.spi.merge.PassThroughMergePolicy"> <hz:eviction eviction-policy="NONE" size="0"/> </hz:map> </hz:config> </hz:hazelcast>
-
Configure a Hazelcast client
<hz:client id="client"> <hz:cluster-name name="${cluster.name}"/> <hz:network connection-timeout="1000" redo-operation="true"> <hz:cluster-routing mode="ALL_MEMBERS"/> <hz:member>10.10.1.2:5701</hz:member> <hz:member>10.10.1.3:5701</hz:member> </hz:network> </hz:client>
If you connect to a cluster in a Spring Boot application via the Hazelcast client with security enabled, and you want to see the health of that cluster, you must enable permissions for transactions. For further information, see the following topics:
-
Configure MapStore and NearCache
For
map-store
, you should set either theclass-name
or theimplementation
attribute.<hz:config id="config"> <hz:map name="map1"> <hz:map-store enabled="true" class-name="com.foo.DummyStore" write-delay-seconds="0" /> <hz:near-cache time-to-live-seconds="0" max-idle-seconds="60" invalidate-on-change="true" > <hz:eviction eviction-policy="LRU" size="5000"/> </hz:near-cache> </hz:map> <hz:map name="map2"> <hz:map-store enabled="true" implementation="dummyMapStore" write-delay-seconds="0" /> </hz:map> </hz:config> <bean id="dummyMapStore" class="com.foo.DummyStore" />
Supported data structures
The following table lists all of the Hazelcast data structures you can use in your Spring application.
Data structure | Example Java configuration | Example XML configuration |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- (needs manual bean addition) |
|
|
- (needs manual bean addition) |
|
|
|
|
|
- (needs manual bean addition) |
|
|
|
|
|
|
|
|
+ [source,java,opts=novalidate] ----- config.addDataConnectionConfig(new DataConnectionConfig() .setName("my-jdbc-data-connection") .setType("Jdbc") .setProperties(getProperties())); ----- + |
|
|
|
|
|
|
|
|
|
|
Supported Spring bean attributes
Hazelcast supports the lazy-init
, scope
and depends-on
bean attributes.
<hz:hazelcast id="instance" lazy-init="true" scope="singleton">
...
</hz:hazelcast>
<hz:client id="client" scope="prototype" depends-on="instance">
...
</hz:client>
Next steps
Once you’ve set up Hazelcast in your Spring application, you can refer to the following sections to configure Hazelcast for common use cases:
For more configuration examples, review our Spring sample application.