1 |
/* Map.java -- An object that maps keys to values |
/* Map.java: interface Map -- An object that maps keys to values |
2 |
Copyright (C) 1998 Free Software Foundation, Inc. |
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. |
This file is part of GNU Classpath. |
6 |
|
|
26 |
executable file might be covered by the GNU General Public License. */ |
executable file might be covered by the GNU General Public License. */ |
27 |
|
|
28 |
|
|
|
// TO DO: |
|
|
// ~ Doc comments for everything. |
|
|
|
|
29 |
package java.util; |
package java.util; |
30 |
|
|
31 |
|
/** |
32 |
|
* An object that maps keys onto values. Keys cannot be duplicated. This |
33 |
|
* interface replaces the obsolete {@link Dictionary} abstract class. |
34 |
|
* <p> |
35 |
|
* |
36 |
|
* The map has three collection views, which are backed by the map |
37 |
|
* (modifications on one show up on the other): a set of keys, a collection |
38 |
|
* of values, and a set of key-value mappings. Some maps have a guaranteed |
39 |
|
* order, but not all do. |
40 |
|
* <p> |
41 |
|
* |
42 |
|
* Note: Be careful about using mutable keys. Behavior is unspecified if |
43 |
|
* a key's comparison behavior is changed after the fact. As a corollary |
44 |
|
* to this rule, don't use a Map as one of its own keys or values, as it makes |
45 |
|
* hashCode and equals have undefined behavior. |
46 |
|
* <p> |
47 |
|
* |
48 |
|
* All maps are recommended to provide a no argument constructor, which builds |
49 |
|
* an empty map, and one that accepts a Map parameter and copies the mappings |
50 |
|
* (usually by putAll), to create an equivalent map. Unfortunately, Java |
51 |
|
* cannot enforce these suggestions. |
52 |
|
* <p> |
53 |
|
* |
54 |
|
* The map may be unmodifiable, in which case unsupported operations will |
55 |
|
* throw an UnsupportedOperationException. Note that some operations may be |
56 |
|
* safe, such as putAll(m) where m is empty, even if the operation would |
57 |
|
* normally fail with a non-empty argument. |
58 |
|
* |
59 |
|
* @author Original author unknown |
60 |
|
* @author Eric Blake <ebb9@email.byu.edu> |
61 |
|
* @see HashMap |
62 |
|
* @see TreeMap |
63 |
|
* @see Hashtable |
64 |
|
* @see SortedMap |
65 |
|
* @see Collection |
66 |
|
* @see Set |
67 |
|
* @since 1.2 |
68 |
|
* @status updated to 1.4 |
69 |
|
*/ |
70 |
public interface Map |
public interface Map |
71 |
{ |
{ |
72 |
|
/** |
73 |
|
* Remove all entries from this Map (optional operation). |
74 |
|
* |
75 |
|
* @throws UnsupportedOperationException if clear is not supported |
76 |
|
*/ |
77 |
public void clear(); |
public void clear(); |
78 |
|
|
79 |
|
/** |
80 |
|
* Returns true if this contains a mapping for the given key. |
81 |
|
* |
82 |
|
* @param key the key to search for |
83 |
|
* @return true if the map contains the key |
84 |
|
* @throws ClassCastException if the key is of an inappropriate type |
85 |
|
* @throws NullPointerException if key is <code>null</code> but the map |
86 |
|
* does not permit null keys |
87 |
|
*/ |
88 |
public boolean containsKey(Object key); |
public boolean containsKey(Object key); |
89 |
|
|
90 |
|
/** |
91 |
|
* Returns true if this contains at least one mapping with the given value. |
92 |
|
* In other words, returns true if a value v exists where |
93 |
|
* <code>(value == null ? v == null : value.equals(v))</code>. This usually |
94 |
|
* requires linear time. |
95 |
|
* |
96 |
|
* @param value the value to search for |
97 |
|
* @return true if the map contains the value |
98 |
|
*/ |
99 |
public boolean containsValue(Object value); |
public boolean containsValue(Object value); |
100 |
|
|
101 |
|
/** |
102 |
|
* Returns a set view of the mappings in this Map. Each element in the |
103 |
|
* set is a Map.Entry. The set is backed by the map, so that changes in |
104 |
|
* one show up in the other. Modifications made while an iterator is |
105 |
|
* in progress cause undefined behavior. If the set supports removal, |
106 |
|
* these methods remove the underlying mapping from the map: |
107 |
|
* <code>Iterator.remove</code>, <code>Set.remove</code>, |
108 |
|
* <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>. |
109 |
|
* Element addition, via <code>add</code> or <code>addAll</code>, is |
110 |
|
* not supported via this set. |
111 |
|
* |
112 |
|
* @return the set view of all mapping entries |
113 |
|
* @see Map.Entry |
114 |
|
*/ |
115 |
public Set entrySet(); |
public Set entrySet(); |
116 |
|
|
117 |
|
/** |
118 |
|
* Compares the specified object with this map for equality. Returns |
119 |
|
* <code>true</code> if the other object is a Map with the same mappings, |
120 |
|
* that is,<br> |
121 |
|
* <code>o instanceof Map && entrySet().equals(((Map) o).entrySet();</code> |
122 |
|
* This allows comparison of maps, regardless of implementation. |
123 |
|
* |
124 |
|
* @param o the object to be compared |
125 |
|
* @return true if the object equals this map |
126 |
|
* @see Set#equals(Object) |
127 |
|
*/ |
128 |
public boolean equals(Object o); |
public boolean equals(Object o); |
129 |
|
|
130 |
|
/** |
131 |
|
* Returns the value mapped by the given key. Returns <code>null</code> if |
132 |
|
* there is no mapping. However, in Maps that accept null values, you |
133 |
|
* must rely on <code>containsKey</code> to determine if a mapping exists. |
134 |
|
* |
135 |
|
* @param key the key to look up |
136 |
|
* @return the value associated with the key, or null if key not in map |
137 |
|
* @throws ClassCastException if the key is an inappropriate type |
138 |
|
* @throws NullPointerException if this map does not accept null keys |
139 |
|
* @see #containsKey(Object) |
140 |
|
*/ |
141 |
public Object get(Object key); |
public Object get(Object key); |
142 |
|
|
143 |
|
/** |
144 |
|
* Associates the given key to the given value (optional operation). If the |
145 |
|
* map already contains the key, its value is replaced. Be aware that in |
146 |
|
* a map that permits <code>null</code> values, a null return does not |
147 |
|
* always imply that the mapping was created. |
148 |
|
* |
149 |
|
* @param key the key to map |
150 |
|
* @param value the value to be mapped |
151 |
|
* @return the previous value of the key, or null if there was no mapping |
152 |
|
* @throws UnsupportedOperationException if the operation is not supported |
153 |
|
* @throws ClassCastException if the key or value is of the wrong type |
154 |
|
* @throws IllegalArgumentException if something about this key or value |
155 |
|
* prevents it from existing in this map |
156 |
|
* @throws NullPointerException if the map forbids null keys or values |
157 |
|
* @see #containsKey(Object) |
158 |
|
*/ |
159 |
public Object put(Object key, Object value); |
public Object put(Object key, Object value); |
160 |
|
|
161 |
|
/** |
162 |
|
* Returns the hash code for this map. This is the sum of all hashcodes |
163 |
|
* for each Map.Entry object in entrySet. This allows comparison of maps, |
164 |
|
* regardless of implementation, and satisfies the contract of |
165 |
|
* Object.hashCode. |
166 |
|
* |
167 |
|
* @return the hash code |
168 |
|
* @see Map.Entry#hashCode() |
169 |
|
*/ |
170 |
public int hashCode(); |
public int hashCode(); |
171 |
|
|
172 |
|
/** |
173 |
|
* Returns true if the map contains no mappings. |
174 |
|
* |
175 |
|
* @return true if the map is empty |
176 |
|
*/ |
177 |
public boolean isEmpty(); |
public boolean isEmpty(); |
178 |
|
|
179 |
|
/** |
180 |
|
* Returns a set view of the keys in this Map. The set is backed by the |
181 |
|
* map, so that changes in one show up in the other. Modifications made |
182 |
|
* while an iterator is in progress cause undefined behavior. If the set |
183 |
|
* supports removal, these methods remove the underlying mapping from |
184 |
|
* the map: <code>Iterator.remove</code>, <code>Set.remove</code>, |
185 |
|
* <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>. |
186 |
|
* Element addition, via <code>add</code> or <code>addAll</code>, is |
187 |
|
* not supported via this set. |
188 |
|
* |
189 |
|
* @return the set view of all keys |
190 |
|
*/ |
191 |
public Set keySet(); |
public Set keySet(); |
192 |
|
|
193 |
|
/** |
194 |
|
* Copies all entries of the given map to this one (optional operation). If |
195 |
|
* the map already contains a key, its value is replaced. |
196 |
|
* |
197 |
|
* @param m the mapping to load into this map |
198 |
|
* @throws UnsupportedOperationException if the operation is not supported |
199 |
|
* @throws ClassCastException if a key or value is of the wrong type |
200 |
|
* @throws IllegalArgumentException if something about a key or value |
201 |
|
* prevents it from existing in this map |
202 |
|
* @throws NullPointerException if the map forbids null keys or values, or |
203 |
|
* if <code>m</code> is null. |
204 |
|
* @see #put(Object, Object) |
205 |
|
*/ |
206 |
public void putAll(Map m); |
public void putAll(Map m); |
207 |
|
|
208 |
|
/** |
209 |
|
* Removes the mapping for this key if present (optional operation). If |
210 |
|
* the key is not present, this returns null. Note that maps which permit |
211 |
|
* null values may also return null if the key was removed. |
212 |
|
* |
213 |
|
* @param key the key to remove |
214 |
|
* @return the value the key mapped to, or null if not present |
215 |
|
* @throws UnsupportedOperationException if deletion is unsupported |
216 |
|
*/ |
217 |
public Object remove(Object o); |
public Object remove(Object o); |
218 |
|
|
219 |
|
/** |
220 |
|
* Returns the number of key-value mappings in the map. If there are more |
221 |
|
* than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE. |
222 |
|
* |
223 |
|
* @return the number of mappings |
224 |
|
*/ |
225 |
public int size(); |
public int size(); |
226 |
|
|
227 |
|
/** |
228 |
|
* Returns a collection (or bag) view of the values in this Map. The |
229 |
|
* collection is backed by the map, so that changes in one show up in |
230 |
|
* the other. Modifications made while an iterator is in progress cause |
231 |
|
* undefined behavior. If the collection supports removal, these methods |
232 |
|
* remove the underlying mapping from the map: <code>Iterator.remove</code>, |
233 |
|
* <code>Collection.remove</code>, <code>removeAll</code>, |
234 |
|
* <code>retainAll</code>, and <code>clear</code>. Element addition, via |
235 |
|
* <code>add</code> or <code>addAll</code>, is not supported via this |
236 |
|
* collection. |
237 |
|
* |
238 |
|
* @return the collection view of all values |
239 |
|
*/ |
240 |
public Collection values(); |
public Collection values(); |
241 |
|
|
242 |
|
/** |
243 |
|
* A map entry (key-value pair). The Map.entrySet() method returns a set |
244 |
|
* view of these objects; there is no other valid way to come across them. |
245 |
|
* These objects are only valid for the duration of an iteration; in other |
246 |
|
* words, if you mess with one after modifying the map, you are asking |
247 |
|
* for undefined behavior. |
248 |
|
* |
249 |
|
* @author Original author unknown |
250 |
|
* @author Eric Blake <ebb9@email.byu.edu> |
251 |
|
* @see Map |
252 |
|
* @see Map#entrySet() |
253 |
|
* @since 1.2 |
254 |
|
* @status updated to 1.4 |
255 |
|
*/ |
256 |
public static interface Entry |
public static interface Entry |
257 |
{ |
{ |
258 |
|
/** |
259 |
|
* Get the key corresponding to this entry. |
260 |
|
* |
261 |
|
* @return the key |
262 |
|
*/ |
263 |
public Object getKey(); |
public Object getKey(); |
264 |
|
|
265 |
|
/** |
266 |
|
* Get the value corresponding to this entry. If you already called |
267 |
|
* Iterator.remove(), this is undefined. |
268 |
|
* |
269 |
|
* @return the value |
270 |
|
*/ |
271 |
public Object getValue(); |
public Object getValue(); |
272 |
|
|
273 |
|
/** |
274 |
|
* Replaces the value with the specified object (optional operation). |
275 |
|
* This writes through to the map, and is undefined if you already |
276 |
|
* called Iterator.remove(). |
277 |
|
* |
278 |
|
* @param value the new value to store |
279 |
|
* @return the old value |
280 |
|
* @throws UnsupportedOperationException if the operation is not supported |
281 |
|
* @throws ClassCastException if the value is of the wrong type |
282 |
|
* @throws IllegalArgumentException if something about the value |
283 |
|
* prevents it from existing in this map |
284 |
|
* @throws NullPointerException if the map forbids null values |
285 |
|
*/ |
286 |
public Object setValue(Object value); |
public Object setValue(Object value); |
287 |
|
|
288 |
|
/** |
289 |
|
* Returns the hash code of the entry. This is defined as the exclusive-or |
290 |
|
* of the hashcodes of the key and value (using 0 for null). In other |
291 |
|
* words, this must be: |
292 |
|
* <pre> |
293 |
|
* (getKey() == null ? 0 : getKey().hashCode()) ^ |
294 |
|
* (getValue() == null ? 0 : getValue().hashCode()) |
295 |
|
* </pre> |
296 |
|
* |
297 |
|
* @return the hash code |
298 |
|
*/ |
299 |
public int hashCode(); |
public int hashCode(); |
300 |
|
|
301 |
|
/** |
302 |
|
* Compares the specified object with this entry. Returns true only if |
303 |
|
* the object is a mapping of identical key and value. In other words, |
304 |
|
* this must be: |
305 |
|
* <pre> |
306 |
|
* (o instanceof Map.Entry) |
307 |
|
* && (getKey() == null ? ((HashMap) o).getKey() == null |
308 |
|
* : getKey().equals(((HashMap) o).getKey())) |
309 |
|
* && (getValue() == null ? ((HashMap) o).getValue() == null |
310 |
|
* : getValue().equals(((HashMap) o).getValue())) |
311 |
|
* </pre> |
312 |
|
* |
313 |
|
* @param o the object to compare |
314 |
|
* @return true if it is equal |
315 |
|
*/ |
316 |
public boolean equals(Object o); |
public boolean equals(Object o); |
317 |
} |
} |
318 |
} |
} |