KAFKA-12815: Update JavaDocs of ValueTransformerWithKey #10731
Conversation
| * <p> | ||
| * Note that if a {@code ValueTransformerWithKey} is used in a {@link KTable#transformValues(ValueTransformerWithKeySupplier, String...)} | ||
| * (or any other overload of {@code KTable#transformValues(...)}) operation, | ||
| * that the provided {@link ProcessorContext} from {@link #init(ProcessorContext)} |
There was a problem hiding this comment.
is this a typo?
if a 'xxx' is used in a 'yyy' operation, that the provided 'zzz' from 'aaa' doesn't guarantee....
Maybe replace that into then?
| * does not guarantee that all context information will be available when {@code transform()} | ||
| * is executed. |
There was a problem hiding this comment.
We might as well formally specify which things may be missing. Otherwise, it's not clear what users should do to guard their code.
| * does not guarantee that all context information will be available when {@code transform()} | |
| * is executed. | |
| * does not guarantee that all record context information will be available when | |
| * {@code transform()} is executed. For example, {@code transform()} may be | |
| * invoked as a result of upstream punctuations or other out-of-band operations, | |
| * in which case there will be no headers, topic name, timestamp, or offset available. | |
| * When those properties are absent, the following placeholder values will | |
| * be filled in: empty headers, `null` topic name, `-1` timestamp, and `-1` offset. | |
| * Implementations of this interface should guard against this case. |
There was a problem hiding this comment.
Well, for KTable#transformValues those things don't apply because there is no out-of-band transformation upstream.
It's the DSL, not the PAPI. It might might sense to add this information in general, but seems to be out-of-scope for this PR?
There was a problem hiding this comment.
All I was trying to do was characterize why the context information might be missing. If there are no out-of-band operations, then there should never be missing context.
| // we move to `RecordMetadata` than would be `null` for this case and thus | ||
| // we won't have the partition information, so it's better to now provide it | ||
| // here either, to not introduce a regression later on | ||
| -1, |
| * then the provided {@link ProcessorContext} from {@link #init(ProcessorContext)} | ||
| * does not guarantee that all context information will be available when {@code transform()} | ||
| * is executed, as it might be executed "out-of-band" due to some internal optimizations | ||
| * applied by the Kafka Streams DSL. |
Follow up to #10720