Skip to content

Commit 02a95c9

Browse files
wolf8334wolf8334
authored
Operator docs: add description and example for StreamConverters.javaCollector (#2992)
* Operator docs: add description and example for StreamConverters.javaCollector Motivation: The javaCollector operator doc page had a TODO placeholder instead of documentation. Modification: - Replace TODO with a Description section explaining how javaCollector works - Add references to javaCollectorParallelUnordered and Sink.collect - Add Scala and Java code examples using Collectors.toList Result: The StreamConverters.javaCollector operator docs are now complete. Tests: sbt "docs/Test/compile" -- passed References: Refs akka/akka-core#25468 * docs: remove Java version reference in javaCollector example Signed-off-by: 钱多多 <2916947+wolf8334@users.noreply.github.com> * docs: add license header to JavaCollectorDocExamples Signed-off-by: 钱多多 <2916947+wolf8334@users.noreply.github.com> * docs: add license header to JavaCollectorDocExamples Signed-off-by: 钱多多 <2916947+wolf8334@users.noreply.github.com> * docs: add license header to JavaCollectorDocExamples Signed-off-by: 钱多多 <2916947+wolf8334@users.noreply.github.com> --------- Signed-off-by: 钱多多 <2916947+wolf8334@users.noreply.github.com>
1 parent ef5bfa6 commit 02a95c9

3 files changed

Lines changed: 100 additions & 2 deletions

File tree

‎docs/src/main/paradox/stream/operators/StreamConverters/javaCollector.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# StreamConverters.javaCollector
22

3-
Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` transformation and reduction operations.
3+
Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java `Collector` transformation and reduction operations.
44

55
@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters)
66

@@ -11,4 +11,25 @@ Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`
1111

1212
## Description
1313

14-
TODO: We would welcome help on contributing descriptions and examples, see: https://github.com/akka/akka/issues/25646
14+
`javaCollector` creates a @apidoc[Sink] that accepts a Java 8 @javadoc[java.util.stream.Collector](java.util.stream.Collector)
15+
factory. The `Collector` accumulates incoming elements into a mutable container as downstream demand is
16+
triggered, and after the stream completes, an optional finisher transforms the accumulated result. The sink
17+
materializes into a @scala[`Future`]@java[`CompletionStage`] holding the final result. All processing
18+
happens sequentially on the stream's materialized execution context.
19+
20+
Since each materialization of the sink must start with a fresh accumulator, the factory is invoked once per
21+
materialization. Use @ref:[javaCollectorParallelUnordered](javaCollectorParallelUnordered.md) if parallel
22+
collection is needed.
23+
24+
@ref:[`Sink.collect`](../Sink/collect.md) provides a simpler API for common collection scenarios.
25+
26+
## Example
27+
28+
In this example, `StreamConverters.javaCollector` uses ``Collectors.toList`` to gather stream elements
29+
into a ``List``.
30+
31+
Scala
32+
: @@snip [JavaCollectorDocExample.scala](/docs/src/test/scala/docs/stream/operators/JavaCollectorDocExample.scala) { #javaCollector }
33+
34+
Java
35+
: @@snip [JavaCollectorDocExamples.java](/docs/src/test/java/jdocs/stream/operators/JavaCollectorDocExamples.java) { #javaCollector }

‎docs/src/test/java/jdocs/stream/operators/JavaCollectorDocExamples.java‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to You under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
package jdocs.stream.operators;
19+
20+
import java.util.Arrays;
21+
import java.util.List;
22+
import java.util.concurrent.CompletionStage;
23+
import java.util.stream.Collectors;
24+
import org.apache.pekko.NotUsed;
25+
import org.apache.pekko.actor.ActorSystem;
26+
import org.apache.pekko.stream.javadsl.Source;
27+
import org.apache.pekko.stream.javadsl.StreamConverters;
28+
29+
public class JavaCollectorDocExamples {
30+
31+
static void example() {
32+
ActorSystem system = null;
33+
34+
// #javaCollector
35+
Source<String, NotUsed> source = Source.from(Arrays.asList("Apache", "Pekko", "Streams"));
36+
37+
CompletionStage<List<String>> result =
38+
source.runWith(StreamConverters.javaCollector(Collectors::toList), system);
39+
// #javaCollector
40+
}
41+
}

‎docs/src/test/scala/docs/stream/operators/JavaCollectorDocExample.scala‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to You under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
18+
package docs.stream.operators
19+
20+
import java.util.stream.Collectors
21+
22+
import org.apache.pekko.NotUsed
23+
import org.apache.pekko.stream.scaladsl.Sink
24+
import org.apache.pekko.stream.scaladsl.Source
25+
import org.apache.pekko.stream.scaladsl.StreamConverters
26+
27+
object JavaCollectorDocExample {
28+
29+
// #javaCollector
30+
val source: Source[String, NotUsed] =
31+
Source(List("Apache", "Pekko", "Streams"))
32+
33+
val sink: Sink[String, _] =
34+
StreamConverters.javaCollector(() => Collectors.toList[String]())
35+
// #javaCollector
36+
}

0 commit comments

Comments
 (0)