RFR: 8029055: Map.merge must refuse null values

[Doug Lea]

On 12/06/2013 05:18 PM, Mike Duigou wrote:
> Hello all. I have updated the webrev
>
> http://cr.openjdk.java.net/~mduigou/JDK-8029055/2/webrev/
>

In light of all the churn on merge and related methods, I did
an editorial pass on jsr166 version of ConcurrentMap. I added
a couple of paragraphs at top-level trying to clue users in
about the issues. And then removed some now-unneeded wording
in some of the per-method specs.
Could you integrate into this webrev?
(http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/main/java/util/concurrent/ConcurrentMap.java?view=log)

Here's the top-level addition:

  * <p>To support atomic usages, ConcurrentMaps are expected not to
  * allow {@code null} as a legal value (and to throw exceptions upon
  * attempted insertions). This enables a return value of {@code null}
  * to unambiguously indicate the absence of a mapping. This interface
  * does not strictly forbid implementations that may hold {@code null}
  * values. However, in any that do so, a {@code null} value must bear
  * the same interpretation as the absence of a mapping in order to
  * conform to method atomicity requirements.  Further, any that do so
  * must override all default method implementations.
  *
  * <p>Several methods (for example {@link #putIfAbsent}) inherited
  * from {@link Map} do not have default implementations, and so must
  * be provided by implementations of this interface, even though they
  * have (non-atomic) default implementations in the {@link Map}
  * interface.
  *

Maybe there is some way to adapt a weaker form of the first paragraph
in Map proper? (Replacing "atomic" with "reliable" :-) When worded
in the above way, the only sanctioned user-level difference
between a map allowing nulls vs one that doesn't is that the
former may have entries explicitly recording absent mappings
rather than omitting them. (Note that this means their size()'s
iterators, etc may differ.) It strikes me that this is the only
allowable difference given all of the Map method specs,
so it may be worth saying so explicitly.

-Doug