Source for java.util.Map

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  20: 02110-1301 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<K, V>
  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<Map.Entry<K, V>> 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:   V 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:   V put(K key, V 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<K> 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<? extends K, ? extends V> 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:   V remove(Object o);
 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<V> 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<K, V>
 277:   {
 278:     /**
 279:      * Get the key corresponding to this entry.
 280:      *
 281:      * @return the key
 282:      */
 283:     K 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:     V 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:     V setValue(V 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 ? ((Map.Entry) o).getKey() == null
 328:                      : getKey().equals(((Map.Entry) o).getKey()))
 329: && (getValue() == null ? ((Map.Entry) o).getValue() == null
 330:                        : getValue().equals(((Map.Entry) 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: }