= Spring Boot Starter for {brandname}
The {brandname} starter provides a set of managed transitive dependencies that include everything your Spring Boot project needs to seamlessly interact with {brandname} in one of two modes:

* Embedded Mode runs {brandname} inside your application.
* Remote Client/Server Mode connects your application to an {brandname} cluster.

[TIP]
====
The {brandname} Spring Boot starter gives you a convenient way to get started with Spring Boot but is optional. To use {brandname} with Spring Boot you can simply add the dependencies you want.
====

= Setting Up Your Project

== Spring Boot Starter Versions

{brandname} supports Spring Boot 1.5.x and 2.x. For Spring Boot 1.5.x, use the Spring 4 dependencies. For Spring Boot 2.x, use the Spring 5 dependencies.

* Spring Boot 1.5.x: Replace `${version.infinispan.starter}` with {sb_starter}
* Spring Boot 2.x: Replace `${version.infinispan.starter}` with {sb2_starter}

== Enforcing {brandname} Versions

This starter uses a high-level API to ensure compatibility between major versions of {brandname}. However you can enforce a specific version of {brandname} with the `infinispan-bom` module.

Add `infinispan-bom` to your `pom.xml` file before the starter dependencies, as follows:

include::../dependencies/sb_bom.adoc[]

[IMPORTANT]
====
The {brandname} Spring Boot starter uses different Spring Boot versions to other projects such as Red Hat OpenShift Application Runtimes. If you want to use a specific Spring Boot version for compatibility with other projects, you must add the correct dependency to your project.
====

== Adding Dependencies for Usage Modes

{brandname} provides different dependencies for each usage mode. Add one of the following to your `pom.xml` file:

Embedded Mode::
include::../dependencies/sb_embedded.adoc[]

Remote Client/Server Mode::
include::../dependencies/sb_remote.adoc[]

= Running in Embedded Mode

. Add `infinispan-spring-boot-starter-embedded` to your project's classpath to enable Embedded mode.
+
This starter operates in Remote Client/Server mode with `infinispan-spring-boot-starter-remote` on the classpath by default.
+
. Use the Spring `@Autowired` annotation to include an `EmbeddedCacheManager` bean in your Java configuration classes, as in the following example:
+
[source,java,options="nowrap"]
----
private final EmbeddedCacheManager cacheManager;

@Autowired
public YourClassName(EmbeddedCacheManager cacheManager) {
    this.cacheManager = cacheManager;
}
----
+
You are now ready to use {brandname} in Embedded Mode. Here is a simple example:
+
[source,java,options="nowrap"]
----
cacheManager.getCache("testCache").put("testKey", "testValue");
System.out.println("Received value from cache: " + cacheManager.getCache("testCache").get("testKey"));
----

== Customizing the Cache Manager

Customize the cache manager with the following configuration beans:

* `InfinispanGlobalConfigurer`
* `InfinispanCacheConfigurer`
* `Configuration`
* `InfinispanConfigurationCustomizer`
* `InfinispanGlobalConfigurationCustomizer`
+
[NOTE]
====
You can create one `InfinispanGlobalConfigurer` bean only. However you can create multiple configurations with the other beans.
====

.InfinispanCacheConfigurer Bean
[source,java,options="nowrap"]
----
@Bean
public InfinispanCacheConfigurer cacheConfigurer() {
	return manager -> {
		final Configuration ispnConfig = new ConfigurationBuilder()
                        .clustering()
                        .cacheMode(CacheMode.LOCAL)
                        .build();

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

.Configuration Bean
Link the bean name to the cache that it configures, as follows:
[source,java,options="nowrap"]
----
@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();
}
----

.Customizer Beans
[source,java,options="nowrap"]
----
@Bean
public InfinispanGlobalConfigurationCustomizer globalCustomizer() {
   return builder -> builder.transport().clusterName(CLUSTER_NAME);
}

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

== Enabling Spring Cache Support

Add the `@EnableCaching` annotation to your application to enable Spring Cache support.

When this starter detects the `EmbeddedCacheManager` bean, it instantiates a new `SpringEmbeddedCacheManager`, which provides an implementation of
https://docs.spring.io/spring/docs/current/spring-framework-reference/html/cache.html[Spring Cache].

== Configuration Properties

Include the following properties in the `application.properties` or `application.yml` file to configure your project:

[source,yaml,options="nowrap"]
----
infinispan.embedded.enabled = # Enables Data Grid capabilities in your application. The value is true (default) or false.
infinispan.embedded.machineId = # Sets the Spring state machine ID.
infinispan.embedded.clusterName = # Sets the name of the Data Grid cluster.
infinispan.embedded.configXml = # Specifies a XML configuration file.
----

[NOTE]
====
If you specify a {brandname} configuration with the `infinispan.embedded.configXml` property, it takes priority over the global configuration bean or any configuration customizer.
====

= Running in Remote Client/Server Mode

. Provide the location for the {brandname} server so the starter can create the `RemoteCacheManager` bean.
+
This starter first attempts to locate the server from the `hotrod-client.properties` file on the classpath. If not found, the starter then attempts to locate the server from your `application.properties` file.
+
* `hotrod-client.properties`:
+
[source,text,options=nowrap]
----
infinispan.client.hotrod.server_list=127.0.0.1:11222
----
+
* `application.properties`:
+
[source,text,options=nowrap]
----
infinispan.remote.server-list=127.0.0.1:11222
----
+
. Use the Spring `@Autowired` annotation to include your own custom cache manager class in your application:
+
[source,java,options="nowrap"]
----
private final RemoteCacheManager cacheManager;

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

== Customizing the Cache Manager

Customize the cache manager with the following configuration beans:

* `InfinispanRemoteConfigurer`
* `Configuration`
* `InfinispanRemoteCacheCustomizer`
+
[NOTE]
====
You can create one `InfinispanRemoteConfigurer` bean only. However you can create multiple configurations with the other beans.
====

.InfinispanRemoteConfigurer Bean
[source,java,options="nowrap"]
----
@Bean
public InfinispanRemoteConfigurer infinispanRemoteConfigurer() {
    return () -> new ConfigurationBuilder()
        .addServer()
        .host("127.0.0.1")
        .port(12345)
        .build();
}
----

.Configuration Bean
[source,java,options="nowrap"]
----
@Bean
public org.infinispan.client.hotrod.configuration.Configuration customConfiguration() {
    new ConfigurationBuilder()
        .addServer()
        .host("127.0.0.1")
        .port(12345)
        .build();
}
----

.InfinispanRemoteCacheCustomizer Bean
[source,java,options="nowrap"]
----
@Bean
public InfinispanRemoteCacheCustomizer customizer() {
    return b -> b.tcpKeepAlive(false);
}
----

[TIP]
====
Use the `@Ordered` annotation to apply customizers in a specific order.
====

== Enabling Spring Cache Support

Add the `@EnableCaching` annotation to your application to enable Spring Cache support.

When the {brandname} starter detects the `RemoteCacheManager` bean, it instantiates a new `SpringRemoteCacheManager`, which provides an implementation of
https://docs.spring.io/spring/docs/current/spring-framework-reference/html/cache.html[Spring Cache].

== Enabling Spring Session Support

{brandname} Spring Session support is built on
`SpringRemoteCacheManager` and `SpringEmbeddedCacheManager`. This starter produces those beans by default.

To use Spring Session in your project, do the following:

. Add this starter to your project.
. Add Spring Session to the classpath.
. Add the following annotations to your configuration:
- `@EnableCaching`
- `@EnableInfinispanRemoteHttpSession`
- `@EnableInfinispanEmbeddedHttpSession`

== Configuration Properties

Include the following properties in the `application.properties` or `application.yml` file to configure your project:

[source,yaml,options="nowrap"]
----
infinispan.remote.clientProperties = # Specifies a custom filename for Hot Rod client properties.
infinispan.remote.enabled = # Enables Data Grid capabilities in your application. The value is true (default) or false.
infinispan.remote.serverList = # Defines a comma-separated list of Data Grid  servers in this format: `host1[:port],host2[:port]`.
infinispan.remote.socketTimeout = # Sets a timeout value, in milliseconds, for socket connections.
infinispan.remote.connectTimeout = # Sets a timeout value for initializing connections with Data Grid servers.
infinispan.remote.maxRetries = # Sets the maximum number of attempts to connect to Data Grid servers.
----

= Exposing {brandname} Statistics

{brandname} supports the Spring Boot Actuator to expose cache statistics as metrics.

[NOTE]
====
{brandname} supports the Actuator with Spring Boot 2.x only.
====

To use the Actuator, add the following to your `pom.xml` file:

include::../dependencies/sb_actuator.adoc[]

You must then activate statistics for the appropriate cache instances, either programmatically or declaratively.

.Programmatically
[source,java,options="nowrap"]
----
@Bean
public InfinispanCacheConfigurer cacheConfigurer() {
   return cacheManager -> {
      final org.infinispan.configuration.cache.Configuration config =
            new ConfigurationBuilder()
                  .jmxStatistics().enable()
                  .build();

      cacheManager.defineConfiguration("my-cache", config);
   };
}
----

.Declaratively
[source,xml,options="nowrap"]
----
<infinispan xmlns="urn:infinispan:config:9.4">
  <cache-container>
    <local-cache name="my-cache" statistics="true"/>
    <local-cache name="other"/>
  </cache-container>
</infinispan>
----

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:

[source,java,options="nowrap"]
----
@Autowire
CacheMetricsRegistrar cacheMetricsRegistrar;

@Autowire
CacheManager cacheManager;
...

cacheMetricsRegistrar.bindCacheToRegistry(cacheManager.getCache("my-cache"));
----
