Status

Current state: Under discussion

Discussion thread: here

JIRA: KAFKA-20297

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

Motivation

The Time interface in org.apache.kafka.common.utils is currently exposed through public APIs but not officially designated as public. Classes such as KafkaStreams and Metrics accept Time parameters in their public constructors, making it part of the user-facing API surface without official support. Following KIP-1247 (Make Bytes public), it should be made officially public.

// multiple KafkaStreams constructors (test-only usage)
public KafkaStreams(Topology topology, Properties props, Time time)

// couple of examples from multiple "org.apache.kafka.common.metrics.Metrics.java" constructors
public Metrics(Time time) {}
public Metrics(MetricConfig defaultConfig, Time time) {}

// in package "org.apache.kafka.common.security.oauthbearer"
public JwtBearerJwtRetriever(Time time) {}
public ClientCredentialsJwtRetriever(Time time) {}

Since Time is already part of the user-facing API surface, it should be officially public.

However, the current Time interface in org.apache.kafka.common.utils combines multiple unrelated responsibilities:

  • Wall clock time (milliseconds())
  • Monotonic timing (nanoseconds(), hiResClockMs())
  • Thread coordination (sleep(), waitObject(), waitForFuture())
  • Timer creation (timer() methods)

Investigation of all officially public Javadoc classes shows that only milliseconds() is needed in the public API. The other methods are only used internally.

Therefore, rather than making the full Time interface public, we introduce a minimal focused public interface exposing only what public API consumers need and make the existing internal Time extend this newly created public Time interface as suggested by Sean Quah during the discussion.

Public Interfaces

New public APIs (4.4):

  • org.apache.kafka.common.Time (minimal, milliseconds() only)

Proposed Changes

Step 1: Create minimal public Time interface (4.4):

A new minimal Time interface will be introduced in org.apache.kafka.common

Step 2: Internal Time Extends Public Time (4.4):

The existing internal Time interface (org.apache.kafka.common.utils.Time) extends the new public interface (org.apache.kafka.common.Time) for backwards compatibility

Step 3: Update public constructors accepting org.apache.kafka.common.utils.Time to use org.apache.kafka.common.Time:

For example, KafkaStreams(Topology, Properties, org.apache.kafka.common.Time), and update corresponding Metrics, ClientCredentialsJwtRetriever and JwtBearerJwtRetriever constructors


Compatibility, Deprecation, and Migration Plan

  • New minimal public Time interface introduced
  • Internal Time extends public Time (backwards compatible)
  • Public constructors in Metrics, KafkaStreams, ClientCredentialsJwtRetriever and JwtBearerJwtRetriever updated to accept org.apache.kafka.common.Time
  • Existing code continues working unchanged as utils.Time IS-A common.Time
  • MockTime requires no changes as it already implements utils.Time which extends common.Time, making it automatically compatible with all updated constructors
  • Users can optionally migrate from org.apache.kafka.common.utils.Time to org.apache.kafka.common.Time where only milliseconds() is needed

Test Plan

This KIP primarily involves API designation rather than functional changes. Testing will focus on:

  • Javadoc generation: Verify org.apache.kafka.common.Time appear correctly in public API documentation
  • Verify existing tests continue passing unchanged

No new system tests are required.

Rejected Alternatives

  • Deprecate utils.Time: Would require @SuppressWarnings("deprecation") across all internal Kafka code using it - huge changes.
  • Deprecate all Time-accepting constructors: Internal Kafka code in other packages (KafkaProducer, KafkaAdminClient) would lose access in version 5.0 when constructors become package-private, breaking testing capabilities.
  • No labels