HSEARCH-3319 Address super-type references

documentation/src/test/java/org/hibernate/search/documentation/search/predicate/FieldReferenceIT.java

@@ -67,6 +67,13 @@ void smoke() {
 							.fetchHits( 20 )
 			).containsOnly( "c" );
 
+			assertThat(
+					searchSession.search( EntityC_.scope )
+							.select( f -> f.field( EntityC_.stringA ) )
+							.where( f -> f.match().field( EntityC_.stringA ).matching( "c" ) )
+							.fetchHits( 20 )
+			).containsOnly( "c" );
+
 			SearchScope<EntityB_union_EntityC_, EntityB> scope = EntityB_union_EntityC_.scope.create( searchSession );
 
 			SearchPredicate searchPredicate =
@@ -200,30 +207,24 @@ public static class EntityA_ {
 		}
 	}
 
-	public static class EntityB_ {
-		public static ValueFieldReference1<EntityB_, String, String, String> stringA;
+	public static class EntityB_ extends EntityA_ {
 		public static ValueFieldReference1<EntityB_, String, String, String> stringB;
 
 		public static RootReferenceScope<EntityB_, EntityB> scope;
 
 		static {
-			stringA = ValueFieldReference1.of( "stringA", EntityB_.class, String.class, String.class, String.class );
 			stringB = ValueFieldReference1.of( "stringB", EntityB_.class, String.class, String.class, String.class );
 
 			scope = RootReferenceScopeImpl.of( EntityB_.class, EntityB.class );
 		}
 	}
 
-	public static class EntityC_ {
-		public static ValueFieldReference1<EntityC_, String, String, String> stringA;
-		public static ValueFieldReference1<EntityC_, String, String, String> stringB;
+	public static class EntityC_ extends EntityB_ {
 		public static ValueFieldReference1<EntityC_, String, String, String> stringC;
 
 		public static RootReferenceScope<EntityC_, EntityC> scope;
 
 		static {
-			stringA = ValueFieldReference1.of( "stringA", EntityC_.class, String.class, String.class, String.class );
-			stringB = ValueFieldReference1.of( "stringB", EntityC_.class, String.class, String.class, String.class );
 			stringC = ValueFieldReference1.of( "stringC", EntityC_.class, String.class, String.class, String.class );
 
 			scope = RootReferenceScopeImpl.of( EntityC_.class, EntityC.class );

engine/src/main/java/org/hibernate/search/engine/search/aggregation/dsl/RangeAggregationFieldStep.java

@@ -10,6 +10,7 @@
 
 import org.hibernate.search.engine.search.common.ValueConvert;
 import org.hibernate.search.engine.search.predicate.dsl.SearchPredicateFactory;
+import org.hibernate.search.engine.search.reference.aggregation.RangeAggregationFieldReference;
 
 /**
  * The initial step in a "range" aggregation definition, where the target field can be set.
@@ -43,4 +44,15 @@ public interface RangeAggregationFieldStep<SR, PDF extends SearchPredicateFactor
 	 */
 	<F> RangeAggregationRangeStep<SR, ?, PDF, F> field(String fieldPath, Class<F> type, ValueConvert convert);
 
+	/**
+	 * Target the given field in the range aggregation.
+	 *
+	 * @param fieldReference The field reference representing a <a href="SearchAggregationFactory.html#field-paths">path</a> to the index field to aggregate.
+	 * @param <F> The type of field values.
+	 * @return The next step.
+	 */
+	default <F> RangeAggregationRangeStep<SR, ?, PDF, F> field(RangeAggregationFieldReference<? super SR, F> fieldReference) {
+		return field( fieldReference.absolutePath(), fieldReference.aggregationType(), fieldReference.valueConvert() );
+	}
+
 }

engine/src/main/java/org/hibernate/search/engine/search/aggregation/dsl/SearchAggregationFactory.java

@@ -9,6 +9,7 @@
 import java.util.function.Function;
 
 import org.hibernate.search.engine.search.common.NamedValues;
+import org.hibernate.search.engine.search.reference.object.ObjectFieldReference;
 import org.hibernate.search.util.common.SearchException;
 import org.hibernate.search.util.common.annotation.Incubating;
 
@@ -101,6 +102,20 @@ <T> AggregationFinalStep<T> withParameters(
 	@Incubating
 	SearchAggregationFactory<SR> withRoot(String objectFieldPath);
 
+	/**
+	 * Create a new aggregation factory whose root for all paths passed to the DSL
+	 * will be the given object field.
+	 * <p>
+	 * See <a href="#field-paths">here</a> for more information.
+	 *
+	 * @param objectFieldReference The reference representing the path from the current root to an object field that will become the new root.
+	 * @return A new aggregation factory using the given object field as root.
+	 */
+	@Incubating
+	default SearchAggregationFactory<SR> withRoot(ObjectFieldReference<? super SR> objectFieldReference) {
+		return withRoot( objectFieldReference.absolutePath() );
+	}
+
 	/**
 	 * @param relativeFieldPath The path to a field, relative to the {@link #withRoot(String) root} of this factory.
 	 * @return The absolute path of the field, for use in native aggregations for example.

engine/src/main/java/org/hibernate/search/engine/search/aggregation/dsl/TermsAggregationFieldStep.java

@@ -11,6 +11,7 @@
 
 import org.hibernate.search.engine.search.common.ValueConvert;
 import org.hibernate.search.engine.search.predicate.dsl.SearchPredicateFactory;
+import org.hibernate.search.engine.search.reference.aggregation.TermsAggregationFieldReference;
 
 /**
  * The initial step in a "terms" aggregation definition, where the target field can be set.
@@ -45,4 +46,16 @@ public interface TermsAggregationFieldStep<SR, PDF extends SearchPredicateFactor
 	<F> TermsAggregationOptionsStep<SR, ?, PDF, F, Map<F, Long>> field(String fieldPath, Class<F> type,
 			ValueConvert convert);
 
+	/**
+	 * Target the given field in the terms aggregation.
+	 *
+	 * @param fieldReference The field reference representing a <a href="SearchAggregationFactory.html#field-paths">path</a> to the index field to aggregate.
+	 * @param <F> The type of field values.
+	 * @return The next step.
+	 */
+	default <F> TermsAggregationOptionsStep<SR, ?, PDF, F, Map<F, Long>> field(
+			TermsAggregationFieldReference<? super SR, F> fieldReference) {
+		return field( fieldReference.absolutePath(), fieldReference.aggregationType(), fieldReference.valueConvert() );
+	}
+
 }

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/ExistsPredicateFieldStep.java

@@ -33,7 +33,7 @@ public interface ExistsPredicateFieldStep<SR, N extends ExistsPredicateOptionsSt
 	 * @return The next step.
 	 */
 	@Incubating
-	default N field(ExistsPredicateFieldReference<SR> field) {
+	default N field(ExistsPredicateFieldReference<? super SR> field) {
 		return field( field.absolutePath() );
 	}
 

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/KnnPredicateFieldStep.java

@@ -22,5 +22,5 @@ public interface KnnPredicateFieldStep<SR> {
 	 */
 	KnnPredicateVectorStep<SR> field(String fieldPath);
 
-	<T> KnnPredicateVectorGenericStep<SR, T> field(KnnPredicateFieldReference<SR, T> field);
+	<T> KnnPredicateVectorGenericStep<SR, T> field(KnnPredicateFieldReference<? super SR, T> field);
 }

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/MatchPredicateFieldStep.java

@@ -61,8 +61,8 @@ default N field(String fieldPath) {
 	 * @return The next step.
 	 */
 	@SuppressWarnings("unchecked")
-	default <T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<SR, T>> field(
-			MatchPredicateFieldReference<SR, T> fieldReference) {
+	default <T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<? super SR, T>> field(
+			MatchPredicateFieldReference<? super SR, T> fieldReference) {
 		return fields( fieldReference );
 	}
 
@@ -82,6 +82,6 @@ default N field(String fieldPath) {
 	 * @see #field(MatchPredicateFieldReference)
 	 */
 	@SuppressWarnings("unchecked")
-	<T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<SR, T>> fields(
-			MatchPredicateFieldReference<SR, T>... fieldReferences);
+	<T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<? super SR, T>> fields(
+			MatchPredicateFieldReference<? super SR, T>... fieldReferences);
 }

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/NestedPredicateFieldStep.java

@@ -38,7 +38,7 @@ public interface NestedPredicateFieldStep<SR, N extends NestedPredicateNestStep<
 	 * to apply the predicate on.
 	 * @return The next step.
 	 */
-	default N objectField(NestedPredicateFieldReference<SR> field) {
+	default N objectField(NestedPredicateFieldReference<? super SR> field) {
 		return objectField( field.absolutePath() );
 	}
 

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/PhrasePredicateFieldMoreStep.java

@@ -75,7 +75,7 @@ default S field(String fieldPath) {
 	 */
 	@Incubating
 	@SuppressWarnings("unchecked")
-	default S field(PhrasePredicateFieldReference<SR, ?> field) {
+	default S field(PhrasePredicateFieldReference<? super SR, ?> field) {
 		return fields( field );
 	}
 
@@ -95,7 +95,7 @@ default S field(PhrasePredicateFieldReference<SR, ?> field) {
 	 */
 	@Incubating
 	@SuppressWarnings("unchecked")
-	default S fields(PhrasePredicateFieldReference<SR, ?>... fields) {
+	default S fields(PhrasePredicateFieldReference<? super SR, ?>... fields) {
 		String[] paths = new String[fields.length];
 		for ( int i = 0; i < fields.length; i++ ) {
 			paths[i] = fields[i].absolutePath();

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/PhrasePredicateFieldStep.java

@@ -74,7 +74,7 @@ default N field(String fieldPath) {
 	 */
 	@Incubating
 	@SuppressWarnings("unchecked")
-	default N field(PhrasePredicateFieldReference<SR, ?> field) {
+	default N field(PhrasePredicateFieldReference<? super SR, ?> field) {
 		return fields( field );
 	}
 
@@ -97,7 +97,7 @@ default N field(PhrasePredicateFieldReference<SR, ?> field) {
 	 */
 	@Incubating
 	@SuppressWarnings("unchecked")
-	default N fields(PhrasePredicateFieldReference<SR, ?>... fields) {
+	default N fields(PhrasePredicateFieldReference<? super SR, ?>... fields) {
 		String[] paths = new String[fields.length];
 		for ( int i = 0; i < fields.length; i++ ) {
 			paths[i] = fields[i].absolutePath();

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/RangePredicateFieldStep.java

@@ -66,8 +66,8 @@ default N field(String fieldPath) {
 	 * @return The next step.
 	 */
 	@SuppressWarnings("unchecked")
-	default <T> RangePredicateFieldMoreGenericStep<SR, ?, ?, RangePredicateFieldReference<SR, T>, T> field(
-			RangePredicateFieldReference<SR, T> field) {
+	default <T> RangePredicateFieldMoreGenericStep<SR, ?, ?, RangePredicateFieldReference<? super SR, T>, T> field(
+			RangePredicateFieldReference<? super SR, T> field) {
 		return fields( field );
 	}
 
@@ -87,7 +87,7 @@ default N field(String fieldPath) {
 	 * @see #field(RangePredicateFieldReference)
 	 */
 	@SuppressWarnings("unchecked")
-	<T> RangePredicateFieldMoreGenericStep<SR, ?, ?, RangePredicateFieldReference<SR, T>, T> fields(
-			RangePredicateFieldReference<SR, T>... fields);
+	<T> RangePredicateFieldMoreGenericStep<SR, ?, ?, RangePredicateFieldReference<? super SR, T>, T> fields(
+			RangePredicateFieldReference<? super SR, T>... fields);
 
 }

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/SearchPredicateFactory.java

@@ -13,6 +13,7 @@
 import org.hibernate.search.engine.search.common.BooleanOperator;
 import org.hibernate.search.engine.search.common.NamedValues;
 import org.hibernate.search.engine.search.predicate.SearchPredicate;
+import org.hibernate.search.engine.search.reference.object.ObjectFieldReference;
 import org.hibernate.search.engine.search.reference.predicate.NestedPredicateFieldReference;
 import org.hibernate.search.util.common.SearchException;
 import org.hibernate.search.util.common.annotation.Incubating;
@@ -248,7 +249,7 @@ SimpleBooleanPredicateOptionsStep<?> or(PredicateFinalStep firstSearchPredicate,
 	 * @return The initial step of a DSL where the "nested" predicate can be defined.
 	 * @see NestedPredicateFieldStep
 	 */
-	default NestedPredicateClausesStep<SR, ?> nested(NestedPredicateFieldReference<SR> field) {
+	default NestedPredicateClausesStep<SR, ?> nested(NestedPredicateFieldReference<? super SR> field) {
 		return nested( field.absolutePath() );
 	}
 
@@ -369,6 +370,21 @@ PredicateFinalStep withParameters(
 	@Incubating
 	SearchPredicateFactory<SR> withRoot(String objectFieldPath);
 
+	/**
+	 * Create a new predicate factory whose root for all paths passed to the DSL
+	 * will be the given object field.
+	 * <p>
+	 * This is used to call reusable methods that apply the same predicate
+	 * on different object fields that have same structure (same sub-fields).
+	 *
+	 * @param objectFieldReference The reference representing the path from the current root to an object field that will become the new root.
+	 * @return A new predicate factory using the given object field as root.
+	 */
+	@Incubating
+	default SearchPredicateFactory<SR> withRoot(ObjectFieldReference<? super SR> objectFieldReference) {
+		return withRoot( objectFieldReference.absolutePath() );
+	}
+
 	/**
 	 * @param relativeFieldPath The path to a field, relative to the {@link #withRoot(String) root} of this factory.
 	 * @return The absolute path of the field, for use in native predicates for example.

engine/src/main/java/org/hibernate/search/engine/search/predicate/dsl/impl/AbstractMatchPredicateFieldMoreStep.java

@@ -53,11 +53,12 @@ abstract class AbstractMatchPredicateFieldMoreStep<
 		);
 	}
 
-	public static <SR, T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<SR, T>> create(
-			SearchPredicateDslContext<?> dslContext, MatchPredicateFieldReference<SR, T>[] fields) {
+	public static <SR, T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<? super SR, T>> create(
+			SearchPredicateDslContext<?> dslContext, MatchPredicateFieldReference<? super SR, T>[] fields) {
+		List<MatchPredicateFieldReference<? super SR, T>> fieldList = Arrays.asList( fields );
 		return new MatchPredicateFieldMoreStepFieldReference<>(
 				dslContext,
-				Arrays.asList( fields )
+				fieldList
 		);
 	}
 
@@ -158,31 +159,32 @@ private static class MatchPredicateFieldMoreStepFieldReference<SR, T>
 			AbstractMatchPredicateFieldMoreStep<MatchPredicateFieldMoreStepFieldReference.CommonState<SR, T>,
 					MatchPredicateFieldMoreStepFieldReference<SR, T>,
 					T,
-					MatchPredicateFieldReference<SR, T>>
+					MatchPredicateFieldReference<? super SR, T>>
 			implements
 			MatchPredicateFieldMoreGenericStep<MatchPredicateFieldMoreStepFieldReference<SR, T>,
 					MatchPredicateFieldMoreStepFieldReference.CommonState<SR, T>,
 					T,
-					MatchPredicateFieldReference<SR, T>> {
+					MatchPredicateFieldReference<? super SR, T>> {
 
 		MatchPredicateFieldMoreStepFieldReference(SearchPredicateDslContext<?> dslContext,
-				List<MatchPredicateFieldReference<SR, T>> fieldPaths) {
+				List<MatchPredicateFieldReference<? super SR, T>> fieldPaths) {
 			super( new CommonState<>( dslContext ), fieldPaths );
 		}
 
 		private MatchPredicateFieldMoreStepFieldReference(CommonState<SR, T> commonState,
-				List<MatchPredicateFieldReference<SR, T>> fieldPaths) {
+				List<MatchPredicateFieldReference<? super SR, T>> fieldPaths) {
 			super( commonState, fieldPaths );
 		}
 
 		@Override
-		public MatchPredicateFieldMoreStepFieldReference<SR, T> field(MatchPredicateFieldReference<SR, T> field) {
+		public MatchPredicateFieldMoreStepFieldReference<SR, T> field(MatchPredicateFieldReference<? super SR, T> field) {
 			return new MatchPredicateFieldMoreStepFieldReference<>( commonState, Collections.singletonList( field ) );
 		}
 
 		@Override
 		@SuppressWarnings("unchecked")
-		public MatchPredicateFieldMoreStepFieldReference<SR, T> fields(MatchPredicateFieldReference<SR, T>... fieldPaths) {
+		public MatchPredicateFieldMoreStepFieldReference<SR, T> fields(
+				MatchPredicateFieldReference<? super SR, T>... fieldPaths) {
 			return new MatchPredicateFieldMoreStepFieldReference<>( commonState, Arrays.asList( fieldPaths ) );
 		}
 
@@ -197,13 +199,15 @@ protected MatchPredicateFieldMoreStepFieldReference<SR, T> thisAsS() {
 		}
 
 		@Override
-		protected String fieldPath(MatchPredicateFieldReference<SR, T> field) {
+		protected String fieldPath(MatchPredicateFieldReference<? super SR, T> field) {
 			return field.absolutePath();
 		}
 
 		private static class CommonState<SR, T>
 				extends
-				GenericCommonState<T, MatchPredicateFieldReference<SR, T>, MatchPredicateFieldMoreStepFieldReference<SR, T>> {
+				GenericCommonState<T,
+						MatchPredicateFieldReference<? super SR, T>,
+						MatchPredicateFieldMoreStepFieldReference<SR, T>> {
 			CommonState(SearchPredicateDslContext<?> dslContext) {
 				super( dslContext );
 			}
@@ -212,7 +216,7 @@ CommonState<SR, T> matching(T value) {
 				Contracts.assertNotNull( value, "value" );
 
 				for ( MatchPredicateFieldMoreStepFieldReference<SR, T> fieldSetState : getFieldSetStates() ) {
-					for ( Map.Entry<MatchPredicateFieldReference<SR, T>,
+					for ( Map.Entry<MatchPredicateFieldReference<? super SR, T>,
 							MatchPredicateBuilder> entry : fieldSetState.predicateBuilders
 									.entrySet() ) {
 						entry.getValue().value( value, entry.getKey().valueConvert() );