< prev index next >
src/java.base/share/classes/java/util/AbstractMap.java
Print this page
*** 25,52 ****
package java.util;
import java.util.Map.Entry;
/**
! * This class provides a skeletal implementation of the <tt>Map</tt>
* interface, to minimize the effort required to implement this interface.
*
* <p>To implement an unmodifiable map, the programmer needs only to extend this
! * class and provide an implementation for the <tt>entrySet</tt> method, which
* returns a set-view of the map's mappings. Typically, the returned set
! * will, in turn, be implemented atop <tt>AbstractSet</tt>. This set should
! * not support the <tt>add</tt> or <tt>remove</tt> methods, and its iterator
! * should not support the <tt>remove</tt> method.
*
* <p>To implement a modifiable map, the programmer must additionally override
! * this class's <tt>put</tt> method (which otherwise throws an
! * <tt>UnsupportedOperationException</tt>), and the iterator returned by
! * <tt>entrySet().iterator()</tt> must additionally implement its
! * <tt>remove</tt> method.
*
* <p>The programmer should generally provide a void (no argument) and map
! * constructor, as per the recommendation in the <tt>Map</tt> interface
* specification.
*
* <p>The documentation for each non-abstract method in this class describes its
* implementation in detail. Each of these methods may be overridden if the
* map being implemented admits a more efficient implementation.
--- 25,52 ----
package java.util;
import java.util.Map.Entry;
/**
! * This class provides a skeletal implementation of the {@code Map}
* interface, to minimize the effort required to implement this interface.
*
* <p>To implement an unmodifiable map, the programmer needs only to extend this
! * class and provide an implementation for the {@code entrySet} method, which
* returns a set-view of the map's mappings. Typically, the returned set
! * will, in turn, be implemented atop {@code AbstractSet}. This set should
! * not support the {@code add} or {@code remove} methods, and its iterator
! * should not support the {@code remove} method.
*
* <p>To implement a modifiable map, the programmer must additionally override
! * this class's {@code put} method (which otherwise throws an
! * {@code UnsupportedOperationException}), and the iterator returned by
! * {@code entrySet().iterator()} must additionally implement its
! * {@code remove} method.
*
* <p>The programmer should generally provide a void (no argument) and map
! * constructor, as per the recommendation in the {@code Map} interface
* specification.
*
* <p>The documentation for each non-abstract method in this class describes its
* implementation in detail. Each of these methods may be overridden if the
* map being implemented admits a more efficient implementation.
*** 77,110 ****
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation returns <tt>entrySet().size()</tt>.
*/
public int size() {
return entrySet().size();
}
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation returns <tt>size() == 0</tt>.
*/
public boolean isEmpty() {
return size() == 0;
}
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over <tt>entrySet()</tt> searching
* for an entry with the specified value. If such an entry is found,
! * <tt>true</tt> is returned. If the iteration terminates without
! * finding such an entry, <tt>false</tt> is returned. Note that this
* implementation requires linear time in the size of the map.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*/
--- 77,110 ----
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation returns {@code entrySet().size()}.
*/
public int size() {
return entrySet().size();
}
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation returns {@code size() == 0}.
*/
public boolean isEmpty() {
return size() == 0;
}
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over {@code entrySet()} searching
* for an entry with the specified value. If such an entry is found,
! * {@code true} is returned. If the iteration terminates without
! * finding such an entry, {@code false} is returned. Note that this
* implementation requires linear time in the size of the map.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*/
*** 128,141 ****
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over <tt>entrySet()</tt> searching
* for an entry with the specified key. If such an entry is found,
! * <tt>true</tt> is returned. If the iteration terminates without
! * finding such an entry, <tt>false</tt> is returned. Note that this
* implementation requires linear time in the size of the map; many
* implementations will override this method.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
--- 128,141 ----
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over {@code entrySet()} searching
* for an entry with the specified key. If such an entry is found,
! * {@code true} is returned. If the iteration terminates without
! * finding such an entry, {@code false} is returned. Note that this
* implementation requires linear time in the size of the map; many
* implementations will override this method.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*** 160,173 ****
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over <tt>entrySet()</tt> searching
* for an entry with the specified key. If such an entry is found,
* the entry's value is returned. If the iteration terminates without
! * finding such an entry, <tt>null</tt> is returned. Note that this
* implementation requires linear time in the size of the map; many
* implementations will override this method.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
--- 160,173 ----
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over {@code entrySet()} searching
* for an entry with the specified key. If such an entry is found,
* the entry's value is returned. If the iteration terminates without
! * finding such an entry, {@code null} is returned. Note that this
* implementation requires linear time in the size of the map; many
* implementations will override this method.
*
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*** 196,206 ****
/**
* {@inheritDoc}
*
* @implSpec
* This implementation always throws an
! * <tt>UnsupportedOperationException</tt>.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
--- 196,206 ----
/**
* {@inheritDoc}
*
* @implSpec
* This implementation always throws an
! * {@code UnsupportedOperationException}.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
*** 211,232 ****
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over <tt>entrySet()</tt> searching for an
* entry with the specified key. If such an entry is found, its value is
! * obtained with its <tt>getValue</tt> operation, the entry is removed
* from the collection (and the backing map) with the iterator's
! * <tt>remove</tt> operation, and the saved value is returned. If the
! * iteration terminates without finding such an entry, <tt>null</tt> is
* returned. Note that this implementation requires linear time in the
* size of the map; many implementations will override this method.
*
* <p>Note that this implementation throws an
! * <tt>UnsupportedOperationException</tt> if the <tt>entrySet</tt>
! * iterator does not support the <tt>remove</tt> method and this map
* contains a mapping for the specified key.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
--- 211,232 ----
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation iterates over {@code entrySet()} searching for an
* entry with the specified key. If such an entry is found, its value is
! * obtained with its {@code getValue} operation, the entry is removed
* from the collection (and the backing map) with the iterator's
! * {@code remove} operation, and the saved value is returned. If the
! * iteration terminates without finding such an entry, {@code null} is
* returned. Note that this implementation requires linear time in the
* size of the map; many implementations will override this method.
*
* <p>Note that this implementation throws an
! * {@code UnsupportedOperationException} if the {@code entrySet}
! * iterator does not support the {@code remove} method and this map
* contains a mapping for the specified key.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
*** 262,277 ****
/**
* {@inheritDoc}
*
* @implSpec
* This implementation iterates over the specified map's
! * <tt>entrySet()</tt> collection, and calls this map's <tt>put</tt>
* operation once for each entry returned by the iteration.
*
* <p>Note that this implementation throws an
! * <tt>UnsupportedOperationException</tt> if this map does not support
! * the <tt>put</tt> operation and the specified map is nonempty.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
--- 262,277 ----
/**
* {@inheritDoc}
*
* @implSpec
* This implementation iterates over the specified map's
! * {@code entrySet()} collection, and calls this map's {@code put}
* operation once for each entry returned by the iteration.
*
* <p>Note that this implementation throws an
! * {@code UnsupportedOperationException} if this map does not support
! * the {@code put} operation and the specified map is nonempty.
*
* @throws UnsupportedOperationException {@inheritDoc}
* @throws ClassCastException {@inheritDoc}
* @throws NullPointerException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
*** 283,297 ****
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation calls <tt>entrySet().clear()</tt>.
*
* <p>Note that this implementation throws an
! * <tt>UnsupportedOperationException</tt> if the <tt>entrySet</tt>
! * does not support the <tt>clear</tt> operation.
*
* @throws UnsupportedOperationException {@inheritDoc}
*/
public void clear() {
entrySet().clear();
--- 283,297 ----
/**
* {@inheritDoc}
*
* @implSpec
! * This implementation calls {@code entrySet().clear()}.
*
* <p>Note that this implementation throws an
! * {@code UnsupportedOperationException} if the {@code entrySet}
! * does not support the {@code clear} operation.
*
* @throws UnsupportedOperationException {@inheritDoc}
*/
public void clear() {
entrySet().clear();
*** 312,325 ****
* {@inheritDoc}
*
* @implSpec
* This implementation returns a set that subclasses {@link AbstractSet}.
* The subclass's iterator method returns a "wrapper object" over this
! * map's <tt>entrySet()</tt> iterator. The <tt>size</tt> method
! * delegates to this map's <tt>size</tt> method and the
! * <tt>contains</tt> method delegates to this map's
! * <tt>containsKey</tt> method.
*
* <p>The set is created the first time this method is called,
* and returned in response to all subsequent calls. No synchronization
* is performed, so there is a slight chance that multiple calls to this
* method will not all return the same set.
--- 312,325 ----
* {@inheritDoc}
*
* @implSpec
* This implementation returns a set that subclasses {@link AbstractSet}.
* The subclass's iterator method returns a "wrapper object" over this
! * map's {@code entrySet()} iterator. The {@code size} method
! * delegates to this map's {@code size} method and the
! * {@code contains} method delegates to this map's
! * {@code containsKey} method.
*
* <p>The set is created the first time this method is called,
* and returned in response to all subsequent calls. No synchronization
* is performed, so there is a slight chance that multiple calls to this
* method will not all return the same set.
*** 369,382 ****
* {@inheritDoc}
*
* @implSpec
* This implementation returns a collection that subclasses {@link
* AbstractCollection}. The subclass's iterator method returns a
! * "wrapper object" over this map's <tt>entrySet()</tt> iterator.
! * The <tt>size</tt> method delegates to this map's <tt>size</tt>
! * method and the <tt>contains</tt> method delegates to this map's
! * <tt>containsValue</tt> method.
*
* <p>The collection is created the first time this method is called, and
* returned in response to all subsequent calls. No synchronization is
* performed, so there is a slight chance that multiple calls to this
* method will not all return the same collection.
--- 369,382 ----
* {@inheritDoc}
*
* @implSpec
* This implementation returns a collection that subclasses {@link
* AbstractCollection}. The subclass's iterator method returns a
! * "wrapper object" over this map's {@code entrySet()} iterator.
! * The {@code size} method delegates to this map's {@code size}
! * method and the {@code contains} method delegates to this map's
! * {@code containsValue} method.
*
* <p>The collection is created the first time this method is called, and
* returned in response to all subsequent calls. No synchronization is
* performed, so there is a slight chance that multiple calls to this
* method will not all return the same collection.
*** 427,455 ****
// Comparison and hashing
/**
* Compares the specified object with this map for equality. Returns
! * <tt>true</tt> if the given object is also a map and the two maps
! * represent the same mappings. More formally, two maps <tt>m1</tt> and
! * <tt>m2</tt> represent the same mappings if
! * <tt>m1.entrySet().equals(m2.entrySet())</tt>. This ensures that the
! * <tt>equals</tt> method works properly across different implementations
! * of the <tt>Map</tt> interface.
*
* @implSpec
* This implementation first checks if the specified object is this map;
! * if so it returns <tt>true</tt>. Then, it checks if the specified
* object is a map whose size is identical to the size of this map; if
! * not, it returns <tt>false</tt>. If so, it iterates over this map's
! * <tt>entrySet</tt> collection, and checks that the specified map
* contains each mapping that this map contains. If the specified map
! * fails to contain such a mapping, <tt>false</tt> is returned. If the
! * iteration completes, <tt>true</tt> is returned.
*
* @param o object to be compared for equality with this map
! * @return <tt>true</tt> if the specified object is equal to this map
*/
public boolean equals(Object o) {
if (o == this)
return true;
--- 427,455 ----
// Comparison and hashing
/**
* Compares the specified object with this map for equality. Returns
! * {@code true} if the given object is also a map and the two maps
! * represent the same mappings. More formally, two maps {@code m1} and
! * {@code m2} represent the same mappings if
! * {@code m1.entrySet().equals(m2.entrySet())}. This ensures that the
! * {@code equals} method works properly across different implementations
! * of the {@code Map} interface.
*
* @implSpec
* This implementation first checks if the specified object is this map;
! * if so it returns {@code true}. Then, it checks if the specified
* object is a map whose size is identical to the size of this map; if
! * not, it returns {@code false}. If so, it iterates over this map's
! * {@code entrySet} collection, and checks that the specified map
* contains each mapping that this map contains. If the specified map
! * fails to contain such a mapping, {@code false} is returned. If the
! * iteration completes, {@code true} is returned.
*
* @param o object to be compared for equality with this map
! * @return {@code true} if the specified object is equal to this map
*/
public boolean equals(Object o) {
if (o == this)
return true;
*** 481,497 ****
}
/**
* Returns the hash code value for this map. The hash code of a map is
* defined to be the sum of the hash codes of each entry in the map's
! * <tt>entrySet()</tt> view. This ensures that <tt>m1.equals(m2)</tt>
! * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two maps
! * <tt>m1</tt> and <tt>m2</tt>, as required by the general contract of
* {@link Object#hashCode}.
*
* @implSpec
! * This implementation iterates over <tt>entrySet()</tt>, calling
* {@link Map.Entry#hashCode hashCode()} on each element (entry) in the
* set, and adding up the results.
*
* @return the hash code value for this map
* @see Map.Entry#hashCode()
--- 481,497 ----
}
/**
* Returns the hash code value for this map. The hash code of a map is
* defined to be the sum of the hash codes of each entry in the map's
! * {@code entrySet()} view. This ensures that {@code m1.equals(m2)}
! * implies that {@code m1.hashCode()==m2.hashCode()} for any two maps
! * {@code m1} and {@code m2}, as required by the general contract of
* {@link Object#hashCode}.
*
* @implSpec
! * This implementation iterates over {@code entrySet()}, calling
* {@link Map.Entry#hashCode hashCode()} on each element (entry) in the
* set, and adding up the results.
*
* @return the hash code value for this map
* @see Map.Entry#hashCode()
*** 506,519 ****
}
/**
* Returns a string representation of this map. The string representation
* consists of a list of key-value mappings in the order returned by the
! * map's <tt>entrySet</tt> view's iterator, enclosed in braces
! * (<tt>"{}"</tt>). Adjacent mappings are separated by the characters
! * <tt>", "</tt> (comma and space). Each key-value mapping is rendered as
! * the key followed by an equals sign (<tt>"="</tt>) followed by the
* associated value. Keys and values are converted to strings as by
* {@link String#valueOf(Object)}.
*
* @return a string representation of this map
*/
--- 506,519 ----
}
/**
* Returns a string representation of this map. The string representation
* consists of a list of key-value mappings in the order returned by the
! * map's {@code entrySet} view's iterator, enclosed in braces
! * ({@code "{}"}). Adjacent mappings are separated by the characters
! * {@code ", "} (comma and space). Each key-value mapping is rendered as
! * the key followed by an equals sign ({@code "="}) followed by the
* associated value. Keys and values are converted to strings as by
* {@link String#valueOf(Object)}.
*
* @return a string representation of this map
*/
*** 536,546 ****
sb.append(',').append(' ');
}
}
/**
! * Returns a shallow copy of this <tt>AbstractMap</tt> instance: the keys
* and values themselves are not cloned.
*
* @return a shallow copy of this map
*/
protected Object clone() throws CloneNotSupportedException {
--- 536,546 ----
sb.append(',').append(' ');
}
}
/**
! * Returns a shallow copy of this {@code AbstractMap} instance: the keys
* and values themselves are not cloned.
*
* @return a shallow copy of this map
*/
protected Object clone() throws CloneNotSupportedException {
*** 568,582 ****
// exposing a common abstract class.
/**
* An Entry maintaining a key and a value. The value may be
! * changed using the <tt>setValue</tt> method. This class
* facilitates the process of building custom map
* implementations. For example, it may be convenient to return
! * arrays of <tt>SimpleEntry</tt> instances in method
! * <tt>Map.entrySet().toArray</tt>.
*
* @since 1.6
*/
public static class SimpleEntry<K,V>
implements Entry<K,V>, java.io.Serializable
--- 568,582 ----
// exposing a common abstract class.
/**
* An Entry maintaining a key and a value. The value may be
! * changed using the {@code setValue} method. This class
* facilitates the process of building custom map
* implementations. For example, it may be convenient to return
! * arrays of {@code SimpleEntry} instances in method
! * {@code Map.entrySet().toArray}.
*
* @since 1.6
*/
public static class SimpleEntry<K,V>
implements Entry<K,V>, java.io.Serializable
*** 687,697 ****
}
/**
* Returns a String representation of this map entry. This
* implementation returns the string representation of this
! * entry's key followed by the equals character ("<tt>=</tt>")
* followed by the string representation of this entry's value.
*
* @return a String representation of this map entry
*/
public String toString() {
--- 687,697 ----
}
/**
* Returns a String representation of this map entry. This
* implementation returns the string representation of this
! * entry's key followed by the equals character ("{@code =}")
* followed by the string representation of this entry's value.
*
* @return a String representation of this map entry
*/
public String toString() {
*** 700,710 ****
}
/**
* An Entry maintaining an immutable key and value. This class
! * does not support method <tt>setValue</tt>. This class may be
* convenient in methods that return thread-safe snapshots of
* key-value mappings.
*
* @since 1.6
*/
--- 700,710 ----
}
/**
* An Entry maintaining an immutable key and value. This class
! * does not support method {@code setValue}. This class may be
* convenient in methods that return thread-safe snapshots of
* key-value mappings.
*
* @since 1.6
*/
*** 758,768 ****
}
/**
* Replaces the value corresponding to this entry with the specified
* value (optional operation). This implementation simply throws
! * <tt>UnsupportedOperationException</tt>, as this class implements
* an <i>immutable</i> map entry.
*
* @param value new value to be stored in this entry
* @return (Does not return)
* @throws UnsupportedOperationException always
--- 758,768 ----
}
/**
* Replaces the value corresponding to this entry with the specified
* value (optional operation). This implementation simply throws
! * {@code UnsupportedOperationException}, as this class implements
* an <i>immutable</i> map entry.
*
* @param value new value to be stored in this entry
* @return (Does not return)
* @throws UnsupportedOperationException always
*** 818,828 ****
}
/**
* Returns a String representation of this map entry. This
* implementation returns the string representation of this
! * entry's key followed by the equals character ("<tt>=</tt>")
* followed by the string representation of this entry's value.
*
* @return a String representation of this map entry
*/
public String toString() {
--- 818,828 ----
}
/**
* Returns a String representation of this map entry. This
* implementation returns the string representation of this
! * entry's key followed by the equals character ("{@code =}")
* followed by the string representation of this entry's value.
*
* @return a String representation of this map entry
*/
public String toString() {
< prev index next >