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
005 This file is part of GNU Classpath.
006
007 GNU Classpath is free software; you can redistribute it and/or modify
008 it under the terms of the GNU General Public License as published by
009 the Free Software Foundation; either version 2, or (at your option)
010 any later version.
011
012 GNU Classpath is distributed in the hope that it will be useful, but
013 WITHOUT ANY WARRANTY; without even the implied warranty of
014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 General Public License for more details.
016
017 You should have received a copy of the GNU General Public License
018 along with GNU Classpath; see the file COPYING. If not, write to the
019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020 02110-1301 USA.
021
022 Linking this library statically or dynamically with other modules is
023 making a combined work based on this library. Thus, the terms and
024 conditions of the GNU General Public License cover the whole
025 combination.
026
027 As a special exception, the copyright holders of this library give you
028 permission to link this library with independent modules to produce an
029 executable, regardless of the license terms of these independent
030 modules, and to copy and distribute the resulting executable under
031 terms of your choice, provided that you also meet, for each linked
032 independent module, the terms and conditions of the license of that
033 module. An independent module is a module which is not derived from
034 or based on this library. If you modify this library, you may extend
035 this exception to your version of the library, but you are not
036 obligated to do so. If you do not wish to do so, delete this
037 exception statement from your version. */
038
039
040 package 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 */
081 public 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 }