Infinispan Logo

Infinispan Remote Weather App Tutorial

Learn how to use Infinispan from the Console and remote Hot Rod clients. This tutorial includes Java applications that use Infinispan capabilities to provide services for a searchable weather monitoring system.


By completing this tutorial, you will learn how to:

  1. Run Infinispan Server.

  2. Access and use the Infinispan Console.

  3. Create Infinispan caches.

  4. Read and write data as primitive types and Java objects.

  5. Add lifespans to entries so data expires.

  6. Deploy client listeners to get event notifications.

  7. Search the data store for specific values.

  8. Use out-of-the-box testing with Junit 5 for verification.


To complete this tutorial, you need:

  • Approximately 25 to 30 minutes

  • IDE such as Intellij

  • JDK 8 or JDK 11 or later

  • Apache Maven 3.6.2 or later

  • Docker or Podman

Run mvn --version to verify that Maven uses the correct JDK if you have multiple Java versions installed.

Weather System Architecture

This tutorial builds a Weather System with the following Java applications:

  1. TemperatureLoaderApp

  2. TemperatureMonitorApp

  3. WeatherLoaderApp

  4. WeatherFinderApp

Temperature Subsystem

The Temperature Loader and Temperature Monitor applications comprise the temperature subsystem, as shown below:

Temperature Loader

This application loads temperatures for geographic locations and runs every five seconds. Infinispan stores that data in the temperature cache as follows:

  • Location: Key String

  • Temperature: Value Float

Temperature Monitor

This application monitors the temperature of each location. Infinispan sends notifications when temperatures change and the application displays each new temperature.

Weather Subsystem

The Weather Loader and Weather Finder applications comprise the weather subsystem, as shown below:

Weather Loader

This application loads weather information for geographic locations and runs every five seconds. Infinispan stores that data in the weather cache as follows:

  • Location: Key String

  • Weather: Value LocationWeather (temperature, condition, city, country)

Weather Finder

This application uses Infinispan Search capabilities to perform text search and continuous queries.

Starting Infinispan Server

Before you start coding fun stuff, you need to start Infinispan Server. For this tutorial, you need a locally running server instance.

You can do one of the following:

  • Pull the container image and run with Docker or Podman.

  • Download the server distribution and extract it to your filesystem.


By default, Infinispan Server requires user authentication. This tutorial uses admin and pass credentials but you can use any username and password.

Running the Container Image

The easiest way to run Infinispan Server locally is to pull the container image.

  • Podman

    podman run --net=host -p 11222:11222 -e USER="admin" -e PASS="pass"

  • Docker

    docker run -it -p 11222:11222 -e USER="admin" -e PASS="pass" infinispan/server:12.0

Running the Server Distribution

Infinispan Server comes as a bare metal distribution that you can run locally.

  1. Download the server distribution from Infinispan Downloads and extract it.

  2. Open a terminal window in the resulting directory. This is $ISPN_HOME.

  3. Add credentials.

    $ ./bin/ user create admin -p pass
  4. Run Infinispan Server.

    $ ./bin/

Accessing the Infinispan Console

Open http://localhost:11222/ in any browser.

You’ll see the Welcome to Infinispan Server page.

Welcome to the console

To start using the Infinispan Console, do the following:

  1. Select Go to the console.

  2. Enter your credentials (admin/pass).

Getting the Weather Application

You can create the Weather Application yourself going step by step or you can skip ahead and use the complete solution.

Establishing Remote Connections

Connect to your locally running Infinispan Server from a Hot Rod Java client.

Add Dependencies

Open the pom.xml file for this project and confirm that the following dependencies are available:

  • infinispan-client-hotrod adds the Java Hot Rod Client.

  • infinispan-query-dsl adds the Infinispan Search API.

  • infinispan-remote-query-client adds a remote search client.


Create a Remote Connection

Update the connect() method in the DataSourceConnector class as follows:

ConfigurationBuilder builder = new ConfigurationBuilder(); (1)

builder.uri("hotrod://admin:pass@localhost:11222"); (2)

builder.clientIntelligence(ClientIntelligence.BASIC); (3)

remoteCacheManager = new RemoteCacheManager(; (4)
1 Creates a ConfigurationBuilder
2 HotRod URI connection (server, port and credentials)
3 Uses BASIC Hot Rod client intelligence. This is required to use Docker with a Mac.
4 Creates a RemoteCacheManager with the configuration.

Test the Connection

Run HealthChecker to make sure your connection is successful.

You should see the following messages:

---- Connect to Infinispan ----
INFO: ISPN004021: Infinispan version: Infinispan ...
---- Connection count: 1 ----
---- Shutdown the client ----

Implementing Temperature Loader

In this section of the tutorial, you implement the Temperature Loader application and learn how to:

  • Create caches from the Console.

  • Read data from the cache.

  • Write data to the cache.

  • Expire entries in the cache.

Create a Temperature Cache

Update the getTemperatureCache() method in the DataSourceConnector class to invoke getOrCreateCache() as follows:

public RemoteCache<String, Float> getTemperatureCache() {
   return remoteCacheManager.administration().getOrCreateCache("temperature", "example.PROTOBUF_DIST"); (1)
1 Adds a cache named temperature that uses the example.PROTOBUF_DIST configuration template.

This template uses Protobuf encoding for keys and values so that you can operate on data from different clients. You can

View the configuration for the example.PROTOBUF_DIST template from the Console at localhost:11222/console/container/default/configurations/

Put and Read Temperature Data

Implement the getForLocation() method in the TemperatureLoader service as follows:
   public Float getForLocation(String location) {
      Float temperature = cache.get(location); (1)
      if (temperature == null) {
         temperature = fetchTemperature(); (2)
         cache.put(location, temperature); (3)
      return temperature;
1 Get the value for the location key.
2 Fetches the value if it does not exist in the cache.

The private fetchTemperature() method emulates an external service call that takes 200ms to retrieve the temperature for a geographic location.

3 Adds the value to the temperature cache.

Verify Temperature Loader

Run TemperatureLoaderApp to check that it adds temperature data.

The first time the application runs, it takes about two seconds to load data. Subsequent calls retrieve the temperature from the cache, which increases performance.

You should see messages such as the following:


---- Connect to Infinispan ----
<timestamp> org.infinispan.client.hotrod.RemoteCacheManager actualStart
INFO: ISPN004021: Infinispan version: Infinispan 'Corona Extra' 11.0.1.Final
---- Get or create the 'temperature' cache ----
---- Press any key to quit ----
---- Loading information ----
Rome, Italy - 22.000622
Como, Italy - 21.044369

---- Loaded in 1762ms ----
---- Loading information ----
Rome, Italy - 22.000622
Como, Italy - 21.044369
---- Loaded in 44ms ----
---- Shutdown the client ----

Expiring Data

At this point, data in the cache remains the same, even if temperatures at the locations change. You can use expiration to remove data after a period of time so that the Temperature Loader fetches new data for the temperature cache.

Update the put() method in the TemperatureLoader class so data expires after 20 seconds as follows:
   cache.put(location, temperature, 20, TimeUnit.SECONDS);

Run the TemperatureLoaderApp class again. After 20 seconds you should notice that temperature loading performance decreases because the service needs to fetch data again.

Implementing Temperature Monitor

In this section of the tutorial, you implement the Temperature Monitor application and learn how to use Infinispan Client Listeners.

These client listeners enable the Temperator Monitor application to display notifications about temperature changes that happen for each location.

Create a Client Listener

At present, client listeners do not include values of keys in receiving events. For this reason, you use the Async API to get the value and display the temperature that corresponds to the key.

Update the TemperatureMonitor service as follows:
    @ClientListener (1)
    public class TemperatureChangesListener {
      private String location;

      TemperatureChangesListener(String location) {
         this.location = location;

      @ClientCacheEntryCreated (2)
      public void created(ClientCacheEntryCreatedEvent event) {
         if(event.getKey().equals(location)) {
            cache.getAsync(location) (3)
                  .whenComplete((temperature, ex) ->
                  System.out.printf(">> Location %s Temperature %s", location, temperature));


    public void monitorLocation(String location) {
        System.out.println("---- Start monitoring temperature changes for " + location + " ----\n");
        TemperatureChangesListener temperatureChangesListener = new TemperatureChangesListener(location);
        cache.addClientListener(temperatureChangesListener); (4)
1 Annotates TemperatureChangesListener with @ClientListener to make it an Infinispan Client Listener.
2 Uses the @ClientCacheEntryCreated annotation to get notifications every time data is added to the temperature cache.
3 Filters locations by key and gets values using the async call and then prints the new values.
4 Adds the client listener to the cache.

The preceding example filters events in the listener. However, these events can also be filtered server-side with an event filter. However, you must create the filter and deploy it to Infinispan Server, which is beyond the scope of this tutorial.

Always remove client listeners from caches when you no longer need them.

Verify Temperature Monitor

Make sure that TemperatureLoaderApp is running and then run TemperatureMonitorApp.

You should see a message that displays the current temperature of a location and then get notifications for new temperatures every 20 seconds.


---- Connect to Infinispan ----
<timestamp> org.infinispan.client.hotrod.RemoteCacheManager actualStart
INFO: ISPN004021: Infinispan version: Infinispan 'Corona Extra' 11.0.1.Final
---- Get or create the 'temperature' cache ----
Temperature 14.185611 for Bilbao, Spain
---- Start monitoring temperature changes for Bilbao, Spain ----
---- Press any key to quit ----
>> Location Bilbao, Spain Temperature 7.374308
>> Location Bilbao, Spain Temperature 24.784744

Change the expiration values to get more notifications. Use @ClientCacheEntryExpired to get notifications when data expires.

Implementing Weather Loader

In this section of the tutorial, you implement the Weather Loader application and learn how to:

  • Add complex key/value entries to a cache.

  • Serialize Java objects so they can be transmitted to Infinispan Server.

  • Use Protobuf encoding for searchable data so you perform remote queries from Hot Rod Java clients as well as REST clients and other Hot Rod clients such as C# and Node.js.

Annotate the LocationWeather POJO

Infinispan uses Protostream to serialize data to byte.

Add the @ProtoField annotation to LocationWeather as follows:
    public class LocationWeather {

       @ProtoField(number = 1, defaultValue = "0.0")
       float temperature;

       @ProtoField(number = 2)
       String condition;

       @ProtoField(number = 3)
       String city;

       @ProtoField(number = 4)
       String country;

Configure the Serialization Context

To marshall the annotated LocationWeather class, Infinispan requires a Protobuf schema. You can either provide a Protobuf descriptor file or create a descriptor file from the annotations you added to the POJO.

In LocationWeatherMarshallingContext, you add the schema to the Protobuf cache in Infinispan and then build a Protobuf using the @AutoProtoSchemaBuilder method.

includeClasses = {
schemaFileName = "weather.proto",
schemaFilePath = "proto/",
schemaPackageName = "")
public interface LocationWeatherSchema extends SerializationContextInitializer {

Run mvn clean package from the command line or build the project in your IDE to generate the LocationWeatherSchemaImpl class.

       // Retrieve metadata cache
      RemoteCache<String, String> metadataCache =
            cacheManager.getCache(ProtobufMetadataManagerConstants.PROTOBUF_METADATA_CACHE_NAME); (1)

      GeneratedSchema schema = new LocationWeatherSchemaImpl(); (2)

      // Define the new schema on the server too
      metadataCache.put(schema.getProtoFileName(), schema.getProtoFile()); (3)
1 Retrieves the metadata cache that stores all Protobuf schemas.
2 Use the class generated from the LocationWeatherSchema interface to retrieve the schema.
3 Adds the schema to the cache.

Create a Weather Cache

In this step, you create a weather cache that can store LocationWeather objects. First you must initialize the marshalling context in the application and then create the cache, as follows:

    public RemoteCache<String, LocationWeather> getWeatherCache() {
        System.out.println("--- Get or Create a queryable weather cache ---");

        LocationWeatherMarshallingContext.initSerializationContext(remoteCacheManager); (1)

        return remoteCacheManager.administration()
              .getOrCreateCache("weather", "example.PROTOBUF_DIST"); (2)
1 Initializes the serialization context.
2 Creates the weather cache.

Verify Weather Loader

The code that loads data into the weather cache is located in the Because this service is similar to the code you implemented for the TemperatureLoader service, you don’t need to do anything else.

Run WeatherLoaderApp to check that it loads weather data.

You should see messages that indicate the weather cache is created and weather information is added for different locations:

---- Connect to Infinispan ----
<timestamp> org.infinispan.client.hotrod.RemoteCacheManager actualStart
INFO: ISPN004021: Infinispan version: Infinispan 'Corona Extra' 11.0.1.Final
LocationWeatherMarshallingContext - initialize the serialization context for LocationWeather class
---- Get or create the 'weather' cache ----
---- Press any key to quit ----

---- Loading information ----
Rome, Italy - LocationWeather{temperature=17.252243, condition='SUNNY', city='Rome', country='Italy'}
Como, Italy - LocationWeather{temperature=24.495003, condition='WINDLESS', city='Como', country='Italy'}
Basel, Switzerland - LocationWeather{temperature=19.795946, condition='WINDLESS', city='Basel', country='Switzerland'}
Bern, Switzerland - LocationWeather{temperature=20.455978, condition='WINDLESS', city='Bern', country='Switzerland'}
---- Loaded in 3386ms ----

---- Loading information ----
Rome, Italy - LocationWeather{temperature=17.252243, condition='CLOUDY', city='Rome', country='Italy'}
Como, Italy - LocationWeather{temperature=24.495003, condition='PARTIALLY_COVERED', city='Como', country='Italy'}
---- Loaded in 70ms ----

Implementing Weather Finder

In this section of the tutorial, you learn how to:

  • Create and run FROM queries.

  • Create and run SELECT queries.

  • Perform continuous queries.

Create a FROM Query

Create a FROM query on values in the weather cache as follows:
   public List<LocationWeather> findByCountry(String country) {
      QueryFactory queryFactory = Search.getQueryFactory(weather); (1)

      Query<LocationWeather> query = queryFactory.create("FROM WHERE country = :country"); (2)

      query.setParameter("country", country); (3)

      return query.execute().list(); (4)
1 Gets the QueryFactory from the cache.
2 Creates a FROM query using the Ickle query language. This query finds each LocationWeather in a country.
3 Sets the country parameter.
4 Executes the query and returns the list.

Run the FROM Query

Make sure WeatherLoaderApp is running and then run WeatherFinderApp.

You should see output such as the following:
---- Get or create the 'weather' cache ----
Spain: [LocationWeather{temperature=6.2846804, condition='CLOUDY',city='Bilbao', country='Spain'},
LocationWeather{temperature=18.044653, condition='SUNNY', city='Madrid', country='Spain'}]

Create a SELECT Query

For some queries, you don’t want every field for an object. In this example, you create and run a query that returns only the city that matches a given weather condition.
    public List<String> findByCondition(WeatherCondition condition) {
      Query<Object[]> query = createFindLocationWeatherByConditionQuery(condition);
      return query.execute().list().stream().map(data -> (String) data[0]).collect(Collectors.toList()); (4)

    private Query<Object[]> createFindLocationWeatherByConditionQuery(WeatherCondition condition) {
      QueryFactory queryFactory = Search.getQueryFactory(weather); (1)

      Query<Object[]> query = queryFactory.create("SELECT city FROM w where w.condition = :condition"); (2)

      query.setParameter("condition",; (3)

      return query;
1 Gets the QueryFactory from the cache.
2 Creates a SELECT query using the Ickle query language. This query finds every LocationWeather with a weather condition and returns only the city.
3 Sets the condition parameter.
4 Executes the query, returns the list, and filters the Object[] to get the String results.

Run the SELECT Query

Make sure WeatherLoaderApp is running and then run WeatherFinderApp.

You should see output such as the following:
SUNNY: [Madrid]
CLOUDY: [Lisbon, Bilbao, Newcastle, Como]
RAINY: [Cluj-Napoca]
FOGGY: [Washington, Porto, Rome]
WINDLESS: [London, Raleigh]
DRY: [Ottawa]
WET: [Basel, Bucarest]

Create a Continuous Query

Continuous Queries allow applications to register listeners that receive the entries matching a query filter. In this way, applications are continuously notified of changes to the queried data set.
public void findWeatherByConditionContinuously(WeatherCondition condition) {
      Query<Object[]> query = createFindLocationWeatherByConditionQuery(condition); (1)

      ContinuousQuery<String, LocationWeather> continuousQuery = Search.getContinuousQuery(weather); (2)

      ContinuousQueryListener<> listener =
            new ContinuousQueryListener<String, Object[]>() { (3)
               public void resultJoining(String key, Object[] data) {
                   System.out.printf("%s is now %s%n", data[0], condition);

      continuousQuery.addContinuousQueryListener(query, listener); (4)
1 Creates a query that finds all locations with a certain weather condition; for example, 'Sunny'.
2 Creates a continuous query on the weather cache.
3 Creates a continuous query listener and prints the condition.
4 Matches the query and the listener in the ContinuousQuery object

Always remove continuous queries when you no longer need them.

Run the Continuous Query

Make sure WeatherLoaderApp is running and then run WeatherFinderApp.

You should see output such as the following:
---- Press any key to quit ----
Madrid is now SUNNY
Bilbao is now SUNNY
Toronto is now SUNNY
Newcastle is now SUNNY
Cluj-Napoca is now SUNNY
Porto is now SUNNY

Testing Infinispan Server

Test containers are a great way to run an Infinispan Server and test with a Junit 5 extension.

This section of the tutorial provides an example test that verifies the temperatures loaded in Infinispan Server are correct.

You need Docker for this part of the tutorial.

Add Dependencies

Open the pom.xml file for this project and add the infinispan-server-testdriver-junit5 dependency as follows:


JUnit 4 rules are also available for out-of-the-box testing with Infinispan Server. Check the infinispan-server-testdriver-junit4 dependency.

Using Test Containers

Create a Junit 5 Test and use the InfinispanServerExtension.

   static InfinispanServerExtension infinispanServerExtension = InfinispanServerExtensionBuilder.server(); (1)

   public void loadLocationTemperature() {
      DataSourceConnector dataSourceConnector = new DataSourceConnector(createRemoteCacheManager());
      TemperatureLoader temperatureLoader = new TemperatureLoader(dataSourceConnector);
      Float temperatureLoaderForLocation = temperatureLoader.getForLocation(WeatherLoader.LOCATIONS[0]);

   private RemoteCacheManager createRemoteCacheManager() {
      RemoteCacheManager remoteCacheManager = infinispanServerExtension.hotrod().createRemoteCacheManager();
      SerializationContext serCtx = MarshallerUtil.getSerializationContext(remoteCacheManager);
      LocationWeatherSchema schema = new LocationWeatherSchemaImpl();
      return remoteCacheManager;
1 Registers the Junit 5 Infinispan Server Extension.
2 Adds a serialization context for the tests.

What’s Next?

Congratulations on completing this tutorial!

You should now be well on your way with using the Infinispan Server. Here are some more things to help you keep learning:

Infinispan Integrations

Quarkus, Spring Boot, Vert.x and other frameworks are featured in the Infinispan demos.

Kubernetes Operator

Visit the Infinispan Operator Guide and learn how to deploy and scale Infinispan on Kubernetes or OpenShift.

Remote Clients

Try the Infinispan REST API and check out different Hot Rod clients to use Infinispan with other programming languages.