Status

Current state: "Under Discussion"

Discussion thread: here

JIRA: KAFKA-8794

Released: <Kafka Version>

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

Motivation

As of 2.6, there is a glitch in Admin#describeLogDirs method. This method returns DescribeLogDirsResult, whose methods return org.apache.kafka.common.requests.DescribeLogDirsResponse.LogDirInfo instances (which in turn contains DescribeLogDirsResponse.ReplicaInfo instances.) However, org.apache.kafka.common.requests package is not a public package; as a result, the Javadoc of DescribeLogDirsResult class does not provide any information about the LogDirInfo class.

The API itself is still callable, but this glitch makes the users of this API call have to make a rough guess about how to use this class.

DescribeLogDirsResponse.[LogDirInfo, ReplicaInfo] are intended to be used as a internal class. So, it would be better to hide these classes from the public and provide other public classes instead.

Public Interfaces

For the consistency with other Result classes (e.g., DescribeReplicaLogDirsResult), DescribeLogDirsResult now provides the following inner classes: LogDirInfo, ReplicaInfo. Each of them inherits DescribeLogDirsResponse.LogDirInfo, DescribeLogDirsResponse.ReplicaInfo for backward compatibility.

public class DescribeLogDirsResult {
  ...


  /**
   * State of a LogDir, (possibly) with an error code. Possible error codes are:
   * <p><ul>
   *   <li>KAFKA_STORAGE_ERROR (56)
   *   <li>UNKNOWN (-1)
   * </ul><p>
   */
  static public class LogDirInfo extends DescribeLogDirsResponse.LogDirInfo {
    public LogDirInfo(Errors error, Map<TopicPartition, ReplicaInfo> replicaInfos) {
      ...
    }
  }

  /**
   * State of a replica.
   **/
  static public class ReplicaInfo extends DescribeLogDirsResponse.ReplicaInfo {
    public ReplicaInfo(long size, long offsetLag, boolean isFuture) {
      ...
    }
  }
}

Proposed Changes

• DescribeLogDirsResponse.LogDirInfo is now deprecated, in favor of DescribeLogDirsResult.LogDirInfo.
• DescribeLogDirsResponse.ReplicaInfo is now deprecated, in favor of DescribeLogDirsResult.ReplicationInfo.
• DescribeLogDirsResponse.LogDirInfo.replicaInfos is also deprecated in favor of DescribeLogDirsResult.LogDirInfo.tpToReplicaInfos.

public class DescribeLogDirsResponse extends AbstractResponse {
  ...

  /**
   * State of a LogDir, (possibly) with an error code. Possible error codes are:
   * <p><ul>
   *   <li>KAFKA_STORAGE_ERROR (56)
   *   <li>UNKNOWN (-1)
   * </ul><p>
   *
   * @deprecated Since 2.6. Use {@link org.apache.kafka.clients.admin.DescribeLogDirsResult.LogDirInfo} instead.
   */
  @Deprecated
  static public class LogDirInfo {
    public final Errors error;

    /**
     * @deprecated Since 2.6. Use {@link LogDirInfo#tpToReplicaInfos} instead.
     */
    @Deprecated
    public final Map<TopicPartition, ReplicaInfo> replicaInfos;

    public final Map<TopicPartition, org.apache.kafka.clients.admin.DescribeLogDirsResult.ReplicaInfo> tpToReplicaInfos;
    ...
  }

  /**
   * State of a replica.
   *
   * @deprecated Since 2.6. Use {@link org.apache.kafka.clients.admin.DescribeLogDirsResult.ReplicaInfo} instead.
   **/
  @Deprecated
  static public class ReplicaInfo {
    ...
  }
}

The return type of DescribeLogDirsResult#[all, values] are not changed. Instead, they now return DescribeLogDirsResult.LogDirInfo instances instead of DescribeLogDirsResponse.LogDirInfo. The return type change is a future work.

Compatibility, Deprecation, and Migration Plan

Since the new classes inherit the older classes, there will be no code-breaking. Instead, the users will be informed to change the old code with deprecation warnings and Javadoc notes.

Test Plan

None.

Rejected Alternatives

None.