THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| Table of Contents |
|---|
Status
Current state: Adopted
Under Discussion thread: here
Discussion
Vote thread: here
JIRA: KAFKA-6987
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).
...
Adding toCompletionStage() is sufficient because CompletionStage itself exposes toCompletableFuture(), so anyone who needs an actual CompletableFuture (e.g. for interoperating with 3rd party APIs that require one) can get one. However, CompletableFuture exposes methods for future completion which should not be called by users (only the Admin client should be completing the returned futures), so calling these will be prevented. It is expected that users wanting to block on the completion of the KafkaFuture would use kafkaFuture.get(), rather than calling kafkaFuture.toCompletionStage().toCompletableFuture().get(), so the need to access the CompleteableFuture should be rare.
...
- Remove the
@InterfaceStability.Evolvingannotation onKafkaFutureto reflect the reality that changing this class incompatibly would cause of too much user code to break. - Deprecate the static class
KafkaFuture.Function, which already had Javadoc noting thatKafkaFuture.BaseFunctionwas preferred. - Annotating
KafkaFuture.Function,.BaseFunctionand.BiFunctionwith@FunctionalInterface, like the corresponding interfaces injava.util.
The methods of future admin client *Result classes would continue to use KafkaFuture for the sake of consistency.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
/**
* A flexible future which supports call chaining and other asynchronous programming patterns.
*
* <h3>Relation to {@code CompletableFuture}</h3>
* <p>This class exists because support for a Future-like construct was once needed on Java versions predating
* the addition of {@code CompletableFuture}. It is now possible to obtain a {@code CompletionStage} from a
* {@code KafkaFuture} instance by calling {@link #toCompletionStage()}.
* If converting {@link KafkaFuture#whenComplete(BiConsumer)} or {@link KafkaFuture#thenApply(BaseFunction)} to
* {@link CompletableFuture#whenComplete(java.util.function.BiConsumer)} or
* {@link CompletableFuture#thenApply(java.util.function.Function)} be aware that the returned
* {@code KafkaFuture} will fail with an {@code ExecutionException}, where as a {@code CompletableFuture} fails
* with a {@code CompletionException}.
*/
class KafkaFuture<Void> {
// ... existing methods ...
/**
* Get a CompletionStage with the same completion properties as this KafkaFuture.
* The returned instance will complete when this future completes and in the same way
* (with the same result or exception).
*
* Calling<p>Calling toCompletableFuture() on the returned instance will yield a CompletableFuture,
* but invocation of the completion methods (complete() and other methods in the complete*()
* and obtrude*() families) on that CompleteableFuture instance will result in
* UnsupportedOperationException being thrown. Unlike a minimal CompletableFuture
* the get*() and other methods of that CompletableFuture not inherited from CompletionStage
* will work normally.
*
* <p>If you want to block on the completion of a KafkaFuture you should use
* {@link #get()}, {@link #get} or {@link #getNow(Object)}, rather then calling
* {@code .toCompletionStage().toCompletableFuture().get()} etc.
*/
CompletionStage toCompletionStage();
/**
* A function which takes objects of type A and returns objects of type B.
*
* Prefer the functional interface {@link BaseFunction} over the class {@link Function}. This class is here for
* backwards compatibility reasons and might be deprecated/removed in a future release.
* @deprecated Replaced by the functional interface {@link BaseFunction} over the class {@link Function}.
*/
@Deprecated // adding this
public static abstract class Function<A, B> implements BaseFunction<A, B> { }
} |
...
To get the required completion-safety properties a new (internal) KafkaCompletableFuture class, a subclass of CompletableFuture, will be introduced. This KIP will allow access to the instance of that subclass wrapped by a KafkaFutureImpl, and that instance will be completed within within KafkaFutureImpl via a different method than the complete/completeExceptionally that 's inherited it inherits from CompletableFuture.
KafkaFutureImpl would gain a new public constructor for wrapping a KafkaCompletableFuture, which will allow implementation of KafkaFuture#allOf() to be simplified.
...