--- jsr166/src/main/java/util/AbstractMap.java	2005/06/10 16:06:46	1.12
+++ jsr166/src/main/java/util/AbstractMap.java	2005/09/10 20:15:50	1.17
@@ -6,6 +6,7 @@
  */
 
 package java.util;
+import java.util.*; // for javadoc (till 6280605 is fixed)
 import java.util.Map.Entry;
 
 /**
@@ -252,11 +253,8 @@ public abstract class AbstractMap<K,V> i
      * @throws IllegalArgumentException      {@inheritDoc}
      */
     public void putAll(Map<? extends K, ? extends V> m) {
-	Iterator<? extends Entry<? extends K, ? extends V>> i = m.entrySet().iterator();
-	while (i.hasNext()) {
-	    Entry<? extends K, ? extends V> e = i.next();
-	    put(e.getKey(), e.getValue());
-	}
+        for (Map.Entry<? extends K, ? extends V> e : m.entrySet())
+            put(e.getKey(), e.getValue());
     }
 
     /**
@@ -387,7 +385,13 @@ public abstract class AbstractMap<K,V> i
     // Comparison and hashing
 
     /**
-     * {@inheritDoc}
+     * 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.
      *
      * <p>This implementation first checks if the specified object is this map;
      * if so it returns <tt>true</tt>.  Then, it checks if the specified
@@ -397,6 +401,9 @@ public abstract class AbstractMap<K,V> i
      * 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)
@@ -404,8 +411,8 @@ public abstract class AbstractMap<K,V> i
 
 	if (!(o instanceof Map))
 	    return false;
-	Map<K,V> t = (Map<K,V>) o;
-	if (t.size() != size())
+	Map<K,V> m = (Map<K,V>) o;
+	if (m.size() != size())
 	    return false;
 
         try {
@@ -415,10 +422,10 @@ public abstract class AbstractMap<K,V> i
 		K key = e.getKey();
                 V value = e.getValue();
                 if (value == null) {
-                    if (!(t.get(key)==null && t.containsKey(key)))
+                    if (!(m.get(key)==null && m.containsKey(key)))
                         return false;
                 } else {
-                    if (!value.equals(t.get(key)))
+                    if (!value.equals(m.get(key)))
                         return false;
                 }
             }
@@ -432,14 +439,19 @@ public abstract class AbstractMap<K,V> i
     }
 
     /**
-     * {@inheritDoc}
+     * 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}.
      *
      * <p>This implementation iterates over <tt>entrySet()</tt>, calling
-     * <tt>hashCode()</tt> on each element (entry) in the set, and
-     * adding up the results.
+     * {@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()
-     * @see Object#hashCode()
      * @see Object#equals(Object)
      * @see Set#equals(Object)
      */
@@ -459,43 +471,28 @@ public abstract class AbstractMap<K,V> i
      * <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
-     * <tt>String.valueOf(Object)</tt>.<p>
+     * {@link String#valueOf(Object)}.
      *
-     * This implementation creates an empty string buffer, appends a left
-     * brace, and iterates over the map's <tt>entrySet</tt> view, appending
-     * the string representation of each <tt>map.entry</tt> in turn.  After
-     * appending each entry except the last, the string <tt>", "</tt> is
-     * appended.  Finally a right brace is appended.  A string is obtained
-     * from the stringbuffer, and returned.
-     *
-     * @return a String representation of this map
+     * @return a string representation of this map
      */
     public String toString() {
-	StringBuilder sb = new StringBuilder();
-	sb.append("{");
-
 	Iterator<Entry<K,V>> i = entrySet().iterator();
-        boolean hasNext = i.hasNext();
-        while (hasNext) {
+	if (! i.hasNext())
+	    return "{}";
+
+	StringBuilder sb = new StringBuilder();
+	sb.append('{');
+	for (;;) {
 	    Entry<K,V> e = i.next();
 	    K key = e.getKey();
-            V value = e.getValue();
-	    if (key == this)
-		sb.append("(this Map)");
-	    else
-		sb.append(key);
-	    sb.append("=");
-	    if (value == this)
-		sb.append("(this Map)");
-	    else
-		sb.append(value);
-            hasNext = i.hasNext();
-            if (hasNext)
-                sb.append(", ");
-        }
-
-	sb.append("}");
-	return sb.toString();
+	    V value = e.getValue();
+	    sb.append(key   == this ? "(this Map)" : key);
+	    sb.append('=');
+	    sb.append(value == this ? "(this Map)" : value);
+	    if (! i.hasNext())
+		return sb.append('}').toString();
+	    sb.append(", ");
+	}
     }
 
     /**
@@ -516,7 +513,7 @@ public abstract class AbstractMap<K,V> i
      * Test for equality, checking for nulls.
      */
     private static boolean eq(Object o1, Object o2) {
-        return (o1 == null ? o2 == null : o1.equals(o2));
+        return o1 == null ? o2 == null : o1.equals(o2);
     }
 
     // Implementation Note: SimpleEntry and SimpleImmutableEntry
@@ -533,9 +530,15 @@ public abstract class AbstractMap<K,V> i
      * 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>
+     * <tt>Map.entrySet().toArray</tt>.
+     *
+     * @since 1.6
      */
-    public static class SimpleEntry<K,V> implements Entry<K,V> {
+    public static class SimpleEntry<K,V>
+	implements Entry<K,V>, java.io.Serializable
+    {
+	private static final long serialVersionUID = -8499721149061103585L;
+
 	private final K key;
 	private V value;
 
@@ -601,8 +604,8 @@ public abstract class AbstractMap<K,V> i
 	}
 
 	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());
 	}
 
         /**
@@ -620,12 +623,18 @@ public abstract class AbstractMap<K,V> i
     }
 
     /**
-     * An Entry maintaining an immutable key and value, This class
+     * 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
      */
-    public static class SimpleImmutableEntry<K,V> implements Entry<K,V> {
+    public static class SimpleImmutableEntry<K,V>
+	implements Entry<K,V>, java.io.Serializable
+    {
+	private static final long serialVersionUID = 7138329143949025153L;
+
 	private final K key;
 	private final V value;
 
@@ -692,8 +701,8 @@ public abstract class AbstractMap<K,V> i
 	}
 
 	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());
 	}
 
         /**