HSEARCH-3319 WIP: DRAFT: IDEA: TEST: Type-safe field references

documentation/src/test/java/org/hibernate/search/documentation/search/converter/ProjectionConverterIT.java

@@ -34,7 +34,8 @@
 
 class ProjectionConverterIT {
 	@RegisterExtension
-	public DocumentationSetupHelper setupHelper = DocumentationSetupHelper.withSingleBackend( BackendConfigurations.simple() );
+	public DocumentationSetupHelper setupHelper = DocumentationSetupHelper.withSingleBackend(
+			BackendConfigurations.simple() );
 
 	private EntityManagerFactory entityManagerFactory;
 

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

@@ -6,6 +6,9 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.TypedFieldReference;
+import org.hibernate.search.util.common.annotation.Incubating;
+
 /**
  * The step in a query string predicate definition, where the query string to match can be set
  * (see the superinterface {@link CommonQueryStringPredicateMatchingStep}),
@@ -54,4 +57,46 @@ default S field(String fieldPath) {
 	 */
 	S fields(String... fieldPaths);
 
+	/**
+	 * Target the given field in the query string predicate,
+	 * as an alternative to the already-targeted fields.
+	 * <p>
+	 * Only text fields are supported.
+	 * <p>
+	 * See {@link CommonQueryStringPredicateFieldStep#field(String)} for more information on targeted fields.
+	 *
+	 * @param field The field reference representing a <a href="SearchPredicateFactory.html#field-paths">path</a> to the index field
+	 * to apply the predicate on.
+	 * @return The next step.
+	 *
+	 * @see CommonQueryStringPredicateFieldStep#field(String)
+	 */
+	@Incubating
+	default S field(TypedFieldReference<?> field) {
+		return fields( field );
+	}
+
+	/**
+	 * Target the given fields in the query string predicate,
+	 * as an alternative to the already-targeted fields.
+	 * <p>
+	 * Only text fields are supported.
+	 * <p>
+	 * See {@link CommonQueryStringPredicateFieldStep#fields(String...)} for more information on targeted fields.
+	 *
+	 * @param fields The field reference representing <a href="SearchPredicateFactory.html#field-paths">paths</a> to the index fields
+	 * to apply the predicate on.
+	 * @return The next step.
+	 *
+	 * @see CommonQueryStringPredicateFieldStep#fields(String...)
+	 */
+	@Incubating
+	default S fields(TypedFieldReference<?>... fields) {
+		String[] paths = new String[fields.length];
+		for ( int i = 0; i < fields.length; i++ ) {
+			paths[i] = fields[i].absolutePath();
+		}
+		return fields( paths );
+	}
+
 }

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

@@ -6,6 +6,9 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.TypedFieldReference;
+import org.hibernate.search.util.common.annotation.Incubating;
+
 /**
  * The initial step in a query string predicate definition, where the target field can be set.
  *
@@ -51,4 +54,50 @@ default N field(String fieldPath) {
 	 */
 	N fields(String... fieldPaths);
 
+
+	/**
+	 * Target the given field in the query string predicate.
+	 * <p>
+	 * Only text fields are supported.
+	 * <p>
+	 * Multiple fields may be targeted by the same predicate:
+	 * the predicate will match if <em>any</em> targeted field matches.
+	 * <p>
+	 * When targeting multiple fields, those fields must have compatible types.
+	 * Please refer to the reference documentation for more information.
+	 *
+	 * @param field The field reference representing a <a href="SearchPredicateFactory.html#field-paths">path</a> to the index field
+	 * to apply the predicate on.
+	 * @return The next step.
+	 */
+	@Incubating
+	default N field(TypedFieldReference<?> field) {
+		return fields( field );
+	}
+
+	/**
+	 * Target the given fields in the query string predicate.
+	 * <p>
+	 * Only text fields are supported.
+	 * <p>
+	 * Equivalent to {@link #field(String)} followed by multiple calls to
+	 * {@link #field(String)},
+	 * the only difference being that calls to {@link CommonQueryStringPredicateFieldMoreStep#boost(float)}
+	 * and other field-specific settings on the returned step will only need to be done once
+	 * and will apply to all the fields passed to this method.
+	 *
+	 * @param fields The field reference representing <a href="SearchPredicateFactory.html#field-paths">paths</a> to the index fields
+	 * to apply the predicate on.
+	 * @return The next step.
+	 *
+	 * @see #field(String)
+	 */
+	@Incubating
+	default N fields(TypedFieldReference<?>... fields) {
+		String[] paths = new String[fields.length];
+		for ( int i = 0; i < fields.length; i++ ) {
+			paths[i] = fields[i].absolutePath();
+		}
+		return fields( paths );
+	}
 }

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

@@ -6,6 +6,7 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.TypedFieldReference;
 
 /**
  * The initial step in an "exists" predicate definition, where the target field can be set.
@@ -23,4 +24,15 @@ public interface ExistsPredicateFieldStep<N extends ExistsPredicateOptionsStep<?
 	 */
 	N field(String fieldPath);
 
+	/**
+	 * Target the given field in the "exists" predicate.
+	 *
+	 * @param field The field reference representing a <a href="SearchPredicateFactory.html#field-paths">path</a> to the index field
+	 * to apply the predicate on.
+	 * @return The next step.
+	 */
+	default N field(TypedFieldReference<?> field) {
+		return field( field.absolutePath() );
+	}
+
 }

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

@@ -6,6 +6,8 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.TypedFieldReference;
+
 /**
  * The initial step in a "knn" predicate definition, where the target field can be set.
  */
@@ -18,4 +20,6 @@ public interface KnnPredicateFieldStep {
 	 * @return The next step in the knn predicate DSL.
 	 */
 	KnnPredicateVectorStep field(String fieldPath);
+
+	<T> KnnPredicateVectorGenericStep<T> field(TypedFieldReference<T> field);
 }

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

@@ -0,0 +1,19 @@
+/*
+ * 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.search.predicate.dsl;
+
+/**
+ * The step in a "knn" predicate definition where the vector to match is defined.
+ */
+public interface KnnPredicateVectorGenericStep<T> {
+	/**
+	 * @param vector The vector from which to compute the distance to vectors in the indexed field.
+	 * @return The next step in the knn predicate DSL.
+	 */
+	KnnPredicateOptionsStep matching(T vector);
+
+}

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

@@ -0,0 +1,55 @@
+/*
+ * 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.search.predicate.dsl;
+
+/**
+ * The step in a "match" predicate definition where the value to match can be set
+ * (see the superinterface {@link MatchPredicateMatchingStep}),
+ * or optional parameters for the last targeted field(s) can be set,
+ * or more target fields can be added.
+ *
+ * @param <S> The "self" type (the actual exposed type of this step).
+ * @param <N> The type of the next step.
+ * @param <T> The type of the match value.
+ * @param <V> The type representing the fields.
+ */
+public interface MatchPredicateFieldMoreGenericStep<
+		S extends MatchPredicateFieldMoreGenericStep<?, N, T, V>,
+		N extends MatchPredicateOptionsStep<?>,
+		T,
+		V>
+		extends MatchPredicateMatchingGenericStep<N, T>, MultiFieldPredicateFieldBoostStep<S> {
+
+	/**
+	 * Target the given field in the match predicate,
+	 * as an alternative to the already-targeted fields.
+	 * <p>
+	 * See {@link MatchPredicateFieldStep#field(String)} for more information about targeting fields.
+	 *
+	 * @param field The field with a <a href="SearchPredicateFactory.html#field-paths">path</a> to the index field
+	 * to apply the predicate on.
+	 * @return The next step.
+	 *
+	 * @see MatchPredicateFieldStep#field(String)
+	 */
+	S field(V field);
+
+	/**
+	 * Target the given fields in the match predicate,
+	 * as an alternative to the already-targeted fields.
+	 * <p>
+	 * See {@link MatchPredicateFieldStep#fields(String...)} for more information about targeting fields.
+	 *
+	 * @param fieldPaths The fields with <a href="SearchPredicateFactory.html#field-paths">paths</a> to the index fields
+	 * to apply the predicate on.
+	 * @return The next step.
+	 *
+	 * @see MatchPredicateFieldStep#fields(String...)
+	 */
+	S fields(V... fieldPaths);
+
+}

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

@@ -18,36 +18,6 @@
 public interface MatchPredicateFieldMoreStep<
 		S extends MatchPredicateFieldMoreStep<?, N>,
 		N extends MatchPredicateOptionsStep<?>>
-		extends MatchPredicateMatchingStep<N>, MultiFieldPredicateFieldBoostStep<S> {
-
-	/**
-	 * Target the given field in the match predicate,
-	 * as an alternative to the already-targeted fields.
-	 * <p>
-	 * See {@link MatchPredicateFieldStep#field(String)} for more information about targeting fields.
-	 *
-	 * @param fieldPath The <a href="SearchPredicateFactory.html#field-paths">path</a> to the index field
-	 * to apply the predicate on.
-	 * @return The next step.
-	 *
-	 * @see MatchPredicateFieldStep#field(String)
-	 */
-	default S field(String fieldPath) {
-		return fields( fieldPath );
-	}
-
-	/**
-	 * Target the given fields in the match predicate,
-	 * as an alternative to the already-targeted fields.
-	 * <p>
-	 * See {@link MatchPredicateFieldStep#fields(String...)} for more information about targeting fields.
-	 *
-	 * @param fieldPaths The <a href="SearchPredicateFactory.html#field-paths">paths</a> to the index fields
-	 * to apply the predicate on.
-	 * @return The next step.
-	 *
-	 * @see MatchPredicateFieldStep#fields(String...)
-	 */
-	S fields(String... fieldPaths);
+		extends MatchPredicateMatchingStep<N>, MatchPredicateFieldMoreGenericStep<S, N, Object, String> {
 
 }

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

@@ -6,6 +6,7 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.TypedFieldReference;
 
 /**
  * The initial step in a "match" predicate definition, where the target field can be set.
@@ -33,7 +34,7 @@ default N field(String fieldPath) {
 	 * Target the given fields in the match predicate.
 	 * <p>
 	 * Equivalent to {@link #field(String)} followed by multiple calls to
-	 * {@link MatchPredicateFieldMoreStep#field(String)},
+	 * {@link MatchPredicateFieldMoreStep#field(Object)},
 	 * the only difference being that calls to {@link MatchPredicateFieldMoreStep#boost(float)}
 	 * and other field-specific settings on the returned step will only need to be done once
 	 * and will apply to all the fields passed to this method.
@@ -45,4 +46,16 @@ default N field(String fieldPath) {
 	 * @see #field(String)
 	 */
 	N fields(String... fieldPaths);
+
+	/**
+	 * TODO
+	 */
+	default <T> MatchPredicateFieldMoreGenericStep<?, ?, T, TypedFieldReference<T>> field(TypedFieldReference<T> field) {
+		return fields( field );
+	}
+
+	/**
+	 * TODO
+	 */
+	<T> MatchPredicateFieldMoreGenericStep<?, ?, T, TypedFieldReference<T>> fields(TypedFieldReference<T>... fields);
 }

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

@@ -0,0 +1,26 @@
+/*
+ * 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.search.predicate.dsl;
+
+/**
+ * The step in a "match" predicate definition where the value to match can be set.
+ *
+ * @param <N> The type of the next step.
+ * @param <T> The type of the match value.
+ */
+public interface MatchPredicateMatchingGenericStep<N extends MatchPredicateOptionsStep<?>, T> {
+
+	/**
+	 * Require at least one of the targeted fields to match the given value.
+	 *
+	 * @param value The value to match.
+	 * The signature of this method defines this parameter as an {@code T},
+	 * but a specific type is expected depending on the targeted field.
+	 * @return The next step.
+	 */
+	N matching(T value);
+}

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

@@ -13,7 +13,8 @@
  *
  * @param <N> The type of the next step.
  */
-public interface MatchPredicateMatchingStep<N extends MatchPredicateOptionsStep<?>> {
+public interface MatchPredicateMatchingStep<N extends MatchPredicateOptionsStep<?>>
+		extends MatchPredicateMatchingGenericStep<N, Object> {
 
 	/**
 	 * Require at least one of the targeted fields to match the given value.
@@ -22,7 +23,7 @@ public interface MatchPredicateMatchingStep<N extends MatchPredicateOptionsStep<
 	 * See {@link ValueConvert#YES}.
 	 *
 	 * @param value The value to match.
-	 * The signature of this method defines this parameter as an {@link Object},
+	 * The signature of this method defines this parameter as an {@code T},
 	 * but a specific type is expected depending on the targeted field.
 	 * See {@link ValueConvert#YES} for more information.
 	 * @return The next step.
@@ -47,5 +48,4 @@ default N matching(Object value) {
 	 * @see ValueConvert
 	 */
 	N matching(Object value, ValueConvert convert);
-
 }

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

@@ -7,6 +7,7 @@
 package org.hibernate.search.engine.search.predicate.dsl;
 
 import org.hibernate.search.engine.backend.types.ObjectStructure;
+import org.hibernate.search.engine.search.reference.NestedObjectFieldReference;
 
 /**
  * The initial step in a "nested" predicate definition, where the target field can be set.
@@ -27,4 +28,17 @@ public interface NestedPredicateFieldStep<N extends NestedPredicateNestStep<?>>
 	 */
 	N objectField(String fieldPath);
 
+	/**
+	 * Set the object field to "nest" on.
+	 * <p>
+	 * The selected field must have a {@link ObjectStructure#NESTED nested structure} in the targeted indexes.
+	 *
+	 * @param field The field reference representing a <a href="SearchPredicateFactory.html#field-paths">path</a> to the object field
+	 * to apply the predicate on.
+	 * @return The next step.
+	 */
+	default N objectField(NestedObjectFieldReference field) {
+		return objectField( field.absolutePath() );
+	}
+
 }