Using Hot Rod Java clients

Hot Rod is a binary TCP protocol that Infinispan offers high-performance client-server interactions with the following capabilities:

Hot Rod clients use intelligence mechanisms to efficiently send requests to Infinispan Server clusters. By default, the Hot Rod protocol has the HASH_DISTRIBUTION_AWARE intelligence mechanism enabled.

Clients do not receive topology change events for Infinispan clusters, such as nodes joining or leaving, and use only the list of Infinispan Server network locations that you add to the client configuration.

Clients receive and store topology change events for Infinispan clusters to dynamically keep track of Infinispan Servers on the network.

To receive cluster topology, clients need the network location, either IP address or host name, of at least one Hot Rod server at startup. After the client connects, Infinispan Server transmits the topology to the client. When Infinispan Server nodes join or leave the cluster, Infinispan transmits an updated topology to the client.

Clients receive and store topology change events for Infinispan clusters in addition to hashing information that enables clients to identify which nodes store specific keys.

For example, consider a put(k,v) operation. The client calculates the hash value for the key so it can locate the exact Infinispan Server node on which the data resides. Clients can then connect directly to that node to perform read and write operations.

The benefit of HASH_DISTRIBUTION_AWARE intelligence is that Infinispan Server does not need to look up values based on key hashes, which uses less server-side resources. Another benefit is that Infinispan Server responds to client requests more quickly because they do not need to make additional network roundtrips.

By default, Hot Rod client uses the intelligence that you configure globally for all the Infinispan clusters.

When you configure Hot Rod client to use multiple Infinispan clusters you can use different intelligence for each of the clusters.

If a server does not report the topology as BASIC, or the client is unable to connect to a server due to network issues, the client will mark the server as failed. A client does not attempt to connect to a server marked as failed until the client receives an updated topology. Because BASIC topology never sends an update, the client will not re-attempt connection.

To avoid such a situation, you can use the serverFailureTimeout setting that clears the failed server status after a defined period of time. Infinispan will try to reconnect to the server after the defined timeout. If the server is still unreachable, it is marked as failed again and the connection will be re-attempted after the defined timeout. You can disabled reconnection attempts by setting the serverFailureTimeout value to -1.

Hot Rod Java clients balance requests to Infinispan Server clusters so that read and write operations are spread across nodes.

Clients that use BASIC or TOPOLOGY_AWARE intelligence use request balancing for all requests. Clients that use HASH_DISTRIBUTION_AWARE intelligence send requests directly to the node that stores the desired key. If the node does not respond, the clients then fall back to request balancing.

The default balancing strategy is round-robin, so Hot Rod clients perform request balancing as in the following example where s1, s2, s3 are nodes in a Infinispan cluster:

You can use custom FailoverRequestBalancingStrategy implementations if you add your class in the Hot Rod client configuration.

Hot Rod clients can automatically failover when Infinispan cluster topologies change. For instance, Hot Rod clients that are topology-aware can detect when one or more Infinispan servers fail.

In addition to failover between clustered Infinispan servers, Hot Rod clients can failover between Infinispan clusters.

For example, you have a Infinispan cluster running in New York (NYC) and another cluster running in London (LON). Clients sending requests to NYC detect that no nodes are available so they switch to the cluster in LON. Clients then maintain connections to LON until you manually switch clusters or failover happens again.

Conditional operations, such as putIfAbsent(), replace(), remove(), have strict method return guarantees. Likewise, some operations can require previous values to be returned.

Even though Hot Rod clients can failover, you should use transactional caches to ensure that operations do not partially complete and leave conflicting entries on different nodes.

Infinispan Server allows you to connect Hot Rod clients with different versions. For instance during a migration or upgrade to your Infinispan cluster, the Hot Rod client version might be a lower Infinispan version than Infinispan Server.

Hot Rod protocol version 3.x automatically negotiates the highest version possible for clients with Infinispan Server.

Clients that use a Hot Rod protocol version that is higher than the Infinispan Server version must set the infinispan.client.hotrod.protocol_version property.

Configure Project Object Model (POM) files in your project to use Infinispan dependencies for embedded caches, Hot Rod clients, and other capabilities.

The following example shows the Infinispan version and BOM:

Add Infinispan artifacts as dependencies to your pom.xml as required.

Add Hot Rod Java client dependencies to include it in your project.

Infinispan Server Requirements

Configure Hot Rod Java client connections to Infinispan Server.

You can also configure Hot Rod client connections with URIs as follows:

If the hotrod-client.properties file is not on the application classpath then you need to specify the location, as in the following example:

Infinispan Server uses different mechanisms to authenticate Hot Rod client connections.

The BasicCallbackHandler, as shown in the GSSAPI example, invokes the following callbacks:

Use a TokenCallbackHandler to refresh OAuth2 tokens before they expire, as in the following example:

Hot Rod clients set up a default CallbackHandler to pass credentials to SASL mechanisms. In some cases you might need to provide a custom CallbackHandler, as in the following example:

Infinispan Server can enforce SSL/TLS encryption and present Hot Rod clients with certificates to establish trust and negotiate secure connections.

To verify certificates issued to Infinispan Server, Hot Rod clients require either the full certificate chain or a partial chain that starts with the Root CA. You provide server certificates to Hot Rod clients as trust stores.

By default, Hot Rod clients will also perform hostname validation by matching the dNSName or iPAddress or both types contained by the server certificate’s subjectAltName extension with the expected hostname.

Add a client trust store to the $ISPN_HOME/server/conf directory and configure Infinispan Server to use it, if necessary.

Hot Rod Java clients can provide statistics that include remote cache and near-cache hits and misses as well as connection pool usage.

When you configure OpenTelemetry tracing on both the client VM and the Infinispan Server, the Hot Rod client enables automatic correlation of tracing spans between the client application and the Infinispan Server.

Near caches are local to Hot Rod clients and store recently used data so that every read operation does not need to traverse the network, which significantly increases performance.

Near caches:

You should always use bounded near caches by specifying the maximum number of entries they can contain. When near caches reach the maximum number of entries, eviction automatically takes place to remove older entries. This means you do not need to manually keep the cache size within the boundaries of the client JVM.

Bloom filters optimize performance for write operations by reducing the total number of invalidation messages.

Bloom filters:

To avoid sending data unnecessarily, write operations on remote caches return null instead of previous values.

For example, the following method calls do not return previous values for keys:

You can, however, change the default behavior so your invocations return previous values for keys.

Use the Infinispan Hot Rod API to create remote caches on Infinispan Server from Java, C++, .NET/C#, JS clients and more.

This procedure shows you how to use Hot Rod Java clients that create remote caches on first access. You can find code examples for other Hot Rod clients in the Infinispan Tutorials.

Hot Rod Java clients collect and expose metrics related to the connection pool and cache requests. Implement the SPI RemoteCacheManagerMetricsRegistry to register metrics in the collector of your choice. Infinispan provides an implementation using Micrometer.

You can configure generic implementation of Hot Rod client metrics or the provided Micrometer implementation as shown in the following examples.

The collection methods keySet, entrySet and values are backed by the remote cache. That is that every method is called back into the RemoteCache. This is useful as it allows for the various keys, entries or values to be retrieved lazily, and not requiring them all be stored in the client memory at once if the user does not want.

These collections adhere to the Map specification being that add and addAll are not supported but all other methods are supported.

One thing to note is the Iterator.remove and Set.remove or Collection.remove methods require more than 1 round trip to the server to operate. You can check out the RemoteCache Javadoc to see more details about these and the other methods.

The iterator method of these collections uses retrieveEntries internally, which is described below. If you notice retrieveEntries takes an argument for the batch size. There is no way to provide this to the iterator. As such the batch size can be configured via system property infinispan.client.hotrod.batch_size or through the ConfigurationBuilder when configuring the RemoteCacheManager.

Also the retrieveEntries iterator returned is Closeable as such the iterators from keySet, entrySet and values return an AutoCloseable variant. Therefore you should always close these `Iterator`s when you are done with them.

What if I want a deep copy and not a backing collection?

Previous version of RemoteCache allowed for the retrieval of a deep copy of the keySet. This is still possible with the new backing map, you just have to copy the contents yourself. Also you can do this with entrySet and values, which we didn’t support before.

Infinispan provides a remote iterator API to retrieve entries where memory resources are constrained or if you plan to do server-side filtering or conversion.

Use the MetadataValue interface for versioned operations.

The following example shows a remove operation that occurs only if the version of the value for the entry is unchanged:

Infinispan provides a Streaming API that implements methods that return instances of InputStream and OutputStream so you can stream large objects between Hot Rod clients and Infinispan servers.

Consider the following example of a large object:

You could read the object through streaming as follows:

The InputStream returned by the RemoteStreamingCache.get(K key) method implements the VersionedMetadata interface, so you can retrieve version and expiration information as follows:

The CounterManager interface is the entry point to define, retrieve and remove counters.

Hot Rod clients can retrieve the CounterManager interface as in the following example:

Java Hot Rod clients can register listeners to receive cache-entry level events. Cache entry created, modified and removed events are supported.

Creating a client listener is very similar to embedded listeners, except that different annotations and event classes are used. Here’s an example of a client listener that prints out each event received:

ClientCacheEntryCreatedEvent and ClientCacheEntryModifiedEvent instances provide information on the affected key, and the version of the entry. This version can be used to invoke conditional operations on the server, such as replaceWithVersion or removeWithVersion.

ClientCacheEntryRemovedEvent events are only sent when the remove operation succeeds. In other words, if a remove operation is invoked but no entry is found or no entry should be removed, no event is generated. Users interested in removed events, even when no entry was removed, can develop event customization logic to generate such events. More information can be found in the customizing client events section.

All ClientCacheEntryCreatedEvent, ClientCacheEntryModifiedEvent and ClientCacheEntryRemovedEvent event instances also provide a boolean isCommandRetried() method that will return true if the write command that caused this had to be retried again due to a topology change. This could be a sign that this event has been duplicated or another event was dropped and replaced (eg: ClientCacheEntryModifiedEvent replaced ClientCacheEntryCreatedEvent).

Once the client listener implementation has been created, it needs to be registered with the server. To do so, execute:

You can configure and use Hot Rod clients in JTA Transactions.

To participate in a transaction, the Hot Rod client requires the TransactionManager with which it interacts and whether it participates in the transaction through the Synchronization or XAResource interface.

The MultimapCacheManager interface is the entry point to get a RemoteMultimapCache.

Hot Rod clients can retrieve the MultimapCacheManager interface as in the following example:

Run Infinispan Server instances using Testcontainers for faster, simpler JUnit tests.

The Infinispan Server test container is based on the official container image provided by Infinispan.