Infinispan Client Extension Reference Guide

Infinispan is a distributed, in-memory key/value store that provides Quarkus applications with a highly configurable and independently scalable data layer. This extension gives you client functionality that connects applications running on Quarkus with remote Infinispan clusters. To get started with Infinispan, we recommend:

  1. Following the Get Started Tutorial (5 minutes).

  2. Running the remote cache simple code tutorials.

Learn more in the Infinispan documentation.


Run the following command in the base directory of your Quarkus project to add the infinispan-client extension:

quarkus extension add 'infinispan-client'
./mvnw quarkus:add-extension -Dextensions='infinispan-client'
./gradlew addExtension --extensions='infinispan-client'

This command adds the following dependency to your build file:

implementation 'io.quarkus:quarkus-infinispan-client'
annotationProcessor 'org.infinispan.protostream:protostream-processor:{infinispan-protostream-version}' (1)
1 Mandatory in the Gradle build to enable the generation of the files in the annotation based serialization

Connection to Infinispan

Running the server

You need at least one running instance of the Infinispan Server.

Development mode

If you are running a Docker instance, you can use Infinispan Dev Services and connect without configuration.

If you want to run the server yourself using Docker, check out the 5-minute Getting stated with Infinispan tutorial to run Infinispan Server

You can also download ${infinispan.version} Server bare metal distribution and run the following command from the distribution folder.

$ ./bin/

Infinispan Server enables authentication and security authorization by default, so you need to create a user with permissions.

  • If you run the Infinispan Server image, pass the USER="admin" and PASS="password" parameters.

  • If you run the bare metal distribution, use the Command Line Interface (CLI) as follows:

    $ ./bin/ user create admin -p password
Production mode

In Kubernetes, we recommend the Infinispan Operator. Additionally, grab a look to the Cross Site Replication tutorial. You will learn how to run two separate Infinispan Clusters with docker compose (for local dev) and the Operator.

Configuring the connection

If you are running an Infinispan Server, add the following properties to connect in the file in the src/main/resources directory.

quarkus.infinispan-client.hosts=localhost:11222 (1)

quarkus.infinispan-client.username=admin (2)
quarkus.infinispan-client.password=password (3)

quarkus.infinispan-client.client-intelligence=BASIC (4)
1 Sets Infinispan Server address list, separated with commas
2 Sets the authentication username
3 Sets the authentication password
4 Sets the client intelligence. Use BASIC as a workaround if using Docker for Mac.

Alternatively, you can use uri connection by providing a single connection property

quarkus.infinispan-client.uri=hotrod://admin:password@localhost:11222 (1)
quarkus.infinispan-client.client-intelligence=BASIC (2)
1 Sets Infinispan URI connection. The following properties will be ignored: hosts, username and password.
2 Sets the client intelligence. Use BASIC as a workaround if using Docker for Mac

Use Infinispan Dev Services to run a server and connect without configuration.

Infinispan Health Check

If you are using the quarkus-smallrye-health extension, the Infinispan client extensions will automatically add a readiness health check to validate the connection.

When you access the /q/health/ready endpoint of your application you will have information about the server connection and available caches.

This behavior can be disabled via the property

Tracing with OpenTelemetry

Infinispan supports instrumentation of the server via OpenTelemetry. Having the quarkus-opentelemetry extension will propagate the traces from the Infinispan Client to the Server. This behavior can be disabled via the property quarkus.infinispan-client.tracing.propagation.enabled

Creating caches from the client

When a cache is accessed from the client, if the cache does not exist in the Infinispan Server and you want to create it on first access, use one of the following properties:

quarkus.infinispan-client.cache.books.configuration-uri=cacheConfig.json (1)
quarkus.infinispan-client.cache.magazine.configuration=<distributed-cache><encoding media-type="application/x-protostream"/></distributed-cache> (2)
1 The file name located under the resources folder that contains the configuration of the 'books' cache
2 The configuration in xml of the 'magazine' (yaml and json are also supported)

If both configuration-uri and configuration are configured for the same cache with the same Quarkus profile, configuration-uri gets preference over configuration.

Cache configuration can be provided in XML, JSON or YAML. Use the Infinispan Console and the cache configuration Wizard to learn more about Infinispan Caches and create guided configurations.

If nothing is configured for a particular cache, it will be created with the following basic configuration:

    <encoding media-type="application/x-protostream"/>
    "distributed-cache": {
        "encoding": {
            "media-type": "application/x-protostream"
    mediaType: "application/x-protostream"

Authentication mechanisms

You can use the following authentication mechanisms with the Infinispan client:


  • PLAIN (recommended only in combination with TLS encryption)


Other authentication mechanisms, such as SCRAM and GSSAPI, are not yet verified with the Infinispan client.

You can find more information on configuring authentication in Hot Rod Endpoint Authentication Mechanisms.

You must configure authentication in the file if you use Dependency Injection.

Serialization (Key Value types support)

By default, the client will support keys and values of the following types: byte[], primitive wrappers (e.g. Integer, Long, Double), String, Date and Instant. User types require some additional steps that are detailed here. Let’s say we have the following user classes:
public class Author {
   private final String name;
   private final String surname;

   public Author(String name, String surname) { = Objects.requireNonNull(name);
      this.surname = Objects.requireNonNull(surname);
   // Getter/Setter/equals/hashCode/toString omitted
public class Book {
   private final String title;
   private final String description;
   private final int publicationYear;
   private final Set<Author> authors;
   private final BigDecimal price;

   public Book(String title, String description, int publicationYear, Set<Author> authors, BigDecimal price) {
      this.title = Objects.requireNonNull(title);
      this.description = Objects.requireNonNull(description);
      this.publicationYear = publicationYear;
      this.authors = Objects.requireNonNull(authors);
      this.price = price;
   // Getter/Setter/equals/hashCode/toString omitted

Serialization of user types uses a library based on protobuf, called Protostream.

Infinispan caches can store keys and values in different encodings, but recommend using Protocol Buffers (Protobuf).

For more information see our Cache Encoding and Marshalling guide.

Annotation based Serialization

This can be done automatically by adding protostream annotations to your user classes. In addition, a single Initializer annotated interface is required which controls how the supporting classes are generated.

Here is an example of how the preceding classes should be changed:
    public Author(String name, String surname) { = Objects.requireNonNull(name);
        this.surname = Objects.requireNonNull(surname);

    @ProtoField(number = 1)
    public String getName() {
        return name;

    @ProtoField(number = 2)
    public String getSurname() {
        return surname;
    public Book(String title, String description, int publicationYear, Set<Author> authors) {
        this.title = Objects.requireNonNull(title);
        this.description = Objects.requireNonNull(description);
        this.publicationYear = publicationYear;
        this.authors = Objects.requireNonNull(authors);

    @ProtoField(number = 1)
    public String getTitle() {
        return title;

    @ProtoField(number = 2)
    public String getDescription() {
        return description;

    @ProtoField(number = 3, defaultValue = "-1")
    public int getPublicationYear() {
        return publicationYear;

    @ProtoField(number = 4)
    public Set<Author> getAuthors() {
        return authors;

If your classes have only mutable fields, then the ProtoFactory annotation is not required, assuming your class has a no arg constructor.

Then all that is required is a very simple GeneratedSchema interface with an annotation on it to specify configuration settings
import org.infinispan.protostream.GeneratedSchema;
import org.infinispan.protostream.annotations.AutoProtoSchemaBuilder;

@AutoProtoSchemaBuilder(includeClasses = { Book.class, Author.class, BigDecimalAdapter.class }, schemaPackageName = "book_sample")
interface BookStoreSchema extends GeneratedSchema {

Protostream provides default Protobuf mappers for commonly used types as BigDecimal, included in the org.infinispan.protostream.types package.

So in this case we will automatically generate the marshaller and schemas for the included classes and place them in the schema package automatically. The package does not have to be provided, but if you use Infinispan search capabilities, you must know the generated package.

In Quarkus the schemaFileName and schemaFilePath attributes should NOT be set on the AutoProtoSchemaBuilder annotation. Setting either attributes causes native runtime errors.

Custom serialization

The previous method is suggested for any case when the user can annotate their classes. Unfortunately the user may not be able to annotate all classes they will put in the cache. In this case you must define your schema and create your own Marshaller(s) yourself.

Protobuf schema

You can supply a protobuf schema through either one of two ways.

  1. Proto File
    You can put the .proto file in the META-INF directory of the project. These files will automatically be picked up at initialization time.

    package book_sample;
    message Book {
      required string title = 1;
      required string description = 2;
      required int32 publicationYear = 3; // no native Date type available in Protobuf
      repeated Author authors = 4;
      requited double price = 5; // no native BigDecimal type available in Protobuf
    message Author {
      required string name = 1;
      required string surname = 2;
  2. In Code
    Or you can define the proto schema directly in user code by defining a produced bean of type org.infinispan.protostream.FileDescriptorSource.

       FileDescriptorSource bookProtoDefinition() {
          return FileDescriptorSource.fromString("library.proto", "package book_sample;\n" +
                "\n" +
                "message Book {\n" +
                "  required string title = 1;\n" +
                "  required string description = 2;\n" +
                "  required int32 publicationYear = 3; // no native Date type available in Protobuf\n" +
                "\n" +
                "  repeated Author authors = 4;\n" +
                "\n" +
                "  required double price = 5; // no native BigDecimal type available in Protobuf\n" +
                "}\n" +
                "\n" +
                "message Author {\n" +
                "  required string name = 1;\n" +
                "  required string surname = 2;\n" +
User Marshaller

The last thing to do is to provide a org.infinispan.protostream.MessageMarshaller implementation for each user class defined in the proto schema. This class is then provided via @Produces in a similar fashion to the code based proto schema definition above.

Here is the Marshaller class for our Author & Book classes.

The type name must match the <protobuf package>.<protobuf message> exactly!
public class AuthorMarshaller implements MessageMarshaller<Author> {

   public String getTypeName() {
      return "book_sample.Author";

   public Class<? extends Author> getJavaClass() {
      return Author.class;

   public void writeTo(ProtoStreamWriter writer, Author author) throws IOException {
      writer.writeString("name", author.getName());
      writer.writeString("surname", author.getSurname());

   public Author readFrom(ProtoStreamReader reader) throws IOException {
      String name = reader.readString("name");
      String surname = reader.readString("surname");
      return new Author(name, surname);
public class BookMarshaller implements MessageMarshaller<Book> {

   public String getTypeName() {
      return "book_sample.Book";

   public Class<? extends Book> getJavaClass() {
      return Book.class;

   public void writeTo(ProtoStreamWriter writer, Book book) throws IOException {
      writer.writeString("title", book.getTitle());
      writer.writeString("description", book.getDescription());
      writer.writeInt("publicationYear", book.getPublicationYear());
      writer.writeCollection("authors", book.getAuthors(), Author.class);
      writer.writeDouble("price", book.getPrice().doubleValue());

   public Book readFrom(ProtoStreamReader reader) throws IOException {
      String title = reader.readString("title");
      String description = reader.readString("description");
      int publicationYear = reader.readInt("publicationYear");
      Set<Author> authors = reader.readCollection("authors", new HashSet<>(), Author.class);
      BigDecimal price = BigDecimal.valueOf(reader.readDouble("price"));
      return new Book(title, description, publicationYear, authors, price);

And you pass the marshaller by defining the following:

   MessageMarshaller authorMarshaller() {
      return new AuthorMarshaller();

   MessageMarshaller bookMarshaller() {
      return new BookMarshaller();
The above produced Marshaller method MUST return MessageMarshaller without types or else it will not be found.

Dependency Injection

As you saw above we support the user injecting Marshaller configuration. You can do the inverse with the Infinispan client extension providing injection for RemoteCacheManager and RemoteCache objects. There is one global RemoteCacheManager that takes all the configuration parameters setup in the above sections.

It is very simple to inject these components. All you need to do is to add the @Inject annotation to the field, constructor or method. In the below code we utilize field and constructor injection.
    @Inject SomeClass(RemoteCacheManager remoteCacheManager) {
       this.remoteCacheManager = remoteCacheManager;

    RemoteCache<String, Book> cache;

    RemoteCacheManager remoteCacheManager;

If you notice the RemoteCache declaration has an additional optional annotation named Remote. This is a qualifier annotation allowing you to specify which named cache that will be injected. This annotation is not required and if it is not supplied, the default cache will be injected.

Other types may be supported for injection, please see other sections for more information

Registering Protobuf Schemas with Infinispan Server

You need to register the generated Protobuf schemas with Infinispan Server to perform queries or convert from Protobuf to other media types such as JSON.

You can check the schemas that exist under the Schemas tab by logging into Infinispan Console at http://SERVER_HOST:SERVER_PORT (for example http://localhost:11222).

Check the Infinispan Dev Services Guide to connect to the Infinispan Dev Services server.

By default, Protobuf schemas generated this way will be registered by this extension when the client first connects. However, it might be required to handle the registration manually as a schema may evolve over time when used in production, so you can disable this from occurring by configuring the quarkus.infinispan-client.use-schema-registration to false.

To configure the schema manually please use Infinispan Operator for Kubernetes deployments, Infinispan Console, REST API or the Hot Rod Java Client.

Caching using annotations

The Infinispan Client extension offers a set of annotations that can be used in a CDI managed bean to enable caching abilities with Infinispan.

Caching annotations are not allowed on private methods. They will work fine with any other access modifier including package-private (no explicit modifier).


Loads a method result from the cache without executing the method body whenever possible.

When a method annotated with @CacheResult is invoked, Quarkus will use the method argument as the cache key and check in the cache whether the method has been already invoked. Methods with multiple parameters are not allowed. For composite keys, define a Protobuf schema that will hold multiple values. If a value is found in the cache, it is returned and the annotated method is never actually executed. If no value is found, the annotated method is invoked and the returned value is stored in the cache using the computed key. This annotation cannot be used on a method returning void.

Infinispan Client extension is not able yet to cache null values unlike the Quarkus-Cache extension.


Removes an entry from the cache.

When a method annotated with @CacheInvalidate is invoked, Infinispan will use the method argument as a cache key to try to remove an existing entry from the cache. If the key does not identify any cache entry, nothing will happen.


When a method annotated with @CacheInvalidateAll is invoked, Infinispan will remove all entries from the cache.


The Infinispan client supports both indexed and non-indexed search as long as the ProtoStreamMarshaller is configured above. This allows the user to query based on the properties of the proto schema. Indexed queries are preferred for performance reasons.

<distributed-cache name="books" statistics="true">
    <!-- other configuration -->
	<indexing enabled="true" storage="filesystem" startup-mode="PURGE">
  "books": {
    "distributed-cache": {
      "indexing": {
        "enabled": true,
        "storage": "filesystem",
        "startupMode": "PURGE",
        "indexed-entities": [
  # other configuration
    enabled: "true"
    storage: "filesystem"
    startupMode: "PURGE"
      - "book_sample.Book"

Query builds upon the proto definitions you can configure when setting up the ProtoStreamMarshaller. Either method of Serialization above will automatically register the schema with the server at startup, meaning that you will automatically gain the ability to query objects stored in the remote Infinispan Server.
@Indexed (1)
public class Book {

    public Book(String title, String description, int publicationYear, Set<Author> authors) {

    @ProtoField(number = 1)
    @Text (2)
    public String getTitle() {
        return title;

    @ProtoField(number = 2)
    @Keyword(projectable = true, sortable = true, normalizer = "lowercase", indexNullAs = "unnamed", norms = false) (3)
    public String getDescription() {
        return description;
1 @Indexed annotation makes the POJO indexable
2 @Basic annotation is used for indexed fields without any special transformation
3 @Keyword annotation is used to apply a normalizer to a text field

You can use either the Query DSL or the Ickle Query language with the Quarkus Infinispan client extension.

You can read more about querying in the Infinispan documentation.


Infinispan also has a notion of counters and the Quarkus Infinispan client supports them out of the box.

The Quarkus Infinispan client extension allows for Dependency Injection of the CounterManager directly. All you need to do is annotate your field, constructor or method, and you get it with no fuss. You can then use counters as you would normally.

CounterManager counterManager;

You can read more about clustered counters in the Infinispan documentation.

Near Caching

Near caching is disabled by default, but you can enable it on a per cache basic by configuring the following properties:

quarkus.infinispan-client.cache.books.near-cache-mode=INVALIDATED (1)
quarkus.infinispan-client.cache.books.near-cache-max-entries=200 (2)
quarkus.infinispan-client.cache.books.near-cache-use-bloom-filter=true (3)
1 Enables near caching for the 'books' cache by setting the mode to INVALIDATED
2 Sets the maximum number of entries that the near cache of the 'books' cache can hold before eviction occurs
3 Enables bloom filter for the 'books' cache

Bounded near caching

You should always use bounded near caches by specifying the maximum number of entries they can contain.

Bloom filters

If you need to optimize the performance for write operations by reducing the total number of invalidation messages, enable bloom filter. Bloom filters reside on Infinispan Server and keep track of the entries that the client has requested. They cannot be used with unbounded near cache: maximum number of entries must be defined when enabling bloom filters.


Encryption at this point requires additional steps to get working.

The first step is to configure the file to point to your truststore and/or keystore. This is further detailed here.

The Infinispan Client extension enables SSL/TLS by default. You can read more about this at Using SSL With Native Executables.

Additional Features

The Infinispan Client has additional features that were not mentioned here. This means this feature was not tested in a Quarkus environment, and they may or may not work. Please let us know if you need these added!

Dev Services for Infinispan

When you use the infinispan-client extension in dev mode or in test, Quarkus automatically starts an Infinispan server and configure your application.

Enabling / Disabling Dev Services for Infinispan

Learn more in the Infinispan Dev Services guide.

Shared server

Quarkus will share the Infinispan broker if you have multiple applications running in dev mode. Dev Services for Infinispan implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single broker.

Dev Services for Infinispan starts the container with the quarkus-dev-service-infinispan label which is used to identify the container.

If you need multiple (shared) Infinispan server, you can configure the quarkus.infinispan-client.devservices.service-name attribute and indicate the server name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is infinispan.

Sharing is enabled by default in dev mode, but disabled in test mode. You can disable the sharing with quarkus.infinispan-client.devservices.shared=false.

Setting the port

By default, Dev Services for Infinispan picks a random port and configures the application. You can set the port by configuring the quarkus.infinispan-client.devservices.port property.

Testing helpers

To start an Infinispan Server for your unit tests, Quarkus provides one QuarkusTestResourceLifecycleManager that relies on Infinispan Server Test Container.

  • io.quarkus.test.infinispan.client.InfinispanTestResource will start a single instance on port 11222 with user 'admin' and password 'password'.

To use them, you need to add the io.quarkus:quarkus-test-infinispan-client dependency to your pom.xml.

For more information about the usage of a QuarkusTestResourceLifecycleManager please read Quarkus test resource.

Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property



If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running.




Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.



Indicates if the Infinispan server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Infinispan starts a new container. The discovery uses the quarkus-dev-service-infinispan label. The value is configured using the service-name property. Container sharing is only used in dev mode.




The value of the quarkus-dev-service-infinispan label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services for Infinispan looks for a container with the quarkus-dev-service-infinispan label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the quarkus-dev-service-infinispan label set to the specified value. This property is used when you need multiple shared Infinispan servers.




The image to use. Note that only official Infinispan images are supported.



List of the artifacts to automatically download and add to the Infinispan server libraries. For example a Maven coordinate (org.postgresql:postgresql:42.3.1) or a dependency location url. If an invalid value is passed, the Infinispan server will throw an error when trying to start.


list of string

Add a site name to start the Infinispan Server Container with Cross Site Replication enabled (ex. lon). Cross Site Replication is the capability to connect two separate Infinispan Server Clusters that might run in different Data Centers, and configure backup caches to copy the data across the clusters with active-active or active-passive replication. See more about Cross Site Replication in the Infinispan Documentation Configure mcast-port to avoid forming a cluster with any other running Infinispan Server container.



If you are running an Infinispan Server already in docker, if the containers use the same mcastPort they will form a cluster. Set a different mcastPort to create a separate cluster in Docker (e. 46656). A common use case in a local Docker development mode, is the need of having two different Infinispan Clusters with Cross Site Replication enabled. see



Runs the Infinispan Server container with tracing enabled. Traces are disabled by default




Sets Infinispan Server otlp endpoint. Default value is http://localhost:4317




Whether a health check is published in case the smallrye-health extension is present.




Sets the bounded entry count for near cache. If this value is 0 or less near cache is disabled.




Sets the URI of the running Infinispan server to connect to. hotrod://localhost:11222@admin:password If provided hosts, username and password will be ignored.



Sets the host name/port to connect to. Each one is separated by a semicolon (eg. host1:11222;host2:11222).



Enables or disables Protobuf generated schemas upload to the server. Set it to 'false' when you need to handle the lifecycle of the Protobuf Schemas on Server side yourself. Default is 'true'.




Sets client intelligence used by authentication Available values: * BASIC - Means that the client doesn’t handle server topology changes and therefore will only use the list of servers supplied at configuration time. * TOPOLOGY_AWARE - Use this provider if you don’t want the client to present any certificates to the remote TLS host. * HASH_DISTRIBUTION_AWARE - Like TOPOLOGY_AWARE but with the additional advantage that each request involving keys will be routed to the server who is the primary owner which improves performance greatly. This is the default.




Enables or disables authentication. Set it to false when connecting to an Infinispan Server without authentication. deployments. Default is 'true'.




Sets username used by authentication.



Sets password used by authentication.



Sets realm used by authentication




Sets server name used by authentication




Sets client subject, necessary for those SASL mechanisms which require it to access client credentials.



Specifies a CallbackHandler to be used during the authentication handshake. The `Callback`s that need to be handled are specific to the chosen SASL mechanism.



Sets SASL mechanism used by authentication. Available values: * DIGEST-MD5 - Uses the MD5 hashing algorithm in addition to nonces to encrypt credentials. This is the default. * EXTERNAL - Uses client certificates to provide valid identities to Infinispan Server and enable encryption. * PLAIN - Sends credentials in plain text (unencrypted) over the wire in a way that is similar to HTTP BASIC authentication. You should use PLAIN authentication only in combination with TLS encryption.




Specifies the filename of a truststore to use to create the SSLContext. You also need to specify a trustStorePassword. Setting this property implicitly enables SSL/TLS.



Specifies the password needed to open the truststore You also need to specify a trustStore. Setting this property implicitly enables SSL/TLS.



Specifies the type of the truststore, such as JKS or JCEKS. Defaults to JKS if trustStore is enabled.



Configures the secure socket protocol. Setting this property implicitly enables SSL/TLS.



Sets the ssl provider. For example BCFIPS Setting this implicitly enables SSL/TLS.



Configures the ciphers. Setting this property implicitly enables SSL/TLS.


list of string

Whether a tracing propagation is enabled in case the Opentelemetry extension is present. By default the propagation of the context is propagated from the client to the Infinispan Server.




Cache configuration in inlined XML to create the cache on first access. Will be ignored if the configuration-uri is provided for the same cache name. An example of the user defined property: quarkus.infinispan-client.cache.bookscache.configuration=



Cache configuration file in XML whose path will be converted to URI to create the cache on first access. An example of the user defined property. cacheConfig.xml file is located in the 'resources' folder: quarkus.infinispan-client.cache.bookscache.configuration-uri=cacheConfig.xml



The maximum number of entries to keep locally for the specified cache.



Sets near cache mode used by the Infinispan Client Available values: * DISABLED - Means that near caching is disabled. This is the default value. * INVALIDATED - Means is near caching is invalidated, so when entries are updated or removed server-side, invalidation messages will be sent to clients to remove them from the near cache.


disabled, invalidated

Enables bloom filter for near caching. Bloom filters optimize performance for write operations by reducing the total number of invalidation messages.