ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/AbstractMap.java
(Generate patch)

Comparing jsr166/src/main/java/util/AbstractMap.java (file contents):
Revision 1.9 by jsr166, Sat May 14 01:52:24 2005 UTC vs.
Revision 1.24 by jsr166, Sun May 20 07:54:01 2007 UTC

# Line 1 | Line 1
1   /*
2 < * %W% %E%
2 > * Copyright 1997-2006 Sun Microsystems, Inc.  All Rights Reserved.
3 > * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4   *
5 < * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
6 < * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
5 > * This code is free software; you can redistribute it and/or modify it
6 > * under the terms of the GNU General Public License version 2 only, as
7 > * published by the Free Software Foundation.  Sun designates this
8 > * particular file as subject to the "Classpath" exception as provided
9 > * by Sun in the LICENSE file that accompanied this code.
10 > *
11 > * This code is distributed in the hope that it will be useful, but WITHOUT
12 > * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 > * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 > * version 2 for more details (a copy is included in the LICENSE file that
15 > * accompanied this code).
16 > *
17 > * You should have received a copy of the GNU General Public License version
18 > * 2 along with this work; if not, write to the Free Software Foundation,
19 > * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 > *
21 > * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 > * CA 95054 USA or visit www.sun.com if you need additional information or
23 > * have any questions.
24   */
25  
26   package java.util;
# Line 29 | Line 47 | import java.util.Map.Entry;
47   * constructor, as per the recommendation in the <tt>Map</tt> interface
48   * specification.
49   *
50 < * <p>The documentation for each non-abstract methods in this class describes its
50 > * <p>The documentation for each non-abstract method in this class describes its
51   * implementation in detail.  Each of these methods may be overridden if the
52   * map being implemented admits a more efficient implementation.
53   *
54   * <p>This class is a member of the
55 < * <a href="{@docRoot}/../guide/collections/index.html">
55 > * <a href="{@docRoot}/../technotes/guides/collections/index.html">
56   * Java Collections Framework</a>.
57   *
58   * @param <K> the type of keys maintained by this map
# Line 85 | Line 103 | public abstract class AbstractMap<K,V> i
103       * finding such an entry, <tt>false</tt> is returned.  Note that this
104       * implementation requires linear time in the size of the map.
105       *
88 –     * @throws NullPointerException {@inheritDoc}
106       * @throws ClassCastException   {@inheritDoc}
107 +     * @throws NullPointerException {@inheritDoc}
108       */
109      public boolean containsValue(Object value) {
110          Iterator<Entry<K,V>> i = entrySet().iterator();
# Line 116 | Line 134 | public abstract class AbstractMap<K,V> i
134       * implementation requires linear time in the size of the map; many
135       * implementations will override this method.
136       *
119 –     * @throws NullPointerException {@inheritDoc}
137       * @throws ClassCastException   {@inheritDoc}
138 +     * @throws NullPointerException {@inheritDoc}
139       */
140      public boolean containsKey(Object key) {
141          Iterator<Map.Entry<K,V>> i = entrySet().iterator();
# Line 147 | Line 165 | public abstract class AbstractMap<K,V> i
165       * implementation requires linear time in the size of the map; many
166       * implementations will override this method.
167       *
150 –     * @throws NullPointerException          {@inheritDoc}
168       * @throws ClassCastException            {@inheritDoc}
169 +     * @throws NullPointerException          {@inheritDoc}
170       */
171      public V get(Object key) {
172          Iterator<Entry<K,V>> i = entrySet().iterator();
# Line 178 | Line 196 | public abstract class AbstractMap<K,V> i
196       * <tt>UnsupportedOperationException</tt>.
197       *
198       * @throws UnsupportedOperationException {@inheritDoc}
181 –     * @throws NullPointerException          {@inheritDoc}
199       * @throws ClassCastException            {@inheritDoc}
200 +     * @throws NullPointerException          {@inheritDoc}
201       * @throws IllegalArgumentException      {@inheritDoc}
202       */
203      public V put(K key, V value) {
# Line 204 | Line 222 | public abstract class AbstractMap<K,V> i
222       * contains a mapping for the specified key.
223       *
224       * @throws UnsupportedOperationException {@inheritDoc}
207 –     * @throws NullPointerException          {@inheritDoc}
225       * @throws ClassCastException            {@inheritDoc}
226 +     * @throws NullPointerException          {@inheritDoc}
227       */
228      public V remove(Object key) {
229          Iterator<Entry<K,V>> i = entrySet().iterator();
# Line 247 | Line 265 | public abstract class AbstractMap<K,V> i
265       * the <tt>put</tt> operation and the specified map is nonempty.
266       *
267       * @throws UnsupportedOperationException {@inheritDoc}
250 –     * @throws NullPointerException          {@inheritDoc}
268       * @throws ClassCastException            {@inheritDoc}
269 +     * @throws NullPointerException          {@inheritDoc}
270       * @throws IllegalArgumentException      {@inheritDoc}
271       */
272      public void putAll(Map<? extends K, ? extends V> m) {
273 <        Iterator<? extends Entry<? extends K, ? extends V>> i = m.entrySet().iterator();
274 <        while (i.hasNext()) {
257 <            Entry<? extends K, ? extends V> e = i.next();
258 <            put(e.getKey(), e.getValue());
259 <        }
273 >        for (Map.Entry<? extends K, ? extends V> e : m.entrySet())
274 >            put(e.getKey(), e.getValue());
275      }
276  
277      /**
# Line 387 | Line 402 | public abstract class AbstractMap<K,V> i
402      // Comparison and hashing
403  
404      /**
405 <     * {@inheritDoc}
405 >     * Compares the specified object with this map for equality.  Returns
406 >     * <tt>true</tt> if the given object is also a map and the two maps
407 >     * represent the same mappings.  More formally, two maps <tt>m1</tt> and
408 >     * <tt>m2</tt> represent the same mappings if
409 >     * <tt>m1.entrySet().equals(m2.entrySet())</tt>.  This ensures that the
410 >     * <tt>equals</tt> method works properly across different implementations
411 >     * of the <tt>Map</tt> interface.
412       *
413       * <p>This implementation first checks if the specified object is this map;
414       * if so it returns <tt>true</tt>.  Then, it checks if the specified
# Line 397 | Line 418 | public abstract class AbstractMap<K,V> i
418       * contains each mapping that this map contains.  If the specified map
419       * fails to contain such a mapping, <tt>false</tt> is returned.  If the
420       * iteration completes, <tt>true</tt> is returned.
421 +     *
422 +     * @param o object to be compared for equality with this map
423 +     * @return <tt>true</tt> if the specified object is equal to this map
424       */
425      public boolean equals(Object o) {
426          if (o == this)
# Line 404 | Line 428 | public abstract class AbstractMap<K,V> i
428  
429          if (!(o instanceof Map))
430              return false;
431 <        Map<K,V> t = (Map<K,V>) o;
432 <        if (t.size() != size())
431 >        Map<K,V> m = (Map<K,V>) o;
432 >        if (m.size() != size())
433              return false;
434  
435          try {
# Line 415 | Line 439 | public abstract class AbstractMap<K,V> i
439                  K key = e.getKey();
440                  V value = e.getValue();
441                  if (value == null) {
442 <                    if (!(t.get(key)==null && t.containsKey(key)))
442 >                    if (!(m.get(key)==null && m.containsKey(key)))
443                          return false;
444                  } else {
445 <                    if (!value.equals(t.get(key)))
445 >                    if (!value.equals(m.get(key)))
446                          return false;
447                  }
448              }
# Line 432 | Line 456 | public abstract class AbstractMap<K,V> i
456      }
457  
458      /**
459 <     * {@inheritDoc}
459 >     * Returns the hash code value for this map.  The hash code of a map is
460 >     * defined to be the sum of the hash codes of each entry in the map's
461 >     * <tt>entrySet()</tt> view.  This ensures that <tt>m1.equals(m2)</tt>
462 >     * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two maps
463 >     * <tt>m1</tt> and <tt>m2</tt>, as required by the general contract of
464 >     * {@link Object#hashCode}.
465       *
466       * <p>This implementation iterates over <tt>entrySet()</tt>, calling
467 <     * <tt>hashCode()</tt> on each element (entry) in the set, and
468 <     * adding up the results.
467 >     * {@link Map.Entry#hashCode hashCode()} on each element (entry) in the
468 >     * set, and adding up the results.
469       *
470 +     * @return the hash code value for this map
471       * @see Map.Entry#hashCode()
442 –     * @see Object#hashCode()
472       * @see Object#equals(Object)
473       * @see Set#equals(Object)
474       */
# Line 459 | Line 488 | public abstract class AbstractMap<K,V> i
488       * <tt>", "</tt> (comma and space).  Each key-value mapping is rendered as
489       * the key followed by an equals sign (<tt>"="</tt>) followed by the
490       * associated value.  Keys and values are converted to strings as by
491 <     * <tt>String.valueOf(Object)</tt>.<p>
491 >     * {@link String#valueOf(Object)}.
492       *
493 <     * This implementation creates an empty string buffer, appends a left
465 <     * brace, and iterates over the map's <tt>entrySet</tt> view, appending
466 <     * the string representation of each <tt>map.entry</tt> in turn.  After
467 <     * appending each entry except the last, the string <tt>", "</tt> is
468 <     * appended.  Finally a right brace is appended.  A string is obtained
469 <     * from the stringbuffer, and returned.
470 <     *
471 <     * @return a String representation of this map.
493 >     * @return a string representation of this map
494       */
495      public String toString() {
474 –        StringBuffer buf = new StringBuffer();
475 –        buf.append("{");
476 –
496          Iterator<Entry<K,V>> i = entrySet().iterator();
497 <        boolean hasNext = i.hasNext();
498 <        while (hasNext) {
497 >        if (! i.hasNext())
498 >            return "{}";
499 >
500 >        StringBuilder sb = new StringBuilder();
501 >        sb.append('{');
502 >        for (;;) {
503              Entry<K,V> e = i.next();
504              K key = e.getKey();
505 <            V value = e.getValue();
506 <            if (key == this)
507 <                buf.append("(this Map)");
508 <            else
509 <                buf.append(key);
510 <            buf.append("=");
511 <            if (value == this)
512 <                buf.append("(this Map)");
490 <            else
491 <                buf.append(value);
492 <            hasNext = i.hasNext();
493 <            if (hasNext)
494 <                buf.append(", ");
495 <        }
496 <
497 <        buf.append("}");
498 <        return buf.toString();
505 >            V value = e.getValue();
506 >            sb.append(key   == this ? "(this Map)" : key);
507 >            sb.append('=');
508 >            sb.append(value == this ? "(this Map)" : value);
509 >            if (! i.hasNext())
510 >                return sb.append('}').toString();
511 >            sb.append(", ");
512 >        }
513      }
514  
515      /**
# Line 516 | Line 530 | public abstract class AbstractMap<K,V> i
530       * Test for equality, checking for nulls.
531       */
532      private static boolean eq(Object o1, Object o2) {
533 <        return (o1 == null ? o2 == null : o1.equals(o2));
533 >        return o1 == null ? o2 == null : o1.equals(o2);
534      }
535  
536      // Implementation Note: SimpleEntry and SimpleImmutableEntry
# Line 533 | Line 547 | public abstract class AbstractMap<K,V> i
547       * facilitates the process of building custom map
548       * implementations. For example, it may be convenient to return
549       * arrays of <tt>SimpleEntry</tt> instances in method
550 <     * <tt>Map.entrySet().toArray</tt>
550 >     * <tt>Map.entrySet().toArray</tt>.
551 >     *
552 >     * @since 1.6
553       */
554 <    public static class SimpleEntry<K,V> implements Entry<K,V> {
554 >    public static class SimpleEntry<K,V>
555 >        implements Entry<K,V>, java.io.Serializable
556 >    {
557 >        private static final long serialVersionUID = -8499721149061103585L;
558 >
559          private final K key;
560          private V value;
561  
# Line 555 | Line 575 | public abstract class AbstractMap<K,V> i
575           * Creates an entry representing the same mapping as the
576           * specified entry.
577           *
578 <         * @param entry the entry to copy.
578 >         * @param entry the entry to copy
579           */
580          public SimpleEntry(Entry<? extends K, ? extends V> entry) {
581              this.key   = entry.getKey();
# Line 593 | Line 613 | public abstract class AbstractMap<K,V> i
613              return oldValue;
614          }
615  
616 +        /**
617 +         * Compares the specified object with this entry for equality.
618 +         * Returns {@code true} if the given object is also a map entry and
619 +         * the two entries represent the same mapping.  More formally, two
620 +         * entries {@code e1} and {@code e2} represent the same mapping
621 +         * if<pre>
622 +         *   (e1.getKey()==null ?
623 +         *    e2.getKey()==null :
624 +         *    e1.getKey().equals(e2.getKey()))
625 +         *   &amp;&amp;
626 +         *   (e1.getValue()==null ?
627 +         *    e2.getValue()==null :
628 +         *    e1.getValue().equals(e2.getValue()))</pre>
629 +         * This ensures that the {@code equals} method works properly across
630 +         * different implementations of the {@code Map.Entry} interface.
631 +         *
632 +         * @param o object to be compared for equality with this map entry
633 +         * @return {@code true} if the specified object is equal to this map
634 +         *         entry
635 +         * @see    #hashCode
636 +         */
637          public boolean equals(Object o) {
638              if (!(o instanceof Map.Entry))
639                  return false;
# Line 600 | Line 641 | public abstract class AbstractMap<K,V> i
641              return eq(key, e.getKey()) && eq(value, e.getValue());
642          }
643  
644 +        /**
645 +         * Returns the hash code value for this map entry.  The hash code
646 +         * of a map entry {@code e} is defined to be: <pre>
647 +         *   (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
648 +         *   (e.getValue()==null ? 0 : e.getValue().hashCode())</pre>
649 +         * This ensures that {@code e1.equals(e2)} implies that
650 +         * {@code e1.hashCode()==e2.hashCode()} for any two Entries
651 +         * {@code e1} and {@code e2}, as required by the general
652 +         * contract of {@link Object#hashCode}.
653 +         *
654 +         * @return the hash code value for this map entry
655 +         * @see    #equals
656 +         */
657          public int hashCode() {
658 <            return ((key   == null)   ? 0 :   key.hashCode()) ^
659 <                   ((value == null)   ? 0 : value.hashCode());
658 >            return (key   == null ? 0 :   key.hashCode()) ^
659 >                   (value == null ? 0 : value.hashCode());
660          }
661  
662          /**
# Line 620 | Line 674 | public abstract class AbstractMap<K,V> i
674      }
675  
676      /**
677 <     * An Entry maintaining an immutable key and value, This class
677 >     * An Entry maintaining an immutable key and value.  This class
678       * does not support method <tt>setValue</tt>.  This class may be
679       * convenient in methods that return thread-safe snapshots of
680       * key-value mappings.
681 +     *
682 +     * @since 1.6
683       */
684 <    public static class SimpleImmutableEntry<K,V> implements Entry<K,V> {
684 >    public static class SimpleImmutableEntry<K,V>
685 >        implements Entry<K,V>, java.io.Serializable
686 >    {
687 >        private static final long serialVersionUID = 7138329143949025153L;
688 >
689          private final K key;
690          private final V value;
691  
# Line 684 | Line 744 | public abstract class AbstractMap<K,V> i
744              throw new UnsupportedOperationException();
745          }
746  
747 +        /**
748 +         * Compares the specified object with this entry for equality.
749 +         * Returns {@code true} if the given object is also a map entry and
750 +         * the two entries represent the same mapping.  More formally, two
751 +         * entries {@code e1} and {@code e2} represent the same mapping
752 +         * if<pre>
753 +         *   (e1.getKey()==null ?
754 +         *    e2.getKey()==null :
755 +         *    e1.getKey().equals(e2.getKey()))
756 +         *   &amp;&amp;
757 +         *   (e1.getValue()==null ?
758 +         *    e2.getValue()==null :
759 +         *    e1.getValue().equals(e2.getValue()))</pre>
760 +         * This ensures that the {@code equals} method works properly across
761 +         * different implementations of the {@code Map.Entry} interface.
762 +         *
763 +         * @param o object to be compared for equality with this map entry
764 +         * @return {@code true} if the specified object is equal to this map
765 +         *         entry
766 +         * @see    #hashCode
767 +         */
768          public boolean equals(Object o) {
769              if (!(o instanceof Map.Entry))
770                  return false;
# Line 691 | Line 772 | public abstract class AbstractMap<K,V> i
772              return eq(key, e.getKey()) && eq(value, e.getValue());
773          }
774  
775 +        /**
776 +         * Returns the hash code value for this map entry.  The hash code
777 +         * of a map entry {@code e} is defined to be: <pre>
778 +         *   (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
779 +         *   (e.getValue()==null ? 0 : e.getValue().hashCode())</pre>
780 +         * This ensures that {@code e1.equals(e2)} implies that
781 +         * {@code e1.hashCode()==e2.hashCode()} for any two Entries
782 +         * {@code e1} and {@code e2}, as required by the general
783 +         * contract of {@link Object#hashCode}.
784 +         *
785 +         * @return the hash code value for this map entry
786 +         * @see    #equals
787 +         */
788          public int hashCode() {
789 <            return ((key   == null)   ? 0 :   key.hashCode()) ^
790 <                   ((value == null)   ? 0 : value.hashCode());
789 >            return (key   == null ? 0 :   key.hashCode()) ^
790 >                   (value == null ? 0 : value.hashCode());
791          }
792  
793          /**

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines