0
# Stream Processing
1

2
Advanced stream operations for key-value data processing with the MapStream interface providing specialized operations for Map-like data structures. This extends Java's Stream API with dedicated support for key-value pair operations, enabling powerful data transformation pipelines.
3

4
## Capabilities
5

6
### MapStream Operations
7

8
Specialized stream interface for processing key-value pairs with dedicated operations for keys, values, and entries.
9

10
```java { .api }
11
/**
12
 * Stream-like operations on key-value pairs
13
 */
14
public interface MapStream<K, V> extends BaseStream<Entry<K, V>, MapStream<K, V>> {
15
    /**
16
     * Create MapStream from Map
17
     * @param map Source map
18
     * @return MapStream of map entries
19
     */
20
    static <K, V> MapStream<K, V> of(Map<? extends K, ? extends V> map);
21
    
22
    /**
23
     * Create MapStream from nullable Map
24
     * @param map Source map (can be null)
25
     * @return MapStream of map entries or empty stream
26
     */
27
    static <K, V> MapStream<K, V> ofNullable(Map<? extends K, ? extends V> map);
28
    
29
    /**
30
     * Create MapStream from Entry collection
31
     * @param collection Collection of entries
32
     * @return MapStream of entries
33
     */
34
    static <K, V> MapStream<K, V> of(Collection<? extends Entry<? extends K, ? extends V>> collection);
35
    
36
    /**
37
     * Create MapStream from Entry stream
38
     * @param stream Stream of entries
39
     * @return MapStream of entries
40
     */
41
    static <K, V> MapStream<K, V> of(Stream<? extends Entry<? extends K, ? extends V>> stream);
42
    
43
    /**
44
     * Concatenate two MapStreams
45
     * @param a First MapStream
46
     * @param b Second MapStream
47
     * @return Concatenated MapStream
48
     */
49
    static <K, V> MapStream<K, V> concat(MapStream<? extends K, ? extends V> a, MapStream<? extends K, ? extends V> b);
50
    
51
    /**
52
     * Create empty MapStream
53
     * @return Empty MapStream
54
     */
55
    static <K, V> MapStream<K, V> empty();
56
    
57
    /**
58
     * Create MapStream from individual key-value pairs
59
     * @param k1 First key
60
     * @param v1 First value
61
     * @return MapStream with single entry
62
     */
63
    static <K, V> MapStream<K, V> of(K k1, V v1);
64
    
65
    /**
66
     * Create MapStream from key-value pairs (up to 10 pairs supported)
67
     */
68
    static <K, V> MapStream<K, V> of(K k1, V v1, K k2, V v2);
69
    // ... additional overloads for 3-10 key-value pairs
70
    
71
    /**
72
     * Create MapStream from Entry varargs
73
     * @param entries Entries to include
74
     * @return MapStream of entries
75
     */
76
    static <K, V> MapStream<K, V> ofEntries(Entry<? extends K, ? extends V>... entries);
77
    
78
    /**
79
     * Create Entry instance
80
     * @param key Entry key
81
     * @param value Entry value
82
     * @return Map Entry instance
83
     */
84
    static <K, V> Entry<K, V> entry(K key, V value);
85
    
86
    /**
87
     * Get stream of entries
88
     * @return Stream of Map.Entry objects
89
     */
90
    Stream<Entry<K, V>> entries();
91
    
92
    /**
93
     * Get stream of keys
94
     * @return Stream of keys
95
     */
96
    Stream<K> keys();
97
    
98
    /**
99
     * Get stream of values
100
     * @return Stream of values
101
     */
102
    Stream<V> values();
103
    
104
    /**
105
     * Filter entries by predicate
106
     * @param predicate Entry filter predicate
107
     * @return Filtered MapStream
108
     */
109
    MapStream<K, V> filter(Predicate<? super Entry<K, V>> predicate);
110
    
111
    /**
112
     * Filter entries by key predicate
113
     * @param predicate Key filter predicate
114
     * @return Filtered MapStream
115
     */
116
    MapStream<K, V> filterKey(Predicate<? super K> predicate);
117
    
118
    /**
119
     * Filter entries by value predicate
120
     * @param predicate Value filter predicate
121
     * @return Filtered MapStream
122
     */
123
    MapStream<K, V> filterValue(Predicate<? super V> predicate);
124
    
125
    /**
126
     * Transform entries
127
     * @param mapper Entry transformation function
128
     * @return MapStream with transformed entries
129
     */
130
    <R, S> MapStream<R, S> map(Function<? super Entry<K, V>, ? extends Entry<R, S>> mapper);
131
    
132
    /**
133
     * Transform keys
134
     * @param mapper Key transformation function
135
     * @return MapStream with transformed keys
136
     */
137
    <R> MapStream<R, V> mapKey(Function<? super K, ? extends R> mapper);
138
    
139
    /**
140
     * Transform values
141
     * @param mapper Value transformation function
142
     * @return MapStream with transformed values
143
     */
144
    <R> MapStream<K, R> mapValue(Function<? super V, ? extends R> mapper);
145
    
146
    /**
147
     * Transform to object stream
148
     * @param mapper Entry to object transformation function
149
     * @return Stream of transformed objects
150
     */
151
    <R> Stream<R> mapToObj(Function<? super Entry<K, V>, ? extends R> mapper);
152
    
153
    /**
154
     * Transform to int stream
155
     * @param mapper Entry to int transformation function
156
     * @return IntStream of transformed values
157
     */
158
    IntStream mapToInt(ToIntFunction<? super Entry<K, V>> mapper);
159
    
160
    /**
161
     * Transform to long stream
162
     * @param mapper Entry to long transformation function
163
     * @return LongStream of transformed values
164
     */
165
    LongStream mapToLong(ToLongFunction<? super Entry<K, V>> mapper);
166
    
167
    /**
168
     * Transform to double stream
169
     * @param mapper Entry to double transformation function
170
     * @return DoubleStream of transformed values
171
     */
172
    DoubleStream mapToDouble(ToDoubleFunction<? super Entry<K, V>> mapper);
173
    
174
    /**
175
     * Flat map entries to multiple entries
176
     * @param mapper Function producing stream of entries
177
     * @return Flattened MapStream
178
     */
179
    <R, S> MapStream<R, S> flatMap(Function<? super Entry<K, V>, ? extends Stream<? extends Entry<R, S>>> mapper);
180
    
181
    /**
182
     * Flat map keys to multiple entries
183
     * @param mapper Function producing stream of entries from key
184
     * @return Flattened MapStream
185
     */
186
    <R, S> MapStream<R, S> flatMapKey(Function<? super K, ? extends Stream<? extends Entry<R, S>>> mapper);
187
    
188
    /**
189
     * Flat map values to multiple entries
190
     * @param mapper Function producing stream of entries from value
191
     * @return Flattened MapStream
192
     */
193
    <R, S> MapStream<R, S> flatMapValue(Function<? super V, ? extends Stream<? extends Entry<R, S>>> mapper);
194
    
195
    /**
196
     * Peek at entries without modifying stream
197
     * @param action Action to perform on each entry
198
     * @return This MapStream
199
     */
200
    MapStream<K, V> peek(Consumer<? super Entry<K, V>> action);
201
    
202
    /**
203
     * Peek at keys without modifying stream
204
     * @param action Action to perform on each key
205
     * @return This MapStream
206
     */
207
    MapStream<K, V> peekKey(Consumer<? super K> action);
208
    
209
    /**
210
     * Peek at values without modifying stream
211
     * @param action Action to perform on each value
212
     * @return This MapStream
213
     */
214
    MapStream<K, V> peekValue(Consumer<? super V> action);
215
    
216
    /**
217
     * Remove duplicate entries
218
     * @return MapStream with unique entries
219
     */
220
    MapStream<K, V> distinct();
221
    
222
    /**
223
     * Sort entries by natural order
224
     * @return Sorted MapStream
225
     */
226
    MapStream<K, V> sorted();
227
    
228
    /**
229
     * Sort entries by comparator
230
     * @param comparator Entry comparator
231
     * @return Sorted MapStream
232
     */
233
    MapStream<K, V> sorted(Comparator<? super Entry<K, V>> comparator);
234
    
235
    /**
236
     * Sort entries by key comparator
237
     * @param comparator Key comparator
238
     * @return Sorted MapStream
239
     */
240
    MapStream<K, V> sortedByKey(Comparator<? super K> comparator);
241
    
242
    /**
243
     * Sort entries by value comparator
244
     * @param comparator Value comparator
245
     * @return Sorted MapStream
246
     */
247
    MapStream<K, V> sortedByValue(Comparator<? super V> comparator);
248
    
249
    /**
250
     * Limit stream to first n entries
251
     * @param maxSize Maximum number of entries
252
     * @return Limited MapStream
253
     */
254
    MapStream<K, V> limit(long maxSize);
255
    
256
    /**
257
     * Skip first n entries
258
     * @param n Number of entries to skip
259
     * @return MapStream with skipped entries
260
     */
261
    MapStream<K, V> skip(long n);
262
    
263
    /**
264
     * Count entries in stream
265
     * @return Number of entries
266
     */
267
    long count();
268
    
269
    /**
270
     * Apply action to each entry
271
     * @param action Action to perform
272
     */
273
    void forEach(Consumer<? super Entry<K, V>> action);
274
    
275
    /**
276
     * Apply action to each entry in encounter order
277
     * @param action Action to perform
278
     */
279
    void forEachOrdered(Consumer<? super Entry<K, V>> action);
280
    
281
    /**
282
     * Check if any entry matches predicate
283
     * @param predicate Test predicate
284
     * @return true if any match found
285
     */
286
    boolean anyMatch(Predicate<? super Entry<K, V>> predicate);
287
    
288
    /**
289
     * Check if all entries match predicate
290
     * @param predicate Test predicate
291
     * @return true if all match
292
     */
293
    boolean allMatch(Predicate<? super Entry<K, V>> predicate);
294
    
295
    /**
296
     * Check if no entries match predicate
297
     * @param predicate Test predicate
298
     * @return true if none match
299
     */
300
    boolean noneMatch(Predicate<? super Entry<K, V>> predicate);
301
    
302
    /**
303
     * Find any entry
304
     * @return Optional containing any entry or empty
305
     */
306
    Optional<Entry<K, V>> findAny();
307
    
308
    /**
309
     * Find first entry
310
     * @return Optional containing first entry or empty
311
     */
312
    Optional<Entry<K, V>> findFirst();
313
    
314
    /**
315
     * Collect entries using collector
316
     * @param collector Collector to use
317
     * @return Collected result
318
     */
319
    <R> R collect(Collector<? super Entry<K, V>, ?, R> collector);
320
    
321
    /**
322
     * Collect to Map
323
     * @return Map containing all entries
324
     */
325
    Map<K, V> collect(Collector<Entry<K, V>, ?, Map<K, V>> collector);
326
    
327
    /**
328
     * Convert to array
329
     * @return Array of entries
330
     */
331
    Object[] toArray();
332
    
333
    /**
334
     * Convert to typed array
335
     * @param generator Array generator function
336
     * @return Typed array of entries
337
     */
338
    <A> A[] toArray(IntFunction<A[]> generator);
339
}
340
```
341

342
**Usage Examples:**
343

344
```java
345
import aQute.bnd.stream.MapStream;
346
import java.util.Map;
347
import java.util.stream.Collectors;
348

349
// Create from Map
350
Map<String, Integer> data = Map.of("a", 1, "b", 2, "c", 3);
351
MapStream<String, Integer> stream = MapStream.of(data);
352

353
// Filter and transform
354
Map<String, String> result = MapStream.of(data)
355
    .filterValue(v -> v > 1)
356
    .mapValue(v -> "Value: " + v)
357
    .collect(Collectors.toMap(
358
        Entry::getKey,
359
        Entry::getValue
360
    ));
361

362
// Key-based operations
363
MapStream.of("apple", 5, "banana", 6, "cherry", 6)
364
    .filterKey(k -> k.startsWith("a"))
365
    .mapValue(v -> v * 2)
366
    .forEach(entry -> System.out.println(entry));
367

368
// Complex transformations
369
Map<String, List<String>> grouped = MapStream.of(
370
        "apple", "fruit",
371
        "carrot", "vegetable", 
372
        "banana", "fruit"
373
    )
374
    .collect(Collectors.groupingBy(
375
        Entry::getValue,
376
        Collectors.mapping(Entry::getKey, Collectors.toList())
377
    ));
378

379
// Stream operations
380
MapStream.of(data)
381
    .peekKey(k -> System.out.println("Processing: " + k))
382
    .sortedByValue(Integer::compareTo)
383
    .limit(2)
384
    .mapToObj(entry -> entry.getKey() + "=" + entry.getValue())
385
    .forEach(System.out::println);
386
```
387

388
### Tri-Consumer Interface
389

390
Functional interface for consuming three arguments, useful for complex stream operations.
391

392
```java { .api }
393
/**
394
 * Functional interface for consuming three arguments
395
 */
396
@FunctionalInterface
397
public interface TriConsumer<T, U, V> {
398
    /**
399
     * Accept three arguments
400
     * @param t First argument
401
     * @param u Second argument
402
     * @param v Third argument
403
     */
404
    void accept(T t, U u, V v);
405
}
406
```
407

408
**Usage Examples:**
409

410
```java
411
import aQute.bnd.stream.TriConsumer;
412

413
// Use with complex operations
414
TriConsumer<String, Integer, Boolean> processor = (name, count, enabled) -> {
415
    if (enabled) {
416
        System.out.println("Processing " + name + " with count " + count);
417
    }
418
};
419

420
// Apply the consumer
421
processor.accept("test", 42, true);
422

423
// Use in stream operations or method references
424
someDataStructure.forEach(processor);
425
```
426

427
## Stream Collectors
428

429
Specialized collectors for MapStream operations.
430

431
```java { .api }
432
public interface MapStream<K, V> {
433
    /**
434
     * Collector for creating immutable Map
435
     * @return Collector that produces Map
436
     */
437
    static <K, V> Collector<Entry<K, V>, ?, Map<K, V>> toMap();
438
    
439
    /**
440
     * Collector for creating Map with merge function
441
     * @param mergeFunction Function to merge duplicate values
442
     * @return Collector that produces Map
443
     */
444
    static <K, V> Collector<Entry<K, V>, ?, Map<K, V>> toMap(BinaryOperator<V> mergeFunction);
445
    
446
    /**
447
     * Collector for creating specific Map type
448
     * @param mergeFunction Function to merge duplicate values
449
     * @param mapSupplier Supplier for Map implementation
450
     * @return Collector that produces specified Map type
451
     */
452
    static <K, V, M extends Map<K, V>> Collector<Entry<K, V>, ?, M> toMap(
453
        BinaryOperator<V> mergeFunction,
454
        Supplier<M> mapSupplier);
455
}
456
```