001/* Map.java: interface Map -- An object that maps keys to values 002 interface Map.Entry -- an Entry in a Map 003 Copyright (C) 1998, 2001, 2004, 2005 Free Software Foundation, Inc. 004 005This file is part of GNU Classpath. 006 007GNU Classpath is free software; you can redistribute it and/or modify 008it under the terms of the GNU General Public License as published by 009the Free Software Foundation; either version 2, or (at your option) 010any later version. 011 012GNU Classpath is distributed in the hope that it will be useful, but 013WITHOUT ANY WARRANTY; without even the implied warranty of 014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015General Public License for more details. 016 017You should have received a copy of the GNU General Public License 018along with GNU Classpath; see the file COPYING. If not, write to the 019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02002110-1301 USA. 021 022Linking this library statically or dynamically with other modules is 023making a combined work based on this library. Thus, the terms and 024conditions of the GNU General Public License cover the whole 025combination. 026 027As a special exception, the copyright holders of this library give you 028permission to link this library with independent modules to produce an 029executable, regardless of the license terms of these independent 030modules, and to copy and distribute the resulting executable under 031terms of your choice, provided that you also meet, for each linked 032independent module, the terms and conditions of the license of that 033module. An independent module is a module which is not derived from 034or based on this library. If you modify this library, you may extend 035this exception to your version of the library, but you are not 036obligated to do so. If you do not wish to do so, delete this 037exception statement from your version. */ 038 039 040package java.util; 041 042/** 043 * An object that maps keys onto values. Keys cannot be duplicated. This 044 * interface replaces the obsolete {@link Dictionary} abstract class. 045 * <p> 046 * 047 * The map has three collection views, which are backed by the map 048 * (modifications on one show up on the other): a set of keys, a collection 049 * of values, and a set of key-value mappings. Some maps have a guaranteed 050 * order, but not all do. 051 * <p> 052 * 053 * Note: Be careful about using mutable keys. Behavior is unspecified if 054 * a key's comparison behavior is changed after the fact. As a corollary 055 * to this rule, don't use a Map as one of its own keys or values, as it makes 056 * hashCode and equals have undefined behavior. 057 * <p> 058 * 059 * All maps are recommended to provide a no argument constructor, which builds 060 * an empty map, and one that accepts a Map parameter and copies the mappings 061 * (usually by putAll), to create an equivalent map. Unfortunately, Java 062 * cannot enforce these suggestions. 063 * <p> 064 * 065 * The map may be unmodifiable, in which case unsupported operations will 066 * throw an UnsupportedOperationException. Note that some operations may be 067 * safe, such as putAll(m) where m is empty, even if the operation would 068 * normally fail with a non-empty argument. 069 * 070 * @author Original author unknown 071 * @author Eric Blake (ebb9@email.byu.edu) 072 * @see HashMap 073 * @see TreeMap 074 * @see Hashtable 075 * @see SortedMap 076 * @see Collection 077 * @see Set 078 * @since 1.2 079 * @status updated to 1.4 080 */ 081public interface Map<K, V> 082{ 083 /** 084 * Remove all entries from this Map (optional operation). 085 * 086 * @throws UnsupportedOperationException if clear is not supported 087 */ 088 void clear(); 089 090 /** 091 * Returns true if this contains a mapping for the given key. 092 * 093 * @param key the key to search for 094 * @return true if the map contains the key 095 * @throws ClassCastException if the key is of an inappropriate type 096 * @throws NullPointerException if key is <code>null</code> but the map 097 * does not permit null keys 098 */ 099 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}