Infinispan Spring Boot
Clone or download
Latest commit c5e7429 Oct 10, 2018

README.adoc

Infinispan Spring Boot Starter

Getting Started

Infinispan Spring Boot Starter can operate on one of two modes:

  • Embedded (Infinispan operates along with your application)

  • Client/Server (your app connects to a remote Infinispan cluster)

In order to get started, just add our Spring Boot Starter as dependency in your project’s pom file:

Embedded
<dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>infinispan-spring-boot-starter-embedded</artifactId>
    <version>${version.infinispan.starter}</version>
</dependency>
Client/Server
<dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>infinispan-spring-boot-starter-remote</artifactId>
    <version>${version.infinispan.starter}</version>
</dependency>

Each one of the aforementioned dependencies transitively pulls all the necessary dependencies to allow the Spring Boot application to work seamlessly with Infinispan in the specified mode.

Enforcing specific version

The starters use high level API provided by Infinispan. Therefore they should be compatible even within major version changes. If you wish to use different Infinispan version than provided by this starter, provide Infinispan BOM before this starter declaration:

<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>
           <version>${version.infinispan.starter}</version>
       </dependency>
    </dependencies>
 </dependencyManagement>

Using Embedded mode

The starters operate in Client/Server mode by default. Enabling Embedded mode requires adding infinispan-core to the classpath.

Once you add infinispan’s spring-boot-starter as a dependency to your project, a bean of type EmbeddedCacheManager can be autowired into your java configuration classes. Just simply add:

private final EmbeddedCacheManager cacheManager;

@Autowired
public YourClassName(EmbeddedCacheManager cacheManager) {
    this.cacheManager = cacheManager;
}

And that’s it. You can use it now as you wish. For example:

cacheManager.getCache("testCache").put("testKey", "testValue");
System.out.println("Received value from cache: " + cacheManager.getCache("testCache").get("testKey"));

The starter provide additional properties that can be placed in application.properties:

  • infinispan.embedded.enabled - Set it to false to disable Infinispan Embedded support provided by this starter.

  • infinispan.embedded.configXml - Sets path to the Infinispan XML configuration file.

  • infinispan.embedded.machineId - Sets machine id.

  • infinispan.embedded.clusterName - Sets cluster name.

Customization

You can further customize the cache manager by creating beans of types InfinispanCacheConfigurer, Configuration, InfinispanConfigurationCustomizer, InfinispanGlobalConfigurationCustomizer, InfinispanGlobalConfigurer.

You can have multiple beans of type InfinispanCacheConfigurer, Configuration, InfinispanConfigurationCustomizer, and InfinispanGlobalConfigurationCustomizer`but you can only have one bean of type `InfinispanGlobalConfigurer.

InfinispanCacheConfigurer
@Bean
public InfinispanCacheConfigurer cacheConfigurer() {
	return manager -> {
		final Configuration ispnConfig = new ConfigurationBuilder()
                        .clustering()
                        .cacheMode(CacheMode.LOCAL)
                        .build();

		manager.defineConfiguration("local-sync-config", ispnConfig);
	};
}

If Configuration is used, the bean name is used to link the configuration to the cache it refers to:

Configuration
@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();
}
Customizers
@Bean
public InfinispanGlobalConfigurationCustomizer globalCustomizer() {
   return builder -> builder.transport().clusterName(CLUSTER_NAME);
}

@Bean
public InfinispanConfigurationCustomizer configurationCustomizer() {
   return builder -> builder.memory().evictionType(EvictionType.COUNT);
}

Moreover, you can specify the location of the infinispan XML configuration file by setting the property infinispan.embedded.config-xml in application.properties or application.yml.

Example
infinispan.embedded.config-xml=infinispan-conf.xml

Please note, if infinispan.embedded.config-xml is used, the global configuration returned by the bean of type InfinispanGlobalConfigurer and any customizer will not be used.

Spring Cache support

Simply adding @EnableCaching to the application will enable Spring Cache support. This works because once the starter detects EmbeddedCacheManager bean, it will instantiate a new SpringEmbeddedCacheManager which provides an implementation of Spring Cache.

Using Client/Server mode

The Starter will try to locate hotrod-client.properties file placed on the classpath and create a RemoteCacheManager based on it. A sample file may look like the following

infinispan.client.hotrod.server_list=127.0.0.1:6667

If the file is not found, the starters will check infinispan.remote.server-list property from application.properties file:

infinispan.remote.server-list=127.0.0.1:11222

The configuration also uses the following properties:

  • infinispan.remote.enabled - Set it to false to disable Infinispan Client/Server support provided by this starter.

  • infinispan.remote.serverList - Comma separated list of Infinispan endpoints (address and port pairs).

  • infinispan.remote.socketTimeout - Socket timeout for connection.

  • infinispan.remote.connectTimeout - Timeout for initializing connection.

  • infinispan.remote.maxRetries - Maximum number of retries.

It is also possible to use application parameters described in official Infinispan documentation.

After supplying valid server list parameter, just add this code snippet to your app:

private final RemoteCacheManager cacheManager;

@Autowired
public YourClassName(RemoteCacheManager cacheManager) {
    this.cacheManager = cacheManager;
}

Customization

The default filename for Hot Rod client can be altered using the following property: infinispan.remote.client-properties.

It is also possible to create a custom configuration using either a bean of type InfinispanRemoteConfigurer or of type Configuration :

InfinispanRemoteConfigurer
@Bean
public InfinispanRemoteConfigurer infinispanRemoteConfigurer() {
    return () -> new ConfigurationBuilder()
        .addServer()
        .host("127.0.0.1")
        .port(12345)
        .build();
}
Configuration
@Bean
public org.infinispan.client.hotrod.configuration.Configuration customConfiguration() {
    new ConfigurationBuilder()
        .addServer()
        .host("127.0.0.1")
        .port(12345)
        .build();
}

In addition you can add a number of InfinispanRemoteCacheCustomizer instances to further tuning the configuration.

Tip
to apply the custmoizers according to as pecifi order, you can use the @Ordered annotation.
Example
@Bean
public InfinispanRemoteCacheCustomizer customizer() {
    return b -> b.tcpKeepAlive(false);
}

Spring Cache support

Simply adding @EnableCaching to the application will enable Spring Cache support. This works because once the starter detects RemoteCacheManager bean, it will instantiate a new SpringRemoteCacheManager which provides an implementation of Spring Cache.

Spring Session support

Infinispan Spring Session support is built on SpringRemoteCacheManager and SpringEmbeddedCacheManager. Those beans are produced by this starter by default. In order to use Spring Session in your project you will need to:

  • Add this starter to your project.

  • Add Spring Session to the classpath.

  • Add @EnableCaching and @EnableInfinispanRemoteHttpSession or @EnableInfinispanEmbeddedHttpSession to your configuration.

Example Project

Please take a look at the Infinispan Simple Tutorials.