lucliu1108 commented on code in PR #22807:
URL: https://github.com/apache/kafka/pull/22807#discussion_r3580785492
##########
streams/src/main/java/org/apache/kafka/streams/kstream/KStream.java:
##########
@@ -1347,13 +1345,29 @@ <GlobalKey, GlobalValue, VOut> KStream<K, VOut>
join(final GlobalKTable<GlobalKe
/**
* See {@link #join(GlobalKTable, KeyValueMapper, ValueJoiner)}.
*
- * <p>Note that the {@link KStream} key is read-only and must not be
modified, as this can lead to corrupt
- * partitioning and incorrect results.
+ * <b>Warning:</b> {@code readOnlyKey} is the {@code KStream} record's
key, <b>not</b>
+ * the join key produced by {@code keySelector}. Unlike {@link
#join(KTable, ValueJoinerWithKey)
+ * KStream-KTable} and {@link #join(KStream, ValueJoinerWithKey,
JoinWindows) KStream-KStream}
+ * joins — where the stream key <em>is</em> the join key — {@link
GlobalKTable} joins derive
+ * the join key via {@code keySelector}, so {@code readOnlyKey} does
<b>not</b> necessarily
+ * match the key of the {@link GlobalKTable} record being joined.
+ *
+ * @deprecated Use {@link #join(GlobalKTable, KeyValueMapper,
ValueJoinerWithMappedAndStreamKey)}
+ * instead, which exposes both the mapped join key and the
stream record's key.
*/
+ @Deprecated
<GlobalKey, GlobalValue, VOut> KStream<K, VOut> join(final
GlobalKTable<GlobalKey, GlobalValue> globalTable,
final
KeyValueMapper<? super K, ? super V, ? extends GlobalKey> keySelector,
final
ValueJoinerWithKey<? super K, ? super V, ? super GlobalValue, ? extends VOut>
joiner);
+ /**
+ * As {@link #join(GlobalKTable, KeyValueMapper, ValueJoiner)}, but the
joiner receives both
+ * the mapped join key (used to look up the {@link GlobalKTable} value)
and the {@link KStream} record key.
Review Comment:
Fix: I updated the javadoc for `join(GlobalKTable, KeyValueMapper,
ValueJoiner)` to point it to the new method. And simplified the description of
the 4 added methods.
The warning messages of the 4 deprecated methods are left as they were (some
repeatedness) so developers could see why they get deprecated directly. Is this
better or it would be more preferable to repeat less on those as well?
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
