libjava/java/util/Map.java

   1 /* Map.java: interface Map -- An object that maps keys to values
   2              interface Map.Entry -- an Entry in a Map
   3    Copyright (C) 1998, 2001, 2004, 2005  Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  20 02111-1307 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39
  40 package java.util;
  41
  42 /**
  43  * An object that maps keys onto values. Keys cannot be duplicated. This
  44  * interface replaces the obsolete {@link Dictionary} abstract class.
  45  * <p>
  46  *
  47  * The map has three collection views, which are backed by the map
  48  * (modifications on one show up on the other): a set of keys, a collection
  49  * of values, and a set of key-value mappings. Some maps have a guaranteed
  50  * order, but not all do.
  51  * <p>
  52  *
  53  * Note: Be careful about using mutable keys.  Behavior is unspecified if
  54  * a key's comparison behavior is changed after the fact.  As a corollary
  55  * to this rule, don't use a Map as one of its own keys or values, as it makes
  56  * hashCode and equals have undefined behavior.
  57  * <p>
  58  *
  59  * All maps are recommended to provide a no argument constructor, which builds
  60  * an empty map, and one that accepts a Map parameter and copies the mappings
  61  * (usually by putAll), to create an equivalent map.  Unfortunately, Java
  62  * cannot enforce these suggestions.
  63  * <p>
  64  *
  65  * The map may be unmodifiable, in which case unsupported operations will
  66  * throw an UnsupportedOperationException.  Note that some operations may be
  67  * safe, such as putAll(m) where m is empty, even if the operation would
  68  * normally fail with a non-empty argument.
  69  *
  70  * @author Original author unknown
  71  * @author Eric Blake (ebb9@email.byu.edu)
  72  * @see HashMap
  73  * @see TreeMap
  74  * @see Hashtable
  75  * @see SortedMap
  76  * @see Collection
  77  * @see Set
  78  * @since 1.2
  79  * @status updated to 1.4
  80  */
  81 public interface Map
  82 {
  83   /**
  84    * Remove all entries from this Map (optional operation).
  85    *
  86    * @throws UnsupportedOperationException if clear is not supported
  87    */
  88   void clear();
  89
  90   /**
  91    * Returns true if this contains a mapping for the given key.
  92    *
  93    * @param key the key to search for
  94    * @return true if the map contains the key
  95    * @throws ClassCastException if the key is of an inappropriate type
  96    * @throws NullPointerException if key is <code>null</code> but the map
  97    *         does not permit null keys
  98    */
  99   boolean containsKey(Object key);
 100
 101   /**
 102    * Returns true if this contains at least one mapping with the given value.
 103    * In other words, returns true if a value v exists where
 104    * <code>(value == null ? v == null : value.equals(v))</code>. This usually
 105    * requires linear time.
 106    *
 107    * @param value the value to search for
 108    * @return true if the map contains the value
 109    * @throws ClassCastException if the type of the value is not a valid type
 110    *         for this map.
 111    * @throws NullPointerException if the value is null and the map doesn't
 112    *         support null values.
 113    */
 114   boolean containsValue(Object value);
 115
 116   /**
 117    * Returns a set view of the mappings in this Map.  Each element in the
 118    * set is a Map.Entry.  The set is backed by the map, so that changes in
 119    * one show up in the other.  Modifications made while an iterator is
 120    * in progress cause undefined behavior.  If the set supports removal,
 121    * these methods remove the underlying mapping from the map:
 122    * <code>Iterator.remove</code>, <code>Set.remove</code>,
 123    * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
 124    * Element addition, via <code>add</code> or <code>addAll</code>, is
 125    * not supported via this set.
 126    *
 127    * @return the set view of all mapping entries
 128    * @see Map.Entry
 129    */
 130   Set entrySet();
 131
 132   /**
 133    * Compares the specified object with this map for equality. Returns
 134    * <code>true</code> if the other object is a Map with the same mappings,
 135    * that is,<br>
 136    * <code>o instanceof Map && entrySet().equals(((Map) o).entrySet();</code>
 137    * This allows comparison of maps, regardless of implementation.
 138    *
 139    * @param o the object to be compared
 140    * @return true if the object equals this map
 141    * @see Set#equals(Object)
 142    */
 143   boolean equals(Object o);
 144
 145   /**
 146    * Returns the value mapped by the given key. Returns <code>null</code> if
 147    * there is no mapping.  However, in Maps that accept null values, you
 148    * must rely on <code>containsKey</code> to determine if a mapping exists.
 149    *
 150    * @param key the key to look up
 151    * @return the value associated with the key, or null if key not in map
 152    * @throws ClassCastException if the key is an inappropriate type
 153    * @throws NullPointerException if this map does not accept null keys
 154    * @see #containsKey(Object)
 155    */
 156   Object get(Object key);
 157
 158   /**
 159    * Associates the given key to the given value (optional operation). If the
 160    * map already contains the key, its value is replaced. Be aware that in
 161    * a map that permits <code>null</code> values, a null return does not
 162    * always imply that the mapping was created.
 163    *
 164    * @param key the key to map
 165    * @param value the value to be mapped
 166    * @return the previous value of the key, or null if there was no mapping
 167    * @throws UnsupportedOperationException if the operation is not supported
 168    * @throws ClassCastException if the key or value is of the wrong type
 169    * @throws IllegalArgumentException if something about this key or value
 170    *         prevents it from existing in this map
 171    * @throws NullPointerException if either the key or the value is null,
 172    *         and the map forbids null keys or values
 173    * @see #containsKey(Object)
 174    */
 175   Object put(Object key, Object value);
 176
 177   /**
 178    * Returns the hash code for this map. This is the sum of all hashcodes
 179    * for each Map.Entry object in entrySet.  This allows comparison of maps,
 180    * regardless of implementation, and satisfies the contract of
 181    * Object.hashCode.
 182    *
 183    * @return the hash code
 184    * @see Map.Entry#hashCode()
 185    */
 186   int hashCode();
 187
 188   /**
 189    * Returns true if the map contains no mappings.
 190    *
 191    * @return true if the map is empty
 192    */
 193   boolean isEmpty();
 194
 195   /**
 196    * Returns a set view of the keys in this Map.  The set is backed by the
 197    * map, so that changes in one show up in the other.  Modifications made
 198    * while an iterator is in progress cause undefined behavior.  If the set
 199    * supports removal, these methods remove the underlying mapping from
 200    * the map: <code>Iterator.remove</code>, <code>Set.remove</code>,
 201    * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
 202    * Element addition, via <code>add</code> or <code>addAll</code>, is
 203    * not supported via this set.
 204    *
 205    * @return the set view of all keys
 206    */
 207   Set keySet();
 208
 209   /**
 210    * Copies all entries of the given map to this one (optional operation). If
 211    * the map already contains a key, its value is replaced.
 212    *
 213    * @param m the mapping to load into this map
 214    * @throws UnsupportedOperationException if the operation is not supported
 215    * @throws ClassCastException if a key or value is of the wrong type
 216    * @throws IllegalArgumentException if something about a key or value
 217    *         prevents it from existing in this map
 218    * @throws NullPointerException if the map forbids null keys or values, or
 219    *         if <code>m</code> is null.
 220    * @see #put(Object, Object)
 221    */
 222   void putAll(Map m);
 223
 224   /**
 225    * Removes the mapping for this key if present (optional operation). If
 226    * the key is not present, this returns null. Note that maps which permit
 227    * null values may also return null if the key was removed.
 228    *
 229    * @param key the key to remove
 230    * @return the value the key mapped to, or null if not present.
 231    * @throws UnsupportedOperationException if deletion is unsupported
 232    * @throws NullPointerException if the key is null and this map doesn't
 233    *         support null keys.
 234    * @throws ClassCastException if the type of the key is not a valid type
 235    *         for this map.
 236    */
 237   Object remove(Object key);
 238
 239   /**
 240    * Returns the number of key-value mappings in the map. If there are more
 241    * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.
 242    *
 243    * @return the number of mappings
 244    */
 245   int size();
 246
 247   /**
 248    * Returns a collection (or bag) view of the values in this Map.  The
 249    * collection is backed by the map, so that changes in one show up in
 250    * the other.  Modifications made while an iterator is in progress cause
 251    * undefined behavior.  If the collection supports removal, these methods
 252    * remove the underlying mapping from the map: <code>Iterator.remove</code>,
 253    * <code>Collection.remove</code>, <code>removeAll</code>,
 254    * <code>retainAll</code>, and <code>clear</code>. Element addition, via
 255    * <code>add</code> or <code>addAll</code>, is not supported via this
 256    * collection.
 257    *
 258    * @return the collection view of all values
 259    */
 260   Collection values();
 261
 262   /**
 263    * A map entry (key-value pair). The Map.entrySet() method returns a set
 264    * view of these objects; there is no other valid way to come across them.
 265    * These objects are only valid for the duration of an iteration; in other
 266    * words, if you mess with one after modifying the map, you are asking
 267    * for undefined behavior.
 268    *
 269    * @author Original author unknown
 270    * @author Eric Blake (ebb9@email.byu.edu)
 271    * @see Map
 272    * @see Map#entrySet()
 273    * @since 1.2
 274    * @status updated to 1.4
 275    */
 276   interface Entry
 277   {
 278     /**
 279      * Get the key corresponding to this entry.
 280      *
 281      * @return the key
 282      */
 283     Object getKey();
 284
 285     /**
 286      * Get the value corresponding to this entry. If you already called
 287      * Iterator.remove(), this is undefined.
 288      *
 289      * @return the value
 290      */
 291     Object getValue();
 292
 293     /**
 294      * Replaces the value with the specified object (optional operation).
 295      * This writes through to the map, and is undefined if you already
 296      * called Iterator.remove().
 297      *
 298      * @param value the new value to store
 299      * @return the old value
 300      * @throws UnsupportedOperationException if the operation is not supported
 301      * @throws ClassCastException if the value is of the wrong type
 302      * @throws IllegalArgumentException if something about the value
 303      *         prevents it from existing in this map
 304      * @throws NullPointerException if the map forbids null values
 305      */
 306     Object setValue(Object value);
 307
 308
 309     /**
 310      * Returns the hash code of the entry.  This is defined as the
 311      * exclusive-or of the hashcodes of the key and value (using 0 for
 312      * <code>null</code>). In other words, this must be:
 313      *
 314 <p><pre>(getKey() == null ? 0 : getKey().hashCode())
 315 ^ (getValue() == null ? 0 : getValue().hashCode())</pre>
 316      *
 317      * @return the hash code
 318      */
 319     int hashCode();
 320
 321     /**
 322      * Compares the specified object with this entry. Returns true only if
 323      * the object is a mapping of identical key and value. In other words,
 324      * this must be:
 325      *
 326 <p><pre>(o instanceof Map.Entry)
 327 && (getKey() == null ? ((HashMap) o).getKey() == null
 328                      : getKey().equals(((HashMap) o).getKey()))
 329 && (getValue() == null ? ((HashMap) o).getValue() == null
 330                        : getValue().equals(((HashMap) o).getValue()))</pre>
 331      *
 332      * @param o the object to compare
 333      *
 334      * @return <code>true</code> if it is equal
 335      */
 336     boolean equals(Object o);
 337   }
 338 }