A Polling Java Future

2020-05-08T00:00:00+00:00

There are times in Java, when we want to act on a state transition in some object. Ideally, the object allows us to register a listener, which is called when the state changes. Unfortunately, this is not always the case, especially when the class stems from a third-party library and is outside our control. In this case, we need to poll the state regularly, to detect the change we are interested in and then invoke the callback we want. The Java concurrency library offers a neat abstraction with the CompletableFuture. In this post we try to wrap the polling into such a future, that can be used by a wide variety of frameworks, especially for reactive programming.

As a starting point we need to have an object, that we want to observe. Let us assume, this object implements org.springframework.context.Phased. Essentially, this interface looks like this:

public interface Phased {
    int getPhase();
}

We want to create a CompletableFuture, that gets completed, when our observed phase has a certain value, say 1 for this post. So we want to create some implementation for the following method:

public <P extends Phased> CompletableFuture<P> awaitPhaseOne(P observable) {
    // poll observable until observable.getPhase() == 1
    return CompletableFuture.failedFuture(
        new IllegalStateException("not yet implemented")
    );
}

For now, we just return a failed future until we have the correct implementation. But let us have a look at the message signature first: The function returns a future, that potentially wraps the observed object. This allows consumers to execute further operations on this object:

awaitPhaseOne(observable).thenApply(o -> doSomething(o));

This return type is not the only possibility, it just serves as a useful example.

Let us now have a look, how we can use java.util.concurrent to implement our polling future. We will need three ingredients:

the CompletableFuture, that we want to create
a Runnable, that does the actual polling
a ScheduledExecutorService, that executes the Runnable

Putting it all together we arrive at the following implementation.

public <P extends Phased> CompletableFuture<P> awaitPhaseOne(P observable) {
    ScheduledExecutorService executor =
        Executors.newSingleThreadScheduledExecutor();
    CompletableFuture<P> future = new CompletableFuture<>();
    ScheduledFuture<?> scheduled = executor.scheduleAtFixedRate(
        // the Runnable executed in each polling run
        () -> { 
            if (observable.getPhase() == 1) {
                future.complete(observable);
            }
        },
        100, // initial delay
        200, // period between executions
        TimeUnit.MILLISECONDS  // time unit
    );
    future.whenComplete((obs, thrown) -> scheduled.cancel(true));
    return future;
}

We start with creating a new executor. This is a very simplistic approach, that we will revisit later.

Next we create the future, that is our desired CompletableFuture. We have not checked our observable yet, so the future is not completed.

The polling is now started by scheduling a Runnable with the executor. We use an anonymous lambda function, that checks the phase of our observable. If we find the desired phase 1, we complete the future. The runnable is scheduled to start polling after 100 milliseconds with an interval of 200 milliseconds. Of course, these values will be configurable in a production setting.

Before we return the future we need to ensure, that the polling is stopped once the future is completed. This is done with a small callback using future.whenComplete.

Our implementation separates nicely the code that is testing the observable from the polling infrastructure. The underlying design is a closure consisting of the Runnable accessing both the observable and the CompletableFuture. A ScheduledExecutorService allows scheduling with a fixed rate, as we used in our implementation or scheduling with fixed delay in between executions. More sophisticated schedules like for example exponential back-off require custom scheduling of the runs.

Let us come back to the creation of the ScheduledExecutorService: With the code above, a new instance is created for every call to the function awaitPhaseOne(). This implementation will spawn a new thread during each invocation. If it is called at high frequency, this is a severe performance issue. We can solve this issue by using a globally managed ScheduledExecutorService either in the surrounding class or from some other part of our application.

Another optimization is to check the polling condition before scheduling the Runnable and return immediately. Combining this pre-check with an extracted ScheduledExecutorService, we get the following implementation:

public class PollingFuture {

    private final ScheduledExecutorService executor;

    public PollingFuture(int corePoolSize) {
        this.executor = Executors.newScheduledThreadPool(corePoolSize);
    }

    public <P extends Phased> CompletableFuture<P> awaitPhaseOne(P observable) {
        if (isPhaseOne(observable)) {
            return CompletableFuture.completedFuture(observable);
        }
        CompletableFuture<P> future = new CompletableFuture<>();
        ScheduledFuture<?> scheduled = executor.scheduleAtFixedRate(
            // the Runnable executed in each polling run
            () -> {
                if (isPhaseOne(observable)) {
                    future.complete(observable);
                }
            }, 100, // initial delay
            200, // period between executions
            TimeUnit.MILLISECONDS // time unit
        );
        future.whenComplete((obs, thrown) -> scheduled.cancel(true));
        return future;
    }

    private <P extends Phased> boolean isPhaseOne(P observable) {
        return observable.getPhase() == 1;
    }
}

Note, that the first check of the polling condition is now executed during the function invocation in the main thread. If this was a long-running execution, this early check may hurt performance more, than what can be gained by not scheduling the Runnable. The whole logic on when to complete the CompletableFuture is now extracted to the private function isPhaseOne(...). Everything else is the glue code to create the polling future.

In summary, we developed a small class, that allows us to wrap polling for some condition into a CompletableFuture. We have seen, that handling a ScheduledExecutorService is required for the implementation. The resulting Future can be used in different asynchronous applications, e.g. with Spring WebFlux a reactive stack for building web applications.

Kafka Streams Suppress Feature

2020-04-04T00:00:00+00:00

Kafka Streams is a Java streaming framework, that tightly integrates with Apache Kafka. In contrast to Apache Spark of Apache Flink it does not require a separate cluster runtime. Instead it consists of a Java library to be fully integrated into any Java application. In that way it can augment the capabilities of that application by adding stream processing of Kafka topics. The suppression feature allows for fine-grained control of the message frequency when using aggregations. For a full feature description of Kafka Streams check out the documentation on the Apache project page or from Confluent.

Kafka Streams provides its own DSL to describe the stream processing topology. It is built upon two primitives: KStream and KTable. KStream is an abstraction of one or more Kafka topics. It supports message processing one message at a time. Aggregating multiple messages yields a KTable. KTables can be transformed back to a KStream consisting of the changelog of the KTable. The Kafka Streams documentation from Confluent contains a nice description of this stream-table-duality.

Generating the changelog out of a KTable will generate at least one message for each aggregated message in the resulting KStream. Therefore, downstream processors will see as many messages as were contained in the original KStream. For some applications, it would be beneficial to have downsampling of the message frequency at the cost of accuracy or latency. This is, what the suppress feature of Kafka Streams provides. It allows us to suppress messages on the changelog stream according to configurable conditions.

To understand the available suppressions, it is necessary to know the aggregations Kafka Streams supports. Messages will always be aggregated by their respective Kafka message key. This aggregation can be unbound or windowed. Kafka Streams supports different kinds of time windows and also a notion of session windows. A detailed description of windowed aggregations is contained in the official documentation.

Building on these aggregations, there are two modes of suppression, that are supported by Kafka Streams. All KTables support a time window suppression. That means changelog messages are only forwarded downstream after a certain duration has passed after the first change to the KTable was made. This requires a buffer, whose size can be configured in bytes or number of messages. If the buffer is exceeded before the duration is reached, the changelog will be emitted regardless.

public void suppressWithBoundedBuffer(StreamsBuilder builder) {
    builder.stream("events")
        .groupByKey() // group events by key
        .count()      // use event count as easy aggregation
        .suppress(
            Suppressed.untilTimeLimit(
                Duration.ofSeconds(2),       // emit count every 2 seconds
                BufferConfig.maxRecords(100) // collect at most 100 keys
            )
        );
}

The other mode is only supported for windowed aggregations. In this case all changelog messages can be suppressed until the window is closed. For time windowed aggregations, it is required to configure a grace period, to allow for late messages. It can be set to 0, but it needs to be explicitly set, otherwise no message will be forwarded. Since the closing of the window can occur well after any buffer size is exceeded, no messages will be forwarded if this limit is reached. Instead Kafka Streams will try to shut down the application.

public void suppressWithUnboundedBuffer(StreamsBuilder builder) {
    builder.stream("events")
        .groupByKey() // group events by key
        .windowedBy(
            TimeWindows
                .of(Duration.ofSeconds(2))    // time windows of 2 seconds
                .grace(Duration.ofSeconds(1)) // allow 1 second lateness
        )
        .count() // use event count as easy aggregation
        .suppress(
            Suppressed.untilWindowCloses(
                BufferConfig.unbounded() // do not restrict buffer
            )
        );
}

There is a nice blog post by John Roesler on Kafka Streams take on Watermarks and Triggers, that describes the suppress feature in great detail.

Software Engineering & Architecture

A Polling Java Future

Kafka Streams Suppress Feature