--- 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.