787 /**
788 * Replaces the entry for the specified key only if currently
789 * mapped to the specified value.
790 *
791 * <p>The default implementation makes no guarantees about synchronization
792 * or atomicity properties of this method. Any implementation providing
793 * atomicity guarantees must override this method and document its
794 * concurrency properties.
795 *
796 * @implSpec
797 * The default implementation is equivalent to, for this {@code map}:
798 *
799 * <pre> {@code
800 * if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
801 * map.put(key, newValue);
802 * return true;
803 * } else
804 * return false;
805 * }</pre>
806 *
807 * @param key key with which the specified value is associated
808 * @param oldValue value expected to be associated with the specified key
809 * @param newValue value to be associated with the specified key
810 * @return {@code true} if the value was replaced
811 * @throws UnsupportedOperationException if the {@code put} operation
812 * is not supported by this map
813 * (<a href="Collection.html#optional-restrictions">optional</a>)
814 * @throws ClassCastException if the class of a specified key or value
815 * prevents it from being stored in this map
816 * @throws NullPointerException if a specified key or value is null,
817 * and this map does not permit null keys or values
818 * @throws IllegalArgumentException if some property of a specified key
819 * or value prevents it from being stored in this map
820 * @since 1.8
821 */
822 default boolean replace(K key, V oldValue, V newValue) {
823 Object curValue = get(key);
824 if (!Objects.equals(curValue, oldValue) ||
825 (curValue == null && !containsKey(key))) {
826 return false;
827 }
828 put(key, newValue);
829 return true;
830 }
831
832 /**
833 * Replaces the entry for the specified key only if it is
834 * currently mapped to some value.
835 *
836 * <p>The default implementation makes no guarantees about synchronization
837 * or atomicity properties of this method. Any implementation providing
|
787 /**
788 * Replaces the entry for the specified key only if currently
789 * mapped to the specified value.
790 *
791 * <p>The default implementation makes no guarantees about synchronization
792 * or atomicity properties of this method. Any implementation providing
793 * atomicity guarantees must override this method and document its
794 * concurrency properties.
795 *
796 * @implSpec
797 * The default implementation is equivalent to, for this {@code map}:
798 *
799 * <pre> {@code
800 * if (map.containsKey(key) && Objects.equals(map.get(key), value)) {
801 * map.put(key, newValue);
802 * return true;
803 * } else
804 * return false;
805 * }</pre>
806 *
807 * @implNote The default implementation does not throw NullPointerException
808 * for maps that do not support null values if oldValue is null unless
809 * newValue is also null.
810 *
811 * @param key key with which the specified value is associated
812 * @param oldValue value expected to be associated with the specified key
813 * @param newValue value to be associated with the specified key
814 * @return {@code true} if the value was replaced
815 * @throws UnsupportedOperationException if the {@code put} operation
816 * is not supported by this map
817 * (<a href="Collection.html#optional-restrictions">optional</a>)
818 * @throws ClassCastException if the class of a specified key or value
819 * prevents it from being stored in this map
820 * @throws NullPointerException if a specified key or newValue is null,
821 * and this map does not permit null keys or values
822 * @throws NullPointerException if oldValue is null and this map does not
823 * permit null values
824 * (<a href="Collection.html#optional-restrictions">optional</a>)
825 * @throws IllegalArgumentException if some property of a specified key
826 * or value prevents it from being stored in this map
827 * @since 1.8
828 */
829 default boolean replace(K key, V oldValue, V newValue) {
830 Object curValue = get(key);
831 if (!Objects.equals(curValue, oldValue) ||
832 (curValue == null && !containsKey(key))) {
833 return false;
834 }
835 put(key, newValue);
836 return true;
837 }
838
839 /**
840 * Replaces the entry for the specified key only if it is
841 * currently mapped to some value.
842 *
843 * <p>The default implementation makes no guarantees about synchronization
844 * or atomicity properties of this method. Any implementation providing
|