Filter Java Stream to 1 and Only 1 Element
Last updated: November 15, 2023
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.