src/share/classes/java/util/Map.java

rev 7682 : 8021591: Additional explicit null checks
Reviewed-by: duke

*** 802,822 ****
       *     return true;
       * } else
       *     return false;
       * }</pre>
       *
       * @param key key with which the specified value is associated
       * @param oldValue value expected to be associated with the specified key
       * @param newValue value to be associated with the specified key
       * @return {@code true} if the value was replaced
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
       *         (<a href="Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of a specified key or value
       *         prevents it from being stored in this map
!      * @throws NullPointerException if a specified key or value is null,
       *         and this map does not permit null keys or values
       * @throws IllegalArgumentException if some property of a specified key
       *         or value prevents it from being stored in this map
       * @since 1.8
       */
      default boolean replace(K key, V oldValue, V newValue) {
--- 802,829 ----
       *     return true;
       * } else
       *     return false;
       * }</pre>
       *
+      * @implNote The default implementation does not throw NullPointerException
+      * for maps that do not support null values if oldValue is null unless
+      * newValue is also null.
+      *
       * @param key key with which the specified value is associated
       * @param oldValue value expected to be associated with the specified key
       * @param newValue value to be associated with the specified key
       * @return {@code true} if the value was replaced
       * @throws UnsupportedOperationException if the {@code put} operation
       *         is not supported by this map
       *         (<a href="Collection.html#optional-restrictions">optional</a>)
       * @throws ClassCastException if the class of a specified key or value
       *         prevents it from being stored in this map
!      * @throws NullPointerException if a specified key or newValue is null,
       *         and this map does not permit null keys or values
+      * @throws NullPointerException if oldValue is null and this map does not
+      *         permit null values
+      *         (<a href="Collection.html#optional-restrictions">optional</a>)
       * @throws IllegalArgumentException if some property of a specified key
       *         or value prevents it from being stored in this map
       * @since 1.8
       */
      default boolean replace(K key, V oldValue, V newValue) {