HSEARCH-3319 Add references to the DSL

Author: marko-bekhta

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

@@ -4,18 +4,25 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.predicate.TypedPredicateFieldReference;
+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}),
  * or optional parameters for the last targeted field(s) can be set,
  * or more target fields can be added.
  *
+ * @param <SR> Scope root type.
+ * @param <FR> Type of the field references.
  * @param <S> The "self" type (the actual exposed type of this step).
  * @param <N> The type of the next step.
  */
 public interface CommonQueryStringPredicateFieldMoreStep<
-		S extends CommonQueryStringPredicateFieldMoreStep<?, N>,
-		N extends CommonQueryStringPredicateOptionsStep<?>>
+		SR,
+		S extends CommonQueryStringPredicateFieldMoreStep<SR, ?, N, FR>,
+		N extends CommonQueryStringPredicateOptionsStep<?>,
+		FR extends TypedPredicateFieldReference<SR, ?>>
 		extends CommonQueryStringPredicateMatchingStep<N>, MultiFieldPredicateFieldBoostStep<S> {
 
 	/**
@@ -52,4 +59,48 @@ 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
+	@SuppressWarnings("unchecked")
+	default S field(FR 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
+	@SuppressWarnings("unchecked")
+	default S fields(FR... 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

@@ -4,12 +4,20 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.predicate.TypedPredicateFieldReference;
+import org.hibernate.search.util.common.annotation.Incubating;
+
 /**
  * The initial step in a query string predicate definition, where the target field can be set.
  *
+ * @param <SR> Scope root type.
+ * @param <FR> Type of the field references.
  * @param <N> The type of the next step.
  */
-public interface CommonQueryStringPredicateFieldStep<N extends CommonQueryStringPredicateFieldMoreStep<?, ?>> {
+public interface CommonQueryStringPredicateFieldStep<
+		SR,
+		N extends CommonQueryStringPredicateFieldMoreStep<SR, ?, ?, FR>,
+		FR extends TypedPredicateFieldReference<SR, ?>> {
 
 	/**
 	 * Target the given field in the query string predicate.
@@ -49,4 +57,52 @@ 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
+	@SuppressWarnings("unchecked")
+	default N field(FR 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
+	@SuppressWarnings("unchecked")
+	default N fields(FR... 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

@@ -4,13 +4,15 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.predicate.ExistsPredicateFieldReference;
+import org.hibernate.search.util.common.annotation.Incubating;
 
 /**
  * The initial step in an "exists" predicate definition, where the target field can be set.
  *
  * @param <N> The type of the next step.
  */
-public interface ExistsPredicateFieldStep<N extends ExistsPredicateOptionsStep<?>> {
+public interface ExistsPredicateFieldStep<SR, N extends ExistsPredicateOptionsStep<?>> {
 
 	/**
 	 * Target the given field in the "exists" predicate.
@@ -21,4 +23,16 @@ 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.
+	 */
+	@Incubating
+	default N field(ExistsPredicateFieldReference<SR> field) {
+		return field( field.absolutePath() );
+	}
+
 }

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

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

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

@@ -0,0 +1,17 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+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<SR, 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<SR> matching(T vector);
+
+}

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

@@ -0,0 +1,54 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+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...)
+	 */
+	@SuppressWarnings("unchecked")
+	S fields(V... fieldPaths);
+
+}

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

@@ -16,36 +16,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

@@ -4,11 +4,12 @@
  */
 package org.hibernate.search.engine.search.predicate.dsl;
 
+import org.hibernate.search.engine.search.reference.predicate.MatchPredicateFieldReference;
 
 /**
  * The initial step in a "match" predicate definition, where the target field can be set.
  */
-public interface MatchPredicateFieldStep<N extends MatchPredicateFieldMoreStep<?, ?>> {
+public interface MatchPredicateFieldStep<SR, N extends MatchPredicateFieldMoreStep<?, ?>> {
 
 	/**
 	 * Target the given field in the match predicate.
@@ -31,7 +32,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.
@@ -43,4 +44,42 @@ default N field(String fieldPath) {
 	 * @see #field(String)
 	 */
 	N fields(String... fieldPaths);
+
+	/**
+	 * Target the given field in the match predicate.
+	 * <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 fieldReference 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.
+	 */
+	@SuppressWarnings("unchecked")
+	default <T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<SR, T>> field(
+			MatchPredicateFieldReference<SR, T> fieldReference) {
+		return fields( fieldReference );
+	}
+
+	/**
+	 * Target the given fields in the match predicate.
+	 * <p>
+	 * Equivalent to {@link #field(String)} followed by multiple calls to
+	 * {@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.
+	 *
+	 * @param fieldReferences The field references representing <a href="SearchPredicateFactory.html#field-paths">paths</a> to the index fields
+	 * to apply the predicate on.
+	 * @return The next step.
+	 *
+	 * @see #field(MatchPredicateFieldReference)
+	 */
+	@SuppressWarnings("unchecked")
+	<T> MatchPredicateFieldMoreGenericStep<?, ?, T, MatchPredicateFieldReference<SR, T>> fields(
+			MatchPredicateFieldReference<SR, T>... fieldReferences);
 }