Robust/src/ClassLibrary/MGC/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., 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   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   /* 0=keys, 1=values */
 196   public Iterator iterator(int type);
 197
 198   /**
 199    * Returns a set view of the keys in this Map.  The set is backed by the
 200    * map, so that changes in one show up in the other.  Modifications made
 201    * while an iterator is in progress cause undefined behavior.  If the set
 202    * supports removal, these methods remove the underlying mapping from
 203    * the map: <code>Iterator.remove</code>, <code>Set.remove</code>,
 204    * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
 205    * Element addition, via <code>add</code> or <code>addAll</code>, is
 206    * not supported via this set.
 207    *
 208    * @return the set view of all keys
 209    */
 210   //Set<K> keySet();
 211
 212   /**
 213    * Copies all entries of the given map to this one (optional operation). If
 214    * the map already contains a key, its value is replaced.
 215    *
 216    * @param m the mapping to load into this map
 217    * @throws UnsupportedOperationException if the operation is not supported
 218    * @throws ClassCastException if a key or value is of the wrong type
 219    * @throws IllegalArgumentException if something about a key or value
 220    *         prevents it from existing in this map
 221    * @throws NullPointerException if the map forbids null keys or values, or
 222    *         if <code>m</code> is null.
 223    * @see #put(Object, Object)
 224    */
 225   //void putAll(Map<? extends K, ? extends V> m);
 226
 227   /**
 228    * Removes the mapping for this key if present (optional operation). If
 229    * the key is not present, this returns null. Note that maps which permit
 230    * null values may also return null if the key was removed.
 231    *
 232    * @param key the key to remove
 233    * @return the value the key mapped to, or null if not present.
 234    * @throws UnsupportedOperationException if deletion is unsupported
 235    * @throws NullPointerException if the key is null and this map doesn't
 236    *         support null keys.
 237    * @throws ClassCastException if the type of the key is not a valid type
 238    *         for this map.
 239    */
 240   Object remove(Object o);
 241
 242   /**
 243    * Returns the number of key-value mappings in the map. If there are more
 244    * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.
 245    *
 246    * @return the number of mappings
 247    */
 248   int size();
 249
 250   Collection values();
 251 }