HSEARCH-3102 Rely on automatic backend type detection in documentation

hibernate · Jul 13, 2020 · 0ca5615 · 0ca5615
1 parent 159896a
commit 0ca5615
Show file tree

Hide file tree

Showing 15 changed files with 115 additions and 87 deletions.
diff --git a/documentation/pom.xml b/documentation/pom.xml
@@ -97,28 +97,44 @@
                         <id>it-lucene</id>
                         <goals>
                             <goal>integration-test</goal>
-                            <goal>verify</goal>
                         </goals>
                         <configuration>
                             <reportNameSuffix>${surefire.environment}-${surefire.executing-module}-lucene</reportNameSuffix>
+                            <classpathDependencyExcludes>
+                                <classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-elasticsearch</classpathDependencyExclude>
+                            </classpathDependencyExcludes>
                             <systemPropertyVariables>
-                                <test.backendType>lucene</test.backendType>
+                                <org.hibernate.search.integrationtest.backend.type>lucene</org.hibernate.search.integrationtest.backend.type>
                             </systemPropertyVariables>
+                            <excludes>
+                                <exclude>**/Elasticsearch*IT</exclude>
+                            </excludes>
                         </configuration>
                     </execution>
                     <execution>
                         <id>it-elasticsearch</id>
                         <goals>
                             <goal>integration-test</goal>
-                            <goal>verify</goal>
                         </goals>
                         <configuration>
                             <reportNameSuffix>${surefire.environment}-${surefire.executing-module}-elasticsearch</reportNameSuffix>
+                            <classpathDependencyExcludes>
+                                <classpathDependencyExclude>org.hibernate.search:hibernate-search-backend-lucene</classpathDependencyExclude>
+                            </classpathDependencyExcludes>
                             <systemPropertyVariables>
-                                <test.backendType>elasticsearch</test.backendType>
+                                <org.hibernate.search.integrationtest.backend.type>elasticsearch</org.hibernate.search.integrationtest.backend.type>
                             </systemPropertyVariables>
+                            <excludes>
+                                <exclude>**/Lucene*IT</exclude>
+                            </excludes>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>it-verify</id>
+                        <goals>
+                            <goal>verify</goal>
+                        </goals>
+                    </execution>
                 </executions>
             </plugin>
             <plugin>

diff --git a/documentation/src/main/asciidoc/reference/backend-elasticsearch.asciidoc b/documentation/src/main/asciidoc/reference/backend-elasticsearch.asciidoc
@@ -50,10 +50,7 @@ and <<mapper-orm-indexing-massindexer,reindex your data>>.
 // Search 5 anchors backward compatibility
 [[elasticsearch-integration-configuration]]
 
-In order to define an Elasticsearch backend,
-the property `hibernate.search.backend.type` must be set to `elasticsearch`.
-
-All other configuration properties are optional,
+All configuration properties of the Elasticsearch backend are optional,
 but the defaults might not suit everyone.
 In particular your production Elasticsearch cluster is probably not reachable at `http://localhost:9200`,
 so you will need to set the address of your cluster by <<backend-elasticsearch-configuration-client,configuring the client>>.

diff --git a/documentation/src/main/asciidoc/reference/backend-lucene.asciidoc b/documentation/src/main/asciidoc/reference/backend-lucene.asciidoc
@@ -6,10 +6,7 @@
 [[backend-lucene-configuration]]
 == Basic configuration
 
-In order to define a Lucene backend,
-the property `hibernate.search.backend.type` must be set to `lucene`.
-
-All other configuration properties are optional,
+All configuration properties of the Lucene backend are optional,
 but the defaults might not suit everyone.
 In particular, you might want to
 <<backend-lucene-configuration-directory-local-filesystem-location,set the location of your indexes in the filesystem>>.

diff --git a/documentation/src/main/asciidoc/reference/configuration.asciidoc b/documentation/src/main/asciidoc/reference/configuration.asciidoc
@@ -43,13 +43,7 @@ They are grouped under a common root:
 * `hibernate.search.backends.<backend name>` for a named backend (advanced usage).
 
 +
-Notable properties:
-
-* `hibernate.search.backend.type`: the type of the backend.
-Set this to either `lucene` or `elasticsearch`.
-
-+
-Other backend properties are explained in the relevant parts of this documentation:
+Backend properties are explained in the relevant parts of this documentation:
 
 * <<backend-lucene-configuration,Lucene backend>>
 * <<backend-elasticsearch-configuration,Elasticsearch backend>>

diff --git a/documentation/src/main/asciidoc/reference/getting-started.asciidoc b/documentation/src/main/asciidoc/reference/getting-started.asciidoc
@@ -145,18 +145,17 @@ so they can be added to any file from which Hibernate ORM takes its configuratio
 * The `hibernate.cfg.xml` file in your classpath, if using Hibernate ORM native bootstrapping.
 * The `persistence.xml` file in your classpath, if using Hibernate ORM JPA bootstrapping.
 
-The minimal working configuration is short, but depends on your setup:
+Hibernate Search provides sensible defaults for all configuration properties,
+but depending on your setup you might want to set the following:
 
 .Hibernate Search properties in `persistence.xml` for a "Hibernate ORM + Lucene" setup
 ====
 [source, XML, indent=0]
 ----
 include::{resourcesdir}/META-INF/persistence.xml[tags=gettingstarted-configuration-orm_lucene]
 ----
-<1> Define a backend relying on Lucene technology.
-<2> The backend will store indexes in the current working directory by default.
-If you want to store the indexes elsewhere,
-uncomment this line and set the value of the property.
+<1> Set the location of indexes in the filesystem.
+By default, the backend will store indexes in the current working directory.
 ====
 
 .Hibernate Search properties in `persistence.xml` for a "Hibernate ORM + Elasticsearch" setup
@@ -165,11 +164,11 @@ uncomment this line and set the value of the property.
 ----
 include::{resourcesdir}/META-INF/persistence.xml[tags=gettingstarted-configuration-orm_elasticsearch]
 ----
-<1> Define a backend relying on Elasticsearch technology.
-<2> The backend will attempt to connect to http://localhost:9200 by default.
-If you want to connect to another URL, uncomment these lines
-and set the value for the "hosts" property,
-and optionally the username and password.
+<1> Set the Elasticsearch hosts to connect to.
+By default, the backend will attempt to connect to `localhost:9200`.
+<2> Set the protocol. The default is `http`, but you may need to use `https`.
+<3> Set the username and password for basic HTTP authentication.
+You may also be interested in <<backend-elasticsearch-configuration-aws,AWS IAM authentication>>.
 ====
 
 [[getting-started-mapping]]

diff --git a/documentation/src/test/java/org/hibernate/search/documentation/analysis/AnalysisIT.java b/documentation/src/test/java/org/hibernate/search/documentation/analysis/AnalysisIT.java
@@ -7,6 +7,7 @@
 package org.hibernate.search.documentation.analysis;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.hibernate.search.util.impl.integrationtest.common.rule.BackendConfiguration.isLucene;
 
 import javax.persistence.Entity;
 import javax.persistence.EntityManagerFactory;
@@ -34,7 +35,7 @@ public class AnalysisIT {
 	public void simple() {
 		EntityManagerFactory entityManagerFactory = setupHelper.start()
 				.withProperties(
-						setupHelper.isLucene()
+						isLucene()
 								? "/analysis/lucene-simple.properties"
 								: "/analysis/elasticsearch-simple.properties"
 				)

diff --git a/...t/java/org/hibernate/search/documentation/configuration/ElasticsearchConfigurationIT.java b/...t/java/org/hibernate/search/documentation/configuration/ElasticsearchConfigurationIT.java
@@ -30,8 +30,6 @@ private Properties buildHibernateConfiguration() {
 		// backend configuration
 		config.put( BackendSettings.backendKey( ElasticsearchBackendSettings.HOSTS ), "127.0.0.1:9200" );
 		config.put( BackendSettings.backendKey( ElasticsearchBackendSettings.PROTOCOL ), "http" );
-		config.put(
-				BackendSettings.backendKey( BackendSettings.TYPE ), ElasticsearchBackendSettings.TYPE_NAME );
 		config.put(
 				BackendSettings.backendKey( ElasticsearchBackendSettings.MULTI_TENANCY_STRATEGY ),
 				MultiTenancyStrategyName.DISCRIMINATOR.externalRepresentation()
@@ -61,7 +59,6 @@ public void shouldBuildHibernateConfiguration() {
 				.containsOnly(
 						entry( "hibernate.search.backend.hosts", "127.0.0.1:9200" ),
 						entry( "hibernate.search.backend.protocol", "http" ),
-						entry( "hibernate.search.backend.type", "elasticsearch" ),
 						entry( "hibernate.search.backend.multi_tenancy.strategy", "discriminator" ),
 						entry( "hibernate.search.backend.version", "7.8" ),
 						entry( "hibernate.search.backend.version_check.enabled", "false" ),

diff --git a/...h/documentation/gettingstarted/withhsearch/withanalysis/GettingStartedWithAnalysisIT.java b/...h/documentation/gettingstarted/withhsearch/withanalysis/GettingStartedWithAnalysisIT.java
@@ -7,12 +7,15 @@
 package org.hibernate.search.documentation.gettingstarted.withhsearch.withanalysis;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.hibernate.search.util.impl.integrationtest.common.rule.BackendConfiguration.BACKEND_TYPE;
+import static org.hibernate.search.util.impl.integrationtest.common.rule.BackendConfiguration.IS_IDE;
 
+import java.util.HashMap;
+import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 import javax.persistence.EntityManagerFactory;
 import javax.persistence.Persistence;
 
-import org.hibernate.search.documentation.testsupport.BackendConfigurations;
 import org.hibernate.search.engine.search.query.SearchResult;
 import org.hibernate.search.mapper.orm.Search;
 import org.hibernate.search.mapper.orm.session.SearchSession;
@@ -24,7 +27,7 @@
 
 public class GettingStartedWithAnalysisIT {
 
-	private final String persistenceUnitName = "GettingStartedWithAnalysisIT_" + BackendConfigurations.BACKEND_TYPE;
+	private final String persistenceUnitName = "GettingStartedWithAnalysisIT_" + BACKEND_TYPE;
 
 	private EntityManagerFactory entityManagerFactory;
 
@@ -35,8 +38,14 @@ public void setup() {
 
 	@After
 	public void cleanup() {
-		if ( entityManagerFactory != null ) {
-			entityManagerFactory.close();
+		if ( IS_IDE ) {
+			Map<String, String> properties = new HashMap<>();
+			// More than one backend type in the classpath, we have to set it explicitly.
+			properties.put( "hibernate.search.backend.type", BACKEND_TYPE );
+			entityManagerFactory = Persistence.createEntityManagerFactory( persistenceUnitName, properties );
+		}
+		else {
+			entityManagerFactory = Persistence.createEntityManagerFactory( persistenceUnitName );
 		}
 	}
 

diff --git a/...mentation/gettingstarted/withhsearch/withoutanalysis/GettingStartedWithoutAnalysisIT.java b/...mentation/gettingstarted/withhsearch/withoutanalysis/GettingStartedWithoutAnalysisIT.java
@@ -7,14 +7,17 @@
 package org.hibernate.search.documentation.gettingstarted.withhsearch.withoutanalysis;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.hibernate.search.util.impl.integrationtest.common.rule.BackendConfiguration.BACKEND_TYPE;
+import static org.hibernate.search.util.impl.integrationtest.common.rule.BackendConfiguration.IS_IDE;
 import static org.junit.Assert.assertEquals;
 
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 import javax.persistence.EntityManagerFactory;
 import javax.persistence.Persistence;
 
-import org.hibernate.search.documentation.testsupport.BackendConfigurations;
 import org.hibernate.search.engine.search.query.SearchResult;
 import org.hibernate.search.mapper.orm.Search;
 import org.hibernate.search.mapper.orm.massindexing.MassIndexer;
@@ -28,13 +31,21 @@
 
 public class GettingStartedWithoutAnalysisIT {
 
-	private final String persistenceUnitName = "GettingStartedWithoutAnalysisIT_" + BackendConfigurations.BACKEND_TYPE;
+	private final String persistenceUnitName = "GettingStartedWithoutAnalysisIT_" + BACKEND_TYPE;
 
 	private EntityManagerFactory entityManagerFactory;
 
 	@Before
 	public void setup() {
-		entityManagerFactory = Persistence.createEntityManagerFactory( persistenceUnitName );
+		if ( IS_IDE ) {
+			Map<String, String> properties = new HashMap<>();
+			// More than one backend type in the classpath, we have to set it explicitly.
+			properties.put( "hibernate.search.backend.type", BACKEND_TYPE );
+			entityManagerFactory = Persistence.createEntityManagerFactory( persistenceUnitName, properties );
+		}
+		else {
+			entityManagerFactory = Persistence.createEntityManagerFactory( persistenceUnitName );
+		}
 	}
 
 	@After

diff --git a/...n/src/test/java/org/hibernate/search/documentation/testsupport/BackendConfigurations.java b/...n/src/test/java/org/hibernate/search/documentation/testsupport/BackendConfigurations.java
@@ -6,33 +6,15 @@
  */
 package org.hibernate.search.documentation.testsupport;
 
-import java.lang.invoke.MethodHandles;
+import static org.hibernate.search.util.impl.integrationtest.common.rule.BackendConfiguration.BACKEND_TYPE;
 
 import org.hibernate.search.backend.lucene.cfg.LuceneIndexSettings;
-import org.hibernate.search.util.common.logging.impl.Log;
-import org.hibernate.search.util.common.logging.impl.LoggerFactory;
 import org.hibernate.search.util.impl.integrationtest.common.TestConfigurationProvider;
 import org.hibernate.search.util.impl.integrationtest.common.rule.BackendConfiguration;
 import org.hibernate.search.util.impl.integrationtest.common.rule.MappingSetupHelper;
 
 public final class BackendConfigurations {
 
-	private static final Log log = LoggerFactory.make( Log.class, MethodHandles.lookup() );
-
-	public static final String BACKEND_TYPE;
-
-	static {
-		String property = System.getProperty( "test.backendType" );
-		if ( property == null ) {
-			log.warn( "The expected backend type wasn't set; tests are probably running from an IDE."
-					+ " Defaulting to 'lucene'." );
-			BACKEND_TYPE = "lucene";
-		}
-		else {
-			BACKEND_TYPE = property;
-		}
-	}
-
 	private BackendConfigurations() {
 	}
 

diff --git a/...rc/test/java/org/hibernate/search/documentation/testsupport/DocumentationSetupHelper.java b/...rc/test/java/org/hibernate/search/documentation/testsupport/DocumentationSetupHelper.java
@@ -95,14 +95,6 @@ protected void close(SessionFactory toClose) {
 		toClose.close();
 	}
 
-	public boolean isElasticsearch() {
-		return defaultBackendConfiguration instanceof DocumentationElasticsearchBackendConfiguration;
-	}
-
-	public boolean isLucene() {
-		return defaultBackendConfiguration instanceof DocumentationLuceneBackendConfiguration;
-	}
-
 	public final class SetupContext
 			extends MappingSetupHelper<SetupContext, SimpleSessionFactoryBuilder, SessionFactory>.AbstractSetupContext {
 

diff --git a/documentation/src/test/resources/META-INF/persistence.xml b/documentation/src/test/resources/META-INF/persistence.xml
@@ -22,12 +22,8 @@
         <exclude-unlisted-classes />
         <properties>
             <!-- tag::gettingstarted-configuration-orm_lucene[] -->
-            <property name="hibernate.search.backend.type"
-                      value="lucene"/> <!--1-->
-            <!--
             <property name="hibernate.search.backend.directory.root"
-                      value="some/filesystem/path"/>
-             --> <!--2-->
+                      value="some/filesystem/path"/> <!--1-->
             <!-- end::gettingstarted-configuration-orm_lucene[] -->
 
             <!--
@@ -49,18 +45,14 @@
         <exclude-unlisted-classes />
         <properties>
             <!-- tag::gettingstarted-configuration-orm_elasticsearch[] -->
-            <property name="hibernate.search.backend.type"
-                      value="elasticsearch" /> <!--1-->
-            <!--
             <property name="hibernate.search.backend.hosts"
-                      value="elasticsearch.mycompany.com"/>
+                      value="elasticsearch.mycompany.com"/> <!--1-->
             <property name="hibernate.search.backend.protocol"
-                      value="https"/>
+                      value="https"/> <!--2-->
             <property name="hibernate.search.backend.username"
-                      value="ironman"/>
+                      value="ironman"/> <!--3-->
             <property name="hibernate.search.backend.password"
                       value="j@rV1s"/>
-             --> <!--2-->
             <!-- end::gettingstarted-configuration-orm_elasticsearch[] -->
 
             <!--
@@ -100,8 +92,6 @@
         <class>org.hibernate.search.documentation.gettingstarted.withhsearch.withanalysis.Book</class>
         <exclude-unlisted-classes />
         <properties>
-            <property name="hibernate.search.backend.type"
-                      value="lucene"/>
             <!-- tag::gettingstarted-configuration-orm_lucene-analysis[] -->
             <property name="hibernate.search.backend.analysis.configurer"
                       value="org.hibernate.search.documentation.gettingstarted.withhsearch.withanalysis.MyLuceneAnalysisConfigurer"/> <!--6-->
@@ -125,16 +115,15 @@
         <class>org.hibernate.search.documentation.gettingstarted.withhsearch.withanalysis.Book</class>
         <exclude-unlisted-classes />
         <properties>
-            <property name="hibernate.search.backend.type"
-                      value="elasticsearch" />
             <!-- tag::gettingstarted-configuration-orm_elasticsearch-analysis[] -->
             <property name="hibernate.search.backend.analysis.configurer"
                       value="org.hibernate.search.documentation.gettingstarted.withhsearch.withanalysis.MyElasticsearchAnalysisConfigurer"/> <!--7-->
             <!-- end::gettingstarted-configuration-orm_elasticsearch-analysis[] -->
 
             <!--
                 Not to be included in the documentation:
-                this configuration is only relevant in our own testing infrastructure.
+                this configuration is only relevant in our own testing in
+                frastructure.
                 WARNING: if you update the property names below,
                 take care to also update the name of the commented properties just above.
              -->

diff --git a/...ch/util/impl/integrationtest/backend/elasticsearch/ElasticsearchBackendConfiguration.java b/...ch/util/impl/integrationtest/backend/elasticsearch/ElasticsearchBackendConfiguration.java
@@ -32,7 +32,6 @@ public Optional<TestRule> testRule() {
 	@Override
 	protected Map<String, Object> backendProperties() {
 		Map<String, Object> properties = new LinkedHashMap<>();
-		properties.put( "type", "elasticsearch" );
 		properties.put( "log.json_pretty_printing", "true" );
 		properties.put( "index_defaults.schema_management.minimal_required_status", "yellow" );
 		ElasticsearchTestHostConnectionConfiguration.get().addToBackendProperties( properties );

diff --git a/...hibernate/search/util/impl/integrationtest/backend/lucene/LuceneBackendConfiguration.java b/...hibernate/search/util/impl/integrationtest/backend/lucene/LuceneBackendConfiguration.java
@@ -20,7 +20,6 @@ public String toString() {
 	@Override
 	protected Map<String, Object> backendProperties() {
 		Map<String, Object> properties = new LinkedHashMap<>();
-		properties.put( "type", "lucene" );
 		properties.put(
 				"directory.root",
 				LuceneTestIndexesPathConfiguration.get().getPath()