Status

Current state: Under Discussion

Discussion thread: here [Change the link from the KIP proposal email archive to your own email thread]

JIRA: KAFKA-12849

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

This KIP could be seen as an spin-off of KIP-740: Clean up public API in TaskId and fix TaskMetadata#taskId(). During the one of the Pull Requests that were created to implement the aforementioned KIP, it became apparent that TaskMetadata should have never been a class available for the general public, but more of an internal class. See https://github.com/apache/kafka/pull/10755#discussion_r639338584

Also it is important to notice that the goal of this KIP needs to still be consistent with that of KIP-740, which was to not expose TaskID as a String in the public APIs.

Public Interfaces

Create a new Interface named TaskMetadata under package org.apache.kafka.streams, which will contain all currently non deprecated methods:

/**
 * Represents the state of a single task running within a {@link KafkaStreams} application.
 */
public interface TaskMetadata {


    /**
     * @return the basic task metadata such as subtopology and partition id
     */
    public TaskId taskId();

    /**
     * This function will return a set of the current TopicPartitions
     */
    public Set<TopicPartition> topicPartitions();

    /**
     * This function will return a map of TopicPartitions and the highest committed offset seen so far
     */
    public Map<TopicPartition, Long> committedOffsets();

    /**
     * This function will return a map of TopicPartitions and the highest offset seen so far in the Topic
     */
    public Map<TopicPartition, Long> endOffsets();

    /**
     * This function will return the time task idling started, if the task is not currently idling it will return empty
     */
    public Optional<Long> timeCurrentIdlingStarted();
}

Additionally, TaskMetadata under org.apache.kafka.streams.processor, will be deprecated:

/**
 * Represents the state of a single task running within a {@link KafkaStreams} application.
 * @deprecated since 3.0, use {@link org.apache.kafka.streams.TaskMetadata} instead
 */
@Deprecated
public class TaskMetadata {
...
}

Proposed Changes

By introducing a new interface on a different package, we are able to keep the same name (no need to come up with some forced name), and also, we are freed from carrying over changes like the one introduced in https://github.com/apache/kafka/pull/10755 where a method getTaskId was introduced (going against Kafka naming convention) because taskId was already taken and needed to be deprecated.
Together with this change, a new class TaskMetadataImpl will be created under org.apache.kafka.streams.internals, which will implement the aforementioned interface with the implementation present on the org.apache.kafka.streams.processor.TaskMetadata. The rest of the Kafka code base using the newly deprecated TaskMetadata will be migrated to use the new classes instead.

Also, by introducing a new interface altogether, we ease the migration of any possible current user of this class meant to be for internal use only.

Compatibility, Deprecation, and Migration Plan

As we create a new interface, these changes are 100% compatible. Users who currently use org.apache.kafka.streams.processor.TaskMetadata, should migrate to org.apache.kafka.streams.TaskMetadata.

Class org.apache.kafka.streams.processor.TaskMetadata will be deprecated and removed in future releases

Rejected Alternatives

An alternative that was rejected, was to directly transform org.apache.kafka.streams.TaskMetadata into an interface with this change. This was seen as a breaking change as the current constructor won't be present any more in this alternative, making possible users of this fail to compile.

Additionally, this change forced us to keep the method `getTaskId` for a while, until we could deprecate and remove the current `taskId` method.