👋 Welcome back pminborg! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

@minborg The following label will be automatically applied to this pull request:

• core-libs

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

/csr

@minborg has indicated that a compatibility and specification (CSR) request is needed for this pull request.

@minborg please create a CSR request for issue JDK-8384062 with the correct fix version. This pull request cannot be integrated until the CSR request is approved.

Webrevs

• 00: Full (d5fa4ee4)

Mailing list message from Remi Forax on core-libs-dev:

Hello,
the problem with java.util.List (unlike say Runtime.Version or Optional#get) is that List is *both* used directly and implemented.

For users, it is clear that removeAtIndex() should be used.

For implementors of java.util.List, it is not clear how to guarantee that remove(index) and removeAtIndex() are always in sync,
especially because most of the named implementation of java.util.List can be inherited.

We do not want to be in a situation where remove(index) and removeAtIndex() have two different implementations.

So I think it's premature to create a PR until we discuss what can be done/should be done to solve that problem.

Should we changed the tooling (javac, IDEs?) so implementation drift are recognized and reported ?
Are there other solutions ?

regards,
Rémi

----- Original Message -----

From: "Per Minborg" <pminborg@openjdk.org>
To: "core-libs-dev" <core-libs-dev@openjdk.org>
Sent: Thursday, May 7, 2026 10:19:39 AM
Subject: RFR: 8384062: Add a new method List::removeAtIndex to avoid overload confusion

For implementors of java.util.List, it is not clear how to guarantee that remove(index) and removeAtIndex() are always in sync, especially because most of the named implementation of java.util.List can be inherited. We do not want to be in a situation where remove(index) and removeAtIndex() have two different implementations.

I don't think it's possible or necessary to try to establish any such guarantee. There are many constraints that List subclasses must uphold that the language and API cannot guarantee.

We could provide some documentation for subclassers so that they don't make mistakes, e.g.,

API Note:

The removeAtIndex method is a synonym for remove(int). They have exactly the same semantics.
Given that the default implementation of removeAtIndex simply calls remove(int), it is usually unnecessary
for subclasses to override the removeAtIndex method.

I sympathize with this change: remove is a textbook example of "bad overloading".

I also definitely sympathize with Remi's concern: we have two identically-behaving methods where one is the most correct one to invoke while the other is the most correct one to override. That's not ideal! We'd be happy if API-clients pretty much forgot remove(int) existed, but when they go to extend AbstractList we want them to suddenly remember.

I don't think there's a fix for this (barring extremely weird ideas). We can do it anyway, but I think that adding this API would have been a "no-brainer" otherwise, and I'm not sure it's totally a "no-brainer" now.

Naming:

• Existing "at-index" methods tend to just end with "-At" (like String.charAt()). (I personally like ends-with-preposition naming, at least for single-arg methods like this.)

• In fact, j.u.Vector names this very same method removeElementAt, but that seems unnecessarily wordy. The fact that j.u.Vector will end up with three methods that do the same thing might be sad if anyone really cared about j.u.Vector anymore.

Existing "at-index" methods tend to just end with "-At" (like String.charAt()). (I personally like ends-with-preposition naming, at least for single-arg methods like this.)

In many ways this would be preferable, but I think @minborg did some searching and found that it would result in a bunch of conflicts.

In fact, j.u.Vector names this very same method removeElementAt, but that seems unnecessarily wordy. The fact that j.u.Vector will end up with three methods that do the same thing might be sad if anyone really cared about j.u.Vector anymore.

Yeah. On the one hand, if we wanted to minimize the overall number of methods in the system, then using removeElementAt would do that; it would accept j.u.Vector as setting a precedent here. Unfortunately it would be a bad precedent as the collections framework (JDK 1.2) deliberately broke with some of the precedents set by the legacy collections from JDK 1.0 such as Vector and Hashtable. In particular, using element in the names of the Vector methods was not carried over into the Collections interfaces. We don't want to start doing that now, 28 years later.

There are a couple of other methods in List that already use "index" such as indexOf, lastIndexOf, so at least this doesn't introduce an entirely new term. But yes, removeAtIndex is a compromise.

I'll admit I'm a bit ambivalent about adding this (not that it is in any way my decision), and being forced to use the name removeAtIndex makes it worse for me, because then we're polluting precedent. Per, how bad would the damage really be from using the good name?