HSEARCH-4843 Introduce a common EntityReference interface and depreca…

…te mapper-specific ones

In the case of the Standalone POJO Mapper we simply remove the
mapper-specific EntityReference, because this mapper is still in Alpha.

backend/elasticsearch/src/main/java/org/hibernate/search/backend/elasticsearch/work/execution/impl/ElasticsearchIndexIndexingPlan.java

@@ -78,7 +78,7 @@ public void delete(DocumentReferenceProvider referenceProvider) {
 
 	@Override
 	public <R> CompletableFuture<MultiEntityOperationExecutionReport<R>> executeAndReport(
-			EntityReferenceFactory<R> entityReferenceFactory, OperationSubmitter operationSubmitter) {
+			EntityReferenceFactory<? extends R> entityReferenceFactory, OperationSubmitter operationSubmitter) {
 		try {
 			ElasticsearchIndexIndexingPlanExecution<R> execution = new ElasticsearchIndexIndexingPlanExecution<>(
 					orchestrator, entityReferenceFactory,

backend/elasticsearch/src/main/java/org/hibernate/search/backend/elasticsearch/work/execution/impl/ElasticsearchIndexIndexingPlanExecution.java

@@ -19,19 +19,19 @@
 /**
  * A single-use, stateful execution of a set of works as part of an indexing plan.
  *
- * @param <R> The type of entity references in the {@link #execute() execution report}.
+ * @param <R> The type of entity references in the {@link #execute(OperationSubmitter) execution report}.
  */
 class ElasticsearchIndexIndexingPlanExecution<R> {
 
 	private final ElasticsearchSerialWorkOrchestrator orchestrator;
-	private final EntityReferenceFactory<R> entityReferenceFactory;
+	private final EntityReferenceFactory<? extends R> entityReferenceFactory;
 
 	private final List<SingleDocumentIndexingWork> works;
 	private final CompletableFuture<Void>[] futures;
 
 	@SuppressWarnings("unchecked")
 	ElasticsearchIndexIndexingPlanExecution(ElasticsearchSerialWorkOrchestrator orchestrator,
-			EntityReferenceFactory<R> entityReferenceFactory,
+			EntityReferenceFactory<? extends R> entityReferenceFactory,
 			List<SingleDocumentIndexingWork> works) {
 		this.orchestrator = orchestrator;
 		this.entityReferenceFactory = entityReferenceFactory;

backend/lucene/src/main/java/org/hibernate/search/backend/lucene/work/execution/impl/LuceneIndexIndexingPlan.java

@@ -92,7 +92,7 @@ public void delete(DocumentReferenceProvider referenceProvider) {
 
 	@Override
 	public <R> CompletableFuture<MultiEntityOperationExecutionReport<R>> executeAndReport(
-			EntityReferenceFactory<R> entityReferenceFactory, OperationSubmitter operationSubmitter) {
+			EntityReferenceFactory<? extends R> entityReferenceFactory, OperationSubmitter operationSubmitter) {
 		try {
 			List<CompletableFuture<MultiEntityOperationExecutionReport<R>>> shardReportFutures = new ArrayList<>();
 			for ( Map.Entry<LuceneSerialWorkOrchestrator, List<SingleDocumentIndexingWork>> entry : worksByOrchestrator.entrySet() ) {

backend/lucene/src/main/java/org/hibernate/search/backend/lucene/work/execution/impl/LuceneIndexIndexingPlanExecution.java

@@ -21,12 +21,12 @@
 /**
  * A single-use, stateful execution of a set of works as part of an indexing plan.
  *
- * @param <R> The type of entity references in the {@link #execute() execution report}.
+ * @param <R> The type of entity references in the {@link #execute(OperationSubmitter) execution report}.
  */
 class LuceneIndexIndexingPlanExecution<R> {
 
 	private final LuceneSerialWorkOrchestrator orchestrator;
-	private final EntityReferenceFactory<R> entityReferenceFactory;
+	private final EntityReferenceFactory<? extends R> entityReferenceFactory;
 	private final DocumentCommitStrategy commitStrategy;
 	private final DocumentRefreshStrategy refreshStrategy;
 
@@ -35,7 +35,7 @@ class LuceneIndexIndexingPlanExecution<R> {
 
 	@SuppressWarnings("unchecked")
 	LuceneIndexIndexingPlanExecution(LuceneSerialWorkOrchestrator orchestrator,
-			EntityReferenceFactory<R> entityReferenceFactory,
+			EntityReferenceFactory<? extends R> entityReferenceFactory,
 			DocumentCommitStrategy commitStrategy,
 			DocumentRefreshStrategy refreshStrategy,
 			List<SingleDocumentIndexingWork> works) {

documentation/pom.xml

@@ -107,6 +107,17 @@
                 <groupId>io.fabric8</groupId>
                 <artifactId>docker-maven-plugin</artifactId>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <!-- For some reason we're getting deprecation warnings about
+                         org.hibernate.search.mapper.orm.common.EntityReference
+                         even though we don't explicitly use it.
+                         This is probably a compiler bug, so here we need to work around it. -->
+                    <showDeprecation>false</showDeprecation>
+                </configuration>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-failsafe-plugin</artifactId>

documentation/src/main/asciidoc/migration/index.asciidoc

@@ -336,6 +336,7 @@ is now `org.hibernate.search.engine.search.predicate.definition.PredicateDefinit
 
 Parts of the API have been deprecated, and may be removed in the next major version:
 
+* `org.hibernate.search.mapper.orm.common.EntityReference`: use `org.hibernate.search.engine.common.EntityReference` instead.
 * `SearchPredicateFactory#bool(Consumer)`, which enables the syntax `f.bool(b -> { b.must(...); b.must(...); }`:
 use the syntax `f.bool().with(b -> { b.must(...); b.must(...); })` instead,
 or (if possible) take advantage of the new `.where(BiConsumer)` method in the Search Query DSL:

documentation/src/test/java/org/hibernate/search/documentation/mapper/orm/bridge/identifierbridge/ormcontext/IdentifierBridgeOrmContextIT.java

@@ -16,7 +16,6 @@
 import org.hibernate.search.documentation.testsupport.BackendConfigurations;
 import org.hibernate.search.documentation.testsupport.DocumentationSetupHelper;
 import org.hibernate.search.mapper.orm.Search;
-import org.hibernate.search.mapper.orm.common.EntityReference;
 import org.hibernate.search.mapper.orm.session.SearchSession;
 
 import org.junit.Before;
@@ -50,12 +49,12 @@ public void smoke() {
 
 			SearchSession searchSession = Search.session( entityManager );
 
-			List<EntityReference> result = searchSession.search( MyEntity.class )
-					.select( f -> f.entityReference() )
+			List<MyData> result = searchSession.search( MyEntity.class )
+					.select( f -> f.id( MyData.class ) )
 					.where( f -> f.matchAll() )
 					.fetchHits( 20 );
 
-			assertThat( result ).extracting( EntityReference::id ).containsExactly( MyData.VALUE2 );
+			assertThat( result ).containsExactly( MyData.VALUE2 );
 		} );
 	}
 

documentation/src/test/java/org/hibernate/search/documentation/search/projection/ProjectionDslIT.java

@@ -25,13 +25,13 @@
 import org.hibernate.search.documentation.testsupport.BackendConfigurations;
 import org.hibernate.search.documentation.testsupport.DocumentationSetupHelper;
 import org.hibernate.search.engine.backend.common.DocumentReference;
+import org.hibernate.search.engine.common.EntityReference;
 import org.hibernate.search.engine.search.common.ValueConvert;
 import org.hibernate.search.engine.search.query.SearchResult;
 import org.hibernate.search.engine.spatial.DistanceUnit;
 import org.hibernate.search.engine.spatial.GeoPoint;
 import org.hibernate.search.mapper.orm.Search;
-import org.hibernate.search.mapper.orm.common.EntityReference;
-import org.hibernate.search.mapper.orm.common.impl.EntityReferenceImpl;
+import org.hibernate.search.mapper.pojo.common.spi.PojoEntityReference;
 import org.hibernate.search.mapper.orm.scope.SearchScope;
 import org.hibernate.search.mapper.orm.session.SearchSession;
 import org.hibernate.search.util.impl.integrationtest.common.assertion.TestComparators;
@@ -40,6 +40,7 @@
 import org.junit.Rule;
 import org.junit.Test;
 
+import org.assertj.core.api.Assertions;
 import org.assertj.core.api.recursive.comparison.RecursiveComparisonConfiguration;
 
 public class ProjectionDslIT {
@@ -133,16 +134,16 @@ public void documentReference() {
 	public void reference() {
 		withinSearchSession( searchSession -> {
 			// tag::reference[]
-			List<EntityReference> hits = searchSession.search( Book.class )
+			List<? extends EntityReference> hits = searchSession.search( Book.class )
 					.select( f -> f.entityReference() )
 					.where( f -> f.matchAll() )
 					.fetchHits( 20 );
 			// end::reference[]
-			assertThat( hits ).containsExactlyInAnyOrder(
-					EntityReferenceImpl.withDefaultName( Book.class, BOOK1_ID ),
-					EntityReferenceImpl.withDefaultName( Book.class, BOOK2_ID ),
-					EntityReferenceImpl.withDefaultName( Book.class, BOOK3_ID ),
-					EntityReferenceImpl.withDefaultName( Book.class, BOOK4_ID )
+			Assertions.<EntityReference>assertThat( hits ).containsExactlyInAnyOrder(
+					PojoEntityReference.withDefaultName( Book.class, BOOK1_ID ),
+					PojoEntityReference.withDefaultName( Book.class, BOOK2_ID ),
+					PojoEntityReference.withDefaultName( Book.class, BOOK3_ID ),
+					PojoEntityReference.withDefaultName( Book.class, BOOK4_ID )
 			);
 		} );
 	}

engine/src/main/java/org/hibernate/search/engine/backend/common/spi/MultiEntityOperationExecutionReport.java

@@ -99,7 +99,7 @@ public Builder<R> failingEntityReference(R reference) {
 			return this;
 		}
 
-		public Builder<R> failingEntityReference(EntityReferenceFactory<R> referenceFactory,
+		public Builder<R> failingEntityReference(EntityReferenceFactory<? extends R> referenceFactory,
 				String typeName, Object entityIdentifier) {
 			R reference = EntityReferenceFactory.safeCreateEntityReference( referenceFactory,
 					typeName, entityIdentifier, this::throwable );

engine/src/main/java/org/hibernate/search/engine/backend/work/execution/spi/IndexIndexingPlan.java

@@ -75,7 +75,7 @@ default CompletableFuture<?> execute(OperationSubmitter operationSubmitter) {
 	 * but the report will contain an exception.
 	 */
 	<R> CompletableFuture<MultiEntityOperationExecutionReport<R>> executeAndReport(
-			EntityReferenceFactory<R> entityReferenceFactory, OperationSubmitter operationSubmitter);
+			EntityReferenceFactory<? extends R> entityReferenceFactory, OperationSubmitter operationSubmitter);
 
 	/**
 	 * Discard all works that are present in this plan.

engine/src/main/java/org/hibernate/search/engine/common/EntityReference.java

@@ -0,0 +1,31 @@
+/*
+ * Hibernate Search, full-text search for your domain model
+ *
+ * License: GNU Lesser General Public License (LGPL), version 2.1 or later
+ * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
+ */
+package org.hibernate.search.engine.common;
+
+/**
+ * A reference to an indexed or contained entity.
+ */
+public interface EntityReference {
+
+	/**
+	 * @return The type of the referenced entity.
+	 */
+	Class<?> type();
+
+	/**
+	 * @return The name of the referenced entity.
+	 */
+	String name();
+
+	/**
+	 * @return The identifier of the referenced entity for Hibernate Search.
+	 * This is the value of the property used to generate the document ID,
+	 * which is generally also the entity ID (though depending on the mapping this may be another unique property).
+	 */
+	Object id();
+
+}

engine/src/main/java/org/hibernate/search/engine/search/projection/dsl/SearchProjectionFactory.java

@@ -11,6 +11,7 @@
 import java.util.function.Function;
 
 import org.hibernate.search.engine.backend.common.DocumentReference;
+import org.hibernate.search.engine.common.EntityReference;
 import org.hibernate.search.engine.search.common.ValueConvert;
 import org.hibernate.search.engine.search.projection.SearchProjection;
 import org.hibernate.search.engine.spatial.GeoPoint;
@@ -52,8 +53,10 @@ public interface SearchProjectionFactory<R, E> {
 	/**
 	 * Project to a reference to the entity that was originally indexed.
 	 * <p>
-	 * The actual type of the reference depends on the mapper used to create the query:
-	 * the ORM mapper will return a class/identifier pair, for example.
+	 * Entity references are instances of type {@link EntityReference},
+	 * but some mappers may expose a different type for backwards compatibility reasons.
+	 * {@link EntityReference} should be favored wherever possible
+	 * as mapper-specific types will eventually be removed.
 	 *
 	 * @return A DSL step where the "entity reference" projection can be defined in more details.
 	 */

engine/src/main/java/org/hibernate/search/engine/search/query/dsl/SearchQuerySelectStep.java

@@ -10,6 +10,7 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+import org.hibernate.search.engine.common.EntityReference;
 import org.hibernate.search.engine.search.predicate.SearchPredicate;
 import org.hibernate.search.engine.search.projection.SearchProjection;
 import org.hibernate.search.engine.search.predicate.dsl.SearchPredicateFactory;
@@ -62,6 +63,11 @@ public interface SearchQuerySelectStep<
 	/**
 	 * Select a reference to the entity that was originally indexed
 	 * as a representation of the search hit for each matching document.
+	 * <p>
+	 * Entity references are instances of type {@link EntityReference},
+	 * but some mappers may expose a different type for backwards compatibility reasons.
+	 * {@link EntityReference} should be favored wherever possible
+	 * as mapper-specific types will eventually be removed.
 	 *
 	 * @return The next step.
 	 * @see SearchQueryWhereStep

integrationtest/mapper/orm-coordination-outbox-polling/src/test/java/org/hibernate/search/integrationtest/mapper/orm/coordination/outboxpolling/automaticindexing/OutboxPollingAutomaticIndexingBackendFailureIT.java

@@ -19,11 +19,11 @@
 import javax.persistence.Id;
 
 import org.hibernate.SessionFactory;
+import org.hibernate.search.engine.common.EntityReference;
 import org.hibernate.search.engine.reporting.EntityIndexingFailureContext;
 import org.hibernate.search.integrationtest.mapper.orm.coordination.outboxpolling.testsupport.util.OutboxEventFilter;
 import org.hibernate.search.integrationtest.mapper.orm.coordination.outboxpolling.testsupport.util.TestFailureHandler;
 import org.hibernate.search.integrationtest.mapper.orm.coordination.outboxpolling.testsupport.util.TestingOutboxPollingInternalConfigurer;
-import org.hibernate.search.mapper.orm.common.EntityReference;
 import org.hibernate.search.mapper.orm.coordination.outboxpolling.cfg.impl.HibernateOrmMapperOutboxPollingImplSettings;
 import org.hibernate.search.mapper.pojo.mapping.definition.annotation.GenericField;
 import org.hibernate.search.mapper.pojo.mapping.definition.annotation.Indexed;

integrationtest/mapper/orm-coordination-outbox-polling/src/test/java/org/hibernate/search/integrationtest/mapper/orm/coordination/outboxpolling/testsupport/util/TestFailureHandler.java

@@ -12,11 +12,11 @@
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+import org.hibernate.search.engine.common.EntityReference;
 import org.hibernate.search.engine.reporting.EntityIndexingFailureContext;
 import org.hibernate.search.engine.reporting.FailureContext;
 import org.hibernate.search.engine.reporting.FailureHandler;
 import org.hibernate.search.engine.reporting.impl.LogFailureHandler;
-import org.hibernate.search.mapper.orm.common.EntityReference;
 
 public class TestFailureHandler implements FailureHandler {
 	public final List<FailureContext> genericFailures = Collections.synchronizedList( new ArrayList<>() );

integrationtest/mapper/orm/src/test/java/org/hibernate/search/integrationtest/mapper/orm/multitenancy/DatabaseMultitenancyIT.java

@@ -15,9 +15,9 @@
 import org.hibernate.Session;
 import org.hibernate.SessionFactory;
 import org.hibernate.search.engine.backend.common.DocumentReference;
+import org.hibernate.search.engine.common.EntityReference;
 import org.hibernate.search.engine.search.query.SearchQuery;
 import org.hibernate.search.mapper.orm.Search;
-import org.hibernate.search.mapper.orm.common.EntityReference;
 import org.hibernate.search.util.impl.integrationtest.common.rule.BackendMock;
 import org.hibernate.search.util.impl.integrationtest.common.rule.StubSearchWorkBehavior;
 import org.hibernate.search.util.impl.integrationtest.mapper.orm.OrmSetupHelper;
@@ -96,8 +96,7 @@ public void shouldMatchOnlyElementsFromOneTenant() {
 
 	@Test
 	public void searchReferences() {
-		List<EntityReference> entityReferences = searchReferences( GEOCHRON_TID, GEOCHRON_MODELS );
-		assertThat( entityReferences ).hasSize( GEOCHRON_MODELS.length );
+		assertThat( searchReferences( GEOCHRON_TID, GEOCHRON_MODELS ) ).hasSize( GEOCHRON_MODELS.length );
 	}
 
 	private void persist(String tenantId, Clock[] models) {
@@ -148,9 +147,9 @@ private List<Clock> searchModel(String searchString, String tenantId, Clock[] mo
 		}
 	}
 
-	private List<EntityReference> searchReferences(String tenantId, Clock[] models) {
+	private List<? extends EntityReference> searchReferences(String tenantId, Clock[] models) {
 		try ( Session session = openSessionWithTenantId( tenantId ) ) {
-			SearchQuery<EntityReference> query = Search.session( session )
+			SearchQuery<? extends EntityReference> query = Search.session( session )
 					.search( Clock.class )
 					.selectEntityReference()
 					.where( f -> f.matchAll() )