diff --git a/bom/application/pom.xml b/bom/application/pom.xml index 4141d71810dc3..6b30f75f4ea2c 100644 --- a/bom/application/pom.xml +++ b/bom/application/pom.xml @@ -128,7 +128,7 @@ 5.7.2 6.14.2 3.20.2 - 12.1.4.Final + 12.1.5.Final 4.4.1.Final 2.9.1 4.1.65.Final diff --git a/docs/src/main/asciidoc/infinispan-client.adoc b/docs/src/main/asciidoc/infinispan-client.adoc index 224bb67112298..1799d34353882 100644 --- a/docs/src/main/asciidoc/infinispan-client.adoc +++ b/docs/src/main/asciidoc/infinispan-client.adoc @@ -13,6 +13,7 @@ provides functionality to allow the client that can connect to said server when Check out the https://infinispan.org/documentation[Infinispan documentation] to find out more about the Infinispan project, in particular the https://infinispan.org/docs/stable/titles/hotrod_java/hotrod_java.html[Hot Rod Java client guide]. + == Solution We recommend that you follow the instructions in the next sections and create the application step by step. @@ -43,15 +44,70 @@ This will add the following to your pom.xml ---- The Infinispan client is configurable in the `application.properties` file that can be -provided in the `src/main/resources` directory. These are the properties that -can be configured in this file: - -include::{generated-dir}/config/quarkus-infinispan-client.adoc[opts=optional, leveloffset=+1] +provided in the `src/main/resources` directory. It is also possible to configure a `hotrod-client.properties` as described in the Infinispan user guide. Note that the `hotrod-client.properties` values overwrite any matching property from the other configuration values (eg. near cache). This properties file is build time only and if it is changed, requires a full rebuild. +== Running and connecting to Infinispan +If you are new to Infinispan, check the 5 minutes https://infinispan.org/get-started/[Getting stated with Infinispan] tutorial to +learn how to run a server locally. + +From Infinispan 12, authentication and authorization are enabled implicitly. Create a user named `admin` to implicitly have a user with the admin role. + +If you are running a container, passing the USER="admin" and PASS="password" will make the trick. + +If you are running a downloaded distribution, use the Command Line Tool from the downloaded server folder. +[source,bash] +---- +./bin/cli.sh user create admin -p password +---- + +Once your Infinispan Server is running, connect to the Infinispan Server witIh these properties. + +[source,properties] +---- +# Your configuration properties +quarkus.infinispan-client.server-list=localhost:11222 + +# Authentication +quarkus.infinispan-client.auth-username=admin +quarkus.infinispan-client.auth-password=password + +## Docker 4 Mac workaround +quarkus.infinispan-client.client-intelligence=BASIC +---- + +== Authentication + +This chart illustrates what mechanisms have been verified to be working properly with +the Quarkus Infinispan Client extension. + +.Mechanisms +|=== +| Name | Verified + +| DIGEST-MD5 +| [green]*Y* + +| PLAIN +| [green]*Y* + +| SCRAM +| [red]*N* + +| EXTERNAL +| [green]*Y* + +| GSSAPI +| [red]*N* + +| Custom +| [red]*N* + +|=== + == Serialization (Key Value types support) By default the client will support keys and values of the following types: byte[], @@ -94,12 +150,19 @@ public class Book { } ---- -Serialization of user types uses a library based on protobuf, called Protostream. +Serialization of user types uses a library based on protobuf, +called https://github.com/infinispan/protostream[Protostream]. + +[TIP] +Infinispan caches can store keys and values in different encodings, but the recommended way +is https://developers.google.com/protocol-buffers[Protobuf]. +The https://infinispan.org/docs/stable/titles/encoding/encoding.html[Marshalling and Encoding] guide +describes how Infinispan encodes data and explains how to use Protobuf and Protostream in detail. === 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 +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: @@ -159,21 +222,25 @@ Here is an example of how the preceding classes should be changed: 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 `SerializationContextInitializer` interface with an annotation +Then all that is required is a very simple `GeneratedSchema` interface with an annotation on it to specify configuration settings -.BookContextInitializer.java +.BooksSchema.java [source,java] ---- -import org.infinispan.protostream.SerializationContextInitializer; +import org.infinispan.protostream.GeneratedSchema; import org.infinispan.protostream.annotations.AutoProtoSchemaBuilder; import org.infinispan.protostream.types.java.math.BigDecimalAdapter; @AutoProtoSchemaBuilder(includeClasses = { Book.class, Author.class, BigDecimalAdapter.class }, schemaPackageName = "book_sample") -interface BookContextInitializer extends SerializationContextInitializer { +interface BookStoreSchema extends GeneratedSchema { } ---- +[TIP] +Protostream provides default Protobuf mappers for commonly used types as `BigDecimal`, +included under 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 utilize querying, you must know the generated package. @@ -357,6 +424,27 @@ annotation is not required and if it is not supplied, the default cache will be NOTE: Other types may be supported for injection, please see other sections for more information +=== Registering Protobuf Schemas with Infinispan Server + +One the serialization on the client guide is done, you must register Protobuf schemas +with Infinispan Server if you want to perform queries or convert from `Protobuf` to other media types +such as `json`. + +[TIP] +If you log to the Infinispan Console for a local running server in `http://localhost:11222`, +you can check the schemas that exist under the `Schemas` tab. + +The `quarkus.infinispan-client.use-schema-upload` property is `true` by default, so the extension +will take care of the schema upload to Infinispan. This is very useful for development mode. +However, if you need to deal yourself with the schema evolution over time, +turn the property to 'false' for production environments. +Use the https://infinispan.org/docs/infinispan-operator/master/operator.html[Infinispan Operator] +for Kubernetes deployments, or the Infinispan Web Console, the +https://infinispan.org/docs/stable/titles/rest/rest.html#rest_v2_protobuf_schemas[REST API] or the +https://infinispan.org/docs/stable/titles/encoding/encoding.html#registering-sci-remote-caches_marshalling[Hot Rod Java Client] +for any other uses cases. + + == Querying The Infinispan client supports both indexed and non indexed querying as long as the @@ -407,37 +495,15 @@ and/or keystore. This is further detailed https://infinispan.org/docs/stable/tit The Infinispan Client extension enables SSL by default. You can read more about this at link:native-and-ssl[Using SSL With Native Executables]. -== Authentication - -This chart illustrates what mechanisms have been verified to be working properly with -the Quarkus Infinispan Client extension. - -.Mechanisms -|=== -| Name | Verified - -| DIGEST-MD5 -| [green]*Y* - -| PLAIN -| [green]*Y* - -| EXTERNAL -| [green]*Y* - -| GSSAPI -| [red]*N* - -| Custom -| [red]*N* - -|=== - The guide for configuring these can be found https://infinispan.org/docs/stable/titles/hotrod_java/hotrod_java.html#hotrod_authentication[here]. -However you need to configure these through the `hotrod-client.properties` file if using Dependency Injection. +However, you need to configure these through the `hotrod-client.properties` file if using Dependency Injection. == 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! + +== Configuration Reference + +include::{generated-dir}/config/quarkus-infinispan-client.adoc[opts=optional, leveloffset=+1] \ No newline at end of file diff --git a/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/InfinispanClientProcessor.java b/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/InfinispanClientProcessor.java index 30fb5c4add76c..6ea927adcffb9 100644 --- a/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/InfinispanClientProcessor.java +++ b/extensions/infinispan-client/deployment/src/main/java/io/quarkus/infinispan/client/deployment/InfinispanClientProcessor.java @@ -22,12 +22,7 @@ import org.infinispan.client.hotrod.logging.LogFactory; import org.infinispan.commons.marshall.ProtoStreamMarshaller; import org.infinispan.commons.util.Util; -import org.infinispan.protostream.BaseMarshaller; -import org.infinispan.protostream.EnumMarshaller; -import org.infinispan.protostream.FileDescriptorSource; -import org.infinispan.protostream.MessageMarshaller; -import org.infinispan.protostream.RawProtobufMarshaller; -import org.infinispan.protostream.SerializationContextInitializer; +import org.infinispan.protostream.*; import org.jboss.jandex.AnnotationInstance; import org.jboss.jandex.AnnotationTarget; import org.jboss.jandex.ClassInfo; @@ -148,7 +143,10 @@ InfinispanPropertiesBuildItem setup(ApplicationArchivesBuildItem applicationArch InfinispanClientProducer.handleProtoStreamRequirements(properties); Collection initializerClasses = index.getAllKnownImplementors(DotName.createSimple( - SerializationContextInitializer.class.getName())); + GeneratedSchema.class.getName())); + initializerClasses + .addAll(index.getAllKnownImplementors(DotName.createSimple(GeneratedSchema.class.getName()))); + Set initializers = new HashSet<>(initializerClasses.size()); for (ClassInfo ci : initializerClasses) { Class initializerClass = Thread.currentThread().getContextClassLoader().loadClass(ci.toString()); diff --git a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java index 27db928910843..28b2710203d28 100644 --- a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java +++ b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientProducer.java @@ -43,6 +43,7 @@ public class InfinispanClientProducer { private static final Log log = LogFactory.getLog(InfinispanClientProducer.class); + public static final String USE_SCHEMA_UPLOAD = "useSchemaUpload"; public static final String PROTOBUF_FILE_PREFIX = "infinispan.client.hotrod.protofile."; public static final String PROTOBUF_INITIALIZERS = "infinispan.client.hotrod.proto-initializers"; @@ -56,41 +57,39 @@ public class InfinispanClientProducer { private void initialize() { log.debug("Initializing CacheManager"); - Configuration conf; if (properties == null) { - // We already loaded and it wasn't present - so use an empty config - conf = new ConfigurationBuilder().build(); - } else { - conf = builderFromProperties(properties).build(); + // We already loaded and it wasn't present - so don't initialize the cache manager + return; } - cacheManager = new RemoteCacheManager(conf); - // TODO: do we want to automatically register all the proto file definitions? - RemoteCache protobufMetadataCache = null; - - Set initializers = (Set) properties.remove(PROTOBUF_INITIALIZERS); - if (initializers != null) { - for (SerializationContextInitializer initializer : initializers) { - if (protobufMetadataCache == null) { - protobufMetadataCache = cacheManager.getCache( - ProtobufMetadataManagerConstants.PROTOBUF_METADATA_CACHE_NAME); - } - protobufMetadataCache.put(initializer.getProtoFileName(), initializer.getProtoFile()); - } - } + Configuration conf = builderFromProperties(properties).build(); + cacheManager = new RemoteCacheManager(conf); - for (Map.Entry property : properties.entrySet()) { - Object key = property.getKey(); - if (key instanceof String) { - String keyString = (String) key; - if (keyString.startsWith(InfinispanClientProducer.PROTOBUF_FILE_PREFIX)) { - String fileName = keyString.substring(InfinispanClientProducer.PROTOBUF_FILE_PREFIX.length()); - String fileContents = (String) property.getValue(); + if (properties.containsKey(USE_SCHEMA_UPLOAD) && (Boolean) properties.get(USE_SCHEMA_UPLOAD)) { + RemoteCache protobufMetadataCache = null; + Set initializers = (Set) properties.remove(PROTOBUF_INITIALIZERS); + if (initializers != null) { + for (SerializationContextInitializer initializer : initializers) { if (protobufMetadataCache == null) { protobufMetadataCache = cacheManager.getCache( ProtobufMetadataManagerConstants.PROTOBUF_METADATA_CACHE_NAME); } - protobufMetadataCache.put(fileName, fileContents); + protobufMetadataCache.put(initializer.getProtoFileName(), initializer.getProtoFile()); + } + } + for (Map.Entry property : properties.entrySet()) { + Object key = property.getKey(); + if (key instanceof String) { + String keyString = (String) key; + if (keyString.startsWith(InfinispanClientProducer.PROTOBUF_FILE_PREFIX)) { + String fileName = keyString.substring(InfinispanClientProducer.PROTOBUF_FILE_PREFIX.length()); + String fileContents = (String) property.getValue(); + if (protobufMetadataCache == null) { + protobufMetadataCache = cacheManager.getCache( + ProtobufMetadataManagerConstants.PROTOBUF_METADATA_CACHE_NAME); + } + protobufMetadataCache.put(fileName, fileContents); + } } } } @@ -210,6 +209,14 @@ private ConfigurationBuilder builderFromProperties(Properties properties) { properties.put(ConfigurationProperties.TRUST_STORE_TYPE, infinispanClientRuntimeConfig.trustStoreType.get()); } + if (infinispanClientRuntimeConfig.serverList.isPresent()) { + properties.put(ConfigurationProperties.SERVER_LIST, infinispanClientRuntimeConfig.serverList.get()); + } + + if (infinispanClientRuntimeConfig.useSchemaUpload.isPresent()) { + properties.put(USE_SCHEMA_UPLOAD, infinispanClientRuntimeConfig.useSchemaUpload.get()); + } + builder.withProperties(properties); return builder; diff --git a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java index b24149963d3de..51b0d79b09e77 100644 --- a/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java +++ b/extensions/infinispan-client/runtime/src/main/java/io/quarkus/infinispan/client/runtime/InfinispanClientRuntimeConfig.java @@ -2,6 +2,10 @@ import java.util.Optional; +import javax.net.ssl.SSLContext; +import javax.security.auth.callback.Callback; +import javax.security.auth.callback.CallbackHandler; + import io.quarkus.runtime.annotations.ConfigItem; import io.quarkus.runtime.annotations.ConfigPhase; import io.quarkus.runtime.annotations.ConfigRoot; @@ -18,20 +22,43 @@ public class InfinispanClientRuntimeConfig { @ConfigItem public Optional serverList; + // @formatter:off + /** + * 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'. + */ + // @formatter:on + @ConfigItem(defaultValue = "true") + Optional useSchemaUpload; + + // @formatter:off /** * Sets client intelligence used by authentication + * Available values: + * * `BASIC` - Means that the client doesn't handle server topology changes and therefore will only used 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. */ - @ConfigItem + // @formatter:on + @ConfigItem(defaultValue = "HASH_DISTRIBUTION_AWARE") Optional clientIntelligence; + // @formatter:off /** - * Enables or disables authentication + * Enables or disables authentication. Set it up to false for not secured Infinispan Server + * deployments. Default is 'true'. */ - @ConfigItem - Optional useAuth; + // @formatter:on + @ConfigItem(defaultValue = "true") + Optional useAuth; /** - * Sets user name used by authentication + * Sets user name used by authentication. */ @ConfigItem Optional authUsername; @@ -45,47 +72,58 @@ public class InfinispanClientRuntimeConfig { /** * Sets realm used by authentication */ - @ConfigItem + @ConfigItem(defaultValue = "default") Optional authRealm; /** * Sets server name used by authentication */ - @ConfigItem + @ConfigItem(defaultValue = "infinispan") Optional authServerName; /** - * Sets client subject used by authentication + * Sets client subject, necessary for those SASL mechanisms which require it to access client credentials. */ @ConfigItem Optional authClientSubject; /** - * Sets callback handler used by authentication + * Specifies a {@link CallbackHandler} to be used during the authentication handshake. + * The {@link Callback}s that need to be handled are specific to the chosen SASL mechanism. */ @ConfigItem Optional authCallbackHandler; + // @formatter:off /** - * Sets SASL mechanism used by authentication + * 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. */ - @ConfigItem + // @formatter:on + @ConfigItem(defaultValue = "DIGEST-MD5") Optional saslMechanism; /** - * Sets the trust store path + * Specifies the filename of a truststore to use to create the {@link SSLContext}. + * You also need to specify a trustStorePassword. + * Setting this property also implicitly enables SSL/TLS. */ @ConfigItem Optional trustStore; /** - * Sets the trust store password + * Specifies the password needed to open the truststore You also need to specify a trustStore. + * Setting this property also implicitly enables SSL/TLS. */ @ConfigItem Optional trustStorePassword; /** - * Sets the trust store type + * Specifies the type of the truststore, such as JKS or JCEKS. Defaults to JKS if trustStore is enabled. */ @ConfigItem Optional trustStoreType; diff --git a/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/BookContextInitializer.java b/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/BookStoreSchema.java similarity index 70% rename from integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/BookContextInitializer.java rename to integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/BookStoreSchema.java index fcd355b225d73..eb118804a30b3 100644 --- a/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/BookContextInitializer.java +++ b/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/BookStoreSchema.java @@ -1,10 +1,10 @@ package io.quarkus.it.infinispan.client; -import org.infinispan.protostream.SerializationContextInitializer; +import org.infinispan.protostream.GeneratedSchema; import org.infinispan.protostream.annotations.AutoProtoSchemaBuilder; import org.infinispan.protostream.types.java.math.BigDecimalAdapter; @AutoProtoSchemaBuilder(includeClasses = { Book.class, Type.class, Author.class, BigDecimalAdapter.class }, schemaPackageName = "book_sample") -interface BookContextInitializer extends SerializationContextInitializer { +interface BookStoreSchema extends GeneratedSchema { } diff --git a/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/TestServlet.java b/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/TestServlet.java index f0c49967f8c57..bec47ec793c33 100644 --- a/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/TestServlet.java +++ b/integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/TestServlet.java @@ -57,6 +57,10 @@ public class TestServlet { @Remote("default") RemoteCache cache; + @Inject + @Remote("booksOld") + RemoteCache boolsOld; + @Inject @Remote("magazine") RemoteCache magazineCache; @@ -78,9 +82,7 @@ void onStart(@Observes StartupEvent ev) { ContinuousQuery continuousQuery = Search.getContinuousQuery(cache); QueryFactory queryFactory = Search.getQueryFactory(cache); - Query query = queryFactory.from(Book.class) - .having("publicationYear").gt(2011) - .build(); + Query query = queryFactory.create("from book_sample.Book where publicationYear > 2011"); ContinuousQueryListener listener = new ContinuousQueryListener() { @Override @@ -182,7 +184,7 @@ public String queryAuthorSurname(@PathParam("id") String name) { Query query = queryFactory.from(Book.class) .having("authors.name").like("%" + name + "%") .build(); - List list = query.list(); + List list = query.execute().list(); if (list.isEmpty()) { return "No one found for " + name; } @@ -202,7 +204,7 @@ public String ickleQueryAuthorSurname(@PathParam("id") String name) { ensureStart(); QueryFactory queryFactory = Search.getQueryFactory(cache); Query query = queryFactory.create("from book_sample.Book b where b.authors.name like '%" + name + "%'"); - List list = query.list(); + List list = query.execute().list(); if (list.isEmpty()) { return "No one found for " + name; } diff --git a/integration-tests/infinispan-client/src/main/resources/application.properties b/integration-tests/infinispan-client/src/main/resources/application.properties index ad6c22b395205..7ff4e328e8dd3 100644 --- a/integration-tests/infinispan-client/src/main/resources/application.properties +++ b/integration-tests/infinispan-client/src/main/resources/application.properties @@ -1,4 +1,5 @@ quarkus.infinispan-client.server-list=localhost:11232 +quarkus.infinispan-client.use-auth=false quarkus.infinispan-client.trust-store=src/main/resources/server.p12 quarkus.infinispan-client.trust-store-password=changeit quarkus.infinispan-client.trust-store-type=PKCS12