API Deprecated/Removal Process

[Stuart Marks]

On 5/12/21 8:43 PM, Eric Bresie wrote:
> I know the benefits of API / implementation removal accommodates change and efficiency to the platform, which I welcome however the more removals that happen, the more risk this will break existing application code, the risk of additional cost for updating existing developed products (which not everyone may have the budget to do so given much is spent on updating own products and priorities without having to introduce changes like this, which prior to pruning of API was less a concern with Java), and just plain risks leaving a bad taste in developer and user’s mouth which could drive people away, which no one wants. So with that said...
> 
> What is the process when dealing with deprecated and removed API? Or more specifically use case of alternative implementations?

We try to remove only things that are old and obsolete and that have very little 
usage (e.g., RMI Activation) or things that have little usage but are very expensive 
to maintain (e.g., Security Manager). There's certainly a risk of breaking projects 
that use these things, and there are undoubtedly costs imposed on such projects.

You also have to account for the cost of having these things in OpenJDK. Costs are 
imposed not only on the maintainers of OpenJDK but also all of its users. Software 
doesn't just sit there passively; it requires active maintenance and effort to keep 
running. These costs aren't always visible.

I'll take RMI Activation as an example since it's something that I've worked on. 
Since RMI Activation involves multiple processes and networking, you shouldn't be 
surprised to learn that the tests for it are fragile. In a CI environment, there are 
lots of intermittent failures. Over the years I've put some effort into fixing some 
of these tests to be more robust. Fixing the tests requires effort, but assessing 
intermittent failures is also an effort, so either way there are costs.

It turns out that the JDK 8-update project is also interested in improving test 
reliablity, so they're backporting some of these test fixes:

https://mail.openjdk.java.net/pipermail/jdk8u-dev/2021-April/013761.html

I'm a bit surprised, but then again, maybe I shouldn't be. The costs of intermittent 
failures are larger than one might think, so it justified the effort of fixing the 
tests and even backporting those test fixes.

There are also costs on users, but they're more indirect. Users might ask, "Why 
can't you add feature X?" Part of the answer might be, "Feature X seems useful, but 
we haven't yet figured out how to make it work with the security manager." Or 
sometimes it's pure opportunity cost. For example, I might have wanted to get 
feature Y into this release, but I didn't have time because I was fixing security 
vulnerabilities in RMI Activation. Thus, feature Y got pushed to the next release, 
or it got dropped altogether.

When these costs get out of balance with the value a feature is providing, then we 
consider removing it.

> I understand depreciation/removal details are usually document in applicable API content and JEP 277 Enhanced Deprecation (https://openjdk.java.net/jeps/277) provides rational and how to annotate things and denotes the need to utilize new interface if available or to use alternative implementation.
> 
> So define aspects of handoff activities to include potential donation of deprecated/removed code, forking to the alternative, address licensing concerns, how to handle name-spacing concerns (i.e. is the old namespace available or does new namespace needed), and documenting alternatives (i.e. tracking alternatives via wiki, doc, javadoc/api, etc).
> 
> Or could some form of dependency injection be used to specify alternatives to ease the transition?

I'm not entirely sure what you're asking here. If OpenJDK removes some feature, and 
some project depends on that feature, then that project has to deal with it somehow. 
There's not much that OpenJDK can do about this, because the range of possible 
actions a project can take is too broad.

A project might decide to stay on JDK 11 indefinitely. It will have a long service 
lifetime, so that might be sufficient for some projects. Even after its support 
lifetime ends, a project can move to a self-support model. Of course, this incurs 
greater costs and risks. At some point they will outweigh the cost of migrating to a 
newer JDK or even rewriting the project, so one of those will get done. Or perhaps 
those costs outweigh the benefit the project is providing, which means the project 
is just abandoned.

Some of the stuff that's been removed has an easy technical solution, like JAXB, 
which has always been available as a separate jar. Other things, like the security 
manager, are too pervasive to be packaged separately. In that case, something 
depending on the security manager will need to be rethought.

Undoubtedly these changes will cause somebody somewhere some pain. But our primary 
task here is to look after the whole project, on behalf of all the maintainers and 
consumers, and try to balance things out.

s'marks