Skip to content

Commit

Permalink
HSEARCH-3319 WIP: DRAFT: IDEA: TEST: Type-safe field references
Browse files Browse the repository at this point in the history
  • Loading branch information
marko-bekhta committed Apr 29, 2024
1 parent a7d4b3f commit 4ba16cb
Show file tree
Hide file tree
Showing 36 changed files with 1,641 additions and 218 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@

class ProjectionConverterIT {
@RegisterExtension
public DocumentationSetupHelper setupHelper = DocumentationSetupHelper.withSingleBackend( BackendConfigurations.simple() );
public DocumentationSetupHelper setupHelper = DocumentationSetupHelper.withSingleBackend(
BackendConfigurations.simple() );

private EntityManagerFactory entityManagerFactory;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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}),
Expand Down Expand Up @@ -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 );
}

}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down Expand Up @@ -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 );
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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() );
}

}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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);
}
Original file line number Diff line number Diff line change
@@ -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);

}
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
/*
* 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...)
*/
@SuppressWarnings("unchecked")
S fields(V... fieldPaths);

}
Original file line number Diff line number Diff line change
Expand Up @@ -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> {

}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -45,4 +46,18 @@ default N field(String fieldPath) {
* @see #field(String)
*/
N fields(String... fieldPaths);

/**
* TODO
*/
@SuppressWarnings("unchecked")
default <T> MatchPredicateFieldMoreGenericStep<?, ?, T, TypedFieldReference<T>> field(TypedFieldReference<T> field) {
return fields( field );
}

/**
* TODO
*/
@SuppressWarnings("unchecked")
<T> MatchPredicateFieldMoreGenericStep<?, ?, T, TypedFieldReference<T>> fields(TypedFieldReference<T>... fields);
}
Original file line number Diff line number Diff line change
@@ -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);
}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -47,5 +48,4 @@ default N matching(Object value) {
* @see ValueConvert
*/
N matching(Object value, ValueConvert convert);

}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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() );
}

}
Loading

0 comments on commit 4ba16cb

Please sign in to comment.