docs(streams): add explanation and examples for stateful vs stateless operations

What
- Introduced a detailed guide distinguishing **stateless** and **stateful** operations in Java Streams.
- Covered:
  1. **Stateless Operations**
     - Definition: process each element independently without tracking state.
     - Examples: filter(), map(), flatMap(), peek(), forEach().
     - Added code demo showing filter + map + forEach pipeline.
     - ✅ Output: 4, 8.

  2. **Stateful Operations**
     - Definition: require tracking previously seen elements or buffering the entire stream.
     - Examples: distinct(), sorted(), limit(), skip(), collect(), reduce().
     - Added code demo showing distinct + sorted pipeline.
     - ✅ Output: 1, 3, 5, 7.

  3. **Performance Considerations**
     - Stateless = faster, element-by-element, well-suited for parallel execution.
     - Stateful = may require memory buffering, reduce efficiency in parallel streams.

  4. **Parallel Stream Example**
     - Demonstrated how stateless ops work efficiently in parallel, but stateful ops like sorted() may disrupt ordering.

Why
- Many developers use streams without understanding the internal distinction between **stateless (fast, parallel-friendly)** and **stateful (requires global knowledge, potential bottleneck)**.
- Highlighting this difference helps optimize code and avoid performance pitfalls when scaling with parallel streams.

Logic
1. **Stateless operations** → independent per-element processing, no memory of past/future, efficient for parallel.
2. **Stateful operations** → require knowledge of entire dataset (e.g., deduplication, sorting, limiting).
3. Understanding the distinction is crucial:
   - For performance tuning (avoid unnecessary stateful ops).
   - For correctness (some stateful ops disrupt order in parallel).
4. Code examples illustrate real-world behavior:
   - Stateless: doubling even numbers → efficient, streaming pipeline.
   - Stateful: removing duplicates + sorting → requires collecting/processing all elements.

Key Takeaways
✔ Stateless ops → filter, map, flatMap, peek, forEach.
✔ Stateful ops → distinct, sorted, limit, skip, collect, reduce.
✔ Stateless = efficient, parallel-friendly.
✔ Stateful = may introduce overhead due to buffering/global knowledge.
✔ Always consider operation type when designing stream pipelines, especially for parallel execution.

Signed-off-by: https://github.com/Someshdiwan <[email protected]>

Author: Someshdiwan

JAVA8/StreamsInJAVA/src/Stateful and Stateless Operations in Java Streams.txt

@@ -0,0 +1,119 @@
+Understanding Stateful and Stateless Operations in Java Streams:
+
+In Java Streams, operations are classified as either **stateless** or **stateful** based on
+how they process the data and whether they require maintaining state across elements.
+
+1. Stateless Operations
+
+Definition:
+These operations process each element independently, without relying on the elements before
+or after it. They do not maintain any internal state.
+
+Examples:
+- filter(Predicate)  → Filters elements based on a condition.
+- map(Function)      → Transforms each element.
+- flatMap(Function)  → Flattens nested collections.
+- peek(Consumer)     → Performs an action on each element.
+- forEach(Consumer)  → Iterates over elements.
+
+Example Code:
+
+import java.util.Arrays;
+import java.util.List;
+
+public class StatelessExample {
+    public static void main(String[] args) {
+        List<Integer> numbers = Arrays.asList(1, 2, 3, 4, 5);
+
+        numbers.stream()
+               .filter(x -> x % 2 == 0)   // Stateless
+               .map(x -> x * 2)           // Stateless
+               .forEach(System.out::println);
+    }
+}
+
+Output:
+4
+8
+
+Why Stateless?
+- Each element is processed independently without tracking previous or future elements.
+
+---------------------------------------------------------------
+2. Stateful Operations
+---------------------------------------------------------------
+
+Definition:
+These operations require keeping track of previously seen elements or processing the entire
+stream before producing output. They may require buffering or sorting.
+
+Examples:
+- distinct()  → Removes duplicate elements.
+- sorted()    → Sorts the elements.
+- limit(n)    → Returns the first n elements.
+- skip(n)     → Skips the first n elements.
+- collect()   → Collects results into a collection.
+- reduce()    → Reduces all elements to a single value.
+
+Example Code:
+
+import java.util.Arrays;
+import java.util.List;
+
+public class StatefulExample {
+    public static void main(String[] args) {
+        List<Integer> numbers = Arrays.asList(5, 3, 7, 1, 5, 3);
+
+        numbers.stream()
+               .distinct()                // Stateful (removes duplicates)
+               .sorted()                  // Stateful (needs to sort entire stream)
+               .forEach(System.out::println);
+    }
+}
+
+Output:
+1
+3
+5
+7
+
+Why Stateful?
+- distinct() needs to track seen elements to remove duplicates.
+- sorted() must process the entire stream to produce an ordered result.
+
+---------------------------------------------------------------
+3. Why Does It Matter?
+---------------------------------------------------------------
+
+Performance Considerations:
+- Stateless operations are faster and process element-by-element.
+- Stateful operations may require buffering and increase memory usage.
+
+Parallel Streams:
+- Stateless operations are well suited for parallel execution.
+- Stateful operations may need synchronization and can degrade performance in parallel streams.
+
+Example: Parallel with Stateless vs Stateful
+
+import java.util.Arrays;
+import java.util.List;
+
+public class ParallelExample {
+    public static void main(String[] args) {
+        List<Integer> nums = Arrays.asList(1, 2, 3, 4, 5, 6);
+
+        // Stateless works well in parallel
+        nums.parallelStream()
+            .filter(x -> x % 2 == 0)
+            .forEach(System.out::println);
+
+        // Stateful may disrupt order in parallel
+        nums.parallelStream()
+            .sorted()
+            .forEach(System.out::println);
+    }
+}
+
+- Stateless → Independent per-element operations, efficient, good for parallel streams.
+- Stateful  → Require knowledge of entire stream or previously processed elements, ay reduce efficiency,
+              especially in parallel.