lucasbru commented on code in PR #18704:
URL: https://github.com/apache/kafka/pull/18704#discussion_r1935265275
##########
streams/src/main/java/org/apache/kafka/streams/kstream/KStream.java:
##########
@@ -670,107 +670,114 @@ <VR> KStream<K, VR> flatMapValues(final
ValueMapperWithKey<? super K, ? super V,
void print(final Printed<K, V> printed);
/**
- * Perform an action on each record of {@code KStream}.
- * This is a stateless record-by-record operation (cf. {@link
#process(ProcessorSupplier, String...)}).
- * Note that this is a terminal operation that returns void.
+ * Perform an action on each record of this {@code KStream}.
+ * This is a stateless record-by-record operation (cf. {@link
#process(ProcessorSupplier, String...)} for
+ * stateful record processing).
*
- * @param action an action to perform on each record
- * @see #process(ProcessorSupplier, String...)
+ * <p>{@code Foreach} is a terminal operation that may triggers side
effects (such as logging or statistics
+ * collection) and returns {@code void} (cf. {@link #peek(ForeachAction)}).
+ *
+ * <p>Note that this operation may execute multiple times for a single
record in failure cases,
+ * and it is <em>not</em> guarded by "exactly-once processing guarantees".
+ *
+ * @param action
+ * an action to perform on each record
*/
void foreach(final ForeachAction<? super K, ? super V> action);
/**
- * Perform an action on each record of {@code KStream}.
- * This is a stateless record-by-record operation (cf. {@link
#process(ProcessorSupplier, String...)}).
- * Note that this is a terminal operation that returns void.
+ * See {@link #foreach(ForeachAction)}.
*
- * @param action an action to perform on each record
- * @param named a {@link Named} config used to name the processor in the
topology
- * @see #process(ProcessorSupplier, String...)
+ * <p>Takes an additional {@link Named} parameter that is used to name the
processor in the topology.
*/
void foreach(final ForeachAction<? super K, ? super V> action, final Named
named);
/**
- * Perform an action on each record of {@code KStream}.
- * This is a stateless record-by-record operation (cf. {@link
#process(ProcessorSupplier, String...)}).
- * <p>
- * Peek is a non-terminal operation that triggers a side effect (such as
logging or statistics collection)
- * and returns an unchanged stream.
- * <p>
- * Note that since this operation is stateless, it may execute multiple
times for a single record in failure cases.
+ * Perform an action on each record of this {@code KStream}.
+ * This is a stateless record-by-record operation (cf. {@link
#process(ProcessorSupplier, String...)} for
+ * stateful record processing).
*
- * @param action an action to perform on each record
- * @see #process(ProcessorSupplier, String...)
- * @return itself
+ * <p>{@code Peek} is a non-terminal operation that may triggers side
effects (such as logging or statistics
+ * collection) and returns an unchanged {@code KStream} (cf. {@link
#foreach(ForeachAction)}).
+ *
+ * <p>Note that this operation may execute multiple times for a single
record in failure cases,
+ * and it is <em>not</em> guarded by "exactly-once processing guarantees".
+ *
+ * @param action
+ * an action to perform on each record
+ *
+ * @return An unmodified {@code KStream}.
*/
KStream<K, V> peek(final ForeachAction<? super K, ? super V> action);
/**
- * Perform an action on each record of {@code KStream}.
- * This is a stateless record-by-record operation (cf. {@link
#process(ProcessorSupplier, String...)}).
- * <p>
- * Peek is a non-terminal operation that triggers a side effect (such as
logging or statistics collection)
- * and returns an unchanged stream.
- * <p>
- * Note that since this operation is stateless, it may execute multiple
times for a single record in failure cases.
+ * See {@link #peek(ForeachAction)}.
*
- * @param action an action to perform on each record
- * @param named a {@link Named} config used to name the processor in the
topology
- * @see #process(ProcessorSupplier, String...)
- * @return itself
+ * <p>Takes an additional {@link Named} parameter that is used to name the
processor in the topology.
*/
KStream<K, V> peek(final ForeachAction<? super K, ? super V> action, final
Named named);
/**
- * Split this stream into different branches. The returned {@link
BranchedKStream} instance can be used for routing
- * the records to different branches depending on evaluation against the
supplied predicates. Records are evaluated against the
- * predicates in the order they are provided with the first matching
predicate accepting the record.
- * <p>
- * Note: Stream branching is a stateless record-by-record operation.
- * Please check {@link BranchedKStream} for detailed description and
usage example
+ * Split this {@code KStream} into different branches. The returned {@link
BranchedKStream} instance can be used
+ * for routing the records to different branches depending on evaluation
against the supplied predicates.
+ * Records are evaluated against the predicates in the order they are
provided with the first matching predicate
+ * accepting the record. Branching is a stateless record-by-record
operation.
+ * See {@link BranchedKStream} for a detailed description and usage
example.
+ *
+ * <p>Splitting a {@code KStream} guarantees, that each input record is
sent to at most one result {@code KStream}.
Review Comment:
```suggestion
* <p>Splitting a {@code KStream} guarantees that each input record is
sent to at most one result {@code KStream}.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscr...@kafka.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
