The Infinispan starter provides a set of managed transitive dependencies that include everything your Spring Boot project needs to seamlessly interact with Infinispan.
The Infinispan Spring Boot starter gives you a convenient way to get started with Spring Boot but is optional. To use Infinispan with Spring Boot you can simply add the dependencies you want. |
1. Setting Up Your Project
Add dependencies for the Infinispan Spring Boot Starter to your project.
1.1. Enforcing Infinispan Versions
This starter uses a high-level API to ensure compatibility between major versions of Infinispan.
However you can enforce a specific version of Infinispan with the infinispan-bom
module.
-
Add
infinispan-bom
to yourpom.xml
file before the starter dependencies.<properties> <version.infinispan>12.1.0.Final</version.infinispan> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-bom</artifactId> <version>${version.infinispan}</version> <type>pom</type> <scope>import</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>${version.spring.boot}</version> <type>pom</type> <scope>import</scope> </dependency> <dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-spring-boot-starter</artifactId> </dependency> </dependencies> </dependencyManagement>
1.2. Adding Dependencies for Usage Modes
Infinispan provides different dependencies for embedded caches and remote caches.
-
Add one of the following to your
pom.xml
file:
<dependency>
<groupId>org.infinispan</groupId>
<artifactId>infinispan-spring-boot-starter-embedded</artifactId>
</dependency>
<dependency>
<groupId>org.infinispan</groupId>
<artifactId>infinispan-spring-boot-starter-remote</artifactId>
</dependency>
2. Running in Embedded Mode
Embed Infinispan caches directly in your project for in-memory data storage.
2.1. Adding the EmbeddedCacheManager Bean
The Infinispan starter operates in Remote Client/Server mode with infinispan-spring-boot-starter-remote
on the classpath by default.
To use embedded caches, you need to add the EmbeddedCacheManager
bean.
-
Add
infinispan-spring-boot-starter-embedded
to your project’s classpath to enable Embedded mode. -
Use the Spring
@Autowired
annotation to include anEmbeddedCacheManager
bean in your Java configuration classes, as in the following example:private final EmbeddedCacheManager cacheManager; @Autowired public YourClassName(EmbeddedCacheManager cacheManager) { this.cacheManager = cacheManager; }
You are now ready to use Infinispan in Embedded Mode, as in the following example:
cacheManager.getCache("testCache").put("testKey", "testValue");
System.out.println("Received value from cache: " + cacheManager.getCache("testCache").get("testKey"));
2.2. Cache Manager Configuration Beans
You can customize the cache manager with the following configuration beans:
-
InfinispanGlobalConfigurer
-
InfinispanCacheConfigurer
-
Configuration
-
InfinispanConfigurationCustomizer
-
InfinispanGlobalConfigurationCustomizer
You can create one |
@Bean
public InfinispanCacheConfigurer cacheConfigurer() {
return manager -> {
final Configuration ispnConfig = new ConfigurationBuilder()
.clustering()
.cacheMode(CacheMode.LOCAL)
.build();
manager.defineConfiguration("local-sync-config", ispnConfig);
};
}
Link the bean name to the cache that it configures, as follows:
@Bean(name = "small-cache")
public org.infinispan.configuration.cache.Configuration smallCache() {
return new ConfigurationBuilder()
.read(baseCache)
.memory().size(1000L)
.memory().evictionType(EvictionType.COUNT)
.build();
}
@Bean(name = "large-cache")
public org.infinispan.configuration.cache.Configuration largeCache() {
return new ConfigurationBuilder()
.read(baseCache)
.memory().size(2000L)
.build();
}
@Bean
public InfinispanGlobalConfigurationCustomizer globalCustomizer() {
return builder -> builder.transport().clusterName(CLUSTER_NAME);
}
@Bean
public InfinispanConfigurationCustomizer configurationCustomizer() {
return builder -> builder.memory().evictionType(EvictionType.COUNT);
}
2.3. Enabling Spring Cache Support
With both embedded and remote caches, Infinispan provides an implementation of Spring Cache that you can enable.
-
Add the
@EnableCaching
annotation to your application.
If the Infinispan starter detects the:
-
EmbeddedCacheManager
bean, it instantiates a newSpringEmbeddedCacheManager
. -
RemoteCacheManager
bean, it instantiates a newSpringRemoteCacheManager
.
3. Running in Client/Server Mode
Store and retrieve data from remote Infinispan clusters using Hot Rod, a custom TCP binary wire protocol.
3.1. Setting Up the RemoteCacheManager
-
Provide the location for the Infinispan server so the starter can create the
RemoteCacheManager
bean. -
Use the Spring
@Autowired
annotation to include your own custom cache manager class in your application:private final RemoteCacheManager cacheManager; @Autowired public YourClassName(RemoteCacheManager cacheManager) { this.cacheManager = cacheManager; }
3.1.1. Properties files
You can specify properties in either hotrod-client.properties
or application.properties
.
The starter first tries to find the server location in hotrod-client.properties
and then from application.properties
.
Specify client configuration in hotrod-client.properties
on your classpath,
for example:
# List Infinispan servers by IP address or hostname at port 11222.
infinispan.client.hotrod.server_list=127.0.0.1:6667
These properties take the format of infinispan.client.*
.
For more information, see org.infinispan.client.hotrod.configuration.
Configure your project with application.properties
files that contain properties in the format of infinispan.remote.*
.
See Application Properties for more information.
3.2. Configuring Marshalling
Configure Infinispan to marshall Java objects into binary format so they can be transferred over the wire or stored to disk.
By default Infinispan uses a Java Serialization marshaller, which requires you to add your classes to an allow list. As an alternative you can use ProtoStream.
-
Open
hotrod-client.properties
orapplication.properties
for editing. -
Do one of the following:
-
Use ProtoStream as the marshaller.
infinispan.client.hotrod.marshaller=org.infinispan.commons.marshall.ProtoStreamMarshaller
infinispan.remote.marshaller=org.infinispan.commons.marshall.ProtoStreamMarshaller
-
Add your classes to the serialization allow list if you use Java Serialization. You can specify a comma-separated list of fully qualified class names or a regular expression to match classes.
infinispan.client.hotrod.java_serial_allowlist=your_marshalled_beans_package.*
infinispan.remote.java-serial-allowlist=your_marshalled_beans_package.*
-
-
Save and close your properties file.
3.3. Cache Manager Configuration Beans
Customize the cache manager with the following configuration beans:
-
InfinispanRemoteConfigurer
-
Configuration
-
InfinispanRemoteCacheCustomizer
You can create one |
@Bean
public InfinispanRemoteConfigurer infinispanRemoteConfigurer() {
return () -> new ConfigurationBuilder()
.addServer()
.host("127.0.0.1")
.port(12345)
.build();
}
@Bean
public org.infinispan.client.hotrod.configuration.Configuration customConfiguration() {
new ConfigurationBuilder()
.addServer()
.host("127.0.0.1")
.port(12345)
.build();
}
@Bean
public InfinispanRemoteCacheCustomizer customizer() {
return b -> b.tcpKeepAlive(false);
}
Use the |
3.4. Enabling Spring Cache Support
With both embedded and remote caches, Infinispan provides an implementation of Spring Cache that you can enable.
-
Add the
@EnableCaching
annotation to your application.
If the Infinispan starter detects the:
-
EmbeddedCacheManager
bean, it instantiates a newSpringEmbeddedCacheManager
. -
RemoteCacheManager
bean, it instantiates a newSpringRemoteCacheManager
.
3.5. Exposing Infinispan Statistics
Infinispan supports the Spring Boot Actuator to expose cache statistics as metrics.
-
Add the following to your
pom.xml
file:<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> <version>${version.spring.boot}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${version.spring.boot}</version> </dependency>
-
Activate statistics for the appropriate cache instances, either programmatically or declaratively.
Programmatically@Bean public InfinispanCacheConfigurer cacheConfigurer() { return cacheManager -> { final org.infinispan.configuration.cache.Configuration config = new ConfigurationBuilder() .jmxStatistics().enable() .build(); cacheManager.defineConfiguration("my-cache", config); }; }
Declaratively<local-cache name="mycache" statistics="true"/>
The Spring Boot Actuator registry binds cache instances when your application starts.
If you create caches dynamically, you should use the CacheMetricsRegistrar
bean to bind caches to the Actuator registry, as follows:
@Autowire
CacheMetricsRegistrar cacheMetricsRegistrar;
@Autowire
CacheManager cacheManager;
...
cacheMetricsRegistrar.bindCacheToRegistry(cacheManager.getCache("my-cache"));
4. Using Spring Session
4.1. Enabling Spring Session Support
Infinispan Spring Session support is built on SpringRemoteCacheManager
and
SpringEmbeddedCacheManager
.
The Infinispan starter produces those beans by default.
-
Add this starter to your project.
-
Add Spring Session to the classpath.
-
Add the following annotations to your configuration:
-
@EnableCaching
-
@EnableInfinispanRemoteHttpSession
-
@EnableInfinispanEmbeddedHttpSession
-
Infinispan does not provide a default cache. To use Spring Session, you must first create a Infinispan cache. |
5. Application Properties
Configure your project with application.properties
or application.yaml
.
# List Infinispan or Data Grid servers by IP address or hostname at port 11222.
infinispan.remote.server-list=127.0.0.1:11222
#
# Embedded Properties - Uncomment properties to use them.
#
# Enables embedded capabilities in your application.
# Values are true (default) or false.
#infinispan.embedded.enabled =
# Sets the Spring state machine ID.
#infinispan.embedded.machineId =
# Sets the name of the embedded cluster.
#infinispan.embedded.clusterName =
# Specifies a XML configuration file that takes priority over the global
# configuration bean or any configuration customizer.
#infinispan.embedded.configXml =
#
# Server Properties - Uncomment properties to use them.
#
# Specifies a custom filename for Hot Rod client properties.
#infinispan.remote.clientProperties =
# Enables remote server connections.
# Values are true (default) or false.
#infinispan.remote.enabled =
# Defines a comma-separated list of servers in this format:
# `host1[:port],host2[:port]`.
#infinispan.remote.serverList =
# Sets a timeout value, in milliseconds, for socket connections.
#infinispan.remote.socketTimeout =
# Sets a timeout value for initializing connections with servers.
#infinispan.remote.connectTimeout =
# Sets the maximum number of attempts to connect to servers.
#infinispan.remote.maxRetries =
# Specifies the marshaller to use.
#infinispan.remote.marshaller =
# Adds your classes to the serialization allow list.
#infinispan.remote.java-serial-allowlist=