Remote Cache: Getting Started

What You Will Learn

How to connect a Java Hot Rod client to an Infinispan Server and perform basic cache operations: put, get, and print values.

Prerequisites

Java 17+
An Infinispan Server running on localhost:11222 (or Docker/Podman available for Testcontainers)

Start an Infinispan Server with Docker or Podman:

docker run -it --rm -p 11222:11222 -e USER=admin -e PASS=password quay.io/infinispan/server:latest

Tip	You can replace `docker` with `podman` in the command above if you use Podman.

Tip	If no server is running, the tutorial code automatically starts an Infinispan Server using Testcontainers.

Step 1: Add the Hot Rod Client Dependency

Add the Infinispan Hot Rod client to your pom.xml:

<dependency>
   <groupId>org.infinispan</groupId>
   <artifactId>infinispan-client-hotrod</artifactId>
</dependency>

Step 2: Connect to the Server

Use ConfigurationBuilder to set up authentication and connect:

    static void connectToInfinispan() {
        // Connect to the server
        cacheManager = TutorialsConnectorHelper.connect();
        // Obtain the remote cache
        cache = cacheManager.getCache(TUTORIAL_CACHE_NAME);
    }

The tutorial uses a shared TutorialsConnectorHelper that handles connection setup and automatically falls back to Testcontainers if no server is running locally.

Step 3: Get a Cache and Store Data

Retrieve a named cache and perform put/get operations:

    static void manipulateCache() {
        // Store a value
        cache.put("key", "value");
        // Retrieve the value and print it out
        System.out.printf("key = %s\n", cache.get("key"));
    }

Step 4: Run the Tutorial

mvn package exec:java

You should see output like:

key = value

What’s Next

Query your data with Ickle queries
Use near-caching for faster reads
Secure your caches with role-based authorization