Summary

Add an idempotent copy operation for Map.Entry, and clarify some confusing and anachronistic specification wording for Map.Entry.

Problem

1. 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.

2. AbstractMap.SimpleImmutableEntry claims it's immutable, but it isn't really. It can be subclassed, and its key or value might be mutable.

3. 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.

Solution

1. Add a new method Map.Entry::copyOf that copies an Entry instance, but avoids making a copy of a copy.

2. Clarify the immutability/unmodifiability of AbstractMap.SimpleImmutableEntry.

3. 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.

Specification

See specdiff.mapentry-v1.zip attached.