Merge pull request quarkusio#29126 from karesti/new-query-annotations

Integrate the api dependency from Infinispan 14  (#ISPN-14268)

bom/application/pom.xml

@@ -131,7 +131,7 @@
         <junit.jupiter.version>5.9.1</junit.jupiter.version>
         <junit-pioneer.version>1.5.0</junit-pioneer.version>
         <testng.version>6.14.2</testng.version>
-        <infinispan.version>14.0.1.Final</infinispan.version>
+        <infinispan.version>14.0.2.Final</infinispan.version>
         <infinispan.protostream.version>4.5.0.Final</infinispan.protostream.version>
         <caffeine.version>3.1.1</caffeine.version>
         <netty.version>4.1.85.Final</netty.version>
@@ -5239,6 +5239,11 @@
                 <version>${smallrye-reactive-messaging.version}</version>
             </dependency>
 
+            <dependency>
+                <groupId>org.infinispan</groupId>
+                <artifactId>infinispan-api</artifactId>
+                <version>${infinispan.version}</version>
+            </dependency>
             <dependency>
                 <groupId>org.infinispan</groupId>
                 <artifactId>infinispan-core</artifactId>

docs/src/main/asciidoc/infinispan-client.adoc

@@ -100,7 +100,7 @@ to create it on first access, use one of the following properties:
 
 [source,properties]
 ----
-quarkus.infinispan-client.cache.books.configuration-uri=cacheConfig.xml <1>
+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
@@ -109,15 +109,42 @@ quarkus.infinispan-client.cache.magazine.configuration=<distributed-cache><encod
 If both `configuration-uri` and `configuration` are configured for the same cache with the same Quarkus profile,
 `configuration-uri` gets preference over `configuration`.
 
+[TIP]
+====
+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:
 
-[source, xml]
+.XML
+[source,xml,options="nowrap",subs=attributes+,role="primary"]
 ----
 <distributed-cache>
     <encoding media-type="application/x-protostream"/>
 </distributed-cache>
 ----
 
+.JSON
+[source,json,options="nowrap",subs=attributes+,role="secondary"]
+----
+{
+    "distributed-cache": {
+        "encoding": {
+            "media-type": "application/x-protostream"
+        }
+    }
+}
+----
+
+.YAML
+[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
+----
+distributedCache:
+  encoding:
+    mediaType: "application/x-protostream"
+----
+
 === Authentication mechanisms
 
 You can use the following authentication mechanisms with the Infinispan client:
@@ -130,10 +157,7 @@ Other authentication mechanisms, such as SCRAM and GSSAPI, are not yet verified
 
 You can find more information on configuring authentication in https://infinispan.org/docs/stable/titles/hotrod_java/hotrod_java.html#hotrod_endpoint_auth-hotrod-client-configuration[Hot Rod Endpoint Authentication Mechanisms].
 
-[NOTE]
-====
-You must configure authentication in the `hotrod-client.properties` file if you use Dependency Injection.
-====
+NOTE: You must configure authentication in the `hotrod-client.properties` file if you use Dependency Injection.
 
 == Serialization (Key Value types support)
 
@@ -267,10 +291,12 @@ interface BookStoreSchema extends GeneratedSchema {
 ----
 
 [TIP]
+====
 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 query capabilities, you must know the generated package.
+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.
 
 NOTE: In Quarkus the `schemaFileName` and `schemaFilePath` attributes should NOT be set on the `AutoProtoSchemaBuilder` annotation. Setting either attributes causes native runtime errors.
 
@@ -439,7 +465,8 @@ the field, constructor or method. In the below code we utilize field and constru
        this.remoteCacheManager = remoteCacheManager;
     }
 
-    @Inject @Remote("myCache")
+    @Inject
+    @Remote("myCache")
     RemoteCache<String, Book> cache;
 
     RemoteCacheManager remoteCacheManager;
@@ -491,10 +518,7 @@ If a value is found in the cache, it is returned and the annotated method is nev
 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`.
 
-[NOTE]
-====
-Infinispan Client extension is not able yet to cache `null` values unlike the Quarkus-Cache extension.
-====
+NOTE: Infinispan Client extension is not able yet to cache `null` values unlike the Quarkus-Cache extension.
 
 === @CacheInvalidate
 
@@ -510,20 +534,95 @@ When a method annotated with `@CacheInvalidateAll` is invoked, Infinispan will r
 
 == Querying
 
-The Infinispan client supports both indexed and non-indexed querying as long as the
+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.
+properties of the proto schema. *Indexed queries are preferred for performance reasons*.
+
+.XML
+[source,xml,options="nowrap",subs=attributes+,role="primary"]
+----
+<distributed-cache name="books" statistics="true">
+    <!-- other configuration -->
+	<indexing enabled="true" storage="filesystem" startup-mode="PURGE">
+		<indexed-entities>
+			<indexed-entity>book_sample.Book</indexed-entity>
+		</indexed-entities>
+	</indexing>
+</distributed-cache>
+----
+
+.JSON
+[source,json,options="nowrap",subs=attributes+,role="secondary"]
+----
+{
+  "books": {
+    "distributed-cache": {
+      ...
+      "indexing": {
+        "enabled": true,
+        "storage": "filesystem",
+        "startupMode": "PURGE",
+        "indexed-entities": [
+          "book_sample.Book"
+        ]
+      }
+    }
+  }
+}
+----
+
+.YAML
+[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
+----
+distributedCache:
+  # other configuration
+  indexing:
+    enabled: "true"
+    storage: "filesystem"
+    startupMode: "PURGE"
+    indexedEntities:
+      - "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.
 
-You can read more about https://infinispan.org/docs/stable/titles/developing/developing.html#creating_ickle_queries-querying[querying] in the Infinispan documentation.
+.Book.java
+[source,java]
+----
+@Indexed <1>
+public class Book {
+
+    @ProtoFactory
+    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.
 
+NOTE: You can read more about https://infinispan.org/docs/stable/titles/query/query.html[querying] in the Infinispan documentation.
+
+
 == Counters
 
 Infinispan also has a notion of counters and the Quarkus Infinispan client supports them out of

extensions/infinispan-client/runtime/pom.xml

@@ -90,6 +90,10 @@
             <artifactId>opentelemetry-api</artifactId>
         </dependency>
 
+        <dependency>
+            <groupId>org.infinispan</groupId>
+            <artifactId>infinispan-api</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.infinispan</groupId>
             <artifactId>infinispan-remote-query-client</artifactId>

integration-tests/infinispan-client/src/main/java/io/quarkus/it/infinispan/client/Book.java

@@ -4,12 +4,16 @@
 import java.util.Objects;
 import java.util.Set;
 
+import org.infinispan.api.annotations.indexing.Indexed;
+import org.infinispan.api.annotations.indexing.Keyword;
+import org.infinispan.api.annotations.indexing.Text;
 import org.infinispan.protostream.annotations.ProtoFactory;
 import org.infinispan.protostream.annotations.ProtoField;
 
 /**
  * @author William Burns
  */
+@Indexed
 public class Book {
     private final String title;
     private final String description;
@@ -29,11 +33,13 @@ public Book(String title, String description, int publicationYear, Set<Author> a
     }
 
     @ProtoField(number = 1)
+    @Text
     public String getTitle() {
         return title;
     }
 
     @ProtoField(number = 2)
+    @Keyword(projectable = true, sortable = true, normalizer = "lowercase", indexNullAs = "unnamed", norms = false)
     public String getDescription() {
         return description;
     }

integration-tests/infinispan-client/src/main/resources/application.properties

@@ -1,10 +1,10 @@
 quarkus.infinispan-client.cache.default.configuration-uri=cacheConfig.xml
-quarkus.infinispan-client.cache.books.configuration-uri=cacheConfig.xml
+quarkus.infinispan-client.cache.books.configuration-uri=booksIndexedConfig.json
 quarkus.infinispan-client.cache.magazine.configuration=<distributed-cache><encoding media-type="application/x-protostream"/></distributed-cache>
 quarkus.infinispan-client.cache.default.near-cache-mode=INVALIDATED
 quarkus.infinispan-client.cache.default.near-cache-max-entries=2
 quarkus.infinispan-client.cache.default.near-cache-use-bloom-filter=false
 quarkus.infinispan-client.cache.magazine.near-cache-mode=INVALIDATED
 quarkus.infinispan-client.cache.magazine.near-cache-max-entries=2
 quarkus.infinispan-client.cache.magazine.near-cache-use-bloom-filter=false
-quarkus.native.resources.includes=cacheConfig.xml
+quarkus.native.resources.includes=cacheConfig.xml,booksIndexedConfig.json

integration-tests/infinispan-client/src/main/resources/booksIndexedConfig.json

@@ -0,0 +1,16 @@
+{
+    "distributed-cache": {
+        "statistics": true,
+        "encoding": {
+            "media-type": "application/x-protostream"
+        },
+        "indexing": {
+            "enabled": true,
+            "storage": "filesystem",
+            "startup-mode": "Purge",
+            "indexed-entities": [
+                "book_sample.Book"
+            ]
+        }
+    }
+}