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 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   public 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   public 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    */
 110   public boolean containsValue(Object value);
 111
 112   /**
 113    * Returns a set view of the mappings in this Map.  Each element in the
 114    * set is a Map.Entry.  The set is backed by the map, so that changes in
 115    * one show up in the other.  Modifications made while an iterator is
 116    * in progress cause undefined behavior.  If the set supports removal,
 117    * these methods remove the underlying mapping from the map:
 118    * <code>Iterator.remove</code>, <code>Set.remove</code>,
 119    * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
 120    * Element addition, via <code>add</code> or <code>addAll</code>, is
 121    * not supported via this set.
 122    *
 123    * @return the set view of all mapping entries
 124    * @see Map.Entry
 125    */
 126   public Set entrySet();
 127
 128   /**
 129    * Compares the specified object with this map for equality. Returns
 130    * <code>true</code> if the other object is a Map with the same mappings,
 131    * that is,<br>
 132    * <code>o instanceof Map && entrySet().equals(((Map) o).entrySet();</code>
 133    * This allows comparison of maps, regardless of implementation.
 134    *
 135    * @param o the object to be compared
 136    * @return true if the object equals this map
 137    * @see Set#equals(Object)
 138    */
 139   public boolean equals(Object o);
 140
 141   /**
 142    * Returns the value mapped by the given key. Returns <code>null</code> if
 143    * there is no mapping.  However, in Maps that accept null values, you
 144    * must rely on <code>containsKey</code> to determine if a mapping exists.
 145    *
 146    * @param key the key to look up
 147    * @return the value associated with the key, or null if key not in map
 148    * @throws ClassCastException if the key is an inappropriate type
 149    * @throws NullPointerException if this map does not accept null keys
 150    * @see #containsKey(Object)
 151    */
 152   public Object get(Object key);
 153
 154   /**
 155    * Associates the given key to the given value (optional operation). If the
 156    * map already contains the key, its value is replaced. Be aware that in
 157    * a map that permits <code>null</code> values, a null return does not
 158    * always imply that the mapping was created.
 159    *
 160    * @param key the key to map
 161    * @param value the value to be mapped
 162    * @return the previous value of the key, or null if there was no mapping
 163    * @throws UnsupportedOperationException if the operation is not supported
 164    * @throws ClassCastException if the key or value is of the wrong type
 165    * @throws IllegalArgumentException if something about this key or value
 166    *         prevents it from existing in this map
 167    * @throws NullPointerException if the map forbids null keys or values
 168    * @see #containsKey(Object)
 169    */
 170   public Object put(Object key, Object value);
 171
 172   /**
 173    * Returns the hash code for this map. This is the sum of all hashcodes
 174    * for each Map.Entry object in entrySet.  This allows comparison of maps,
 175    * regardless of implementation, and satisfies the contract of
 176    * Object.hashCode.
 177    *
 178    * @return the hash code
 179    * @see Map.Entry#hashCode()
 180    */
 181   public int hashCode();
 182
 183   /**
 184    * Returns true if the map contains no mappings.
 185    *
 186    * @return true if the map is empty
 187    */
 188   public boolean isEmpty();
 189
 190   /**
 191    * Returns a set view of the keys in this Map.  The set is backed by the
 192    * map, so that changes in one show up in the other.  Modifications made
 193    * while an iterator is in progress cause undefined behavior.  If the set
 194    * supports removal, these methods remove the underlying mapping from
 195    * the map: <code>Iterator.remove</code>, <code>Set.remove</code>,
 196    * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
 197    * Element addition, via <code>add</code> or <code>addAll</code>, is
 198    * not supported via this set.
 199    *
 200    * @return the set view of all keys
 201    */
 202   public Set keySet();
 203
 204   /**
 205    * Copies all entries of the given map to this one (optional operation). If
 206    * the map already contains a key, its value is replaced.
 207    *
 208    * @param m the mapping to load into this map
 209    * @throws UnsupportedOperationException if the operation is not supported
 210    * @throws ClassCastException if a key or value is of the wrong type
 211    * @throws IllegalArgumentException if something about a key or value
 212    *         prevents it from existing in this map
 213    * @throws NullPointerException if the map forbids null keys or values, or
 214    *         if <code>m</code> is null.
 215    * @see #put(Object, Object)
 216    */
 217   public void putAll(Map m);
 218
 219   /**
 220    * Removes the mapping for this key if present (optional operation). If
 221    * the key is not present, this returns null. Note that maps which permit
 222    * null values may also return null if the key was removed.
 223    *
 224    * @param key the key to remove
 225    * @return the value the key mapped to, or null if not present
 226    * @throws UnsupportedOperationException if deletion is unsupported
 227    */
 228   public Object remove(Object o);
 229
 230   /**
 231    * Returns the number of key-value mappings in the map. If there are more
 232    * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.
 233    *
 234    * @return the number of mappings
 235    */
 236   public int size();
 237
 238   /**
 239    * Returns a collection (or bag) view of the values in this Map.  The
 240    * collection is backed by the map, so that changes in one show up in
 241    * the other.  Modifications made while an iterator is in progress cause
 242    * undefined behavior.  If the collection supports removal, these methods
 243    * remove the underlying mapping from the map: <code>Iterator.remove</code>,
 244    * <code>Collection.remove</code>, <code>removeAll</code>,
 245    * <code>retainAll</code>, and <code>clear</code>. Element addition, via
 246    * <code>add</code> or <code>addAll</code>, is not supported via this
 247    * collection.
 248    *
 249    * @return the collection view of all values
 250    */
 251   public Collection values();
 252
 253   /**
 254    * A map entry (key-value pair). The Map.entrySet() method returns a set
 255    * view of these objects; there is no other valid way to come across them.
 256    * These objects are only valid for the duration of an iteration; in other
 257    * words, if you mess with one after modifying the map, you are asking
 258    * for undefined behavior.
 259    *
 260    * @author Original author unknown
 261    * @author Eric Blake <ebb9@email.byu.edu>
 262    * @see Map
 263    * @see Map#entrySet()
 264    * @since 1.2
 265    * @status updated to 1.4
 266    */
 267   public static interface Entry
 268   {
 269     /**
 270      * Get the key corresponding to this entry.
 271      *
 272      * @return the key
 273      */
 274     public Object getKey();
 275
 276     /**
 277      * Get the value corresponding to this entry. If you already called
 278      * Iterator.remove(), this is undefined.
 279      *
 280      * @return the value
 281      */
 282     public Object getValue();
 283
 284     /**
 285      * Replaces the value with the specified object (optional operation).
 286      * This writes through to the map, and is undefined if you already
 287      * called Iterator.remove().
 288      *
 289      * @param value the new value to store
 290      * @return the old value
 291      * @throws UnsupportedOperationException if the operation is not supported
 292      * @throws ClassCastException if the value is of the wrong type
 293      * @throws IllegalArgumentException if something about the value
 294      *         prevents it from existing in this map
 295      * @throws NullPointerException if the map forbids null values
 296      */
 297     public Object setValue(Object value);
 298
 299
 300     /**
 301      * Returns the hash code of the entry.  This is defined as the
 302      * exclusive-or of the hashcodes of the key and value (using 0 for
 303      * <code>null</code>). In other words, this must be:
 304      *
 305 <p><pre>(getKey() == null ? 0 : getKey().hashCode())
 306 ^ (getValue() == null ? 0 : getValue().hashCode())</pre>
 307      *
 308      * @return the hash code
 309      */
 310     public int hashCode();
 311
 312     /**
 313      * Compares the specified object with this entry. Returns true only if
 314      * the object is a mapping of identical key and value. In other words,
 315      * this must be:
 316      *
 317 <p><pre>(o instanceof Map.Entry)
 318 && (getKey() == null ? ((HashMap) o).getKey() == null
 319                      : getKey().equals(((HashMap) o).getKey()))
 320 && (getValue() == null ? ((HashMap) o).getValue() == null
 321                        : getValue().equals(((HashMap) o).getValue()))</pre>
 322      *
 323      * @param o the object to compare
 324      *
 325      * @return <code>true</code> if it is equal
 326      */
 327     public boolean equals(Object o);
 328   }
 329 }