Stream Pipelines

// ── Imperative loops — each stage runs FULLY and EAGERLY before the next
List<String> namesOld = new ArrayList<>();
for (Person p : people) {
    namesOld.add(p.name());          // STAGE 1 runs completely first — full intermediate list
}
List<String> filteredOld = new ArrayList<>();
for (String n : namesOld) {
    if (n.length() > 3) filteredOld.add(n);   // STAGE 2 then runs completely — another full list
}

// ── Stream pipeline — intermediate ops are LAZY, nothing runs until terminal
Stream<String> pipeline = people.stream()
    .map(Person::name)        // records the operation — NO elements processed yet
    .filter(n -> n.length() > 3);   // ALSO just recorded — still nothing has executed

System.out.println("Pipeline built, but zero elements processed so far");
// At this exact point, NOT A SINGLE element has been mapped or filtered —
// the lambdas above have not been invoked even once

List<String> result = pipeline.collect(Collectors.toList());   // ← actual execution starts HERE
// Now, and only now, elements are pulled one at a time and pushed through
// map() then filter() VERTICALLY, one full element at a time, not stage-by-stage

// ── A pipeline that's built but never given a terminal op does NOTHING ──
Stream<String> neverExecuted = people.stream()
    .map(p -> { System.out.println("mapping!"); return p.name(); });
// "mapping!" is printed ZERO times here — no terminal operation was ever called,
// so this entire pipeline simply never runs at all, regardless of how it's built

// ── A stream is SINGLE-USE — reusing it after a terminal op throws ─────
Stream<String> stream = List.of("a", "b", "c").stream();
long count = stream.count();          // terminal operation — stream is now CONSUMED
// stream.forEach(System.out::println);   // IllegalStateException:
// "stream has already been operated upon or closed"

// CORRECT — get a fresh stream from the source for each separate traversal:
List<String> source = List.of("a", "b", "c");
long count2 = source.stream().count();             // first, independent stream
source.stream().forEach(System.out::println);       // second, independent, FRESH stream

// ── Short-circuiting operations can stop before examining every element ─
List<Integer> numbers = List.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);

boolean hasEven = numbers.stream()
    .peek(n -> System.out.println("checking: " + n))
    .anyMatch(n -> n % 2 == 0);
// Output stops at "checking: 2" — anyMatch() short-circuits the INSTANT a match
// is found, never even examining 3 through 10, despite them being in the source

Optional<Integer> firstBig = numbers.stream()
    .filter(n -> n > 100)
    .findFirst();   // also short-circuits — but here NOTHING matches, so it DOES
// examine every element before concluding Optional.empty()

// ── Short-circuiting is REQUIRED to productively consume an infinite source
Stream<Integer> infinite = Stream.iterate(0, n -> n + 1);   // genuinely never-ending

// infinite.collect(Collectors.toList());   // would NEVER terminate — count()/collect()
// are non-short-circuiting, and there's no end to this source to reach

List<Integer> firstTen = infinite.limit(10)              // limit() — short-circuiting,
    .collect(Collectors.toList());                          // stops pulling after 10 elements
System.out.println(firstTen);   // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Optional<Integer> firstOver1000 = Stream.iterate(0, n -> n + 1)
    .filter(n -> n > 1000)
    .findFirst();   // findFirst() ALSO short-circuits — stops as soon as it finds 1001

// ── Without a general Collector abstraction — every accumulation strategy
// would need its OWN dedicated, hand-written terminal method or manual loop:
Map<String, Double> totalsByCustomerOld = new HashMap<>();
for (Order order : orders) {
    totalsByCustomerOld.merge(order.customer(), order.total(), Double::sum);
}
// Works, but is a hand-written, imperative accumulation loop — not composable,
// not reusable as a building block, and not expressible as part of a stream pipeline

// ── collect(Collector) — the same accumulation, expressed declaratively ─
Map<String, Double> totalsByCustomer = orders.stream()
    .collect(Collectors.groupingBy(
        Order::customer,                              // group key
        Collectors.summingDouble(Order::total)));      // DOWNSTREAM collector — composed!

// ── The four Collector responsibilities, illustrated by toList()'s shape ─
// (conceptually — Collectors.toList() is provided pre-built, rarely hand-implemented)
Collector<String, List<String>, List<String>> manualToList = Collector.of(
    ArrayList::new,                  // supplier — fresh, empty container
    List::add,                       // accumulator — fold one element in
    (list1, list2) -> {              // combiner — merge two partial containers (parallel streams)
        list1.addAll(list2);
        return list1;
    },
    list -> list                     // finisher — container IS already the desired result here
);

// ── Composability — nesting collectors expresses multi-step accumulation
// "Partition orders into shipped/unshipped, and within EACH group, group
// further by customer" — expressed as a single composed pipeline:
Map<Boolean, Map<String, List<Order>>> shippedThenByCustomer = orders.stream()
    .collect(Collectors.partitioningBy(
        Order::isShipped,
        Collectors.groupingBy(Order::customer)));   // nested downstream collector again

// Equivalent hand-written logic would require careful, manually-coordinated
// nested loops or multiple separate passes — collect(Collector) expresses
// the SAME multi-step accumulation as one declarative, composed expression