Implement @RegisterCollector with tests and short doc

RELEASE_NOTES.md

@@ -2,6 +2,7 @@
   - document vavr incompatibility between 0.10.x and 1.0.0-alpha (#2350)
   - Handle.inTransaction: improve exception thrown when restoring transaction isolation #2343
   - add support for Guice 6.x (using javax.inject annotations) and guice 7.x (using jakarta.inject annotations)
+  - add new @RegisterCollector customizing annotation (#2377)
 
 # 3.38.2
   - spring5 JdbiUtil: fix thread safety #2341

core/src/main/java/org/jdbi/v3/core/collector/SimpleCollectorFactory.java

@@ -20,21 +20,25 @@
 import org.jdbi.v3.core.generic.GenericTypes;
 
 class SimpleCollectorFactory implements CollectorFactory {
-    private final Type containerType;
+    private final Type resultType;
     private final Collector<?, ?, ?> collector;
 
-    SimpleCollectorFactory(Type containerType, Collector<?, ?, ?> collector) {
-        this.containerType = containerType;
+    SimpleCollectorFactory(Type resultType, Collector<?, ?, ?> collector) {
+        this.resultType = resultType;
         this.collector = collector;
     }
 
     @Override
     public boolean accepts(Type containerType) {
-        return GenericTypes.isSuperType(containerType, this.containerType);
+        return GenericTypes.isSuperType(containerType, resultType);
     }
 
     @Override
     public Optional<Type> elementType(Type containerType) {
+        Optional<Type> collectedType = GenericTypes.findGenericParameter(collector.getClass(), Collector.class);
+        if (collectedType.isPresent()) {
+            return collectedType;
+        }
         if (GenericTypes.isSuperType(Iterable.class, containerType)) {
             return GenericTypes.findGenericParameter(containerType, Iterable.class);
         }
@@ -48,6 +52,6 @@ public Optional<Type> elementType(Type containerType) {
 
     @Override
     public String toString() {
-        return "CollectorFactory handling " + containerType + " with " + collector;
+        return "CollectorFactory handling " + resultType + " with " + collector;
     }
 }

docs/src/adoc/index.adoc

@@ -4636,7 +4636,14 @@ the `User.id` and `User.name` fields. Likewise for `r_id` and `r_name` into the
 The link:{jdbidocs}/sqlobject/config/RegisterConstructorMapper.html[@RegisterConstructorMapper^] annotation may be repeated multiple times on
 the same type or method to register multiple constructor mappers.
 
+==== @RegisterCollectorFactory
 
+Convenience annotation to register a `CollectorFactory` for this SqlObject method. See <<Collectors>> for more details.
+
+==== @RegisterCollectorFactory
+
+Convenience annotation to register a `Collector` for this SqlObject method. The element and result types are inferred from
+the concrete `Collector<Element, ?, Result>` implementation's type parameters. See <<Collectors>> for more details.
 
 === Other SQL Object annotations
 

sqlobject/src/main/java/org/jdbi/v3/sqlobject/config/RegisterCollector.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jdbi.v3.sqlobject.config;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.stream.Collector;
+
+import org.jdbi.v3.core.extension.annotation.UseExtensionConfigurer;
+import org.jdbi.v3.sqlobject.config.internal.RegisterCollectorImpl;
+
+/**
+ * Registers specifically one collector for a sql object type
+ */
+@UseExtensionConfigurer(RegisterCollectorImpl.class)
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE, ElementType.METHOD})
+public @interface RegisterCollector {
+
+    /**
+     * The collector instance to register
+     *
+     * @return the collector instance
+     */
+    Class<? extends Collector<?, ?, ?>> value();
+
+}

sqlobject/src/main/java/org/jdbi/v3/sqlobject/config/internal/RegisterCollectorImpl.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jdbi.v3.sqlobject.config.internal;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Type;
+import java.util.stream.Collector;
+
+import org.jdbi.v3.core.collector.JdbiCollectors;
+import org.jdbi.v3.core.config.ConfigRegistry;
+import org.jdbi.v3.core.extension.SimpleExtensionConfigurer;
+import org.jdbi.v3.core.generic.GenericTypes;
+import org.jdbi.v3.core.statement.UnableToCreateStatementException;
+import org.jdbi.v3.sqlobject.config.RegisterCollector;
+
+public class RegisterCollectorImpl extends SimpleExtensionConfigurer {
+    @Override
+    public void configure(final ConfigRegistry config, final Annotation annotation, final Class<?> extensionType) {
+        final RegisterCollector registerCollector = (RegisterCollector) annotation;
+        final JdbiCollectors collectors = config.get(JdbiCollectors.class);
+
+        try {
+            final Type resultType = GenericTypes.findGenericParameter(registerCollector.value(), Collector.class, 2)
+                    .orElseThrow(() -> new IllegalArgumentException("Tried to pass non-collector object to @RegisterCollector"));
+            collectors.registerCollector(resultType, registerCollector.value().getConstructor().newInstance());
+        } catch (ReflectiveOperationException | SecurityException e) {
+            throw new UnableToCreateStatementException("Unable to instantiate collector class " + registerCollector.value(), e);
+        }
+    }
+}

sqlobject/src/test/java/org/jdbi/v3/sqlobject/config/RegisterCollectorTest.java

@@ -0,0 +1,91 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jdbi.v3.sqlobject.config;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+import java.util.function.BiConsumer;
+import java.util.function.BinaryOperator;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import java.util.stream.Collector;
+import java.util.stream.Collectors;
+
+import org.jdbi.v3.core.Handle;
+import org.jdbi.v3.core.junit5.H2DatabaseExtension;
+import org.jdbi.v3.sqlobject.statement.SqlQuery;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class RegisterCollectorTest {
+
+    @RegisterExtension
+    H2DatabaseExtension h2 = H2DatabaseExtension.withPlugins();
+    Handle h;
+
+    @BeforeEach
+    void setup() {
+        h = h2.getSharedHandle();
+        h.execute("create table i (i int)");
+        h.execute("insert into i values(1)");
+        h.execute("insert into i values(2)");
+    }
+
+    @Test
+    void registerCollector() {
+        assertThat(h.attach(RegisterCollectorDao.class).select())
+                .isEqualTo("1 2");
+    }
+
+    public interface RegisterCollectorDao {
+        @RegisterCollector(StringConcatCollector.class)
+        @SqlQuery("select i from i order by i asc")
+        String select();
+    }
+
+    public static class StringConcatCollector implements Collector<Integer, List<Integer>, String> {
+        @Override
+        public Supplier<List<Integer>> supplier() {
+            return ArrayList::new;
+        }
+
+        @Override
+        public BiConsumer<List<Integer>, Integer> accumulator() {
+            return (l, i) -> l.add(i);
+        }
+
+        @Override
+        public BinaryOperator<List<Integer>> combiner() {
+            return (a, b) -> {
+                a.addAll(b);
+                return a;
+            };
+        }
+
+        @Override
+        public Function<List<Integer>, String> finisher() {
+            return i -> i.stream().map(Object::toString).collect(Collectors.joining(" "));
+        }
+
+        @Override
+        public Set<Characteristics> characteristics() {
+            return Collections.emptySet();
+        }
+    }
+}