Merge pull request #39413 from yrodiere/refresh-hibernate-search-docs

Refresh documentation (and some tests) of the Hibernate Search + ORM extension

extensions/hibernate-search-orm-elasticsearch/deployment/pom.xml

@@ -59,6 +59,16 @@
             <artifactId>assertj-core</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-vertx-http-deployment</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-vertx-http-dev-ui-tests</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

integration-tests/devmode/src/test/java/io/quarkus/test/devui/AbstractDevUIHibernateSearchTest.java → extensions/hibernate-search-orm-elasticsearch/deployment/src/test/java/io/quarkus/hibernate/search/orm/elasticsearch/test/devui/AbstractDevUITest.java

@@ -1,4 +1,4 @@
-package io.quarkus.test.devui;
+package io.quarkus.hibernate.search.orm.elasticsearch.test.devui;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
@@ -13,15 +13,15 @@
 import io.quarkus.devui.tests.DevUIJsonRPCTest;
 
 /**
- * All tests test the same api call, with different configuration and different expected results.
+ * All DevUI tests check the same api call, with different configuration and different expected results.
  * This abstract class reduces the code in each test.
  */
-public abstract class AbstractDevUIHibernateSearchTest extends DevUIJsonRPCTest {
+public abstract class AbstractDevUITest extends DevUIJsonRPCTest {
 
     private final String expectedPersistenceUnitName;
     private final String expectedClassName;
 
-    public AbstractDevUIHibernateSearchTest(String expectedPersistenceUnitName, String expectedClassName) {
+    public AbstractDevUITest(String expectedPersistenceUnitName, String expectedClassName) {
         super("io.quarkus.quarkus-hibernate-search-orm-elasticsearch");
         this.expectedPersistenceUnitName = expectedPersistenceUnitName;
         this.expectedClassName = expectedClassName;

extensions/hibernate-search-orm-elasticsearch/deployment/src/test/java/io/quarkus/hibernate/search/orm/elasticsearch/test/devui/DevUIActiveFalseAndNamedPuActiveTrueTest.java

@@ -0,0 +1,22 @@
+package io.quarkus.hibernate.search.orm.elasticsearch.test.devui;
+
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.hibernate.search.orm.elasticsearch.test.devui.namedpu.MyNamedPuIndexedEntity;
+import io.quarkus.test.QuarkusDevModeTest;
+
+public class DevUIActiveFalseAndNamedPuActiveTrueTest extends AbstractDevUITest {
+
+    @RegisterExtension
+    static final QuarkusDevModeTest test = new QuarkusDevModeTest()
+            .withApplicationRoot((jar) -> jar
+                    .addAsResource("application-devui-active-false-and-named-pu-active-true.properties",
+                            "application.properties")
+                    .addClasses(MyIndexedEntity.class)
+                    .addClasses(MyNamedPuIndexedEntity.class));
+
+    public DevUIActiveFalseAndNamedPuActiveTrueTest() {
+        super("namedpu", MyNamedPuIndexedEntity.class.getName());
+    }
+
+}

extensions/hibernate-search-orm-elasticsearch/deployment/src/test/java/io/quarkus/hibernate/search/orm/elasticsearch/test/devui/DevUIActiveFalseTest.java

@@ -0,0 +1,20 @@
+package io.quarkus.hibernate.search.orm.elasticsearch.test.devui;
+
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.test.QuarkusDevModeTest;
+
+public class DevUIActiveFalseTest extends AbstractDevUITest {
+
+    @RegisterExtension
+    static final QuarkusDevModeTest test = new QuarkusDevModeTest()
+            .withApplicationRoot(
+                    (jar) -> jar.addAsResource("application-devui-active-false.properties", "application.properties")
+                            .addClasses(MyIndexedEntity.class));
+
+    public DevUIActiveFalseTest() {
+        // Hibernate Search is inactive: the dev console should be empty.
+        super(null, null);
+    }
+
+}

extensions/hibernate-search-orm-elasticsearch/deployment/src/test/java/io/quarkus/hibernate/search/orm/elasticsearch/test/devui/DevUISmokeTest.java

@@ -0,0 +1,18 @@
+package io.quarkus.hibernate.search.orm.elasticsearch.test.devui;
+
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.test.QuarkusDevModeTest;
+
+public class DevUISmokeTest extends AbstractDevUITest {
+
+    @RegisterExtension
+    static final QuarkusDevModeTest test = new QuarkusDevModeTest()
+            .withApplicationRoot(
+                    (jar) -> jar.addAsResource("application-devui.properties", "application.properties")
+                            .addClasses(MyIndexedEntity.class));
+
+    public DevUISmokeTest() {
+        super("<default>", MyIndexedEntity.class.getName());
+    }
+}

integration-tests/devmode/src/test/java/io/quarkus/test/devui/MyIndexedEntity.java → extensions/hibernate-search-orm-elasticsearch/deployment/src/test/java/io/quarkus/hibernate/search/orm/elasticsearch/test/devui/MyIndexedEntity.java

@@ -1,4 +1,4 @@
-package io.quarkus.test.devui;
+package io.quarkus.hibernate.search.orm.elasticsearch.test.devui;
 
 import jakarta.persistence.Entity;
 import jakarta.persistence.Id;

integration-tests/devmode/src/test/java/io/quarkus/test/devui/namedpu/MyNamedPuIndexedEntity.java → extensions/hibernate-search-orm-elasticsearch/deployment/src/test/java/io/quarkus/hibernate/search/orm/elasticsearch/test/devui/namedpu/MyNamedPuIndexedEntity.java

@@ -1,4 +1,4 @@
-package io.quarkus.test.devui.namedpu;
+package io.quarkus.hibernate.search.orm.elasticsearch.test.devui.namedpu;
 
 import jakarta.persistence.Entity;
 import jakarta.persistence.Id;

extensions/hibernate-search-orm-elasticsearch/deployment/src/test/resources/application-devui-active-false-and-named-pu-active-true.properties

@@ -0,0 +1,27 @@
+# We already start Elasticsearch with Maven
+quarkus.devservices.enabled=false
+
+quarkus.datasource.db-kind=h2
+quarkus.datasource.jdbc.url=jdbc:h2:mem:default;DB_CLOSE_DELAY=-1
+
+quarkus.datasource."nameddatasource".db-kind=h2
+quarkus.datasource."nameddatasource".jdbc.url=jdbc:h2:mem:nameddatasource;DB_CLOSE_DELAY=-1
+
+quarkus.hibernate-orm.datasource=<default>
+quarkus.hibernate-orm.packages=io.quarkus.hibernate.search.orm.elasticsearch.test.devui
+quarkus.hibernate-orm.database.generation=drop-and-create
+
+quarkus.hibernate-orm."namedpu".datasource=nameddatasource
+quarkus.hibernate-orm."namedpu".packages=io.quarkus.hibernate.search.orm.elasticsearch.test.devui.namedpu
+quarkus.hibernate-orm."namedpu".database.generation=drop-and-create
+
+# Hibernate Search is inactive for the default PU
+quarkus.hibernate-search-orm.active=false
+quarkus.hibernate-search-orm.elasticsearch.version=8.12
+quarkus.hibernate-search-orm.elasticsearch.hosts=${elasticsearch.hosts:localhost:9200}
+quarkus.hibernate-search-orm.schema-management.strategy=drop-and-create-and-drop
+
+# ... but it's (implicitly) active for a named PU
+quarkus.hibernate-search-orm."namedpu".elasticsearch.version=8.12
+quarkus.hibernate-search-orm."namedpu".elasticsearch.hosts=${elasticsearch.hosts:localhost:9200}
+quarkus.hibernate-search-orm."namedpu".schema-management.strategy=drop-and-create-and-drop

extensions/hibernate-search-orm-elasticsearch/deployment/src/test/resources/application-devui-active-false.properties

@@ -0,0 +1,12 @@
+# We already start Elasticsearch with Maven
+quarkus.devservices.enabled=false
+
+quarkus.datasource.db-kind=h2
+quarkus.datasource.jdbc.url=jdbc:h2:mem:default;DB_CLOSE_DELAY=-1
+
+quarkus.hibernate-orm.database.generation=drop-and-create
+
+quarkus.hibernate-search-orm.active=false
+quarkus.hibernate-search-orm.elasticsearch.version=8.12
+quarkus.hibernate-search-orm.elasticsearch.hosts=${elasticsearch.hosts:localhost:9200}
+quarkus.hibernate-search-orm.schema-management.strategy=drop-and-create-and-drop

extensions/hibernate-search-orm-elasticsearch/deployment/src/test/resources/application-devui.properties

@@ -0,0 +1,11 @@
+# We already start Elasticsearch with Maven
+quarkus.devservices.enabled=false
+
+quarkus.datasource.db-kind=h2
+quarkus.datasource.jdbc.url=jdbc:h2:mem:default;DB_CLOSE_DELAY=-1
+
+quarkus.hibernate-orm.database.generation=drop-and-create
+
+quarkus.hibernate-search-orm.elasticsearch.version=8.12
+quarkus.hibernate-search-orm.elasticsearch.hosts=${elasticsearch.hosts:localhost:9200}
+quarkus.hibernate-search-orm.schema-management.strategy=drop-and-create-and-drop

extensions/hibernate-search-orm-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/orm/elasticsearch/runtime/HibernateSearchElasticsearchBuildTimeConfigPersistenceUnit.java

@@ -33,11 +33,18 @@ public interface HibernateSearchElasticsearchBuildTimeConfigPersistenceUnit {
      *
      * The referenced bean must implement `FailureHandler`.
      *
+     * See
+     * link:{hibernate-search-docs-url}#configuration-background-failure-handling[this section of the reference documentation]
+     * for more information.
+     *
      * [NOTE]
      * ====
      * Instead of setting this configuration property,
      * you can simply annotate your custom `FailureHandler` implementation with `@SearchExtension`
      * and leave the configuration property unset: Hibernate Search will use the annotated implementation automatically.
+     * See xref:hibernate-search-orm-elasticsearch.adoc#plugging-in-custom-components[this section]
+     * for more information.
+     *
      * If this configuration property is set, it takes precedence over any `@SearchExtension` annotation.
      * ====
      *
@@ -118,7 +125,7 @@ interface SchemaManagementConfig {
          * When analysis is configured both through an analysis configurer and these custom settings, the behavior is undefined;
          * it should not be relied upon.
          *
-         * See https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_single/#backend-elasticsearch-configuration-index-settings[this section of the reference documentation]
+         * See link:{hibernate-search-docs-url}#backend-elasticsearch-configuration-index-settings[this section of the reference documentation]
          * for more information.
          *
          * @asciidoclet
@@ -134,7 +141,7 @@ interface SchemaManagementConfig {
          * The file does not need to (and generally shouldn't) contain the full mapping:
          * Hibernate Search will automatically inject missing properties (index fields) in the given mapping.
          *
-         * See https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_single/#backend-elasticsearch-mapping-custom[this section of the reference documentation]
+         * See link:{hibernate-search-docs-url}#backend-elasticsearch-mapping-custom[this section of the reference documentation]
          * for more information.
          *
          * @asciidoclet
@@ -160,6 +167,9 @@ interface AnalysisConfig {
          * Instead of setting this configuration property,
          * you can simply annotate your custom `ElasticsearchAnalysisConfigurer` implementations with `@SearchExtension`
          * and leave the configuration property unset: Hibernate Search will use the annotated implementation automatically.
+         * See xref:hibernate-search-orm-elasticsearch.adoc#plugging-in-custom-components[this section]
+         * for more information.
+         *
          * If this configuration property is set, it takes precedence over any `@SearchExtension` annotation.
          * ====
          *
@@ -172,7 +182,7 @@ interface AnalysisConfig {
     interface LayoutConfig {
         /**
          * A xref:hibernate-search-orm-elasticsearch.adoc#bean-reference-note-anchor[bean reference] to the component
-         * used to configure layout (e.g. index names, index aliases).
+         * used to configure the Elasticsearch layout: index names, index aliases, ...
          *
          * The referenced bean must implement `IndexLayoutStrategy`.
          *
@@ -196,6 +206,9 @@ interface LayoutConfig {
          * Instead of setting this configuration property,
          * you can simply annotate your custom `IndexLayoutStrategy` implementation with `@SearchExtension`
          * and leave the configuration property unset: Hibernate Search will use the annotated implementation automatically.
+         * See xref:hibernate-search-orm-elasticsearch.adoc#plugging-in-custom-components[this section]
+         * for more information.
+         *
          * If this configuration property is set, it takes precedence over any `@SearchExtension` annotation.
          * ====
          *
@@ -223,7 +236,8 @@ interface CoordinationConfig {
     interface MappingConfig {
         /**
          * One or more xref:hibernate-search-orm-elasticsearch.adoc#bean-reference-note-anchor[bean references]
-         * to the component(s) used to configure Hibernate Search mapping.
+         * to the component(s) used to configure the Hibernate Search mapping,
+         * in particular programmatically.
          *
          * The referenced beans must implement `HibernateOrmSearchMappingConfigurer`.
          *
@@ -235,6 +249,9 @@ interface MappingConfig {
          * Instead of setting this configuration property,
          * you can simply annotate your custom `HibernateOrmSearchMappingConfigurer` implementations with `@SearchExtension`
          * and leave the configuration property unset: Hibernate Search will use the annotated implementation automatically.
+         * See xref:hibernate-search-orm-elasticsearch.adoc#plugging-in-custom-components[this section]
+         * for more information.
+         *
          * If this configuration property is set, it takes precedence over any `@SearchExtension` annotation.
          * ====
          *

extensions/hibernate-search-orm-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/orm/elasticsearch/runtime/HibernateSearchElasticsearchRuntimeConfigPersistenceUnit.java

@@ -347,6 +347,9 @@ interface IndexingPlanSynchronizationConfig {
          * Instead of setting this configuration property,
          * you can simply annotate your custom `IndexingPlanSynchronizationStrategy` implementation with `@SearchExtension`
          * and leave the configuration property unset: Hibernate Search will use the annotated implementation automatically.
+         * See xref:hibernate-search-orm-elasticsearch.adoc#plugging-in-custom-components[this section]
+         * for more information.
+         *
          * If this configuration property is set, it takes precedence over any `@SearchExtension` annotation.
          * ====
          *
@@ -481,7 +484,7 @@ interface SchemaManagementConfig {
          * Also, drop indexes and their schema on shutdown.
          * !===
          *
-         * See https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_single/#mapper-orm-schema-management-strategy[this section of the reference documentation]
+         * See link:{hibernate-search-docs-url}#mapper-orm-schema-management-strategy[this section of the reference documentation]
          * for more information.
          *
          * @asciidoclet

integration-tests/devmode/pom.xml

@@ -69,11 +69,6 @@
             <artifactId>quarkus-hibernate-orm-deployment</artifactId>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>io.quarkus</groupId>
-            <artifactId>quarkus-hibernate-search-orm-elasticsearch-deployment</artifactId>
-            <scope>test</scope>
-        </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-jdbc-h2-deployment</artifactId>