Streams vs loops

Written Explanation

What a stream is

A stream is a sequence of elements flowing from a source through a pipeline of operations. Three facts define it:

• It does not store data. It carries elements from somewhere else, such as a list.
• It does not change its source. Filtering a stream built from a list gives you a new result and leaves the list as it was.
• It is consumed once. After the pipeline has run, the stream is finished.

The Java documentation (the java.util.stream package summary) states the first two points directly, and says that once a terminal operation has run, you must get a new stream from the source to traverse the data again.

The three parts of a pipeline

Every stream pipeline has the same shape:

Read this pipeline from top to bottom, one station per line:

List<String> longNames = names.stream()      // source
    .filter(n -> n.length() > 3)             // intermediate: keep long names
    .map(String::toUpperCase)                // intermediate: change each one
    .toList();                               // terminal: pack into a list

The arguments to filter and map are the lambda and method reference you met in BEG-035. filter expects a Predicate (a yes/no question about one item) and map expects a Function (turn one item into another).

The lambda n -> n.length() > 3 is passed in once, but Java applies it to each element as the element reaches that station.

The same job as a loop

Here is the identical task written as a loop:

List<String> longNames = new ArrayList<>();
for (String n : names) {
    if (n.length() > 3) {
        longNames.add(n.toUpperCase());
    }
}

Both produce the same list. The difference is in what you spell out:

Neither is better in general. A stream shines when the job is "a short chain of simple steps over a collection". A loop shines when the job needs counters, flags, early break, or several results at once. Lesson 6 returns to this choice, and the demos at the end of the module practice it.

Where streams come from

The most common source is a collection: list.stream(), set.stream(). A map has no stream() method of its own, but its entrySet(), keySet(), and values() are collections, so you can write map.entrySet().stream(). An array can be turned into a stream with Arrays.stream(array), and a few fixed values with Stream.of(1, 2, 3).

Results are new objects

In the pipeline above, toList() hands back a new list. The original names list is untouched. Since Java 16, toList() returns an unmodifiable list: calling add on it throws UnsupportedOperationException, just like the List.of list you met in BEG-030. If you need a list you can change, wrap it: new ArrayList<>(stream.toList()).

A stream is used once

This is the rule that surprises beginners most:

Stream<String> st = names.stream().filter(n -> n.length() > 3);
System.out.println(st.count());   // works: 4
System.out.println(st.count());   // IllegalStateException

The first count() is a terminal operation, so it uses the stream up. The second call fails with the message stream has already been operated upon or closed. The Javadoc says an implementation may throw this exception when it detects reuse and does not promise to detect every case, so never rely on the exception: simply do not reuse a stream. If you need the data again, call names.stream() again. The source list is still there.

Nothing happens until the end

An intermediate operation does not do any work by itself. It only adds a station to the belt. Work starts when a terminal operation asks for the result. This is called laziness, and Lesson 3 explains it fully. For now, remember one consequence: a pipeline without a terminal operation is a belt that was never switched on.

The conveyor-belt analogy, and where it stops

The belt is a good picture for the order of stations. It is less accurate in two places. First, Java does not have to push each item through every station in separate passes; it may fuse the stations so that one pass over the data does everything. Second, a real belt carries physical goods that are gone once packed, while a stream's source list is still there afterwards.