1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/Map.java Tue Feb 26 16:54:16 2013 +0100
1.3 @@ -0,0 +1,478 @@
1.4 +/*
1.5 + * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package java.util;
1.30 +
1.31 +/**
1.32 + * An object that maps keys to values. A map cannot contain duplicate keys;
1.33 + * each key can map to at most one value.
1.34 + *
1.35 + * <p>This interface takes the place of the <tt>Dictionary</tt> class, which
1.36 + * was a totally abstract class rather than an interface.
1.37 + *
1.38 + * <p>The <tt>Map</tt> interface provides three <i>collection views</i>, which
1.39 + * allow a map's contents to be viewed as a set of keys, collection of values,
1.40 + * or set of key-value mappings. The <i>order</i> of a map is defined as
1.41 + * the order in which the iterators on the map's collection views return their
1.42 + * elements. Some map implementations, like the <tt>TreeMap</tt> class, make
1.43 + * specific guarantees as to their order; others, like the <tt>HashMap</tt>
1.44 + * class, do not.
1.45 + *
1.46 + * <p>Note: great care must be exercised if mutable objects are used as map
1.47 + * keys. The behavior of a map is not specified if the value of an object is
1.48 + * changed in a manner that affects <tt>equals</tt> comparisons while the
1.49 + * object is a key in the map. A special case of this prohibition is that it
1.50 + * is not permissible for a map to contain itself as a key. While it is
1.51 + * permissible for a map to contain itself as a value, extreme caution is
1.52 + * advised: the <tt>equals</tt> and <tt>hashCode</tt> methods are no longer
1.53 + * well defined on such a map.
1.54 + *
1.55 + * <p>All general-purpose map implementation classes should provide two
1.56 + * "standard" constructors: a void (no arguments) constructor which creates an
1.57 + * empty map, and a constructor with a single argument of type <tt>Map</tt>,
1.58 + * which creates a new map with the same key-value mappings as its argument.
1.59 + * In effect, the latter constructor allows the user to copy any map,
1.60 + * producing an equivalent map of the desired class. There is no way to
1.61 + * enforce this recommendation (as interfaces cannot contain constructors) but
1.62 + * all of the general-purpose map implementations in the JDK comply.
1.63 + *
1.64 + * <p>The "destructive" methods contained in this interface, that is, the
1.65 + * methods that modify the map on which they operate, are specified to throw
1.66 + * <tt>UnsupportedOperationException</tt> if this map does not support the
1.67 + * operation. If this is the case, these methods may, but are not required
1.68 + * to, throw an <tt>UnsupportedOperationException</tt> if the invocation would
1.69 + * have no effect on the map. For example, invoking the {@link #putAll(Map)}
1.70 + * method on an unmodifiable map may, but is not required to, throw the
1.71 + * exception if the map whose mappings are to be "superimposed" is empty.
1.72 + *
1.73 + * <p>Some map implementations have restrictions on the keys and values they
1.74 + * may contain. For example, some implementations prohibit null keys and
1.75 + * values, and some have restrictions on the types of their keys. Attempting
1.76 + * to insert an ineligible key or value throws an unchecked exception,
1.77 + * typically <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.
1.78 + * Attempting to query the presence of an ineligible key or value may throw an
1.79 + * exception, or it may simply return false; some implementations will exhibit
1.80 + * the former behavior and some will exhibit the latter. More generally,
1.81 + * attempting an operation on an ineligible key or value whose completion
1.82 + * would not result in the insertion of an ineligible element into the map may
1.83 + * throw an exception or it may succeed, at the option of the implementation.
1.84 + * Such exceptions are marked as "optional" in the specification for this
1.85 + * interface.
1.86 + *
1.87 + * <p>This interface is a member of the
1.88 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
1.89 + * Java Collections Framework</a>.
1.90 + *
1.91 + * <p>Many methods in Collections Framework interfaces are defined
1.92 + * in terms of the {@link Object#equals(Object) equals} method. For
1.93 + * example, the specification for the {@link #containsKey(Object)
1.94 + * containsKey(Object key)} method says: "returns <tt>true</tt> if and
1.95 + * only if this map contains a mapping for a key <tt>k</tt> such that
1.96 + * <tt>(key==null ? k==null : key.equals(k))</tt>." This specification should
1.97 + * <i>not</i> be construed to imply that invoking <tt>Map.containsKey</tt>
1.98 + * with a non-null argument <tt>key</tt> will cause <tt>key.equals(k)</tt> to
1.99 + * be invoked for any key <tt>k</tt>. Implementations are free to
1.100 + * implement optimizations whereby the <tt>equals</tt> invocation is avoided,
1.101 + * for example, by first comparing the hash codes of the two keys. (The
1.102 + * {@link Object#hashCode()} specification guarantees that two objects with
1.103 + * unequal hash codes cannot be equal.) More generally, implementations of
1.104 + * the various Collections Framework interfaces are free to take advantage of
1.105 + * the specified behavior of underlying {@link Object} methods wherever the
1.106 + * implementor deems it appropriate.
1.107 + *
1.108 + * @param <K> the type of keys maintained by this map
1.109 + * @param <V> the type of mapped values
1.110 + *
1.111 + * @author Josh Bloch
1.112 + * @see HashMap
1.113 + * @see TreeMap
1.114 + * @see Hashtable
1.115 + * @see SortedMap
1.116 + * @see Collection
1.117 + * @see Set
1.118 + * @since 1.2
1.119 + */
1.120 +public interface Map<K,V> {
1.121 + // Query Operations
1.122 +
1.123 + /**
1.124 + * Returns the number of key-value mappings in this map. If the
1.125 + * map contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
1.126 + * <tt>Integer.MAX_VALUE</tt>.
1.127 + *
1.128 + * @return the number of key-value mappings in this map
1.129 + */
1.130 + int size();
1.131 +
1.132 + /**
1.133 + * Returns <tt>true</tt> if this map contains no key-value mappings.
1.134 + *
1.135 + * @return <tt>true</tt> if this map contains no key-value mappings
1.136 + */
1.137 + boolean isEmpty();
1.138 +
1.139 + /**
1.140 + * Returns <tt>true</tt> if this map contains a mapping for the specified
1.141 + * key. More formally, returns <tt>true</tt> if and only if
1.142 + * this map contains a mapping for a key <tt>k</tt> such that
1.143 + * <tt>(key==null ? k==null : key.equals(k))</tt>. (There can be
1.144 + * at most one such mapping.)
1.145 + *
1.146 + * @param key key whose presence in this map is to be tested
1.147 + * @return <tt>true</tt> if this map contains a mapping for the specified
1.148 + * key
1.149 + * @throws ClassCastException if the key is of an inappropriate type for
1.150 + * this map
1.151 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.152 + * @throws NullPointerException if the specified key is null and this map
1.153 + * does not permit null keys
1.154 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.155 + */
1.156 + boolean containsKey(Object key);
1.157 +
1.158 + /**
1.159 + * Returns <tt>true</tt> if this map maps one or more keys to the
1.160 + * specified value. More formally, returns <tt>true</tt> if and only if
1.161 + * this map contains at least one mapping to a value <tt>v</tt> such that
1.162 + * <tt>(value==null ? v==null : value.equals(v))</tt>. This operation
1.163 + * will probably require time linear in the map size for most
1.164 + * implementations of the <tt>Map</tt> interface.
1.165 + *
1.166 + * @param value value whose presence in this map is to be tested
1.167 + * @return <tt>true</tt> if this map maps one or more keys to the
1.168 + * specified value
1.169 + * @throws ClassCastException if the value is of an inappropriate type for
1.170 + * this map
1.171 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.172 + * @throws NullPointerException if the specified value is null and this
1.173 + * map does not permit null values
1.174 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.175 + */
1.176 + boolean containsValue(Object value);
1.177 +
1.178 + /**
1.179 + * Returns the value to which the specified key is mapped,
1.180 + * or {@code null} if this map contains no mapping for the key.
1.181 + *
1.182 + * <p>More formally, if this map contains a mapping from a key
1.183 + * {@code k} to a value {@code v} such that {@code (key==null ? k==null :
1.184 + * key.equals(k))}, then this method returns {@code v}; otherwise
1.185 + * it returns {@code null}. (There can be at most one such mapping.)
1.186 + *
1.187 + * <p>If this map permits null values, then a return value of
1.188 + * {@code null} does not <i>necessarily</i> indicate that the map
1.189 + * contains no mapping for the key; it's also possible that the map
1.190 + * explicitly maps the key to {@code null}. The {@link #containsKey
1.191 + * containsKey} operation may be used to distinguish these two cases.
1.192 + *
1.193 + * @param key the key whose associated value is to be returned
1.194 + * @return the value to which the specified key is mapped, or
1.195 + * {@code null} if this map contains no mapping for the key
1.196 + * @throws ClassCastException if the key is of an inappropriate type for
1.197 + * this map
1.198 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.199 + * @throws NullPointerException if the specified key is null and this map
1.200 + * does not permit null keys
1.201 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.202 + */
1.203 + V get(Object key);
1.204 +
1.205 + // Modification Operations
1.206 +
1.207 + /**
1.208 + * Associates the specified value with the specified key in this map
1.209 + * (optional operation). If the map previously contained a mapping for
1.210 + * the key, the old value is replaced by the specified value. (A map
1.211 + * <tt>m</tt> is said to contain a mapping for a key <tt>k</tt> if and only
1.212 + * if {@link #containsKey(Object) m.containsKey(k)} would return
1.213 + * <tt>true</tt>.)
1.214 + *
1.215 + * @param key key with which the specified value is to be associated
1.216 + * @param value value to be associated with the specified key
1.217 + * @return the previous value associated with <tt>key</tt>, or
1.218 + * <tt>null</tt> if there was no mapping for <tt>key</tt>.
1.219 + * (A <tt>null</tt> return can also indicate that the map
1.220 + * previously associated <tt>null</tt> with <tt>key</tt>,
1.221 + * if the implementation supports <tt>null</tt> values.)
1.222 + * @throws UnsupportedOperationException if the <tt>put</tt> operation
1.223 + * is not supported by this map
1.224 + * @throws ClassCastException if the class of the specified key or value
1.225 + * prevents it from being stored in this map
1.226 + * @throws NullPointerException if the specified key or value is null
1.227 + * and this map does not permit null keys or values
1.228 + * @throws IllegalArgumentException if some property of the specified key
1.229 + * or value prevents it from being stored in this map
1.230 + */
1.231 + V put(K key, V value);
1.232 +
1.233 + /**
1.234 + * Removes the mapping for a key from this map if it is present
1.235 + * (optional operation). More formally, if this map contains a mapping
1.236 + * from key <tt>k</tt> to value <tt>v</tt> such that
1.237 + * <code>(key==null ? k==null : key.equals(k))</code>, that mapping
1.238 + * is removed. (The map can contain at most one such mapping.)
1.239 + *
1.240 + * <p>Returns the value to which this map previously associated the key,
1.241 + * or <tt>null</tt> if the map contained no mapping for the key.
1.242 + *
1.243 + * <p>If this map permits null values, then a return value of
1.244 + * <tt>null</tt> does not <i>necessarily</i> indicate that the map
1.245 + * contained no mapping for the key; it's also possible that the map
1.246 + * explicitly mapped the key to <tt>null</tt>.
1.247 + *
1.248 + * <p>The map will not contain a mapping for the specified key once the
1.249 + * call returns.
1.250 + *
1.251 + * @param key key whose mapping is to be removed from the map
1.252 + * @return the previous value associated with <tt>key</tt>, or
1.253 + * <tt>null</tt> if there was no mapping for <tt>key</tt>.
1.254 + * @throws UnsupportedOperationException if the <tt>remove</tt> operation
1.255 + * is not supported by this map
1.256 + * @throws ClassCastException if the key is of an inappropriate type for
1.257 + * this map
1.258 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.259 + * @throws NullPointerException if the specified key is null and this
1.260 + * map does not permit null keys
1.261 + * (<a href="Collection.html#optional-restrictions">optional</a>)
1.262 + */
1.263 + V remove(Object key);
1.264 +
1.265 +
1.266 + // Bulk Operations
1.267 +
1.268 + /**
1.269 + * Copies all of the mappings from the specified map to this map
1.270 + * (optional operation). The effect of this call is equivalent to that
1.271 + * of calling {@link #put(Object,Object) put(k, v)} on this map once
1.272 + * for each mapping from key <tt>k</tt> to value <tt>v</tt> in the
1.273 + * specified map. The behavior of this operation is undefined if the
1.274 + * specified map is modified while the operation is in progress.
1.275 + *
1.276 + * @param m mappings to be stored in this map
1.277 + * @throws UnsupportedOperationException if the <tt>putAll</tt> operation
1.278 + * is not supported by this map
1.279 + * @throws ClassCastException if the class of a key or value in the
1.280 + * specified map prevents it from being stored in this map
1.281 + * @throws NullPointerException if the specified map is null, or if
1.282 + * this map does not permit null keys or values, and the
1.283 + * specified map contains null keys or values
1.284 + * @throws IllegalArgumentException if some property of a key or value in
1.285 + * the specified map prevents it from being stored in this map
1.286 + */
1.287 + void putAll(Map<? extends K, ? extends V> m);
1.288 +
1.289 + /**
1.290 + * Removes all of the mappings from this map (optional operation).
1.291 + * The map will be empty after this call returns.
1.292 + *
1.293 + * @throws UnsupportedOperationException if the <tt>clear</tt> operation
1.294 + * is not supported by this map
1.295 + */
1.296 + void clear();
1.297 +
1.298 +
1.299 + // Views
1.300 +
1.301 + /**
1.302 + * Returns a {@link Set} view of the keys contained in this map.
1.303 + * The set is backed by the map, so changes to the map are
1.304 + * reflected in the set, and vice-versa. If the map is modified
1.305 + * while an iteration over the set is in progress (except through
1.306 + * the iterator's own <tt>remove</tt> operation), the results of
1.307 + * the iteration are undefined. The set supports element removal,
1.308 + * which removes the corresponding mapping from the map, via the
1.309 + * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
1.310 + * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
1.311 + * operations. It does not support the <tt>add</tt> or <tt>addAll</tt>
1.312 + * operations.
1.313 + *
1.314 + * @return a set view of the keys contained in this map
1.315 + */
1.316 + Set<K> keySet();
1.317 +
1.318 + /**
1.319 + * Returns a {@link Collection} view of the values contained in this map.
1.320 + * The collection is backed by the map, so changes to the map are
1.321 + * reflected in the collection, and vice-versa. If the map is
1.322 + * modified while an iteration over the collection is in progress
1.323 + * (except through the iterator's own <tt>remove</tt> operation),
1.324 + * the results of the iteration are undefined. The collection
1.325 + * supports element removal, which removes the corresponding
1.326 + * mapping from the map, via the <tt>Iterator.remove</tt>,
1.327 + * <tt>Collection.remove</tt>, <tt>removeAll</tt>,
1.328 + * <tt>retainAll</tt> and <tt>clear</tt> operations. It does not
1.329 + * support the <tt>add</tt> or <tt>addAll</tt> operations.
1.330 + *
1.331 + * @return a collection view of the values contained in this map
1.332 + */
1.333 + Collection<V> values();
1.334 +
1.335 + /**
1.336 + * Returns a {@link Set} view of the mappings contained in this map.
1.337 + * The set is backed by the map, so changes to the map are
1.338 + * reflected in the set, and vice-versa. If the map is modified
1.339 + * while an iteration over the set is in progress (except through
1.340 + * the iterator's own <tt>remove</tt> operation, or through the
1.341 + * <tt>setValue</tt> operation on a map entry returned by the
1.342 + * iterator) the results of the iteration are undefined. The set
1.343 + * supports element removal, which removes the corresponding
1.344 + * mapping from the map, via the <tt>Iterator.remove</tt>,
1.345 + * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
1.346 + * <tt>clear</tt> operations. It does not support the
1.347 + * <tt>add</tt> or <tt>addAll</tt> operations.
1.348 + *
1.349 + * @return a set view of the mappings contained in this map
1.350 + */
1.351 + Set<Map.Entry<K, V>> entrySet();
1.352 +
1.353 + /**
1.354 + * A map entry (key-value pair). The <tt>Map.entrySet</tt> method returns
1.355 + * a collection-view of the map, whose elements are of this class. The
1.356 + * <i>only</i> way to obtain a reference to a map entry is from the
1.357 + * iterator of this collection-view. These <tt>Map.Entry</tt> objects are
1.358 + * valid <i>only</i> for the duration of the iteration; more formally,
1.359 + * the behavior of a map entry is undefined if the backing map has been
1.360 + * modified after the entry was returned by the iterator, except through
1.361 + * the <tt>setValue</tt> operation on the map entry.
1.362 + *
1.363 + * @see Map#entrySet()
1.364 + * @since 1.2
1.365 + */
1.366 + interface Entry<K,V> {
1.367 + /**
1.368 + * Returns the key corresponding to this entry.
1.369 + *
1.370 + * @return the key corresponding to this entry
1.371 + * @throws IllegalStateException implementations may, but are not
1.372 + * required to, throw this exception if the entry has been
1.373 + * removed from the backing map.
1.374 + */
1.375 + K getKey();
1.376 +
1.377 + /**
1.378 + * Returns the value corresponding to this entry. If the mapping
1.379 + * has been removed from the backing map (by the iterator's
1.380 + * <tt>remove</tt> operation), the results of this call are undefined.
1.381 + *
1.382 + * @return the value corresponding to this entry
1.383 + * @throws IllegalStateException implementations may, but are not
1.384 + * required to, throw this exception if the entry has been
1.385 + * removed from the backing map.
1.386 + */
1.387 + V getValue();
1.388 +
1.389 + /**
1.390 + * Replaces the value corresponding to this entry with the specified
1.391 + * value (optional operation). (Writes through to the map.) The
1.392 + * behavior of this call is undefined if the mapping has already been
1.393 + * removed from the map (by the iterator's <tt>remove</tt> operation).
1.394 + *
1.395 + * @param value new value to be stored in this entry
1.396 + * @return old value corresponding to the entry
1.397 + * @throws UnsupportedOperationException if the <tt>put</tt> operation
1.398 + * is not supported by the backing map
1.399 + * @throws ClassCastException if the class of the specified value
1.400 + * prevents it from being stored in the backing map
1.401 + * @throws NullPointerException if the backing map does not permit
1.402 + * null values, and the specified value is null
1.403 + * @throws IllegalArgumentException if some property of this value
1.404 + * prevents it from being stored in the backing map
1.405 + * @throws IllegalStateException implementations may, but are not
1.406 + * required to, throw this exception if the entry has been
1.407 + * removed from the backing map.
1.408 + */
1.409 + V setValue(V value);
1.410 +
1.411 + /**
1.412 + * Compares the specified object with this entry for equality.
1.413 + * Returns <tt>true</tt> if the given object is also a map entry and
1.414 + * the two entries represent the same mapping. More formally, two
1.415 + * entries <tt>e1</tt> and <tt>e2</tt> represent the same mapping
1.416 + * if<pre>
1.417 + * (e1.getKey()==null ?
1.418 + * e2.getKey()==null : e1.getKey().equals(e2.getKey())) &&
1.419 + * (e1.getValue()==null ?
1.420 + * e2.getValue()==null : e1.getValue().equals(e2.getValue()))
1.421 + * </pre>
1.422 + * This ensures that the <tt>equals</tt> method works properly across
1.423 + * different implementations of the <tt>Map.Entry</tt> interface.
1.424 + *
1.425 + * @param o object to be compared for equality with this map entry
1.426 + * @return <tt>true</tt> if the specified object is equal to this map
1.427 + * entry
1.428 + */
1.429 + boolean equals(Object o);
1.430 +
1.431 + /**
1.432 + * Returns the hash code value for this map entry. The hash code
1.433 + * of a map entry <tt>e</tt> is defined to be: <pre>
1.434 + * (e.getKey()==null ? 0 : e.getKey().hashCode()) ^
1.435 + * (e.getValue()==null ? 0 : e.getValue().hashCode())
1.436 + * </pre>
1.437 + * This ensures that <tt>e1.equals(e2)</tt> implies that
1.438 + * <tt>e1.hashCode()==e2.hashCode()</tt> for any two Entries
1.439 + * <tt>e1</tt> and <tt>e2</tt>, as required by the general
1.440 + * contract of <tt>Object.hashCode</tt>.
1.441 + *
1.442 + * @return the hash code value for this map entry
1.443 + * @see Object#hashCode()
1.444 + * @see Object#equals(Object)
1.445 + * @see #equals(Object)
1.446 + */
1.447 + int hashCode();
1.448 + }
1.449 +
1.450 + // Comparison and hashing
1.451 +
1.452 + /**
1.453 + * Compares the specified object with this map for equality. Returns
1.454 + * <tt>true</tt> if the given object is also a map and the two maps
1.455 + * represent the same mappings. More formally, two maps <tt>m1</tt> and
1.456 + * <tt>m2</tt> represent the same mappings if
1.457 + * <tt>m1.entrySet().equals(m2.entrySet())</tt>. This ensures that the
1.458 + * <tt>equals</tt> method works properly across different implementations
1.459 + * of the <tt>Map</tt> interface.
1.460 + *
1.461 + * @param o object to be compared for equality with this map
1.462 + * @return <tt>true</tt> if the specified object is equal to this map
1.463 + */
1.464 + boolean equals(Object o);
1.465 +
1.466 + /**
1.467 + * Returns the hash code value for this map. The hash code of a map is
1.468 + * defined to be the sum of the hash codes of each entry in the map's
1.469 + * <tt>entrySet()</tt> view. This ensures that <tt>m1.equals(m2)</tt>
1.470 + * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two maps
1.471 + * <tt>m1</tt> and <tt>m2</tt>, as required by the general contract of
1.472 + * {@link Object#hashCode}.
1.473 + *
1.474 + * @return the hash code value for this map
1.475 + * @see Map.Entry#hashCode()
1.476 + * @see Object#equals(Object)
1.477 + * @see #equals(Object)
1.478 + */
1.479 + int hashCode();
1.480 +
1.481 +}