vvcephei commented on a change in pull request #10731:
URL: https://github.com/apache/kafka/pull/10731#discussion_r639778036
##########
File path:
streams/src/main/java/org/apache/kafka/streams/kstream/ValueTransformerWithKey.java
##########
@@ -75,14 +75,20 @@
void init(final ProcessorContext context);
/**
- * Transform the given [key and ]value to a new value.
+ * Transform the given [key and] value to a new value.
* Additionally, any {@link StateStore} that is {@link
KStream#transformValues(ValueTransformerWithKeySupplier, String...)
* attached} to this operator can be accessed and modified arbitrarily (cf.
* {@link ProcessorContext#getStateStore(String)}).
* <p>
- * Note, that using {@link ProcessorContext#forward(Object, Object)} or
+ * Note that using {@link ProcessorContext#forward(Object, Object)} or
* {@link ProcessorContext#forward(Object, Object, To)} is not allowed
within {@code transform} and
* will result in an {@link StreamsException exception}.
+ * <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,
+ * then the provided {@link ProcessorContext} from {@link
#init(ProcessorContext)}
+ * does not guarantee that all context information will be available when
{@code transform()}
+ * is executed.
Review 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.
```suggestion
* 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.
```
--
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.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
