src/share/classes/java/util/Map.java

Print this page
rev 7485 : 8009736: Comparator API cleanup
Reviewed-by:
Contributed-by: henry.jen@oracle.com


  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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 import java.util.function.BiConsumer;
  29 import java.util.function.BiFunction;
  30 import java.util.function.Function;

  31 
  32 /**
  33  * An object that maps keys to values.  A map cannot contain duplicate keys;
  34  * each key can map to at most one value.
  35  *
  36  * <p>This interface takes the place of the <tt>Dictionary</tt> class, which
  37  * was a totally abstract class rather than an interface.
  38  *
  39  * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which
  40  * allow a map's contents to be viewed as a set of keys, collection of values,
  41  * or set of key-value mappings.  The <i>order</i> of a map is defined as
  42  * the order in which the iterators on the map's collection views return their
  43  * elements.  Some map implementations, like the <tt>TreeMap</tt> class, make
  44  * specific guarantees as to their order; others, like the <tt>HashMap</tt>
  45  * class, do not.
  46  *
  47  * <p>Note: great care must be exercised if mutable objects are used as map
  48  * keys.  The behavior of a map is not specified if the value of an object is
  49  * changed in a manner that affects <tt>equals</tt> comparisons while the
  50  * object is a key in the map.  A special case of this prohibition is that it


 429          */
 430         boolean equals(Object o);
 431 
 432         /**
 433          * Returns the hash code value for this map entry.  The hash code
 434          * of a map entry <tt>e</tt> is defined to be: <pre>
 435          *     (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
 436          *     (e.getValue()==null ? 0 : e.getValue().hashCode())
 437          * </pre>
 438          * This ensures that <tt>e1.equals(e2)</tt> implies that
 439          * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries
 440          * <tt>e1</tt> and <tt>e2</tt>, as required by the general
 441          * contract of <tt>Object.hashCode</tt>.
 442          *
 443          * @return the hash code value for this map entry
 444          * @see Object#hashCode()
 445          * @see Object#equals(Object)
 446          * @see #equals(Object)
 447          */
 448         int hashCode();




































































 449     }
 450 
 451     // Comparison and hashing
 452 
 453     /**
 454      * Compares the specified object with this map for equality.  Returns
 455      * <tt>true</tt> if the given object is also a map and the two maps
 456      * represent the same mappings.  More formally, two maps <tt>m1</tt> and
 457      * <tt>m2</tt> represent the same mappings if
 458      * <tt>m1.entrySet().equals(m2.entrySet())</tt>.  This ensures that the
 459      * <tt>equals</tt> method works properly across different implementations
 460      * of the <tt>Map</tt> interface.
 461      *
 462      * @param o object to be compared for equality with this map
 463      * @return <tt>true</tt> if the specified object is equal to this map
 464      */
 465     boolean equals(Object o);
 466 
 467     /**
 468      * Returns the hash code value for this map.  The hash code of a map is




  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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 import java.util.function.BiConsumer;
  29 import java.util.function.BiFunction;
  30 import java.util.function.Function;
  31 import java.io.Serializable;
  32 
  33 /**
  34  * An object that maps keys to values.  A map cannot contain duplicate keys;
  35  * each key can map to at most one value.
  36  *
  37  * <p>This interface takes the place of the <tt>Dictionary</tt> class, which
  38  * was a totally abstract class rather than an interface.
  39  *
  40  * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which
  41  * allow a map's contents to be viewed as a set of keys, collection of values,
  42  * or set of key-value mappings.  The <i>order</i> of a map is defined as
  43  * the order in which the iterators on the map's collection views return their
  44  * elements.  Some map implementations, like the <tt>TreeMap</tt> class, make
  45  * specific guarantees as to their order; others, like the <tt>HashMap</tt>
  46  * class, do not.
  47  *
  48  * <p>Note: great care must be exercised if mutable objects are used as map
  49  * keys.  The behavior of a map is not specified if the value of an object is
  50  * changed in a manner that affects <tt>equals</tt> comparisons while the
  51  * object is a key in the map.  A special case of this prohibition is that it


 430          */
 431         boolean equals(Object o);
 432 
 433         /**
 434          * Returns the hash code value for this map entry.  The hash code
 435          * of a map entry <tt>e</tt> is defined to be: <pre>
 436          *     (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
 437          *     (e.getValue()==null ? 0 : e.getValue().hashCode())
 438          * </pre>
 439          * This ensures that <tt>e1.equals(e2)</tt> implies that
 440          * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries
 441          * <tt>e1</tt> and <tt>e2</tt>, as required by the general
 442          * contract of <tt>Object.hashCode</tt>.
 443          *
 444          * @return the hash code value for this map entry
 445          * @see Object#hashCode()
 446          * @see Object#equals(Object)
 447          * @see #equals(Object)
 448          */
 449         int hashCode();
 450 
 451         /**
 452          * Returns a comparator that compares {@link Map.Entry} in natural order on key.
 453          *
 454          * <p>The returned comparator is serializable and throws {@link
 455          * NullPointerException} when comparing a map with a null key.
 456          *
 457          * @param  <K> {@link Comparable} key type
 458          * @param  <V> value type
 459          * @return A comparator that compares {@link Map.Entry} in natural order on key.
 460          * @see Comparable
 461          */
 462         public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K,V>> comparingByKey() {
 463             return (Comparator<Map.Entry<K, V>> & Serializable)
 464                 (c1, c2) -> c1.getKey().compareTo(c2.getKey());
 465         }
 466 
 467         /**
 468          * Returns a comparator that compares {@link Map.Entry} in natural order on value.
 469          *
 470          * <p>The returned comparator is serializable and throws {@link
 471          * NullPointerException} when comparing a map with null values.
 472          *
 473          * @param <K> key type
 474          * @param <V> {@link Comparable} value type
 475          * @return A comparator that compares {@link Map.Entry} in natural order on value.
 476          * @see Comparable
 477          */
 478         public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K,V>> comparingByValue() {
 479             return (Comparator<Map.Entry<K, V>> & Serializable)
 480                 (c1, c2) -> c1.getValue().compareTo(c2.getValue());
 481         }
 482 
 483         /**
 484          * Returns a comparator that compares {@link Map.Entry} by key using the given
 485          * {@link Comparator}.
 486          *
 487          * <p>The returned comparator is serializable if the specified comparator
 488          * is also serializable.
 489          *
 490          * @param  <K> key type
 491          * @param  <V> value type
 492          * @param  cmp the key {@link Comparator}
 493          * @return A comparator that compares {@link Map.Entry} by the key.
 494          */
 495         public static <K, V> Comparator<Map.Entry<K, V>> comparingByKey(Comparator<? super K> cmp) {
 496             Objects.requireNonNull(cmp);
 497             return (Comparator<Map.Entry<K, V>> & Serializable)
 498                 (c1, c2) -> cmp.compare(c1.getKey(), c2.getKey());
 499         }
 500 
 501         /**
 502          * Returns a comparator that compares {@link Map.Entry} by value using the given
 503          * {@link Comparator}.
 504          *
 505          * <p>The returned comparator is serializable if the specified comparator
 506          * is also serializable.
 507          *
 508          * @param  <K> key type
 509          * @param  <V> value type
 510          * @param  cmp the value {@link Comparator}
 511          * @return A comparator that compares {@link Map.Entry} by the value.
 512          */
 513         public static <K, V> Comparator<Map.Entry<K, V>> comparingByValue(Comparator<? super V> cmp) {
 514             Objects.requireNonNull(cmp);
 515             return (Comparator<Map.Entry<K, V>> & Serializable)
 516                 (c1, c2) -> cmp.compare(c1.getValue(), c2.getValue());
 517         }
 518     }
 519 
 520     // Comparison and hashing
 521 
 522     /**
 523      * Compares the specified object with this map for equality.  Returns
 524      * <tt>true</tt> if the given object is also a map and the two maps
 525      * represent the same mappings.  More formally, two maps <tt>m1</tt> and
 526      * <tt>m2</tt> represent the same mappings if
 527      * <tt>m1.entrySet().equals(m2.entrySet())</tt>.  This ensures that the
 528      * <tt>equals</tt> method works properly across different implementations
 529      * of the <tt>Map</tt> interface.
 530      *
 531      * @param o object to be compared for equality with this map
 532      * @return <tt>true</tt> if the specified object is equal to this map
 533      */
 534     boolean equals(Object o);
 535 
 536     /**
 537      * Returns the hash code value for this map.  The hash code of a map is