From 477a21f7f9b31c687d45f1001dd93c90df52cf29 Mon Sep 17 00:00:00 2001 From: Andrew John Hughes Date: Sun, 29 Aug 2004 17:28:09 +0000 Subject: AbstractCollection.java, [...]: Added additional exceptions to documentation... 2004-08-29 Andrew John Hughes * java/util/AbstractCollection.java, java/util/AbstractList.java, java/util/AbstractMap.java, java/util/AbstractSequentialList.java, java/util/ArrayList.java, java/util/Arrays.java, java/util/BitSet.java, java/util/Calendar.java, java/util/Collection.java, java/util/ListIterator.java, java/util/Map.java, java/util/SortedSet.java: Added additional exceptions to documentation, along with some additions and corrections. From-SVN: r86730 --- libjava/java/util/AbstractMap.java | 145 +++++++++++++++++++++++++++++++------ 1 file changed, 122 insertions(+), 23 deletions(-) (limited to 'libjava/java/util/AbstractMap.java') diff --git a/libjava/java/util/AbstractMap.java b/libjava/java/util/AbstractMap.java index 4be5f3d..d27e93b 100644 --- a/libjava/java/util/AbstractMap.java +++ b/libjava/java/util/AbstractMap.java @@ -92,6 +92,21 @@ public abstract class AbstractMap implements Map } /** + * Returns a set view of the mappings in this Map. Each element in the + * set must be an implementation of Map.Entry. The set is backed by + * the map, so that changes in one show up in the other. Modifications + * made while an iterator is in progress cause undefined behavior. If + * the set supports removal, these methods must be valid: + * Iterator.remove, Set.remove, + * removeAll, retainAll, and clear. + * Element addition is not supported via this set. + * + * @return the entry set + * @see Map.Entry + */ + public abstract Set entrySet(); + + /** * Remove all entries from this Map (optional operation). This default * implementation calls entrySet().clear(). NOTE: If the entry set does * not permit clearing, then this will fail, too. Subclasses often @@ -153,8 +168,9 @@ public abstract class AbstractMap implements Map * This implementation does a linear search, O(n), over the * entrySet(), returning true if a match * is found, false if the iteration ends. A match is - * defined as (value == null ? v == null : value.equals(v)) - * Subclasses are unlikely to implement this more efficiently. + * defined as a value, v, where (value == null ? v == null : + * value.equals(v)). Subclasses are unlikely to implement + * this more efficiently. * * @param value the value to search for * @return true if the map contains the value @@ -171,21 +187,6 @@ public abstract class AbstractMap implements Map } /** - * Returns a set view of the mappings in this Map. Each element in the - * set must be an implementation of Map.Entry. The set is backed by - * the map, so that changes in one show up in the other. Modifications - * made while an iterator is in progress cause undefined behavior. If - * the set supports removal, these methods must be valid: - * Iterator.remove, Set.remove, - * removeAll, retainAll, and clear. - * Element addition is not supported via this set. - * - * @return the entry set - * @see Map.Entry - */ - public abstract Set entrySet(); - - /** * Compares the specified object with this map for equality. Returns * true if the other object is a Map with the same mappings, * that is,
@@ -277,32 +278,75 @@ public abstract class AbstractMap implements Map if (keys == null) keys = new AbstractSet() { + /** + * Retrieves the number of keys in the backing map. + * + * @return The number of keys. + */ public int size() { return AbstractMap.this.size(); } + /** + * Returns true if the backing map contains the + * supplied key. + * + * @param key The key to search for. + * @return True if the key was found, false otherwise. + */ public boolean contains(Object key) { return containsKey(key); } + /** + * Returns an iterator which iterates over the keys + * in the backing map, using a wrapper around the + * iterator returned by entrySet(). + * + * @return An iterator over the keys. + */ public Iterator iterator() { return new Iterator() { + /** + * The iterator returned by entrySet(). + */ private final Iterator map_iterator = entrySet().iterator(); + /** + * Returns true if a call to next() will + * return another key. + * + * @return True if the iterator has not yet reached + * the last key. + */ public boolean hasNext() { return map_iterator.hasNext(); } + /** + * Returns the key from the next entry retrieved + * by the underlying entrySet() iterator. + * + * @return The next key. + */ public Object next() { return ((Map.Entry) map_iterator.next()).getKey(); } + /** + * Removes the map entry which has a key equal + * to that returned by the last call to + * next(). + * + * @throws UnsupportedOperationException if the + * map doesn't support removal. + */ public void remove() { map_iterator.remove(); @@ -343,11 +387,13 @@ public abstract class AbstractMap implements Map * * @param m the mapping to load into this map * @throws UnsupportedOperationException if the operation is not supported - * @throws ClassCastException if a key or value is of the wrong type + * by this map. + * @throws ClassCastException if a key or value is of the wrong type for + * adding to this map. * @throws IllegalArgumentException if something about a key or value - * prevents it from existing in this map - * @throws NullPointerException if the map forbids null keys or values, or - * if m is null. + * prevents it from existing in this map. + * @throws NullPointerException if the map forbids null keys or values. + * @throws NullPointerException if m is null. * @see #put(Object, Object) */ public void putAll(Map m) @@ -372,7 +418,9 @@ public abstract class AbstractMap implements Map * implementations override it for efficiency. * * @param key the key to remove - * @return the value the key mapped to, or null if not present + * @return the value the key mapped to, or null if not present. + * Null may also be returned if null values are allowed + * in the map and the value of this mapping is null. * @throws UnsupportedOperationException if deletion is unsupported * @see Iterator#remove() */ @@ -461,32 +509,76 @@ public abstract class AbstractMap implements Map if (values == null) values = new AbstractCollection() { + /** + * Returns the number of values stored in + * the backing map. + * + * @return The number of values. + */ public int size() { return AbstractMap.this.size(); } + /** + * Returns true if the backing map contains + * the supplied value. + * + * @param value The value to search for. + * @return True if the value was found, false otherwise. + */ public boolean contains(Object value) { return containsValue(value); } + /** + * Returns an iterator which iterates over the + * values in the backing map, by using a wrapper + * around the iterator returned by entrySet(). + * + * @return An iterator over the values. + */ public Iterator iterator() { return new Iterator() { + /** + * The iterator returned by entrySet(). + */ private final Iterator map_iterator = entrySet().iterator(); + /** + * Returns true if a call to next() will + * return another value. + * + * @return True if the iterator has not yet reached + * the last value. + */ public boolean hasNext() { return map_iterator.hasNext(); } + /** + * Returns the value from the next entry retrieved + * by the underlying entrySet() iterator. + * + * @return The next value. + */ public Object next() { return ((Map.Entry) map_iterator.next()).getValue(); } + /** + * Removes the map entry which has a key equal + * to that returned by the last call to + * next(). + * + * @throws UnsupportedOperationException if the + * map doesn't support removal. + */ public void remove() { map_iterator.remove(); @@ -533,6 +625,7 @@ public abstract class AbstractMap implements Map * @author Eric Blake */ // XXX - FIXME Use fully qualified implements as gcj 3.1 workaround. + // Bug still exists in 3.4.1 static class BasicMapEntry implements Map.Entry { /** @@ -627,7 +720,13 @@ public abstract class AbstractMap implements Map * * @param newVal the new value to store * @return the old value - * @throws NullPointerException if the map forbids null values + * @throws NullPointerException if the map forbids null values. + * @throws UnsupportedOperationException if the map doesn't support + * put(). + * @throws ClassCastException if the value is of a type unsupported + * by the map. + * @throws IllegalArgumentException if something else about this + * value prevents it being stored in the map. */ public Object setValue(Object newVal) { -- cgit v1.1