--- jsr166/src/main/java/util/AbstractMap.java 2005/04/18 05:18:29 1.6
+++ jsr166/src/main/java/util/AbstractMap.java 2005/04/27 07:13:50 1.8
@@ -33,10 +33,13 @@ import java.util.Map.Entry;
* implementation in detail. Each of these methods may be overridden if the
* 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 the type of keys maintained by this map
+ * @param the type of mapped values
+ *
* @author Josh Bloch
* @author Neal Gafter
* @version %I%, %G%
@@ -84,16 +87,16 @@ public abstract class AbstractMap i
* 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.
+ * time linear in the map size for most implementations of Map.
*
- * This implementation iterates over entrySet() searching for an entry
+ * 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.
*/
public boolean containsValue(Object value) {
@@ -127,10 +130,9 @@ public abstract class AbstractMap i
*
* @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.
+ * key.
+ * @throws NullPointerException if key is null
+ * and this map does not permit null keys.
*/
public boolean containsKey(Object key) {
Iterator> i = entrySet().iterator();
@@ -167,10 +169,10 @@ public abstract class AbstractMap i
*
* @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.
- *
+ *
+ * @throws NullPointerException if key is null
+ * and this map does not permit null keys.
+ *
* @see #containsKey(Object)
*/
public V get(Object key) {
@@ -204,25 +206,21 @@ public abstract class AbstractMap i
*
* @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 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.
- *
+ * 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.
+ * keys or values, and the specified key or value is null.
*/
public V put(K key, V value) {
throw new UnsupportedOperationException();
@@ -235,7 +233,7 @@ public abstract class AbstractMap i
* 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
@@ -253,7 +251,7 @@ public abstract class AbstractMap i
* with the specified key, if the implementation supports
* null values.)
* @throws UnsupportedOperationException if the remove operation
- * is not supported by this map.
+ * is not supported by this map.
*/
public V remove(Object key) {
Iterator> i = entrySet().iterator();
@@ -297,15 +295,13 @@ public abstract class AbstractMap i
* 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.
- *
+ * 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.
- *
+ * 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.
+ * 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.
@@ -327,8 +323,8 @@ public abstract class AbstractMap i
* UnsupportedOperationException if the entrySet
* does not support the clear operation.
*
- * @throws UnsupportedOperationException clear is not supported
- * by this map.
+ * @throws UnsupportedOperationException if the clear operation
+ * is not supported by this map.
*/
public void clear() {
entrySet().clear();
@@ -346,27 +342,29 @@ public abstract class AbstractMap i
transient volatile Collection values = null;
/**
- * Returns a Set view of the keys contained in this map. The Set is
- * backed by the map, so changes to the map are reflected in the Set,
- * and vice-versa. (If the map is modified while an iteration over
- * the Set is in progress, the results of the iteration are undefined.)
- * The Set supports element removal, which removes the corresponding entry
- * from the map, via the Iterator.remove, Set.remove, removeAll
- * retainAll, and clear operations. It does not support the add or
- * addAll operations.
- *
- * 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.
+ * Returns a {@link Set} view of the keys contained in this map.
+ * The set is backed by the map, so changes to the map are
+ * reflected in the set, and vice-versa. If the map is modified
+ * while an iteration over the set is in progress (except through
+ * the iterator's own remove operation), the results of
+ * the iteration are undefined. The set supports element removal,
+ * which removes the corresponding mapping from the map, via the
+ * Iterator.remove, Set.remove,
+ * removeAll retainAll, and clear
+ * operations. It does not support the add or addAll
+ * operations.
+ *
+ *
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 keySet() {
if (keySet == null) {
@@ -402,26 +400,29 @@ public abstract class AbstractMap i
}
/**
- * Returns a collection view of the values contained in this map. The
- * collection is backed by the map, so changes to the map are reflected in
- * the collection, and vice-versa. (If the map is modified while an
- * iteration over the collection is in progress, the results of the
- * iteration are undefined.) The collection supports element removal,
- * which removes the corresponding entry from the map, via the
- * Iterator.remove, Collection.remove,
- * removeAll, retainAll and clear operations.
- * It does not support the add or addAll operations.
- *
- * 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.
+ * Returns a {@link Collection} view of the values contained in this map.
+ * The collection is backed by the map, so changes to the map are
+ * reflected in the collection, and vice-versa. If the map is
+ * modified while an iteration over the collection is in progress
+ * (except through the iterator's own remove operation),
+ * the results of the iteration are undefined. The collection
+ * supports element removal, which removes the corresponding
+ * mapping from the map, via the Iterator.remove,
+ * Collection.remove, removeAll,
+ * retainAll and clear operations. It does not
+ * support the add or addAll operations.
+ *
+ *
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.
+ * method will not all return the same collection.
*
* @return a collection view of the values contained in this map.
*/
@@ -458,19 +459,6 @@ public abstract class AbstractMap i
return values;
}
- /**
- * Returns a set view of the mappings contained in this map. Each element
- * in this set is a Map.Entry. The set is backed by the map, so changes
- * to the map are reflected in the set, and vice-versa. (If the map is
- * modified while an iteration over the set is in progress, the results of
- * the iteration are undefined.) The set supports element removal, which
- * removes the corresponding entry from the map, via the
- * Iterator.remove, Set.remove, removeAll,
- * retainAll and clear operations. It does not support
- * the add or addAll operations.
- *
- * @return a set view of the mappings contained in this map.
- */
public abstract Set> entrySet();
@@ -489,7 +477,7 @@ public abstract class AbstractMap i
*
* 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
@@ -523,9 +511,9 @@ public abstract class AbstractMap i
return false;
}
}
- } catch(ClassCastException unused) {
+ } catch (ClassCastException unused) {
return false;
- } catch(NullPointerException unused) {
+ } catch (NullPointerException unused) {
return false;
}
@@ -604,7 +592,7 @@ public abstract class AbstractMap i
buf.append("}");
return buf.toString();
}
-
+
/**
* Returns a shallow copy of this AbstractMap instance: the keys
* and values themselves are not cloned.