Java streams and lambdas.

Map, filter, and reduce showed that map and filter run nothing until a terminal operation, such as collect, asks for results, and that each element then goes through every stage before the next one starts. Picture the terminal operation pulling one element at a time through the pipeline. Two things follow from that model.

First, a terminal operation can stop pulling. findFirst() returns the first element that reaches it, inside an Optional, and then asks for nothing more; orElse("none") takes the element out, or gives "none". An operation that can finish without taking every element is short-circuiting. findFirst, findAny, anyMatch, allMatch, noneMatch, and limit are short-circuiting.

Second, some intermediate operations must see every element before they pass any on. sorted() is one: it cannot know the smallest element until it has seen them all. So a stage before sorted runs for every element, even when a later findFirst stops early.

The code below uses peek, an intermediate operation that runs a lambda on each element as it passes and gives the element on unchanged. The documentation says peek exists mainly for debugging, and here it shows which elements are taken.

A terminal operation pulls elements one at a time; findFirst stops pulling when it has an answer, and sorted takes every element before it passes one on.

Java lambdas and effectively final locals introduced the functional interfaces in java.util.function and method references. Each stream operation asks for one of those interfaces:

• filter takes a Predicate<T>, whose test returns a boolean.
• map takes a Function<T, R>, whose apply turns a T into an R.
• peek and forEach take a Consumer<T>, whose accept returns nothing.
• max and sorted can take a Comparator<T>, such as Comparator.comparing(Fold::minutes).

T is the element type of the stream. In a Stream<Fold>, filter’s lambda receives a Fold. Fold is a record, record Fold(String model, int minutes) {}, so f.minutes() reads a field. A lambda with one parameter needs no brackets, f -> f.minutes() <= 15. Two parameters need them, (a, b) -> a + b. A lambda with several statements puts them in braces and ends with return.

A method reference can stand in for a lambda in three ways that streams use often. Ask where the element goes:

• Fold::model and String::length call the method on the element: the element is the object.
• this::quick calls quick on this object: the element is the argument.
• Integer::sum calls a static method: Integer.sum(a, b) returns a + b, so both values are arguments.

Club::quick names no object, so in filter it would need a Club and a Fold, and filter passes one value. javac reports:

error: incompatible types: invalid method reference

with a second line, unexpected instance method quick(Fold) found in unbound lookup. Use this::quick, or a lambda, f -> quick(f).

Each operation takes one functional interface; a method reference fits when its method can take the element as the object or as the argument.

Map, filter, and reduce showed the error that a second terminal operation on the same Stream throws:

java.lang.IllegalStateException: stream has already been operated upon or closed

A Stream is not a collection. It is one pass over a source, such as a List. A terminal operation uses up the Stream, and the Stream records that. An intermediate operation also uses the Stream it is called on: after s.map(…), a call to s.filter(…) on the same s throws the same exception.

The second use is easy to see when both calls are next to each other. It is harder to see when one Stream is passed to two methods, kept in a field, or returned by a method and then used twice. There are three fixes, and each fits a different case:

• When you have the List, call models.stream() again for each pass. Making a stream is cheap.
• When you receive only a Stream, for example from a method that reads a file, collect it once with toList(), and make a new stream from that List for each question.
• When code must start a pass later, give it a Supplier<Stream<T>>, such as () -> models.stream(); each get() makes a new stream.

A Stream is one pass: give each pass its own stream from the List, and collect a Stream you receive before you use it twice.

collect gathers the elements into a result, and a collector says how. The Collectors class has the common ones.

toList(), a method of Stream itself since Java 16, gives a List that cannot be changed, as Java collections and unmodifiable views showed. collect(Collectors.toList()) gives a List but promises nothing about whether it can be changed.

Collectors.toMap(Fold::model, Fold::minutes) makes one map entry per element: the first function gives the key, the second the value. If two elements give the same key, toMap throws:

java.lang.IllegalStateException: Duplicate key crane (attempted merging values 20 and 15)

A third argument, the merge function, decides what to keep. toMap calls it with the value already stored and the new one, and stores what it returns. Integer::sum adds them. (old, next) -> next keeps the last value, and (old, next) -> old keeps the first. Choose by what the map means; a total needs the sum.

Collectors.groupingBy(Fold::model) makes a Map from each key to a List of the elements with that key. A second collector changes what is kept for each key: groupingBy(Fold::model, Collectors.counting()) keeps the number of elements, as a Long. Both toMap and groupingBy return a HashMap, whose order is not promised; new TreeMap<>(map) gives the same entries sorted by key. Collectors.joining(", ") joins a stream of Strings into one String with ", " between them.

toMap needs a merge function whenever two elements can share a key; groupingBy keeps every element, or a count, for each key.

findFirst, findAny, min, and max give their answer inside an Optional, because there may be no answer: a stream with no elements has no first or largest element. An empty Optional holds nothing. get() on an empty Optional throws:

java.util.NoSuchElementException: No value present

So say what the empty case means instead of calling get(). map(Fold::model) turns an Optional<Fold> into an Optional<String>, and stays empty when it was empty. orElse("none") then gives the value, or "none". orElseThrow(() -> new IllegalStateException("no folds this week")) throws an exception with your own message.

orElse and orElseGet differ in when their default is made. orElse(makeDefault()) calls makeDefault() before orElse runs, every time, even when the Optional has a value: Java computes each argument before a call. orElseGet(() -> makeDefault()) takes a Supplier and calls it only when the Optional is empty. Use orElseGet when making the default costs time or changes something.

Numbers have their own streams. mapToInt(Fold::minutes) gives an IntStream of int values, with no Integer objects. sum() returns an int, 0 for no elements. average() returns an OptionalDouble, because there is no average of nothing. Printed, an empty one shows OptionalDouble.empty; getAsDouble() on it throws like get(), and orElse(0) gives 0.0.

findFirst and max give an Optional and average an OptionalDouble; say what “no elements” means with orElse or orElseGet instead of get().

Each bug below follows from a rule in this lesson.

An effect in map or peek that never runs. Since Java 9, count() may return the size of the source without running the pipeline, when map and peek cannot change the number of elements. Code that adds to a list inside map or peek works while the pipeline ends in collect, and silently stops when someone changes the end to count(). Collect the results, then act on them.

forEach filling an outside list. stream.forEach(f -> result.add(f.model())) gives the right list on one thread. If someone adds parallel(), several threads add to one ArrayList, which is not safe, and elements can be lost. collect or toList() builds the result safely in both cases.

Adding to the result of toList(). The List cannot be changed, so a later add throws UnsupportedOperationException, often far from the stream. When the caller must add, collect with Collectors.toCollection(ArrayList::new).

toMap on real data. Tests use unique names, and the first week with a repeated name crashes with Duplicate key. Decide on the merge function when you write the toMap, not after the crash.

Keep effects out of map and peek, build results with collect or toList(), copy a toList() result before adding, and choose toMap’s merge function at the start.

One list of a club night’s folds, and four questions about it. Decide which elements each pipeline keeps and what each collector or IntStream gives back.