HSEARCH-4577 Update the documentation

Author: marko-bekhta

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

@@ -99,6 +99,9 @@ interfaces are removed in this version. They have their alternatives in a `org.h
 Instead, we are introducing the `org.hibernate.search.mapper.pojo.massindexing.MassIndexingTypeGroupMonitor`
 that can be obtained through `org.hibernate.search.mapper.pojo.massindexing.MassIndexingMonitor#typeGroupMonitor(..)`.
 This new type group monitor has more flexibility and also allows implementors to skip total count computations if needed.
+- `multi()` methods exposed in various projection DSL steps are deprecated in favour of an `accumulator(ProjectionAccumulator.Provider)`.
+Check the `ProjectionAccumulator` factory methods to see the list of built-in accumulators that provide support for nullable/optional single-valued projections
+and for multivalued ones such as lists, sets arrays and more.
 
 [[spi]]
 == SPI

documentation/src/main/asciidoc/public/reference/_binding-projection.adoc

@@ -87,26 +87,32 @@ include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/binding/proje
 
 include::../components/_incubating-warning.adoc[]
 
-You can call `.multi()` on the context passed to the projection binder
-in order to discover whether the constructor parameter being bound is multi-valued
-(according to the same rules as <<mapping-projection-inner-inference-type,implicit inner projection inference>>),
-and to bind a multi-valued projection.
+You can call `.containerElement()` on the context passed to the projection binder
+in order to discover whether the constructor parameter being bound is some sort of container wrapping the value/values
+(according to the same rules as <<mapping-projection-inner-inference-type,implicit inner projection inference>>).
+If the returned value is a non-empty optional, then the `.constructorParameter()` will provide access to the container type in use.
+Additionally, the same context has access to a factory (`.projectionAccumulatorProviderFactory()`)
+from which a projection accumulator can be obtained based on a container and element types
+(if the container type is `null` the `nullable()` single-valued accumulator is returned).
 
 .Implementing and using a `ProjectionBinder` supporting multi-valued projections
 ====
 [source, JAVA, indent=0, subs="+callouts"]
 ----
 include::{sourcedir}/org/hibernate/search/documentation/mapper/orm/binding/projectionbinder/multi/MyFieldProjectionBinder.java[tags=include]
 ----
-<1> `multi()` returns an optional that contains a context
-if and only if the constructor parameter is considered multi-valued.
-<2> Call `multi.definition(...)` to define the projection to use.
-<3> Here we're failing for single-valued constructor parameters,
-but we could theoreticall fall back to a single-valued projection.
-<4> The projection definition, being multi-valued,
-must implement `ProjectionDefinition<List<T>>`,
-where `T` is the exepected type of projected values,
+<1> `containerElement()` returns an optional that contains a type of the container elements
+if and only if the constructor parameter is considered as such that is wrapped in a container, e.g. a multivalued collection.
+<2> Call `context.definition(...)` to define the projection to use.
+<3> Here we're failing for single-valued (nullable) constructor parameters,
+but we could theoretically fall back to a single-valued projection using the `ProjectionAccumulator.nullable()`.
+<4> The projection definition, being multivalued,
+must implement `ProjectionDefinition<SomeCollection<T>>`,
+where `T` is the expected type of projected values,
+`SomeCollection` is one of the supported collection types available in `ProjectionAccumulator`,
 and must configure returned projections accordingly.
+If the required collection type is not present in the `ProjectionAccumulator`,
+then a custom projection accumulator provider can be supplied.
 
 [source, JAVA, indent=0, subs="+callouts"]
 ----
@@ -138,7 +144,8 @@ or by delegating to it in a custom projection definition.
 
 Other methods exposed on the binding context work similarly:
 
-* `.createObjectDefinitionMulti(...)` returns a <<binding-projection-multi,multi-valued>> object projection definition.
+* `.createObjectDefinition(..., ProjectionAccumulator.Provider)` returns an object projection definition with the provided accumulator applied
+and can be used for <<binding-projection-multi,multivalued>> object projections or object projections wrapped in some other containers.
 * `.createCompositeDefinition(...)` returns a (single-valued)
 <<search-dsl-projection-composite,composite projection>> definition
 (which, on contrary to an <<search-dsl-projection-object,object projection>>, is not bound to an object field in the index).

documentation/src/main/asciidoc/public/reference/_mapping-projection.adoc

@@ -39,7 +39,7 @@ See <<mapping-projection-inner-inference>> for more information on how construct
 +
 Alternatively, the field projection can be configured explicitly with <<search-dsl-projection-field-mapping,`@FieldProjection`>>.
 <4> To project on an object field, add a constructor parameter named after that field and with its own custom projection type.
-Multivalued projections <<mapping-projection-inner-inference-type,must be modeled as a `List<...>`>> or supertype.
+Multivalued projections <<mapping-projection-inner-inference-type,must be modeled as one of the multivalued containers available in `ProjectionAccumulator`>> or their supertype.
 +
 Alternatively, the object projection can be configured explicitly with <<search-dsl-projection-object-mapping,`@ObjectProjection`>>.
 <5> Annotate any custom projection type used for object fields with `@ProjectionConstructor` as well.
@@ -106,18 +106,27 @@ for the target field, which in general is the type of the property annotated wit
 (generally mapped using <<mapping-indexedembedded,`@IndexedEmbedded`>>),
 set the parameter type to another custom type annotated with `@ProjectionConstructor`,
 whose constructor will define which fields to extract from that object field.
-* For a multivalued projection, follow the rules above then wrap the type with `Iterable`, `Collection` or `List`,
-e.g. `Iterable<SomeType>`, `Collection<SomeType>` or `List<SomeType>`.
+* For projections where values are wrapped in some container, be it a multivalued projection represented by some collection or array,
+or a single-valued projection wrapped in an optional,
+follow the rules above for the elements inside the container and then wrap the type with one of the containers
+available in `ProjectionAccumulator` (`Iterable`, `Collection`, `List`, etc.),
+e.g. `Iterable<SomeType>`, `Collection<SomeType>`, `List<SomeType>`, etc.
 
 [IMPORTANT]
 ====
 Constructor parameters meant to represent a multivalued projection
-can **only** have the type `Iterable<...>`, `Collection<...>` or `List<...>`.
+**must** have the type of one of the supported multivalued containers.
+====
 
-Other container types such as `Map` or `Optional` are not supported
-https://hibernate.atlassian.net/browse/HSEARCH-4577[at the moment].
+[NOTE]
+====
+In case the `ProjectionAccumulator` does not provide a suitable accumulator for a container/collection
+needed for a constructor parameter mapping, <<binding-projection-multi,a custom projection binding>> can be implemented
+and a user-implemented projection accumulator applied.
 ====
 
+
+
 [[mapping-projection-inner-inference-fieldpath]]
 === [[mapper-orm-mapping-projection-inner-inference-fieldpath]] Inner projection and field path
 

documentation/src/main/asciidoc/public/reference/_search-dsl-projection.adoc

@@ -72,7 +72,7 @@ See <<mapping-projection-inner-inference>> for more information on how construct
 +
 Alternatively, the field projection can be configured explicitly with <<search-dsl-projection-field-mapping,`@FieldProjection`>>.
 <4> To project on an object field, add a constructor parameter named after that field and with its own custom projection type.
-Multivalued projections <<mapping-projection-inner-inference-type,must be modeled as a `List<...>`>> or supertype.
+Multivalued projections <<mapping-projection-inner-inference-type,must be modeled as one of the multivalued containers available in `ProjectionAccumulator`>> or their supertype.
 +
 Alternatively, the object projection can be configured explicitly with <<search-dsl-projection-object-mapping,`@ObjectProjection`>>.
 <5> Annotate any custom projection type used for object fields with `@ProjectionConstructor` as well.
@@ -403,8 +403,8 @@ include::{sourcedir}/org/hibernate/search/documentation/search/projection/Projec
 [[search-dsl-projection-field-multivalued]]
 === Multivalued fields
 
-To return multiple values, and thus allow projection on multivalued fields, use `.multi()`.
-This will change the return type of the projection to `List<T>` where `T` is what the single-valued projection
+To return multiple values, and thus allow projection on multivalued fields, use `.accumulator(..)`.
+This will change the return type of the projection to `SomeContainer<T>` where `T` is what the single-valued projection
 would have returned.
 
 .Returning field values from matched documents, for multivalued fields
@@ -610,8 +610,8 @@ include::{sourcedir}/org/hibernate/search/documentation/search/projection/Projec
 [[search-dsl-projection-distance-multivalued]]
 === Multivalued fields
 
-To return multiple values, and thus allow projection on multivalued fields, use `.multi()`.
-This will change the return type of the projection to `List<Double>`.
+To return multiple values, and thus allow projection on multivalued fields, use `.accumulator(..)`.
+This will change the return type of the projection to `SomeContainer<Double>`.
 
 .Returning the distance to a point, for multivalued fields
 ====
@@ -834,7 +834,7 @@ See <<mapping-projection-inner-inference>> for more information on how construct
 +
 Alternatively, the field projection can be configured explicitly with <<search-dsl-projection-field-mapping,`@FieldProjection`>>.
 <4> To project on an object field, add a constructor parameter named after that field and with its own custom projection type.
-Multivalued projections <<mapping-projection-inner-inference-type,must be modeled as a `List<...>`>> or supertype.
+Multivalued projections <<mapping-projection-inner-inference-type,must be modeled as one of the multivalued containers available in `ProjectionAccumulator`>> or their supertype.
 +
 Alternatively, the object projection can be configured explicitly with <<search-dsl-projection-object-mapping,`@ObjectProjection`>>.
 <5> Annotate any custom projection type used for object fields with `@ProjectionConstructor` as well.

engine/src/main/java/org/hibernate/search/engine/search/projection/ProjectionAccumulator.java

@@ -39,34 +39,72 @@
  */
 public interface ProjectionAccumulator<E, V, A, R> {
 
+	/**
+	 * @return The projection accumulator capable of accumulating single-valued projections in an as-is form,
+	 * i.e. the value is returned without any extra transformations.
+	 * @param <V> The type of values to accumulate.
+	 */
 	static <V> ProjectionAccumulator.Provider<V, V> nullable() {
 		return BuiltInProjectionAccumulators.nullable();
 	}
 
-	static <V> Provider<V, List<V>> list() {
-		return BuiltInProjectionAccumulators.list();
+	/**
+	 * @return The projection accumulator capable of accumulating single-valued projections and wrapping the values in an {@link Optional}.
+	 * @param <V> The type of values to accumulate.
+	 */
+	static <V> Provider<V, Optional<V>> optional() {
+		return BuiltInProjectionAccumulators.optional();
 	}
 
+	/**
+	 * @param converter The function that defines how to convert a list of collected values to the final collection.
+	 * @return An accumulator based on a list as a temporary storage.
+	 * @param <V> The type of values to accumulate.
+	 * @param <C> The type of the resulting collection.
+	 */
 	static <V, C> Provider<V, C> simple(Function<List<V>, C> converter) {
 		return BuiltInProjectionAccumulators.simple( converter );
 	}
 
-	static <V> Provider<V, Optional<V>> optional() {
-		return BuiltInProjectionAccumulators.optional();
+	/**
+	 * @return The projection accumulator capable of accumulating multivalued projections as a {@link List}.
+	 * @param <V> The type of values to accumulate.
+	 */
+	static <V> Provider<V, List<V>> list() {
+		return BuiltInProjectionAccumulators.list();
 	}
 
+	/**
+	 * @return The projection accumulator capable of accumulating multivalued projections as a {@link Set}.
+	 * @param <V> The type of values to accumulate.
+	 */
 	static <V> Provider<V, Set<V>> set() {
 		return BuiltInProjectionAccumulators.set();
 	}
 
+	/**
+	 * @return The projection accumulator capable of accumulating multivalued projections as a {@link SortedSet}.
+	 * @param <V> The type of values to accumulate.
+	 */
 	static <V> Provider<V, SortedSet<V>> sortedSet() {
 		return BuiltInProjectionAccumulators.sortedSet();
 	}
 
+	/**
+	 * @return The projection accumulator capable of accumulating multivalued projections as a {@link SortedSet}
+	 * using a custom comparator.
+	 * @param comparator The comparator which should be used by the sorted set.
+	 * @param <V> The type of values to accumulate.
+	 */
 	static <V> Provider<V, SortedSet<V>> sortedSet(Comparator<? super V> comparator) {
 		return BuiltInProjectionAccumulators.sortedSet( comparator );
 	}
 
+	/**
+	 * @return The projection accumulator capable of accumulating multivalued projections as an array.
+	 * @param componentType The type of the array elements.
+	 * @param <V> The type of values to accumulate.
+	 */
 	static <V> Provider<V, V[]> array(Class<? super V> componentType) {
 		return BuiltInProjectionAccumulators.array( componentType );
 	}

engine/src/main/java/org/hibernate/search/engine/search/projection/dsl/ProjectionAccumulatorProviderFactory.java renamed to engine/src/main/java/org/hibernate/search/engine/search/projection/ProjectionAccumulatorProviderFactory.java

@@ -2,9 +2,8 @@
  * SPDX-License-Identifier: Apache-2.0
  * Copyright Red Hat Inc. and Hibernate Authors
  */
-package org.hibernate.search.engine.search.projection.dsl;
+package org.hibernate.search.engine.search.projection;
 
-import org.hibernate.search.engine.search.projection.ProjectionAccumulator;
 import org.hibernate.search.util.common.annotation.Incubating;
 
 /**
@@ -16,6 +15,8 @@ public interface ProjectionAccumulatorProviderFactory {
 	/**
 	 *
 	 * @param containerType The type of the expected container.
+	 * Passing a {@code null} value as a container type will result in {@link ProjectionAccumulator#nullable() a nullable accumulator}
+	 * being returned, i.e. an accumulator that does not wrap the value in any sort of container.
 	 * @param containerElementType The type of the container elements
 	 * @return The projection accumulator provider for a requested container/element types.
 	 * @param <U> The type of values to accumulate after being transformed.

mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/logging/impl/Log.java

@@ -1050,8 +1050,7 @@ void indexingProgressWithRemainingTime(float estimatePercentileComplete, long do
 
 	@Message(id = ID_OFFSET + 170,
 			value = "Implicit binding of a java.util.SortedSet<%1$s> constructor parameter is not possible since %1$s is not implementing java.lang.Comparable."
-					+ " Either make %1$s implement java.lang.Comparable or use a programmatic mapping and provide"
-					+ " a custom ProjectionAccumulatorProviderFactory that, for example, utilizes a ProjectionAccumulator.sortedSet(comparator) accumulator provider.")
+					+ " Either make %1$s implement java.lang.Comparable or create a custom @ProjectionBinding and use the ProjectionAccumulator.sortedSet(comparator) accumulator provider in it.")
 	SearchException cannotBindSortedSetWithNonComparableElements(@FormatWith(ClassFormatter.class) Class<?> elementType,
 			@Param EventContext eventContext);
 }

mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/search/definition/binding/ProjectionBindingContext.java

@@ -13,8 +13,8 @@
 import org.hibernate.search.engine.environment.bean.BeanReference;
 import org.hibernate.search.engine.environment.bean.BeanResolver;
 import org.hibernate.search.engine.search.projection.ProjectionAccumulator;
+import org.hibernate.search.engine.search.projection.ProjectionAccumulatorProviderFactory;
 import org.hibernate.search.engine.search.projection.definition.ProjectionDefinition;
-import org.hibernate.search.engine.search.projection.dsl.ProjectionAccumulatorProviderFactory;
 import org.hibernate.search.engine.search.projection.dsl.SearchProjectionFactory;
 import org.hibernate.search.mapper.pojo.bridge.mapping.annotation.PropertyBinderRef;
 import org.hibernate.search.mapper.pojo.mapping.definition.annotation.ObjectProjection;
@@ -219,6 +219,10 @@ <C, T> BeanHolder<? extends ProjectionDefinition<C>> createObjectDefinition(Stri
 	 */
 	boolean isIncluded(String fieldPath);
 
+	/**
+	 * @return An instance of a projection accumulator provider factory capable of supplying an accumulator provider
+	 * based on a container and component types.
+	 */
 	@Incubating
 	ProjectionAccumulatorProviderFactory projectionAccumulatorProviderFactory();
 

mapper/pojo-base/src/main/java/org/hibernate/search/mapper/pojo/search/definition/binding/impl/ProjectionBindingContextImpl.java

@@ -21,11 +21,11 @@
 import org.hibernate.search.engine.environment.bean.BeanResolver;
 import org.hibernate.search.engine.mapper.model.spi.MappingElement;
 import org.hibernate.search.engine.search.projection.ProjectionAccumulator;
+import org.hibernate.search.engine.search.projection.ProjectionAccumulatorProviderFactory;
 import org.hibernate.search.engine.search.projection.definition.ProjectionDefinition;
 import org.hibernate.search.engine.search.projection.definition.spi.CompositeProjectionDefinition;
 import org.hibernate.search.engine.search.projection.definition.spi.ConstantProjectionDefinition;
 import org.hibernate.search.engine.search.projection.definition.spi.ObjectProjectionDefinition;
-import org.hibernate.search.engine.search.projection.dsl.ProjectionAccumulatorProviderFactory;
 import org.hibernate.search.mapper.pojo.extractor.builtin.BuiltinContainerExtractors;
 import org.hibernate.search.mapper.pojo.extractor.impl.BoundContainerExtractorPath;
 import org.hibernate.search.mapper.pojo.extractor.mapping.programmatic.ContainerExtractorPath;
@@ -359,6 +359,7 @@ BeanHolder<? extends ProjectionDefinition<? extends P>> complete() {
 		}
 	}
 
+	@Deprecated(since = "8.0")
 	public class MultiContextImpl<PV> implements ProjectionBindingMultiContext {
 		public final PojoTypeModel<PV> parameterContainerElementTypeModel;
 		private final PojoModelValue<PV> parameterContainerElementRootElement;