Revisiting JDK-4512189: ZipConstants leaking into public APIs

[Eirik Bjørsnøs]

On Tue, Nov 28, 2023 at 6:16 PM Alan Bateman <Alan.Bateman at oracle.com>
wrote:

> > In light of this, I would like to revisit this issue, 22 years later:
> [...]
>


> This is a JDK 1.1 era mistake. It would a source incompatible change to
> "remove" the constants. It would require corpus searches to gauge the
> impact. I think the question is whether it's worth the disruption, is
> your motivation to cleanup this area or something stronger?
>

Alan, Lance

Yes, removing anything always incurs a cost. There is the cost for the
OpenJDK team to assess, plan, implement and communicate the change. This is
a fixed, one time, implementation and review cost for a few of us to take
on.

Then there is also a cost paid by any project recompiling source files
referencing these constants and discovering that they have been removed.
Each such project will experience a fixed, one time cost to replace
references with their own constants. This replacement should be relatively
straightforward, given that values are readily available in Java API docs
[1]. A corpus search may help us assess the magnitude of this cost. We can
reduce (or at least ease) this cost by deprecating the constants for a few
releases first, giving projects more time to detect and react to a
forthcoming removal.

But keeping this "peculiarity" afloat does not come for free either. This
cost is perhaps harder to assess, because it is a small cost potentially
affecting many people. There are millions of Java developers out there. A
good chunk of them will through their career eventually need to study the
APIs of ZipFile, ZipEntry, ZipInputStream or ZipOutputStream, either by
reading Javadocs, or by using code completion in their IDE. Most of them
will stumble upon these constants. Some will simply scroll past them,
finding what they looked for. Others will stop, wonder how these constants
are supposed to be used, what part of the API allows them to be used. Most
will soon think "it's probably there for a reason", and continue their
work. But some will be curious, search for an explanation, ask on forums,
study the source code, perhaps stumble upon JDK-4512189.

It's hard to say whether the cumulative cost over years of all these small
distractions is larger than the fixed, one-time cost of the removal. My gut
feeling says yes.

In any case, could it perhaps be worth at least deprecating these
constants? This would signal to API readers that they were a mistake and
should not be given focus. And it would give a compile warning to projects
accidentally referencing the constants.

Then we can spend a few releases deciding whether a removal is warranted.

Eirik.

[1]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20231128/dc59179b/attachment-0001.htm>