History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/util/Map.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/util/Map.java+478−0
@@ -0,0 +1,478 @@
1+/*
2+ * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.util;
27+
28+/**
29+ * An object that maps keys to values. A map cannot contain duplicate keys;
30+ * each key can map to at most one value.
31+ *
32+ * <p>This interface takes the place of the <tt>Dictionary</tt> class, which
33+ * was a totally abstract class rather than an interface.
34+ *
35+ * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which
36+ * allow a map's contents to be viewed as a set of keys, collection of values,
37+ * or set of key-value mappings. The <i>order</i> of a map is defined as
38+ * the order in which the iterators on the map's collection views return their
39+ * elements. Some map implementations, like the <tt>TreeMap</tt> class, make
40+ * specific guarantees as to their order; others, like the <tt>HashMap</tt>
41+ * class, do not.
42+ *
43+ * <p>Note: great care must be exercised if mutable objects are used as map
44+ * keys. The behavior of a map is not specified if the value of an object is
45+ * changed in a manner that affects <tt>equals</tt> comparisons while the
46+ * object is a key in the map. A special case of this prohibition is that it
47+ * is not permissible for a map to contain itself as a key. While it is
48+ * permissible for a map to contain itself as a value, extreme caution is
49+ * advised: the <tt>equals</tt> and <tt>hashCode</tt> methods are no longer
50+ * well defined on such a map.
51+ *
52+ * <p>All general-purpose map implementation classes should provide two
53+ * "standard" constructors: a void (no arguments) constructor which creates an
54+ * empty map, and a constructor with a single argument of type <tt>Map</tt>,
55+ * which creates a new map with the same key-value mappings as its argument.
56+ * In effect, the latter constructor allows the user to copy any map,
57+ * producing an equivalent map of the desired class. There is no way to
58+ * enforce this recommendation (as interfaces cannot contain constructors) but
59+ * all of the general-purpose map implementations in the JDK comply.
60+ *
61+ * <p>The "destructive" methods contained in this interface, that is, the
62+ * methods that modify the map on which they operate, are specified to throw
63+ * <tt>UnsupportedOperationException</tt> if this map does not support the
64+ * operation. If this is the case, these methods may, but are not required
65+ * to, throw an <tt>UnsupportedOperationException</tt> if the invocation would
66+ * have no effect on the map. For example, invoking the {@link #putAll(Map)}
67+ * method on an unmodifiable map may, but is not required to, throw the
68+ * exception if the map whose mappings are to be "superimposed" is empty.
69+ *
70+ * <p>Some map implementations have restrictions on the keys and values they
71+ * may contain. For example, some implementations prohibit null keys and
72+ * values, and some have restrictions on the types of their keys. Attempting
73+ * to insert an ineligible key or value throws an unchecked exception,
74+ * typically <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.
75+ * Attempting to query the presence of an ineligible key or value may throw an
76+ * exception, or it may simply return false; some implementations will exhibit
77+ * the former behavior and some will exhibit the latter. More generally,
78+ * attempting an operation on an ineligible key or value whose completion
79+ * would not result in the insertion of an ineligible element into the map may
80+ * throw an exception or it may succeed, at the option of the implementation.
81+ * Such exceptions are marked as "optional" in the specification for this
82+ * interface.
83+ *
84+ * <p>This interface is a member of the
85+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
86+ * Java Collections Framework</a>.
87+ *
88+ * <p>Many methods in Collections Framework interfaces are defined
89+ * in terms of the {@link Object#equals(Object) equals} method. For
90+ * example, the specification for the {@link #containsKey(Object)
91+ * containsKey(Object key)} method says: "returns <tt>true</tt> if and
92+ * only if this map contains a mapping for a key <tt>k</tt> such that
93+ * <tt>(key==null ? k==null : key.equals(k))</tt>." This specification should
94+ * <i>not</i> be construed to imply that invoking <tt>Map.containsKey</tt>
95+ * with a non-null argument <tt>key</tt> will cause <tt>key.equals(k)</tt> to
96+ * be invoked for any key <tt>k</tt>. Implementations are free to
97+ * implement optimizations whereby the <tt>equals</tt> invocation is avoided,
98+ * for example, by first comparing the hash codes of the two keys. (The
99+ * {@link Object#hashCode()} specification guarantees that two objects with
100+ * unequal hash codes cannot be equal.) More generally, implementations of
101+ * the various Collections Framework interfaces are free to take advantage of
102+ * the specified behavior of underlying {@link Object} methods wherever the
103+ * implementor deems it appropriate.
104+ *
105+ * @param <K> the type of keys maintained by this map
106+ * @param <V> the type of mapped values
107+ *
108+ * @author Josh Bloch
109+ * @see HashMap
110+ * @see TreeMap
111+ * @see Hashtable
112+ * @see SortedMap
113+ * @see Collection
114+ * @see Set
115+ * @since 1.2
116+ */
117+public interface Map<K,V> {
118+ // Query Operations
119+
120+ /**
121+ * Returns the number of key-value mappings in this map. If the
122+ * map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
123+ * <tt>Integer.MAX_VALUE</tt>.
124+ *
125+ * @return the number of key-value mappings in this map
126+ */
127+ int size();
128+
129+ /**
130+ * Returns <tt>true</tt> if this map contains no key-value mappings.
131+ *
132+ * @return <tt>true</tt> if this map contains no key-value mappings
133+ */
134+ boolean isEmpty();
135+
136+ /**
137+ * Returns <tt>true</tt> if this map contains a mapping for the specified
138+ * key. More formally, returns <tt>true</tt> if and only if
139+ * this map contains a mapping for a key <tt>k</tt> such that
140+ * <tt>(key==null ? k==null : key.equals(k))</tt>. (There can be
141+ * at most one such mapping.)
142+ *
143+ * @param key key whose presence in this map is to be tested
144+ * @return <tt>true</tt> if this map contains a mapping for the specified
145+ * key
146+ * @throws ClassCastException if the key is of an inappropriate type for
147+ * this map
148+ * (<a href="Collection.html#optional-restrictions">optional</a>)
149+ * @throws NullPointerException if the specified key is null and this map
150+ * does not permit null keys
151+ * (<a href="Collection.html#optional-restrictions">optional</a>)
152+ */
153+ boolean containsKey(Object key);
154+
155+ /**
156+ * Returns <tt>true</tt> if this map maps one or more keys to the
157+ * specified value. More formally, returns <tt>true</tt> if and only if
158+ * this map contains at least one mapping to a value <tt>v</tt> such that
159+ * <tt>(value==null ? v==null : value.equals(v))</tt>. This operation
160+ * will probably require time linear in the map size for most
161+ * implementations of the <tt>Map</tt> interface.
162+ *
163+ * @param value value whose presence in this map is to be tested
164+ * @return <tt>true</tt> if this map maps one or more keys to the
165+ * specified value
166+ * @throws ClassCastException if the value is of an inappropriate type for
167+ * this map
168+ * (<a href="Collection.html#optional-restrictions">optional</a>)
169+ * @throws NullPointerException if the specified value is null and this
170+ * map does not permit null values
171+ * (<a href="Collection.html#optional-restrictions">optional</a>)
172+ */
173+ boolean containsValue(Object value);
174+
175+ /**
176+ * Returns the value to which the specified key is mapped,
177+ * or {@code null} if this map contains no mapping for the key.
178+ *
179+ * <p>More formally, if this map contains a mapping from a key
180+ * {@code k} to a value {@code v} such that {@code (key==null ? k==null :
181+ * key.equals(k))}, then this method returns {@code v}; otherwise
182+ * it returns {@code null}. (There can be at most one such mapping.)
183+ *
184+ * <p>If this map permits null values, then a return value of
185+ * {@code null} does not <i>necessarily</i> indicate that the map
186+ * contains no mapping for the key; it's also possible that the map
187+ * explicitly maps the key to {@code null}. The {@link #containsKey
188+ * containsKey} operation may be used to distinguish these two cases.
189+ *
190+ * @param key the key whose associated value is to be returned
191+ * @return the value to which the specified key is mapped, or
192+ * {@code null} if this map contains no mapping for the key
193+ * @throws ClassCastException if the key is of an inappropriate type for
194+ * this map
195+ * (<a href="Collection.html#optional-restrictions">optional</a>)
196+ * @throws NullPointerException if the specified key is null and this map
197+ * does not permit null keys
198+ * (<a href="Collection.html#optional-restrictions">optional</a>)
199+ */
200+ V get(Object key);
201+
202+ // Modification Operations
203+
204+ /**
205+ * Associates the specified value with the specified key in this map
206+ * (optional operation). If the map previously contained a mapping for
207+ * the key, the old value is replaced by the specified value. (A map
208+ * <tt>m</tt> is said to contain a mapping for a key <tt>k</tt> if and only
209+ * if {@link #containsKey(Object) m.containsKey(k)} would return
210+ * <tt>true</tt>.)
211+ *
212+ * @param key key with which the specified value is to be associated
213+ * @param value value to be associated with the specified key
214+ * @return the previous value associated with <tt>key</tt>, or
215+ * <tt>null</tt> if there was no mapping for <tt>key</tt>.
216+ * (A <tt>null</tt> return can also indicate that the map
217+ * previously associated <tt>null</tt> with <tt>key</tt>,
218+ * if the implementation supports <tt>null</tt> values.)
219+ * @throws UnsupportedOperationException if the <tt>put</tt> operation
220+ * is not supported by this map
221+ * @throws ClassCastException if the class of the specified key or value
222+ * prevents it from being stored in this map
223+ * @throws NullPointerException if the specified key or value is null
224+ * and this map does not permit null keys or values
225+ * @throws IllegalArgumentException if some property of the specified key
226+ * or value prevents it from being stored in this map
227+ */
228+ V put(K key, V value);
229+
230+ /**
231+ * Removes the mapping for a key from this map if it is present
232+ * (optional operation). More formally, if this map contains a mapping
233+ * from key <tt>k</tt> to value <tt>v</tt> such that
234+ * <code>(key==null ? k==null : key.equals(k))</code>, that mapping
235+ * is removed. (The map can contain at most one such mapping.)
236+ *
237+ * <p>Returns the value to which this map previously associated the key,
238+ * or <tt>null</tt> if the map contained no mapping for the key.
239+ *
240+ * <p>If this map permits null values, then a return value of
241+ * <tt>null</tt> does not <i>necessarily</i> indicate that the map
242+ * contained no mapping for the key; it's also possible that the map
243+ * explicitly mapped the key to <tt>null</tt>.
244+ *
245+ * <p>The map will not contain a mapping for the specified key once the
246+ * call returns.
247+ *
248+ * @param key key whose mapping is to be removed from the map
249+ * @return the previous value associated with <tt>key</tt>, or
250+ * <tt>null</tt> if there was no mapping for <tt>key</tt>.
251+ * @throws UnsupportedOperationException if the <tt>remove</tt> operation
252+ * is not supported by this map
253+ * @throws ClassCastException if the key is of an inappropriate type for
254+ * this map
255+ * (<a href="Collection.html#optional-restrictions">optional</a>)
256+ * @throws NullPointerException if the specified key is null and this
257+ * map does not permit null keys
258+ * (<a href="Collection.html#optional-restrictions">optional</a>)
259+ */
260+ V remove(Object key);
261+
262+
263+ // Bulk Operations
264+
265+ /**
266+ * Copies all of the mappings from the specified map to this map
267+ * (optional operation). The effect of this call is equivalent to that
268+ * of calling {@link #put(Object,Object) put(k, v)} on this map once
269+ * for each mapping from key <tt>k</tt> to value <tt>v</tt> in the
270+ * specified map. The behavior of this operation is undefined if the
271+ * specified map is modified while the operation is in progress.
272+ *
273+ * @param m mappings to be stored in this map
274+ * @throws UnsupportedOperationException if the <tt>putAll</tt> operation
275+ * is not supported by this map
276+ * @throws ClassCastException if the class of a key or value in the
277+ * specified map prevents it from being stored in this map
278+ * @throws NullPointerException if the specified map is null, or if
279+ * this map does not permit null keys or values, and the
280+ * specified map contains null keys or values
281+ * @throws IllegalArgumentException if some property of a key or value in
282+ * the specified map prevents it from being stored in this map
283+ */
284+ void putAll(Map<? extends K, ? extends V> m);
285+
286+ /**
287+ * Removes all of the mappings from this map (optional operation).
288+ * The map will be empty after this call returns.
289+ *
290+ * @throws UnsupportedOperationException if the <tt>clear</tt> operation
291+ * is not supported by this map
292+ */
293+ void clear();
294+
295+
296+ // Views
297+
298+ /**
299+ * Returns a {@link Set} view of the keys contained in this map.
300+ * The set is backed by the map, so changes to the map are
301+ * reflected in the set, and vice-versa. If the map is modified
302+ * while an iteration over the set is in progress (except through
303+ * the iterator's own <tt>remove</tt> operation), the results of
304+ * the iteration are undefined. The set supports element removal,
305+ * which removes the corresponding mapping from the map, via the
306+ * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
307+ * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
308+ * operations. It does not support the <tt>add</tt> or <tt>addAll</tt>
309+ * operations.
310+ *
311+ * @return a set view of the keys contained in this map
312+ */
313+ Set<K> keySet();
314+
315+ /**
316+ * Returns a {@link Collection} view of the values contained in this map.
317+ * The collection is backed by the map, so changes to the map are
318+ * reflected in the collection, and vice-versa. If the map is
319+ * modified while an iteration over the collection is in progress
320+ * (except through the iterator's own <tt>remove</tt> operation),
321+ * the results of the iteration are undefined. The collection
322+ * supports element removal, which removes the corresponding
323+ * mapping from the map, via the <tt>Iterator.remove</tt>,
324+ * <tt>Collection.remove</tt>, <tt>removeAll</tt>,
325+ * <tt>retainAll</tt> and <tt>clear</tt> operations. It does not
326+ * support the <tt>add</tt> or <tt>addAll</tt> operations.
327+ *
328+ * @return a collection view of the values contained in this map
329+ */
330+ Collection<V> values();
331+
332+ /**
333+ * Returns a {@link Set} view of the mappings contained in this map.
334+ * The set is backed by the map, so changes to the map are
335+ * reflected in the set, and vice-versa. If the map is modified
336+ * while an iteration over the set is in progress (except through
337+ * the iterator's own <tt>remove</tt> operation, or through the
338+ * <tt>setValue</tt> operation on a map entry returned by the
339+ * iterator) the results of the iteration are undefined. The set
340+ * supports element removal, which removes the corresponding
341+ * mapping from the map, via the <tt>Iterator.remove</tt>,
342+ * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
343+ * <tt>clear</tt> operations. It does not support the
344+ * <tt>add</tt> or <tt>addAll</tt> operations.
345+ *
346+ * @return a set view of the mappings contained in this map
347+ */
348+ Set<Map.Entry<K, V>> entrySet();
349+
350+ /**
351+ * A map entry (key-value pair). The <tt>Map.entrySet</tt> method returns
352+ * a collection-view of the map, whose elements are of this class. The
353+ * <i>only</i> way to obtain a reference to a map entry is from the
354+ * iterator of this collection-view. These <tt>Map.Entry</tt> objects are
355+ * valid <i>only</i> for the duration of the iteration; more formally,
356+ * the behavior of a map entry is undefined if the backing map has been
357+ * modified after the entry was returned by the iterator, except through
358+ * the <tt>setValue</tt> operation on the map entry.
359+ *
360+ * @see Map#entrySet()
361+ * @since 1.2
362+ */
363+ interface Entry<K,V> {
364+ /**
365+ * Returns the key corresponding to this entry.
366+ *
367+ * @return the key corresponding to this entry
368+ * @throws IllegalStateException implementations may, but are not
369+ * required to, throw this exception if the entry has been
370+ * removed from the backing map.
371+ */
372+ K getKey();
373+
374+ /**
375+ * Returns the value corresponding to this entry. If the mapping
376+ * has been removed from the backing map (by the iterator's
377+ * <tt>remove</tt> operation), the results of this call are undefined.
378+ *
379+ * @return the value corresponding to this entry
380+ * @throws IllegalStateException implementations may, but are not
381+ * required to, throw this exception if the entry has been
382+ * removed from the backing map.
383+ */
384+ V getValue();
385+
386+ /**
387+ * Replaces the value corresponding to this entry with the specified
388+ * value (optional operation). (Writes through to the map.) The
389+ * behavior of this call is undefined if the mapping has already been
390+ * removed from the map (by the iterator's <tt>remove</tt> operation).
391+ *
392+ * @param value new value to be stored in this entry
393+ * @return old value corresponding to the entry
394+ * @throws UnsupportedOperationException if the <tt>put</tt> operation
395+ * is not supported by the backing map
396+ * @throws ClassCastException if the class of the specified value
397+ * prevents it from being stored in the backing map
398+ * @throws NullPointerException if the backing map does not permit
399+ * null values, and the specified value is null
400+ * @throws IllegalArgumentException if some property of this value
401+ * prevents it from being stored in the backing map
402+ * @throws IllegalStateException implementations may, but are not
403+ * required to, throw this exception if the entry has been
404+ * removed from the backing map.
405+ */
406+ V setValue(V value);
407+
408+ /**
409+ * Compares the specified object with this entry for equality.
410+ * Returns <tt>true</tt> if the given object is also a map entry and
411+ * the two entries represent the same mapping. More formally, two
412+ * entries <tt>e1</tt> and <tt>e2</tt> represent the same mapping
413+ * if<pre>
414+ * (e1.getKey()==null ?
415+ * e2.getKey()==null : e1.getKey().equals(e2.getKey())) &amp;&amp;
416+ * (e1.getValue()==null ?
417+ * e2.getValue()==null : e1.getValue().equals(e2.getValue()))
418+ * </pre>
419+ * This ensures that the <tt>equals</tt> method works properly across
420+ * different implementations of the <tt>Map.Entry</tt> interface.
421+ *
422+ * @param o object to be compared for equality with this map entry
423+ * @return <tt>true</tt> if the specified object is equal to this map
424+ * entry
425+ */
426+ boolean equals(Object o);
427+
428+ /**
429+ * Returns the hash code value for this map entry. The hash code
430+ * of a map entry <tt>e</tt> is defined to be: <pre>
431+ * (e.getKey()==null ? 0 : e.getKey().hashCode()) ^
432+ * (e.getValue()==null ? 0 : e.getValue().hashCode())
433+ * </pre>
434+ * This ensures that <tt>e1.equals(e2)</tt> implies that
435+ * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries
436+ * <tt>e1</tt> and <tt>e2</tt>, as required by the general
437+ * contract of <tt>Object.hashCode</tt>.
438+ *
439+ * @return the hash code value for this map entry
440+ * @see Object#hashCode()
441+ * @see Object#equals(Object)
442+ * @see #equals(Object)
443+ */
444+ int hashCode();
445+ }
446+
447+ // Comparison and hashing
448+
449+ /**
450+ * Compares the specified object with this map for equality. Returns
451+ * <tt>true</tt> if the given object is also a map and the two maps
452+ * represent the same mappings. More formally, two maps <tt>m1</tt> and
453+ * <tt>m2</tt> represent the same mappings if
454+ * <tt>m1.entrySet().equals(m2.entrySet())</tt>. This ensures that the
455+ * <tt>equals</tt> method works properly across different implementations
456+ * of the <tt>Map</tt> interface.
457+ *
458+ * @param o object to be compared for equality with this map
459+ * @return <tt>true</tt> if the specified object is equal to this map
460+ */
461+ boolean equals(Object o);
462+
463+ /**
464+ * Returns the hash code value for this map. The hash code of a map is
465+ * defined to be the sum of the hash codes of each entry in the map's
466+ * <tt>entrySet()</tt> view. This ensures that <tt>m1.equals(m2)</tt>
467+ * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two maps
468+ * <tt>m1</tt> and <tt>m2</tt>, as required by the general contract of
469+ * {@link Object#hashCode}.
470+ *
471+ * @return the hash code value for this map
472+ * @see Map.Entry#hashCode()
473+ * @see Object#equals(Object)
474+ * @see #equals(Object)
475+ */
476+ int hashCode();
477+
478+}