kirktrue commented on code in PR #15640:
URL: https://github.com/apache/kafka/pull/15640#discussion_r1586620323
##########
clients/src/main/java/org/apache/kafka/clients/consumer/internals/events/CompletableEvent.java:
##########
@@ -16,9 +16,118 @@
*/
package org.apache.kafka.clients.consumer.internals.events;
+import org.apache.kafka.common.utils.Time;
+import org.apache.kafka.common.utils.Timer;
+
+import java.time.Duration;
+import java.util.concurrent.CancellationException;
import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeoutException;
+
+import static java.util.Objects.requireNonNull;
+/**
+ * {@code CompletableEvent} is an interface that is used by both {@link
CompletableApplicationEvent} and
+ * {@link CompletableBackgroundEvent} for common processing and logic. A
{@code CompletableEvent} is one that
+ * allows the caller to get the {@link #future() future} related to the event
and the event's
+ * {@link #deadlineMs() expiration timestamp}.
+ *
+ * @param <T> Return type for the event when completed
+ */
public interface CompletableEvent<T> {
+ /**
+ * Returns the {@link CompletableFuture future} associated with this
event. Any event will have some related
+ * logic that is executed on its behalf. The event can complete in one of
the following ways:
+ *
+ * <ul>
+ * <li>
+ * Success: when the logic for the event completes successfully,
the data generated by that event
+ * (if applicable) is passed to {@link
CompletableFuture#complete(Object)}. In the case where the generic
+ * bound type is specified as {@link Void}, {@code null} is
provided.</li>
+ * <li>
+ * Error: when the the event logic generates an error, the error
is passed to
+ * {@link CompletableFuture#completeExceptionally(Throwable)}.
+ * </li>
+ * <li>
+ * Timeout: when the time spent executing the event logic exceeds
the {@link #deadlineMs() deadline}, an
+ * instance of {@link TimeoutException} should be created and
passed to
+ * {@link CompletableFuture#completeExceptionally(Throwable)}.
+ * </li>
+ * <li>
+ * Cancelled: when an event remains incomplete when the consumer
closes, the future will be
+ * {@link CompletableFuture#cancel(boolean) cancelled}. Attempts
to {@link Future#get() get the result}
Review Comment:
Good catch!
I had been using `cancel()`, but noticed that the message in the exception
the caller of `Future.get()` later received was unhelpful. Yes, `cancel()`
calls `completeExceptionally(new CancellationException())`, but I wanted the
exception with a (hopefully) meaningful message.
Anyhoo... I've updated the documentation to reflect that change.
--
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
