This page is meant as a template for writing a KIP. To create a KIP choose Tools->Copy on this page and modify with your content and replace the heading with the next KIP number and a description of your issue. Replace anything in italics with your own description.

Status

Current state: Under Discussion

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

JIRA: here

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

Motivation

Headers is a part of public APIs but the usage of Headers is a bit chaos to users.

  1. it has a lot of abstract setters so users have to implement all of them. However, we never call user-defined setters in production.
  2. it is not thread-safe so we have to call "setReadOnly" to make data consistency.
  3. "setReadOnly" is not a part of public API so users have no idea about the "thread-safe" of Headers

We can't improve Headers right now by reason of deprecation cycles. This KIP plans to deprecate and offer default implementation (java.lang.UnsupportedOperationException) to all setters of Headers so we can cleanup all setters to make it be readonly in next major and users are able to remove all useless implementation from their Headers in this patch.

Public Interfaces

The following methods of Headers are deprecated.

    @Deprecated
    default Headers add(Header header) throws IllegalStateException {
        throw new UnsupportedOperationException("this method is deprecated");
    }

    @Deprecated
    default Headers add(String key, byte[] value) throws IllegalStateException {
        throw new UnsupportedOperationException("this method is deprecated");
    }

    @Deprecated
    default Headers remove(String key) throws IllegalStateException {
        throw new UnsupportedOperationException("this method is deprecated");
    }


Proposed Changes

The following changes are added to Headers

  1. deprecated Headers#add(Header)
  2. add default implementation to Headers#add(Header)
  3. deprecated Headers#add(String, byte[])
  4. add default implementation to Headers#add(String, byte[])
  5. deprecated Headers#add(String)
  6. add default implementation to Headers#add(String)

Compatibility, Deprecation, and Migration Plan

C: No methods are removed so compatibility issue does not exist

D: There are three deprecated methods of Headers

MP: User-implemented Headers can remove the deprecated methods

Rejected Alternatives

n/a

  • No labels