Spliterator

## The layered picture Think of it as four layers, from concrete data up to the API you write: ``` Data source (ArrayList, array, file, custom...) │ produces ▼ Spliterator ← LOW-LEVEL: how to traverse (tryAdvance) and split (trySplit) │ wrapped by ▼ Stream / IntStream ← HIGH-LEVEL: map/filter/reduce/collect pipeline │ driven by ▼ Terminal operation ← pulls elements: sequentially, or splits into ForkJoinPool ``` ## The pieces and how they connect **`Spliterator`** — the **low-level** mechanism. It knows *how to walk* a source one element at a time (`tryAdvance`/`forEachRemaining`) and *how to divide it* for parallel work (`trySplit`), plus metadata (`estimateSize`, `characteristics`). It is not something you usually call directly. **`Collection.spliterator()`** — a **default method** added to `Collection` in Java 8 (it actually lives on `Iterable`/`Collection`). Every collection can hand you a Spliterator describing itself, with the right characteristics (an `ArrayList` reports `ORDERED|SIZED|SUBSIZED`, a `HashSet` reports `DISTINCT|SIZED`, etc.). This is the standard factory. **`Collection.stream()` and `parallelStream()`** — the methods you actually call. They are **defined in terms of `spliterator()`**: internally they do roughly `StreamSupport.stream(spliterator(), false)` (or `true` for parallel). So a Stream *is* a high-level pipeline sitting on top of a Spliterator. **`StreamSupport`** — the bridge for **non-Collection** or **custom** sources. Its key method: ```java Stream<T> StreamSupport.stream(Spliterator<T> s, boolean parallel) ``` given any Spliterator, it produces a Stream; the boolean selects sequential vs parallel execution. This is how you stream things that aren't Collections — for example an `Iterable`: ```java public static <T> Stream<T> streamOf(Iterable<T> it) { return StreamSupport.stream(it.spliterator(), false); } ``` or a custom Spliterator over a file, a paged API, or a generator. ## What happens when the terminal operation runs - **Sequential** (`stream()`): the terminal op repeatedly calls `tryAdvance` (or `forEachRemaining`) on the single Spliterator, on the calling thread. - **Parallel** (`parallelStream()`): the framework recursively calls `trySplit` to build a tree of chunks, submits them to the **common ForkJoinPool**, runs `forEachRemaining` on each leaf in a worker thread, and combines results. The Spliterator's `characteristics` (SIZED, ORDERED, DISTINCT, …) tune this. ## Practical takeaways - For a normal collection, just call `.stream()` / `.parallelStream()` — never touch the Spliterator. - To stream an `Iterable`, an array section, or a custom source, get/build a Spliterator and pass it to `StreamSupport.stream(...)`. - `Arrays.stream(...)` and `IntStream.range(...)` are similar convenience wrappers that build Spliterators for you under the hood. - The boolean in `StreamSupport.stream` is your sequential/parallel switch — but parallel only pays off when the Spliterator splits well (see the trySplit question).