Summary

Clarify several conflicting statements about the connection between a Map.Entry object and the map from which it was obtained.

Problem

Various pieces of the specification conflict over the exact behavior of the connection between a Map.Entry object and the map from which it was obtained. There are statements about how a Map.Entry obtained via iteration is connected to the underlying map, and that calls to Map.Entry.setValue() will modify the underlying map. However, TreeMap states that Map.Entry instances it provides are snapshots and aren't connected to the underlying map. These are confusing and apparently contradictory.

Solution

Clarify the specifications in Map.Entry, NavigableMap, and TreeMap.

The core guarantee is that a Map.Entry obtained by and used during iteration of the map's entrySet has at least a one-way connection to the underlying map, in that calling Map.Entry.setValue() will modify the underlying map (if that map permits it). A connection in the opposite direction is unspecified; the behavior of such entries outside of iteration is also unspecified. (In fact, different map implementations such as HashMap and ConcurrentHashMap do differ in this regard.)

Also add clauses specifying that generally, a Map.Entry obtained through a direct method call (as opposed to iterating the entrySet) is a snapshot and thus maintains no connection to the underlying map.

Specification

See attached specdiff.