--- jsr166/src/main/java/util/AbstractMap.java 2005/04/18 05:18:29 1.6 +++ jsr166/src/main/java/util/AbstractMap.java 2007/09/11 15:13:59 1.25 @@ -1,8 +1,26 @@ /* - * %W% %E% + * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * - * Copyright 2005 Sun Microsystems, Inc. All rights reserved. - * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Sun designates this + * particular file as subject to the "Classpath" exception as provided + * by Sun in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, + * CA 95054 USA or visit www.sun.com if you need additional information or + * have any questions. */ package java.util; @@ -10,33 +28,36 @@ import java.util.Map.Entry; /** * This class provides a skeletal implementation of the Map - * interface, to minimize the effort required to implement this interface.
+ * interface, to minimize the effort required to implement this interface. * - * To implement an unmodifiable map, the programmer needs only to extend this + *
To implement an unmodifiable map, the programmer needs only to extend this * class and provide an implementation for the entrySet method, which * returns a set-view of the map's mappings. Typically, the returned set * will, in turn, be implemented atop AbstractSet. This set should * not support the add or remove methods, and its iterator - * should not support the remove method.
+ * should not support the remove method. * - * To implement a modifiable map, the programmer must additionally override + *
To implement a modifiable map, the programmer must additionally override * this class's put method (which otherwise throws an * UnsupportedOperationException), and the iterator returned by * entrySet().iterator() must additionally implement its - * remove method.
+ * remove method. * - * The programmer should generally provide a void (no argument) and map + *
The programmer should generally provide a void (no argument) and map * constructor, as per the recommendation in the Map interface - * specification.
+ * specification. * - * The documentation for each non-abstract methods in this class describes its + *
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.
+ * map being implemented admits a more efficient implementation.
*
- * This class is a member of the
- *
+ * This class is a member of the
+ *
* Java Collections Framework.
*
+ * @param
+ * {@inheritDoc}
*
- * This implementation returns entrySet().size().
- *
- * @return the number of key-value mappings in this map.
+ * This implementation returns entrySet().size().
*/
public int size() {
return entrySet().size();
}
/**
- * Returns true if this map contains no key-value mappings.
- *
- * This implementation returns size() == 0.
+ * {@inheritDoc}
*
- * @return true if this map contains no key-value mappings.
+ * This implementation returns size() == 0.
*/
public boolean isEmpty() {
return size() == 0;
}
/**
- * Returns true if this map maps one or more keys to this value.
- * More formally, returns true if and only if this map contains
- * at least one mapping to a value v such that (value==null ?
- * v==null : value.equals(v)). This operation will probably require
- * time linear in the map size for most implementations of map.
- *
- * This implementation iterates over entrySet() searching for an entry
- * with the specified value. If such an entry is found, true is
- * returned. If the iteration terminates without finding such an entry,
- * false is returned. Note that this implementation requires
- * linear time in the size of the map.
- *
- * @param value value whose presence in this map is to be tested.
- *
- * @return true if this map maps one or more keys to this value.
+ * {@inheritDoc}
+ *
+ * This implementation iterates over entrySet() searching
+ * for an entry with the specified value. If such an entry is found,
+ * true is returned. If the iteration terminates without
+ * finding such an entry, false is returned. Note that this
+ * implementation requires linear time in the size of the map.
+ *
+ * @throws ClassCastException {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
*/
public boolean containsValue(Object value) {
Iterator
+ * {@inheritDoc}
+ *
+ * This implementation iterates over entrySet() searching
+ * for an entry with the specified key. If such an entry is found,
+ * true is returned. If the iteration terminates without
+ * finding such an entry, false is returned. Note that this
+ * implementation requires linear time in the size of the map; many
+ * implementations will override this method.
*
- * This implementation iterates over entrySet() searching for an
- * entry with the specified key. If such an entry is found, true
- * is returned. If the iteration terminates without finding such an
- * entry, false is returned. Note that this implementation
- * requires linear time in the size of the map; many implementations will
- * override this method.
- *
- * @param key key whose presence in this map is to be tested.
- * @return true if this map contains a mapping for the specified
- * key.
- *
- * @throws NullPointerException if the key is null and this map
- * does not permit null keys.
+ * @throws ClassCastException {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
*/
public boolean containsKey(Object key) {
Iterator
- *
- * This implementation iterates over 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, null is returned. Note that this implementation
- * requires linear time in the size of the map; many implementations will
- * override this method.
- *
- * @param key key whose associated value is to be returned.
- * @return the value to which this map maps the specified key.
- *
- * @throws NullPointerException if the key is null and this map
- * does not permit null keys.
- *
- * @see #containsKey(Object)
+ * {@inheritDoc}
+ *
+ * This implementation iterates over 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, 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}
*/
public V get(Object key) {
Iterator
+ * {@inheritDoc}
*
- * This implementation always throws an
+ * This implementation always throws an
* UnsupportedOperationException.
*
- * @param key key with which the specified value is to be associated.
- * @param value value to be associated with the specified key.
- *
- * @return the previous value associated with specified key, or null
- * if there was no mapping for key. (A null return can
- * also indicate that the map previously associated null
- * with the specified key, if the implementation supports
- * null values.)
- *
- * @throws UnsupportedOperationException if the put operation is
- * not supported by this map.
- *
- * @throws ClassCastException if the class of the specified key or value
- * prevents it from being stored in this map.
- *
- * @throws IllegalArgumentException if some aspect of this key or value *
- * prevents it from being stored in this map.
- *
- * @throws NullPointerException if this map does not permit null
- * keys or values, and the specified key or value is
- * null.
+ * @throws UnsupportedOperationException {@inheritDoc}
+ * @throws ClassCastException {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
+ * @throws IllegalArgumentException {@inheritDoc}
*/
public V put(K key, V value) {
throw new UnsupportedOperationException();
}
/**
- * Removes the mapping for this key from this map if present (optional
- * operation).
+ * {@inheritDoc}
*
- * This implementation iterates over entrySet() searching for an
+ * This implementation iterates over entrySet() searching for an
* entry with the specified key. If such an entry is found, its value is
* obtained with its getValue operation, the entry is removed
- * from the Collection (and the backing map) with the iterator's
+ * from the collection (and the backing map) with the iterator's
* remove operation, and the saved value is returned. If the
* iteration terminates without finding such an entry, null is
* returned. Note that this implementation requires linear time in the
- * size of the map; many implementations will override this method.
+ * size of the map; many implementations will override this method.
+ *
+ * Note that this implementation throws an
+ * UnsupportedOperationException if the entrySet
+ * iterator does not support the remove method and this map
+ * contains a mapping for the specified key.
*
- * Note that this implementation throws an
- * UnsupportedOperationException if the entrySet iterator
- * does not support the remove method and this map contains a
- * mapping for the specified key.
- *
- * @param key key whose mapping is to be removed from the map.
- * @return the previous value associated with specified key, or null
- * if there was no entry for key. (A null return can
- * also indicate that the map previously associated null
- * with the specified key, if the implementation supports
- * null values.)
- * @throws UnsupportedOperationException if the remove operation
- * is not supported by this map.
+ * @throws UnsupportedOperationException {@inheritDoc}
+ * @throws ClassCastException {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
*/
public V remove(Object key) {
Iterator
+ * {@inheritDoc}
*
- * This implementation iterates over the specified map's
+ * This implementation iterates over the specified map's
* entrySet() collection, and calls this map's put
- * operation once for each entry returned by the iteration.
+ * operation once for each entry returned by the iteration.
*
- * Note that this implementation throws an
+ * Note that this implementation throws an
* UnsupportedOperationException if this map does not support
* the put operation and the specified map is nonempty.
*
- * @param t mappings to be stored in this map.
- *
- * @throws UnsupportedOperationException if the putAll operation
- * is not supported by this map.
- *
- * @throws ClassCastException if the class of a key or value in the
- * specified map prevents it from being stored in this map.
- *
- * @throws IllegalArgumentException if some aspect of a key or value in
- * the specified map prevents it from being stored in this map.
- * @throws NullPointerException if the specified map is null, or if
- * this map does not permit null keys or values, and the
- * specified map contains null keys or values.
- */
- public void putAll(Map extends K, ? extends V> t) {
- Iterator extends Entry extends K, ? extends V>> i = t.entrySet().iterator();
- while (i.hasNext()) {
- Entry extends K, ? extends V> e = i.next();
- put(e.getKey(), e.getValue());
- }
+ * @throws UnsupportedOperationException {@inheritDoc}
+ * @throws ClassCastException {@inheritDoc}
+ * @throws NullPointerException {@inheritDoc}
+ * @throws IllegalArgumentException {@inheritDoc}
+ */
+ public void putAll(Map extends K, ? extends V> m) {
+ for (Map.Entry extends K, ? extends V> e : m.entrySet())
+ put(e.getKey(), e.getValue());
}
/**
- * Removes all mappings from this map (optional operation).
+ * {@inheritDoc}
*
- * This implementation calls entrySet().clear().
+ * This implementation calls entrySet().clear().
*
- * Note that this implementation throws an
+ * Note that this implementation throws an
* UnsupportedOperationException if the entrySet
* does not support the clear operation.
*
- * @throws UnsupportedOperationException clear is not supported
- * by this map.
+ * @throws UnsupportedOperationException {@inheritDoc}
*/
public void clear() {
entrySet().clear();
@@ -346,27 +301,19 @@ public abstract class AbstractMap
- *
- * This implementation returns a Set that subclasses
- * AbstractSet. The subclass's iterator method returns a "wrapper
- * object" over this map's entrySet() iterator. The size method delegates
- * to this map's size method and the contains method delegates to this
- * map's containsKey method.
+ * {@inheritDoc}
+ *
+ * This implementation returns a set that subclasses {@link AbstractSet}.
+ * The subclass's iterator method returns a "wrapper object" over this
+ * map's entrySet() iterator. The size method
+ * delegates to this map's size method and the
+ * contains method delegates to this map's
+ * containsKey method.
*
- * The Set is created the first time this method is called,
+ * 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.
- *
- * @return a Set view of the keys contained in this map.
+ * method will not all return the same set.
*/
public Set
- *
- * This implementation returns a collection that subclasses abstract
- * collection. The subclass's iterator method returns a "wrapper object"
- * over this map's entrySet() iterator. The size method
- * delegates to this map's size method and the contains method delegates
- * to this map's containsValue method.
+ * {@inheritDoc}
+ *
+ * This implementation returns a collection that subclasses {@link
+ * AbstractCollection}. The subclass's iterator method returns a
+ * "wrapper object" over this map's entrySet() iterator.
+ * The size method delegates to this map's size
+ * method and the contains method delegates to this map's
+ * containsValue method.
*
- * The collection is created the first time this method is called, and
+ * 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.
- *
- * @return a collection view of the values contained in this map.
+ * method will not all return the same collection.
*/
public Collection
+ * of the Map interface.
*
- * This implementation first checks if the specified object is this map;
+ * This implementation first checks if the specified object is this map;
* if so it returns true. Then, it checks if the specified
- * object is a map whose size is identical to the size of this set; if
+ * object is a map whose size is identical to the size of this map; if
* not, it returns false. If so, it iterates over this map's
* 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, false is returned. If the
* iteration completes, true is returned.
*
- * @param o object to be compared for equality with this map.
- * @return true if the specified object is equal to this map.
+ * @param o object to be compared for equality with this map
+ * @return true if the specified object is equal to this map
*/
public boolean equals(Object o) {
if (o == this)
@@ -505,8 +444,8 @@ public abstract class AbstractMap
- *
- * This implementation iterates over entrySet(), calling
- * hashCode on each element (entry) in the Collection, and adding
- * up the results.
+ * entrySet() view. This ensures that m1.equals(m2)
+ * implies that m1.hashCode()==m2.hashCode() for any two maps
+ * m1 and m2, as required by the general contract of
+ * {@link Object#hashCode}.
+ *
+ * This implementation iterates over 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.
+ * @return the hash code value for this map
* @see Map.Entry#hashCode()
- * @see Object#hashCode()
* @see Object#equals(Object)
* @see Set#equals(Object)
*/
@@ -566,50 +504,35 @@ public abstract class AbstractMap
- *
- * This implementation creates an empty string buffer, appends a left
- * brace, and iterates over the map's entrySet view, appending
- * the string representation of each map.entry in turn. After
- * appending each entry except the last, the string ", " is
- * appended. Finally a right brace is appended. A string is obtained
- * from the stringbuffer, and returned.
+ * {@link String#valueOf(Object)}.
*
- * @return a String representation of this map.
+ * @return a string representation of this map
*/
public String toString() {
- StringBuffer buf = new StringBuffer();
- buf.append("{");
-
Iterator
+ * (e1.getKey()==null ?
+ * e2.getKey()==null :
+ * e1.getKey().equals(e2.getKey()))
+ * &&
+ * (e1.getValue()==null ?
+ * e2.getValue()==null :
+ * e1.getValue().equals(e2.getValue()))
+ * This ensures that the {@code equals} method works properly across
+ * different implementations of the {@code Map.Entry} interface.
+ *
+ * @param o object to be compared for equality with this map entry
+ * @return {@code true} if the specified object is equal to this map
+ * entry
+ * @see #hashCode
+ */
public boolean equals(Object o) {
if (!(o instanceof Map.Entry))
return false;
@@ -707,9 +657,22 @@ public abstract class AbstractMap
+ * (e.getKey()==null ? 0 : e.getKey().hashCode()) ^
+ * (e.getValue()==null ? 0 : e.getValue().hashCode())
+ * This ensures that {@code e1.equals(e2)} implies that
+ * {@code e1.hashCode()==e2.hashCode()} for any two Entries
+ * {@code e1} and {@code e2}, as required by the general
+ * contract of {@link Object#hashCode}.
+ *
+ * @return the hash code value for this map entry
+ * @see #equals
+ */
public int hashCode() {
- return ((key == null) ? 0 : key.hashCode()) ^
- ((value == null) ? 0 : value.hashCode());
+ return (key == null ? 0 : key.hashCode()) ^
+ (value == null ? 0 : value.hashCode());
}
/**
@@ -718,7 +681,7 @@ public abstract class AbstractMap
+ * (e1.getKey()==null ?
+ * e2.getKey()==null :
+ * e1.getKey().equals(e2.getKey()))
+ * &&
+ * (e1.getValue()==null ?
+ * e2.getValue()==null :
+ * e1.getValue().equals(e2.getValue()))
+ * This ensures that the {@code equals} method works properly across
+ * different implementations of the {@code Map.Entry} interface.
+ *
+ * @param o object to be compared for equality with this map entry
+ * @return {@code true} if the specified object is equal to this map
+ * entry
+ * @see #hashCode
+ */
public boolean equals(Object o) {
if (!(o instanceof Map.Entry))
return false;
@@ -798,9 +788,22 @@ public abstract class AbstractMap
+ * (e.getKey()==null ? 0 : e.getKey().hashCode()) ^
+ * (e.getValue()==null ? 0 : e.getValue().hashCode())
+ * This ensures that {@code e1.equals(e2)} implies that
+ * {@code e1.hashCode()==e2.hashCode()} for any two Entries
+ * {@code e1} and {@code e2}, as required by the general
+ * contract of {@link Object#hashCode}.
+ *
+ * @return the hash code value for this map entry
+ * @see #equals
+ */
public int hashCode() {
- return ((key == null) ? 0 : key.hashCode()) ^
- ((value == null) ? 0 : value.hashCode());
+ return (key == null ? 0 : key.hashCode()) ^
+ (value == null ? 0 : value.hashCode());
}
/**
@@ -809,7 +812,7 @@ public abstract class AbstractMap