Date: Wed, 07 Jan 2004 12:29:52 +0100
From: <###@###.###>
Subject: JDK1.5 documentation issue
To: ###@###.###

Type:                   Bug
Product/Category:       Java2 JRE / SDK 1.5
Subcategory:            JDK/JRE documentation, API, tutorial (bug)
Release:                1.5.0-beta-b31
Operating System:       Generic / Other

The 'boolean remove(Object key, Object value)' method of the
'java.util.concurrent.ConcurrentMap' interface states that the given
method acts as the given example code (except for the that action is
performed atomically).

However, the API is not clear about the result if the given key is not
located in the map. The example code that a 'NullPointerException' will
be thrown and the @return doc doesn't mention negative results.

I'm aware that an extra null check in the example code would still not
be sufficient, since Map implementations potentially can contain null
elements.

I would like to recommend the following example code:

if (map.containsKey(key) && map.get(key).equals(value)) {
	map.remove(key);
	return true;
} else return false;


And for clarity:

@return	true if the value was removed, false otherwise