Add StreamUtils utility class. (#105)

* Add StreamUtils utility class.

- streamNullable to safely stream any iterable, even null.
- last(n) to collect the last n elements from a stream.

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>

* Add caveat in javadoc.

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>

* Add unittest for the utility-class unsupported constructor.

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>

* Suppress and explain sonar warning.

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>

---------

Signed-off-by: Sjoerd Talsma <sjoerdtalsma@users.noreply.github.com>

Author: sjoerdtalsma

src/main/java/nl/talsmasoftware/misc/utils/StreamUtils.java

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2022-2025 Talsma ICT
+ *
+ * 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 nl.talsmasoftware.misc.utils;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+import java.util.stream.Collector;
+import java.util.stream.Stream;
+import java.util.stream.StreamSupport;
+
+public final class StreamUtils {
+
+    private StreamUtils() {
+        throw new UnsupportedOperationException("This is a utility class and cannot be instantiated.");
+    }
+
+    /**
+     * Stream the elements of a (nullable) {@linkplain Iterable} object.
+     *
+     * <p>
+     * The resulting stream also filters any {@code null} elements from the result.
+     *
+     * @param iterable The iterable object (optional, may be {@code null}).
+     * @param <T>      The type of the iterable elements.
+     * @return Non-{@code null} Stream with the elements from the given iterable.
+     * Null-values will be filtered out.
+     */
+    public static <T> Stream<T> streamNullable(Iterable<T> iterable) {
+        if (iterable == null) {
+            return Stream.empty();
+        } else if (iterable instanceof Collection) {
+            return ((Collection<T>) iterable).stream().filter(Objects::nonNull);
+        }
+        return StreamSupport.stream(iterable.spliterator(), false).filter(Objects::nonNull);
+    }
+
+    /**
+     * Collector for the last <em>n</em> elements of a stream.
+     *
+     * <p>
+     * <b>Note:</b> Obvious caveat: the stream to be collected must be a limited stream,
+     * e.g. have an actual last element.
+     *
+     * <p>
+     * The returned list is unmodifiable.
+     *
+     * @param maxSize The maximum size of the list to return.
+     * @param <T>     The type of elements to be collected.
+     * @return Collector returning the last <em>n</em> elements as a list,
+     * or the full stream content if there were at most {@code maxSize} elements.
+     */
+    public static <T> Collector<T, ArrayList<T>, List<T>> last(final int maxSize) {
+        if (maxSize <= 0) {
+            throw new IllegalArgumentException("Maximum size must be a positive number.");
+        }
+        return Collector.of(() -> new ArrayList<>(maxSize),
+                (accumulator, value) -> {
+                    if (accumulator.size() < maxSize) {
+                        accumulator.add(value);
+                    } else {
+                        Collections.rotate(accumulator, -1);
+                        accumulator.set(maxSize - 1, value);
+                    }
+                },
+                (acc1, acc2) -> {
+                    if (acc2.size() < maxSize) {
+                        int skip = acc1.size() + acc2.size() - maxSize;
+                        if (skip <= 0) {
+                            acc2.addAll(0, acc1);
+                        } else {
+                            acc2.addAll(0, acc1.subList(skip, acc1.size()));
+                        }
+                    }
+                    return acc2;
+                },
+                Collections::unmodifiableList);
+    }
+
+} 

src/test/java/nl/talsmasoftware/misc/utils/StreamUtilsTest.java

@@ -0,0 +1,194 @@
+/*
+ * Copyright 2022-2025 Talsma ICT
+ *
+ * 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 nl.talsmasoftware.misc.utils;
+
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationTargetException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collector;
+import java.util.stream.IntStream;
+import java.util.stream.Stream;
+
+import static java.util.stream.Collectors.toCollection;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class StreamUtilsTest {
+    @Test
+    @SuppressWarnings({
+            "java:S1874" // We use java8, where canAccess is not yet available to replace isAccessible.
+    })
+    void streamUtils_utility_class_has_unsupported_constructor() throws ReflectiveOperationException {
+        Constructor<StreamUtils> constructor = StreamUtils.class.getDeclaredConstructor();
+        assertThat(constructor.isAccessible()).isFalse();
+        constructor.setAccessible(true);
+        assertThatThrownBy(constructor::newInstance)
+                .isInstanceOf(InvocationTargetException.class)
+                .cause()
+                .isInstanceOf(UnsupportedOperationException.class)
+                .hasMessage("This is a utility class and cannot be instantiated.");
+    }
+
+    @Test
+    void streamNullable_null_returns_empty_stream() {
+        // when
+        Stream<?> result = StreamUtils.streamNullable(null);
+
+        // then
+        assertThat(result).isNotNull().isEmpty();
+    }
+
+    @Test
+    void streamNullable_empty_returns_empty_stream() {
+        // when
+        Stream<?> result = StreamUtils.streamNullable(Collections.emptyList());
+
+        // then
+        assertThat(result).isNotNull().isEmpty();
+    }
+
+    @Test
+    void streamNullable_empty_Iterable_returns_empty_stream() {
+        // given
+        Iterable<?> emptyIterable = Collections::emptyIterator;
+
+        // when
+        Stream<?> result = StreamUtils.streamNullable(emptyIterable);
+
+        // then
+        assertThat(result).isNotNull().isEmpty();
+    }
+
+    @Test
+    void streamNullable_returns_stream_from_collection() {
+        // when
+        Stream<Integer> result = StreamUtils.streamNullable(Arrays.asList(1, null, 2, null, 3));
+
+        // then
+        assertThat(result).isNotNull().isNotEmpty().hasSize(3).containsExactly(1, 2, 3);
+    }
+
+    @Test
+    void streamNullable_returns_stream_from_iterable() {
+        // given
+        Iterable<Integer> iterable = Arrays.asList(1, null, 2, null, 3)::iterator;
+
+        // when
+        Stream<Integer> result = StreamUtils.streamNullable(iterable);
+
+        // then
+        assertThat(result).isNotNull().isNotEmpty().hasSize(3).containsExactly(1, 2, 3);
+    }
+
+    @Test
+    void last_count_must_be_positive() {
+        assertThatThrownBy(() -> StreamUtils.last(0))
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessage("Maximum size must be a positive number.");
+    }
+
+    @Test
+    void last_2_of_10() {
+        // given
+        Stream<String> stream = IntStream.range(1, 11).mapToObj(Integer::toString);
+
+        // when
+        List<String> result = stream.collect(StreamUtils.last(2));
+
+        // then
+        assertThat(result).hasSize(2).containsExactly("9", "10");
+    }
+
+    @Test
+    void last_10_of_2() {
+        // given
+        Stream<String> stream = Stream.of("1", "2");
+
+        // when
+        List<String> result = stream.collect(StreamUtils.last(10));
+
+        // then
+        assertThat(result).hasSize(2).containsExactly("1", "2");
+    }
+
+    @Test
+    void last_10_of_10() {
+        // given
+        Stream<String> stream = IntStream.range(1, 11).mapToObj(Integer::toString);
+
+        // when
+        List<String> result = stream.collect(StreamUtils.last(10));
+
+        // then
+        assertThat(result).hasSize(10).containsExactly("1", "2", "3", "4", "5", "6", "7", "8", "9", "10");
+    }
+
+    @Test
+    void last_combiner_acc2_is_full() {
+        // given
+        Collector<String, ArrayList<String>, List<String>> collector = StreamUtils.last(10);
+        ArrayList<String> acc1 = IntStream.range(1, 11).mapToObj(Integer::toString).collect(toCollection(ArrayList::new));
+        ArrayList<String> acc2 = IntStream.range(11, 21).mapToObj(Integer::toString).collect(toCollection(ArrayList::new));
+
+        // when
+        List<String> result = collector.combiner().apply(acc1, acc2);
+
+        // then
+        assertThat(result)
+                .hasSize(10)
+                .containsExactly("11", "12", "13", "14", "15", "16", "17", "18", "19", "20")
+                .isSameAs(acc2);
+    }
+
+    @Test
+    void last_combiner_acc2_has_some_space() {
+        // given
+        Collector<String, ArrayList<String>, List<String>> collector = StreamUtils.last(10);
+        ArrayList<String> acc1 = IntStream.range(1, 11).mapToObj(Integer::toString).collect(toCollection(ArrayList::new));
+        ArrayList<String> acc2 = IntStream.range(11, 16).mapToObj(Integer::toString).collect(toCollection(ArrayList::new));
+
+        // when
+        List<String> result = collector.combiner().apply(acc1, acc2);
+
+        // then
+        assertThat(result)
+                .hasSize(10)
+                .containsExactly("6", "7", "8", "9", "10", "11", "12", "13", "14", "15")
+                .isSameAs(acc2);
+    }
+
+    @Test
+    void last_combiner_acc1_and_acc2_both_fit() {
+        // given
+        Collector<String, ArrayList<String>, List<String>> collector = StreamUtils.last(10);
+        ArrayList<String> acc1 = IntStream.range(1, 5).mapToObj(Integer::toString).collect(toCollection(ArrayList::new));
+        ArrayList<String> acc2 = IntStream.range(5, 11).mapToObj(Integer::toString).collect(toCollection(ArrayList::new));
+
+        // when
+        List<String> result = collector.combiner().apply(acc1, acc2);
+
+        // then
+        assertThat(result)
+                .hasSize(10)
+                .containsExactly("1", "2", "3", "4", "5", "6", "7", "8", "9", "10")
+                .isSameAs(acc2);
+    }
+}