1.1 --- a/emul/compact/src/main/java/java/util/Map.java Fri Mar 22 16:59:47 2013 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,478 +0,0 @@
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 -}