Fix Version/s: 17
Compatibility Risk Description:The only API modified is the addition of a static method to an interface, which is fairly safe.
Interface Kind:Java API
Add an idempotent copy operation for
Map.Entry, and clarify some confusing and anachronistic specification wording for
A Map.Entry can have a connection to a backing map, and it is sometimes necessary to copy it in order to break this connection. It's possible (though verbose) to make a copy, but there is no way to avoid making a copy if doing so is unnecessary; thus the need for an idempotent copy.
AbstractMap.SimpleImmutableEntry claims it's immutable, but it isn't really. It can be subclassed, and its key or value might be mutable.
The Map.Entry specs contain some historical wording about the only way to create a Map.Entry is via a map's entry-set view. This is false and needs to be fixed up.
Add a new method Map.Entry::copyOf that copies an Entry instance, but avoids making a copy of a copy.
Clarify the immutability/unmodifiability of AbstractMap.SimpleImmutableEntry.
Reword specifications to clarify that some Map.Entry instances maintain a collection to the backing map and also that some operations affect the backing map, but this is specified to work only for a limited time.
See specdiff.mapentry-v1.zip attached.