* * The map has three collection views, which are backed by the map * (modifications on one show up on the other): a set of keys, a collection * of values, and a set of key-value mappings. Some maps have a guaranteed * order, but not all do. *
* * Note: Be careful about using mutable keys. Behavior is unspecified if * a key's comparison behavior is changed after the fact. As a corollary * to this rule, don't use a Map as one of its own keys or values, as it makes * hashCode and equals have undefined behavior. *
* * All maps are recommended to provide a no argument constructor, which builds * an empty map, and one that accepts a Map parameter and copies the mappings * (usually by putAll), to create an equivalent map. Unfortunately, Java * cannot enforce these suggestions. *
*
* The map may be unmodifiable, in which case unsupported operations will
* throw an UnsupportedOperationException. Note that some operations may be
* safe, such as putAll(m) where m is empty, even if the operation would
* normally fail with a non-empty argument.
*
* @author Original author unknown
* @author Eric Blake (ebb9@email.byu.edu)
* @see HashMap
* @see TreeMap
* @see Hashtable
* @see SortedMap
* @see Collection
* @see Set
* @since 1.2
* @status updated to 1.4
*/
public interface Mapnull but the map
* does not permit null keys
*/
boolean containsKey(Object key);
/**
* Returns true if this contains at least one mapping with the given value.
* In other words, returns true if a value v exists where
* (value == null ? v == null : value.equals(v)). This usually
* requires linear time.
*
* @param value the value to search for
* @return true if the map contains the value
* @throws ClassCastException if the type of the value is not a valid type
* for this map.
* @throws NullPointerException if the value is null and the map doesn't
* support null values.
*/
boolean containsValue(Object value);
/**
* Returns a set view of the mappings in this Map. Each element in the
* set is a Map.Entry. The set is backed by the map, so that changes in
* one show up in the other. Modifications made while an iterator is
* in progress cause undefined behavior. If the set supports removal,
* these methods remove the underlying mapping from the map:
* Iterator.remove, Set.remove,
* removeAll, retainAll, and clear.
* Element addition, via add or addAll, is
* not supported via this set.
*
* @return the set view of all mapping entries
* @see Map.Entry
*/
Settrue if the other object is a Map with the same mappings,
* that is,
* o instanceof Map && entrySet().equals(((Map) o).entrySet();
* This allows comparison of maps, regardless of implementation.
*
* @param o the object to be compared
* @return true if the object equals this map
* @see Set#equals(Object)
*/
boolean equals(Object o);
/**
* Returns the value mapped by the given key. Returns null if
* there is no mapping. However, in Maps that accept null values, you
* must rely on containsKey to determine if a mapping exists.
*
* @param key the key to look up
* @return the value associated with the key, or null if key not in map
* @throws ClassCastException if the key is an inappropriate type
* @throws NullPointerException if this map does not accept null keys
* @see #containsKey(Object)
*/
V get(Object key);
/**
* Associates the given key to the given value (optional operation). If the
* map already contains the key, its value is replaced. Be aware that in
* a map that permits null values, a null return does not
* always imply that the mapping was created.
*
* @param key the key to map
* @param value the value to be mapped
* @return the previous value of the key, or null if there was no mapping
* @throws UnsupportedOperationException if the operation is not supported
* @throws ClassCastException if the key or value is of the wrong type
* @throws IllegalArgumentException if something about this key or value
* prevents it from existing in this map
* @throws NullPointerException if either the key or the value is null,
* and the map forbids null keys or values
* @see #containsKey(Object)
*/
V put(K key, V value);
/**
* Returns the hash code for this map. This is the sum of all hashcodes
* for each Map.Entry object in entrySet. This allows comparison of maps,
* regardless of implementation, and satisfies the contract of
* Object.hashCode.
*
* @return the hash code
* @see Map.Entry#hashCode()
*/
int hashCode();
/**
* Returns true if the map contains no mappings.
*
* @return true if the map is empty
*/
boolean isEmpty();
/**
* Returns a set view of the keys in this Map. The set is backed by the
* map, so that changes in one show up in the other. Modifications made
* while an iterator is in progress cause undefined behavior. If the set
* supports removal, these methods remove the underlying mapping from
* the map: Iterator.remove, Set.remove,
* removeAll, retainAll, and clear.
* Element addition, via add or addAll, is
* not supported via this set.
*
* @return the set view of all keys
*/
Setm is null.
* @see #put(Object, Object)
*/
void putAll(Map m);
/**
* Removes the mapping for this key if present (optional operation). If
* the key is not present, this returns null. Note that maps which permit
* null values may also return null if the key was removed.
*
* @param key the key to remove
* @return the value the key mapped to, or null if not present.
* @throws UnsupportedOperationException if deletion is unsupported
* @throws NullPointerException if the key is null and this map doesn't
* support null keys.
* @throws ClassCastException if the type of the key is not a valid type
* for this map.
*/
V remove(Object o);
/**
* Returns the number of key-value mappings in the map. If there are more
* than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.
*
* @return the number of mappings
*/
int size();
/**
* Returns a collection (or bag) view of the values in this Map. The
* collection is backed by the map, so that changes in one show up in
* the other. Modifications made while an iterator is in progress cause
* undefined behavior. If the collection supports removal, these methods
* remove the underlying mapping from the map: Iterator.remove,
* Collection.remove, removeAll,
* retainAll, and clear. Element addition, via
* add or addAll, is not supported via this
* collection.
*
* @return the collection view of all values
*/
Collectionnull). In other words, this must be:
*
(getKey() == null ? 0 : getKey().hashCode())
^ (getValue() == null ? 0 : getValue().hashCode())
*
* @return the hash code
*/
int hashCode();
/**
* Compares the specified object with this entry. Returns true only if
* the object is a mapping of identical key and value. In other words,
* this must be:
*
(o instanceof Map.Entry)
&& (getKey() == null ? ((Map.Entry) o).getKey() == null
: getKey().equals(((Map.Entry) o).getKey()))
&& (getValue() == null ? ((Map.Entry) o).getValue() == null
: getValue().equals(((Map.Entry) o).getValue()))
*
* @param o the object to compare
*
* @return true if it is equal
*/
boolean equals(Object o);
}
}