Run these code examples that demonstrate Infinispan capabilities and show you how to start using Infinispan caches with your applications.

Building and running the tutorials

Install the required Java and Maven versions before you build and run Infinispan Code Tutorials.

Java

  • Infinispan requires Java 17 as the minimum version.

Maven

To build the tutorials you must use Maven 3.x or greater.

Procedure

  1. Clone the Infinispan Code Tutorials repository.

    $ git clone git@github.com:infinispan/infinispan-simple-tutorials.git

  2. Run the following command from the root directory:

    $ ./mvnw clean install -DskipTests=true

1. Embedded caches

Add Infinispan as a dependency to your Java project and use embedded caches that increase application performance and give you capabilities to handle complex use cases.

1.1. Embedded cache tutorials

You can run embedded cache tutorials directly in your IDE or from the command line as follows:

$ ./mvnw clean package exec:exec
Tutorial link Description

Distributed caches

Demonstrates how Distributed Caches work.

Replicated caches

Demonstrates how Replicated Caches work.

Invalidated caches

Demonstrates how Invalidated Caches work.

Cache alias

Demonstrates how Cache alias work.

Transactions

Demonstrates how transactions work.

Streams

Demonstrates how Distributed Streams work.

JCache integration

Demonstrates how JCache works.

Functional Maps

Demonstrates how Functional Map API works.

Map API

Demonstrates how the Map API works with Infinispan caches.

Multimap

Demonstrates how to use Multimap.

Queries

Uses Infinispan Query to perform full-text queries on cache values.

Clustered Listeners

Detects when data changes in an embedded cache with Clustered Listeners.

Counters

Demonstrates how to use an embedded Clustered Counter.

Clustered Locks

Demonstrates how to use an embedded Clustered Lock.

Clustered execution

Demonstrates how to use an embedded Clustered Counter.

Kubernetes

Demonstrates how to deploy Infinispan Embedded in Kubernetes. However, the recommended way to use Kubernetes and Infinispan is the Infinispan Operator.

Infinispan documentation

You can find more resources about embedded caches in our documentation at:

1.2. Kubernetes and Openshift tutorial

This tutorial contains instructions on how to run Infinispan library mode (as a microservice) in Kubernetes/OpenShift.

Prerequisites: Maven and Docker daemon running in the background.

Prerequisites

  • A running Openshift or Kubernetes cluster

Building the tutorial

This tutorial is built using the maven command:

./mvnw package

Note that target/ directory contains additional directories like docker (with generated Dockerfile) and classes/META-INF/jkube with Kubernetes and OpenShift deployment templates.

If the Docker Daemon is down, the build will omit processing Dockerfiles. Use docker profile to turn it on manually.

Deploying the tutorial to Kubernetes

This is handle by the JKube maven plugin, just invoke:

mvn k8s:build k8s:push k8s:resource k8s:apply -Doptions.image=<IMAGE_NAME> (1)
1 IMAGE_NAME must be replaced with the FQN of the container to deploy to Kubernetes. This container must be created in a repository that you have permissions to push to and is accessible from within your Kubernetes cluster.

Viewing and scaling up

Everything should be up and running at this point. Now login into the OpenShift or Kubernetes cluster and scale the application

kubectl scale --replicas=3  deployment/$(kubectl get rs --namespace=myproject | grep infinispan | awk '{print $1}') --namespace=myproject

Undeploying the tutorial

This is handled by the JKube maven plugin, just invoke:

mvn k8s:undeploy

2. Remote caches

Deploy multiple Infinispan Server instances to create remote cache clusters that give you a fault-tolerant and scalable data tier with high-speed access from Hot Rod and REST clients.

2.1. Remote cache tutorials

To run these tutorials you need at least one locally running instance of Infinispan Server. Each tutorial will try to connect to a running server in localhost:11222 with admin/password credentials. However, if a Docker instance is found, and the server is not running, tutorials will spin up a local server with Testcontainers.

To run the Server as a container image, visit the "Get Started" page in the Infinispan Website:

Get Started with Infinispan

You can download the distribution and run the following commands:

$ ./bin/cli.sh user create admin -p "password"
$ ./bin/server.sh

Infinispan Server enables authentication and authorization by default. Creating a user named admin gives you administrative access to Infinispan Server.
Building and running remote cache tutorials

You can build and run remote cache tutorials directly in your IDE or from the command line as follows:

$ ./mvnw clean package exec:exec

2.2. Hot Rod Java client tutorials

  • Infinispan requires Java 11 at a minimum. However, Hot Rod Java clients running in applications that require Java 8 can continue using older versions of client libraries.

Tutorial link Description

Remote cache use example

The simplest code example that demonstrates how a remote distributed cache works.

Remote cache with cache alias example

Demonstrates how to update a cache config to add an alias and use it to manipulate the cache.

Per cache configuration

Demonstrates how to configure caches dynamically when we connect to the Infinispan Server.

Near caches

Demonstrates how configure near caching to improve the read performance in remote caches.

Cache Admin API

Demonstrates how to use the Administration API to create caches and cache templates dynamically.

Encoding

Demonstrates how encoding of caches work.

Custom marshalling

Demonstrates how custom marshalling works in the context of programmatically creating Protostream schemas and marshallers. Users should generally rely on annotations based generated Protostream marshallers unless exceptional circumstances require manual creation.

Client listeners

Detect when data changes in a remote cache with Client Listeners.

Query

Demonstrates how to query remote cache values.

Continuous query

Demonstrates how to use Continuous Query and remote caches.

Transactions

Demonstrates how remote transactions work.

Secured caches

Demonstrates how to configure caches that have authorization enabled.

TLS authorization

Demonstrates how to connect to Infinispan Server with TLS authorization.

Multimap

Demonstrates how remote multimap works.

Task execution

Demonstrates how to register server tasks and how to execute them from the Hot Rod client.

JUnit 5 and Testcontainers

Demonstrates how to use the Infinispan and JUnit 5 extension.

Persistence

Demonstrates how to use the Infinispan and persistent caches.

Redis Client

Demonstrates how to use the Infinispan and Redis client to read and write using the Resp protocol.

Reactive API

Demonstrates how to use the Infinispan with the reactive API based on Mutiny.

Infinispan documentation

You can find more resources for Hot Rod Java clients in our documentation at:

2.3. Hot Rod Node.JS client tutorials

Prerequisites

  • Node.js 12 or 14

Build
npm install

Running the example

Create a cache named my-cache using the Infinispan Console.

'my-cache' cache configuration
"distributed-cache": {
  "mode": "SYNC",
    "encoding": {
    "media-type": "text/plain"
    },
  "statistics": true
}
Execution
node index.js

Check with the Infinispan Console the my-cache cache detail.

2.4. Hot Rod .NET/C# client tutorials

Prerequisites

Running the example

Do one of the following (1,2 may be suitable for devs while 3 is for runtime):

  1. Copy in this directory (aside this README.md) the following dlls:

    • hotrodcs.dll

    • hotrod.dll

    • hotrod_wrap.dll

    • libeay32.dll (SSL stuff)

    • ssleay32.dll (SSL stuff)

  2. Update dlls location in simple.csproj with the right paths in your file system

  3. Install the binary client on the machine, update the PATH env. variable to include the bin and lib directories of the installed pack, install your application.

HINT THAT CAN SAVE YOU A LOT OF TIME: the .csproj at build time will copy the dlls into the output directory aside the application, this is the simplest way to run the example without changing your setting (PATH variable). As a general rule remember that the unmanaged libraries (hotrod_wrap, hotrod, libeay32, libssl32) must be either in the PATH or in the application working directory.

2.5. Hot Rod C++ client tutorials

Prerequisites

  • Centos 7 (RHEL 7 should work also)

  • Infinispan Server running with the default standalone configuration

Docker

Here is a easy way to setup a Docker container running Centos 7, so you can run the tutorial in a confined environment.

Setup the Server

On the host machine, start at least one Infinispan Server instance.

Create a default cache

curl -vvvv -X POST http://127.0.0.1:11222/rest/v2/caches/default

Change to this README directory, download the client .rpm

    wget https://downloads.jboss.org/infinispan/HotRodCPP/8.3.1.Final/infinispan-hotrod-cpp-8.3.1.Final-RHEL-x86_64.rpm
Start the Centos Docker container
docker run -i -t -v $PWD:/home/infinispan/git/infinispan-simple-tutorial:Z --network="host" centos:7
On the Container
Build the client
cd /home/infinispan/git/infinispan-simple-tutorial/c++
yum install wget unzip cmake make gcc-c++ protobuf-devel cyrus-sasl-devel
rpm -i --force infinispan-hotrod-cpp-8.3.1.Final-RHEL-x86_64.rpm
mkdir build && pushd build
cmake ..
cmake --build .
Run the client
LD_LIBRARY_PATH=/usr/lib ./simple

2.6. Cross-site replication

Learn how to set up two clusters locally and using Infinispan cross site replication.

Cross site replication tutorial

In this tutorial, you start two Infinispan clusters, LON and NY, that provide backups for each other. This tutorial demonstrates Infinispan cross-site replication capabilities locally using docker-compose or the Infinispan Operator with a local Kubernetes cluster like Minikube. In production environments, Infinispan cluster backups are typically located in different data centers.

2.6.1. Docker compose

Make sure you have docker and docker-compose installed locally.
Steps

  1. Run docker-compose up. The docker-compose yaml creates the LON and NYC clusters using the infinispan-xsite.xml file. Access the console of the LON cluster site at http://localhost:11222/console.

  2. Access the console of the NYC cluster site at http://localhost:31222/console.

  3. Run ./create-data.sh to create some sample data. The script creates a cache named xsiteCache in the LON cluster that defines the NYC site as a backup. It is also worth noting that cache topologies can be different when using cross-site replication. In this example, the cache in LON is distributed while the cache in NYC is replicated.

2.6.2. Minikube and Infinispan Operator

Make sure you have minikube installed locally.
Steps

  1. Run ./setup.sh: This script starts minikube, installs the Infinispan Operator, deploys two clusters (LON and NYC) and creates the caches.

  2. Run ./create-data.sh

Both sites are accessible externally using the Infinispan Console through

  • LON (minikube service --url example-cluster-lon-external

  • NYC minikube service --url example-cluster-nyc-external

The credentials are configured using Kubernetes secrets (identities_lon.yaml and identities_nyc.yaml).

To go further use the Infinispan Console or the REST API, add launch additional Cross-Site operations.
Additional resources

2.7. Token based Security Realm with Keycloak

Learn how to handle security authentication in Infinispan with Keycloak.

Token based security tutorial with Keycloak

In this tutorial, you start one Infinispan cluster and Keycloak. This tutorial demonstrates Infinispan security capabilities locally using docker-compose.

2.7.1. Docker compose

Make sure you have docker and docker-compose installed locally.
Steps

  1. Run docker-compose up. Keycloak and Infinispan will start with all the necessary configuration.

  2. Access the console at http://localhost:11222/console. You should be redirected to Keycloak login.

  3. Enter 'admin/adminPassword' credentials in the login page.

  4. You are now back in the console, logged in.

If you are using Docker of Mac or Docker Desktop, network_mode: host might still not be supported. In that case, run docker-compose -f docker-compose-no-linux.yaml up and add 127.0.0.1 keycloak to /etc/hosts.

2.8. Tracing with OpenTelemetry

Learn how to set up a server with traces enabled.

Tracing and OpenTelemetry tutorial

In this tutorial, you start a Infinispan server with tracing enabled. Tracing is done using Jaeger. This tutorial demonstrates Infinispan observability capabilities locally using docker-compose.

2.8.1. Docker compose

Make sure you have docker and docker-compose or podman and podman-compose installed locally.
Steps

  1. Run docker-compose up. The docker-compose yaml creates the Infinispan cluster using the infinispan-tracing-configuration-server.yaml file that sets up the tracing configuration. Access the console of at http://localhost:11222/console with admin/password.

  2. Run the InfinispanRemoteOpenTelemetry main class

  3. Check Jaeger console and visualize the traced spans at http://localhost:16686/

Additional resources

3. Spring and Spring Boot

3.1. Spring and Spring Boot tutorials

These code tutorials use Infinispan Server and require at least one running instance.
Run Spring examples

Two simple tutorials can be run with Spring without Spring Boot:

  • Test caching

$ ./mvnw package exec:exec@spring-caching

  • Test annotations

$ ./mvnw package exec:exec@spring-annotations

To run the Spring Boot tutorials, use the following command.

$ ./mvnw spring-boot:run
Displaying actuator statistics

Navigate to http://localhost:8080/actuator/metrics in your browser to display a list of available metrics. Cache metrics are prefixed with "cache." Display each metric for each cache using tags. For example for the 'puts' stats in the basque-names cache:

http://localhost:8080/actuator/metrics/cache.puts?tag=name:basque-names

Collecting statistics with Prometheus

The prometheus.yml file in this project contains a host.docker.internal binding that allows Prometheus to scrap metrics that the Spring actuator exposes.

Change the YOUR_PATH value in the following command to the directory where Prometheus is running and then run:

Podman
$ podman run -d --name=prometheus -p 9090:9090 -v YOUR_PATH/integrations/spring-boot/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml
Tutorial link Description

Spring Boot and Spring Cache remote mode

Demonstrates how to use Spring Caches with Spring Boot and the Infinispan Server.

Spring Boot, Spring Cache, Reactor and Infinispan Server

Demonstrates how to use Spring Caches with Spring Boot Reactor and the Infinispan Server.

Spring Boot and Spring Session remote mode

Demonstrates how to use Spring Session with Spring Boot and the Infinispan Server.

Spring Boot and Spring Cache embedded mode

Demonstrates how to use Spring Caches with Spring Boot and Infinispan Embedded.

Spring Boot and Spring Session embedded mode

Demonstrates how to use Spring Session with Spring Boot and Infinispan Embedded.

Spring cache embedded without Spring Boot

Demonstrates how to use Spring Cache and Infinispan Embedded without Spring Boot.

Infinispan documentation

You can find more resources in our documentation at:

4. Hibernate

4.1. Hibernate tutorials

You can run these tutorials directly in your IDE or from the command line as follows:

$ ./mvnw clean package
$ ./mvnw exec:exec

Tutorials that involve deploying an archive to Wildfly are first deployed like this:

$ ./mvnw clean package
$ ./mvnw wildfly:deploy
Tutorial link Description

Hibernate local

Demonstrates how Infinispan Embedded and Hibernate work.

Hibernate and Spring local

Demonstrates how Spring, Hibernate and Infinispan work.

Hibernate and WildFly local

Demonstrates how Wildfly and Infinispan work.

Infinispan documentation

You can find more resources in our documentation at: