Filter Java Stream to 1 and Only 1 Element

1. Overview

In this article, we’ll use two methods from Collectors to retrieve the unique element which matches a certain predicate in a given stream of elements.

For both approaches, we’ll define two methods according to the following standard:

• the get method expects to have a unique result. Otherwise, it throws an Exception
• the find method accepts that the result can be missing and returns an Optional with the value if it exists

2. Retrieve the Unique Result Using Reduction

Collectors.reducing performs a reduction of its input elements. To do so, it applies a function specified as a BinaryOperator. The result is described as an Optional. Thus we can define our find method.

In our case, if there are two or more elements after filtering, we just need to discard the result:

public static <T> Optional<T> findUniqueElementMatchingPredicate_WithReduction(Stream<T> elements, Predicate<T> predicate) {
    return elements.filter(predicate)
      .collect(Collectors.reducing((a, b) -> null));
}

To write the get method, we’ll need to make the following changes:

• if we detect two elements, we can directly throw them instead of returning null
• in the end, we need to get the value of the Optional: if it is empty, we also want to throw

Furthermore, in this case, we can directly apply the reducing operation on the Stream:

public static <T> T getUniqueElementMatchingPredicate_WithReduction(Stream<T> elements, Predicate<T> predicate) {
    return elements.filter(predicate)
      .reduce((a, b) -> {
          throw new IllegalStateException("Too many elements match the predicate");
      })
      .orElseThrow(() -> new IllegalStateException("No element matches the predicate"));
}

3. Retrieve the Unique Result Using Collectors.collectingAndThen

Collectors.collectingAndThen applies a function to the result List of a collecting operation.

Hence, to define the find method, we’ll need to take the List and:

• if the List has either zero, or more than two elements, return null
• if the List has exactly one element, return it

Here is the code for this operation:

private static <T> T findUniqueElement(List<T> elements) {
    if (elements.size() == 1) {
        return elements.get(0);
    }
    return null;
}

As a result, the find method reads:

public static <T> Optional<T> findUniqueElementMatchingPredicate_WithCollectingAndThen(Stream<T> elements, Predicate<T> predicate) {
    return elements.filter(predicate)
      .collect(Collectors.collectingAndThen(Collectors.toList(), list -> Optional.ofNullable(findUniqueElement(list))));
}

In order to adapt our private method for the get case, we’ll need to throw if the number of retrieved elements is not exactly 1. Let’s be precise and distinguish the cases where there is no result and too many results, as we did with reduction:

private static <T> T getUniqueElement(List<T> elements) {
    if (elements.size() > 1) {
        throw new IllegalStateException("Too many elements match the predicate");
    } else if (elements.size() == 0) {
        throw new IllegalStateException("No element matches the predicate");
    }
    return elements.get(0);
}

In the end, given that we named our class FilterUtils, we can write the get method:

public static <T> T getUniqueElementMatchingPredicate_WithCollectingAndThen(Stream<T> elements, Predicate<T> predicate) {
    return elements.filter(predicate)
      .collect(Collectors.collectingAndThen(Collectors.toList(), FilterUtils::getUniqueElement));
}

4. Performance Benchmark

Let’s use JMH to run a quick performance comparison between the different methods.

First, let’s apply our methods to

• a Stream containing all the Integers from 1 to 1 million
• a Predicate verifying whether an element is equal to 751879

In this case, the Predicate will be verified for one unique element of the Stream. Let’s have a look at the definition of the Benchmark:

@State(Scope.Benchmark)
public static class MyState {
    final Stream<Integer> getIntegers() { 
        return IntStream.range(1, 1000000).boxed();
    }
    
    final Predicate<Integer> PREDICATE = i -> i == 751879;
}

@Benchmark
public void evaluateFindUniqueElementMatchingPredicate_WithReduction(Blackhole blackhole, MyState state) {
    blackhole.consume(FilterUtils.findUniqueElementMatchingPredicate_WithReduction(state.INTEGERS.stream(), state.PREDICATE));
}

@Benchmark
public void evaluateFindUniqueElementMatchingPredicate_WithCollectingAndThen(Blackhole blackhole, MyState state) {
    blackhole.consume(FilterUtils.findUniqueElementMatchingPredicate_WithCollectingAndThen(state.INTEGERS.stream(), state.PREDICATE));
}

@Benchmark
public void evaluateGetUniqueElementMatchingPredicate_WithReduction(Blackhole blackhole, MyState state) {
    try {
        FilterUtils.getUniqueElementMatchingPredicate_WithReduction(state.INTEGERS.stream(), state.PREDICATE);
    } catch (IllegalStateException exception) {
        blackhole.consume(exception);
    }
}

@Benchmark
public void evaluateGetUniqueElementMatchingPredicate_WithCollectingAndThen(Blackhole blackhole, MyState state) {
    try {
        FilterUtils.getUniqueElementMatchingPredicate_WithCollectingAndThen(state.INTEGERS.stream(), state.PREDICATE);
    } catch (IllegalStateException exception) {
        blackhole.consume(exception);
    }
}

Let’s run it. We’re measuring the number of operations per second. The higher, the better:

Benchmark                                                                          Mode  Cnt    Score    Error  Units
BenchmarkRunner.evaluateFindUniqueElementMatchingPredicate_WithCollectingAndThen  thrpt   25  140.581 ± 28.793  ops/s
BenchmarkRunner.evaluateFindUniqueElementMatchingPredicate_WithReduction          thrpt   25  100.171 ± 36.796  ops/s
BenchmarkRunner.evaluateGetUniqueElementMatchingPredicate_WithCollectingAndThen   thrpt   25  145.568 ±  5.333  ops/s
BenchmarkRunner.evaluateGetUniqueElementMatchingPredicate_WithReduction           thrpt   25  144.616 ± 12.917  ops/s

As we can see, in this case, the different methods perform very similarly.

Let’s change our Predicate to check if an element of the Stream is equal to 0. This condition is false for all elements of the List. We can now run the benchmark again:

Benchmark                                                                          Mode  Cnt    Score    Error  Units
BenchmarkRunner.evaluateFindUniqueElementMatchingPredicate_WithCollectingAndThen  thrpt   25  165.751 ± 19.816  ops/s
BenchmarkRunner.evaluateFindUniqueElementMatchingPredicate_WithReduction          thrpt   25  174.667 ± 20.909  ops/s
BenchmarkRunner.evaluateGetUniqueElementMatchingPredicate_WithCollectingAndThen   thrpt   25  188.293 ± 18.348  ops/s
BenchmarkRunner.evaluateGetUniqueElementMatchingPredicate_WithReduction           thrpt   25  196.689 ±  4.155  ops/s

Here again, the performance chart is quite balanced.

Lastly, let’s check out what happens if we use a Predicate that returns true for values greater than 751879: there is a huge amount of elements of the List that match this Predicate. This leads to the following benchmark:

Benchmark                                                                          Mode  Cnt    Score    Error  Units
BenchmarkRunner.evaluateFindUniqueElementMatchingPredicate_WithCollectingAndThen  thrpt   25   70.879 ±  6.205  ops/s
BenchmarkRunner.evaluateFindUniqueElementMatchingPredicate_WithReduction          thrpt   25  210.142 ± 23.680  ops/s
BenchmarkRunner.evaluateGetUniqueElementMatchingPredicate_WithCollectingAndThen   thrpt   25   83.927 ±  1.812  ops/s
BenchmarkRunner.evaluateGetUniqueElementMatchingPredicate_WithReduction           thrpt   25  252.881 ±  2.710  ops/s

As we can see, the variants with reduction are more efficient. Moreover, using reduce directly on the filtered Stream shines because the Exception is thrown straight after two matching values have been found.

To put it in a nutshell, if performance is a matter:

• Using reduction should be favored
• If we expect a lot of potential matching values to be found, the get method that reduces the Stream is much faster

5. Conclusion

In this tutorial, we saw different methods to retrieve a unique result after filtering a Stream, then compared their efficiency.

As always, the code is available over on GitHub.